devs/cproof
1
2
Fork 1
Code Issues 43 Pull Requests 6 Actions Packages Projects 1 Releases Wiki Activity

docs: Fix indentation
All checks were successful
CI API Docs / Test C API Documentation Generation (pull_request) Successful in 26s
Details
CI API Docs / Test Python API Documentation Generation (pull_request) Successful in 28s
Details
CI Code / Check coding style (pull_request) Successful in 35s
Details
CI Code / Check spelling (pull_request) Successful in 18s
Details
CI Code / Linux (debian) (pull_request) Successful in 13m38s
Details
CI Code / Linux (ubuntu) (pull_request) Successful in 16m18s
Details
CI Code / Linux (arch) (pull_request) Successful in 16m46s
Details

Browse Source
This commit is contained in:
Jabber Developer
2025-09-17 01:02:46 +02:00
parent 9fd62e2304
commit 92cb930810
2 changed files with 246 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
apidocs/python/src/plugin.py
View File

@@ -8,9 +8,9 @@ occurs. You need to define them in your module and they will automatically be us
for callback events. for callback events.
To utilize full functionality, such as the ``prof.cons_show`` function, see ``prof`` To utilize full functionality, such as the ``prof.cons_show`` function, see ``prof``
documentation and use: documentation and use::
::
import prof import prof
""" """
# Initialization and Lifecycle # Initialization and Lifecycle
@@ -28,8 +28,8 @@ def prof_init(version: str, status: str, account_name: str | None, fulljid: str
:param fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in. :param fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in.
:return: None :return: None
Example: Example::
::
def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None: def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None:
prof.cons_show(f"MyPlugin for CProof {version} ({status}) has been loaded, account: {account_name}") prof.cons_show(f"MyPlugin for CProof {version} ({status}) has been loaded, account: {account_name}")
""" """
@@ -42,8 +42,8 @@ def prof_on_start() -> None:
:return: None :return: None
Example: Example::
::
def prof_on_start() -> None: def prof_on_start() -> None:
prof.cons_show("CProof has started...") prof.cons_show("CProof has started...")
""" """
@@ -56,8 +56,8 @@ def prof_on_shutdown() -> None:
:return: None :return: None
Example: Example::
::
def prof_on_shutdown() -> None: def prof_on_shutdown() -> None:
prof.cons_show("CProof is shutting down...") prof.cons_show("CProof is shutting down...")
""" """
@@ -70,8 +70,8 @@ def prof_on_unload() -> None:
:return: None :return: None
Example: Example::
::
def prof_on_unload() -> None: def prof_on_unload() -> None:
prof.cons_show("Plugin unloaded") prof.cons_show("Plugin unloaded")
""" """
@@ -84,8 +84,8 @@ def prof_on_connect(account_name: str, fulljid: str) -> None:
:param fulljid: The full Jabber ID (barejid/resource) of the connected account. :param fulljid: The full Jabber ID (barejid/resource) of the connected account.
:return: None :return: None
Example: Example::
::
def prof_on_connect(account_name: str, fulljid: str) -> None: def prof_on_connect(account_name: str, fulljid: str) -> None:
prof.cons_show(f"Connected as {account_name} ({fulljid})") prof.cons_show(f"Connected as {account_name} ({fulljid})")
""" """
@@ -98,8 +98,8 @@ def prof_on_disconnect(account_name: str, fulljid: str) -> None:
:param fulljid: The full Jabber ID (barejid/resource) of the disconnected account. :param fulljid: The full Jabber ID (barejid/resource) of the disconnected account.
:return: None :return: None
Example: Example::
::
def prof_on_disconnect(account_name: str, fulljid: str) -> None: def prof_on_disconnect(account_name: str, fulljid: str) -> None:
prof.cons_show(f"Disconnected {account_name} ({fulljid})") prof.cons_show(f"Disconnected {account_name} ({fulljid})")
""" """
@@ -118,8 +118,8 @@ def prof_pre_chat_message_display(barejid: str, resource: str, message: str) ->
:param message: The received message. :param message: The received message.
:return: The modified message to display, or None to preserve the original. :return: The modified message to display, or None to preserve the original.
Example: Example::
::
def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None: def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None:
new_message = f"{message} (from {barejid})" new_message = f"{message} (from {barejid})"
return new_message return new_message
@@ -136,8 +136,8 @@ def prof_post_chat_message_display(barejid: str, resource: str, message: str) ->
:param message: The displayed message. :param message: The displayed message.
:return: None :return: None
Example: Example::
::
def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None: def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None:
prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}") prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}")
""" """
@@ -152,8 +152,8 @@ def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
:param message: The message to be sent. :param message: The message to be sent.
:return: The modified message to send, or None to cancel sending. :return: The modified message to send, or None to cancel sending.
Example: Example::
::
def prof_pre_chat_message_send(barejid: str, message: str) -> str | None: def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
return f"{message} (sent by plugin)" return f"{message} (sent by plugin)"
""" """
@@ -168,8 +168,8 @@ def prof_post_chat_message_send(barejid: str, message: str) -> None:
:param message: The sent message. :param message: The sent message.
:return: None :return: None
Example: Example::
::
def prof_post_chat_message_send(barejid: str, message: str) -> None: def prof_post_chat_message_send(barejid: str, message: str) -> None:
prof.cons_show(f"Sent to {barejid}: {message}") prof.cons_show(f"Sent to {barejid}: {message}")
""" """
@@ -188,8 +188,8 @@ def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str
:param message: The received message. :param message: The received message.
:return: The modified message to display, or None to preserve the original. :return: The modified message to display, or None to preserve the original.
Example: Example::
::
def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None: def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None:
return f"{message} (from {nick})" return f"{message} (from {nick})"
""" """
@@ -205,8 +205,8 @@ def prof_post_room_message_display(barejid: str, nick: str, message: str) -> Non
:param message: The displayed message. :param message: The displayed message.
:return: None :return: None
Example: Example::
::
def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None: def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None:
prof.cons_show(f"Displayed in {barejid} from {nick}: {message}") prof.cons_show(f"Displayed in {barejid} from {nick}: {message}")
""" """
@@ -221,8 +221,8 @@ def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
:param message: The message to be sent. :param message: The message to be sent.
:return: The modified message to send, or None to cancel sending. :return: The modified message to send, or None to cancel sending.
Example: Example::
::
def prof_pre_room_message_send(barejid: str, message: str) -> str | None: def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
return f"{message} (sent by plugin)" return f"{message} (sent by plugin)"
""" """
@@ -237,8 +237,8 @@ def prof_post_room_message_send(barejid: str, message: str) -> None:
:param message: The sent message. :param message: The sent message.
:return: None :return: None
Example: Example::
::
def prof_post_room_message_send(barejid: str, message: str) -> None: def prof_post_room_message_send(barejid: str, message: str) -> None:
prof.cons_show(f"Sent to {barejid}: {message}") prof.cons_show(f"Sent to {barejid}: {message}")
""" """
@@ -253,8 +253,8 @@ def prof_on_room_history_message(barejid: str, nick: str, message: str, timestam
:param timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``). :param timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``).
:return: None :return: None
Example: Example::
::
def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None: def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None:
prof.cons_show(f"History in {barejid} from {nick} at {timestamp}: {message}") prof.cons_show(f"History in {barejid} from {nick} at {timestamp}: {message}")
""" """
@@ -273,8 +273,8 @@ def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str
:param message: The received message. :param message: The received message.
:return: The modified message to display, or None to preserve the original. :return: The modified message to display, or None to preserve the original.
Example: Example::
::
def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None: def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None:
return f"{message} (private from {nick})" return f"{message} (private from {nick})"
""" """
@@ -290,8 +290,8 @@ def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> Non
:param message: The displayed message. :param message: The displayed message.
:return: None :return: None
Example: Example::
::
def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None: def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None:
prof.cons_show(f"Displayed private in {barejid} from {nick}: {message}") prof.cons_show(f"Displayed private in {barejid} from {nick}: {message}")
""" """
@@ -307,8 +307,8 @@ def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | N
:param message: The message to be sent. :param message: The message to be sent.
:return: The modified message to send, or None to cancel sending. :return: The modified message to send, or None to cancel sending.
Example: Example::
::
def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None: def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None:
return f"{message} (private to {nick})" return f"{message} (private to {nick})"
""" """
@@ -324,8 +324,8 @@ def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
:param message: The sent message. :param message: The sent message.
:return: None :return: None
Example: Example::
::
def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None: def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
prof.cons_show(f"Sent private to {nick} in {barejid}: {message}") prof.cons_show(f"Sent private to {nick} in {barejid}: {message}")
""" """
@@ -342,8 +342,8 @@ def prof_on_message_stanza_send(stanza: str) -> str | None:
:param stanza: The XMPP message stanza to send. :param stanza: The XMPP message stanza to send.
:return: The modified stanza to send, or None to preserve the original. :return: The modified stanza to send, or None to preserve the original.
Example: Example::
::
def prof_on_message_stanza_send(stanza: str) -> str | None: def prof_on_message_stanza_send(stanza: str) -> str | None:
prof.cons_show(f"Sending message stanza: {stanza}") prof.cons_show(f"Sending message stanza: {stanza}")
return stanza return stanza
@@ -358,8 +358,8 @@ def prof_on_message_stanza_receive(stanza: str) -> bool:
:param stanza: The received XMPP message stanza. :param stanza: The received XMPP message stanza.
:return: True to allow CProof to process the stanza, False to block processing. :return: True to allow CProof to process the stanza, False to block processing.
Example: Example::
::
def prof_on_message_stanza_receive(stanza: str) -> bool: def prof_on_message_stanza_receive(stanza: str) -> bool:
prof.cons_show(f"Received message stanza: {stanza}") prof.cons_show(f"Received message stanza: {stanza}")
return True return True
@@ -374,8 +374,8 @@ def prof_on_presence_stanza_send(stanza: str) -> str | None:
:param stanza: The XMPP presence stanza to send. :param stanza: The XMPP presence stanza to send.
:return: The modified stanza to send, or None to preserve the original. :return: The modified stanza to send, or None to preserve the original.
Example: Example::
::
def prof_on_presence_stanza_send(stanza: str) -> str | None: def prof_on_presence_stanza_send(stanza: str) -> str | None:
prof.cons_show(f"Sending presence stanza: {stanza}") prof.cons_show(f"Sending presence stanza: {stanza}")
return stanza return stanza
@@ -390,8 +390,8 @@ def prof_on_presence_stanza_receive(stanza: str) -> bool:
:param stanza: The received XMPP presence stanza. :param stanza: The received XMPP presence stanza.
:return: True to allow CProof to process the stanza, False to block processing. :return: True to allow CProof to process the stanza, False to block processing.
Example: Example::
::
def prof_on_presence_stanza_receive(stanza: str) -> bool: def prof_on_presence_stanza_receive(stanza: str) -> bool:
prof.cons_show(f"Received presence stanza: {stanza}") prof.cons_show(f"Received presence stanza: {stanza}")
return True return True
@@ -406,8 +406,8 @@ def prof_on_iq_stanza_send(stanza: str) -> str | None:
:param stanza: The XMPP IQ stanza to send. :param stanza: The XMPP IQ stanza to send.
:return: The modified stanza to send, or None to preserve the original. :return: The modified stanza to send, or None to preserve the original.
Example: Example::
::
def prof_on_iq_stanza_send(stanza: str) -> str | None: def prof_on_iq_stanza_send(stanza: str) -> str | None:
prof.cons_show(f"Sending IQ stanza: {stanza}") prof.cons_show(f"Sending IQ stanza: {stanza}")
return stanza return stanza
@@ -422,8 +422,8 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool:
:param stanza: The received XMPP IQ stanza. :param stanza: The received XMPP IQ stanza.
:return: True to allow CProof to process the stanza, False to block processing. :return: True to allow CProof to process the stanza, False to block processing.
Example: Example::
::
def prof_on_iq_stanza_receive(stanza: str) -> bool: def prof_on_iq_stanza_receive(stanza: str) -> bool:
prof.cons_show(f"Received IQ stanza: {stanza}") prof.cons_show(f"Received IQ stanza: {stanza}")
return True return True
@@ -441,8 +441,8 @@ def prof_on_contact_offline(barejid: str, resource: str, status: str | None) ->
:param status: The status message received with the offline presence, or None. :param status: The status message received with the offline presence, or None.
:return: None :return: None
Example: Example::
::
def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None: def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None:
prof.cons_show(f"{barejid}/{resource} went offline: {status or 'No status'}") prof.cons_show(f"{barejid}/{resource} went offline: {status or 'No status'}")
""" """
@@ -458,8 +458,8 @@ def prof_on_contact_presence(barejid: str, resource: str, presence: str, status:
:param priority: The priority associated with the resource. :param priority: The priority associated with the resource.
:return: None :return: None
Example: Example::
::
def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None: def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None:
prof.notify(f"{barejid} is {presence}", 5000, "Presence") prof.notify(f"{barejid} is {presence}", 5000, "Presence")
""" """
@@ -474,8 +474,8 @@ def prof_on_chat_win_focus(barejid: str) -> None:
:param barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``). :param barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``).
:return: None :return: None
Example: Example::
::
def prof_on_chat_win_focus(barejid: str) -> None: def prof_on_chat_win_focus(barejid: str) -> None:
prof.cons_show(f"Focused chat window for {barejid}") prof.cons_show(f"Focused chat window for {barejid}")
""" """
@@ -487,8 +487,8 @@ def prof_on_room_win_focus(barejid: str) -> None:
:param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
:return: None :return: None
Example: Example::
::
def prof_on_room_win_focus(barejid: str) -> None: def prof_on_room_win_focus(barejid: str) -> None:
prof.cons_show(f"Focused room window for {barejid}") prof.cons_show(f"Focused room window for {barejid}")
""" """

310
apidocs/python/src/prof.py
View File

@@ -1,8 +1,8 @@
""" """
The prof module provides a Python API for plugins to interact with CProof. The prof module provides a Python API for plugins to interact with CProof.
Plugins must import this module to access its functions:
:: Plugins must import this module to access its functions::
import prof import prof
Functions are grouped into sections for console interaction, command management, Functions are grouped into sections for console interaction, command management,
@@ -20,10 +20,11 @@ class CommandCallback(Protocol):
:param command_parameters: Variable string arguments passed to the callback. :param command_parameters: Variable string arguments passed to the callback.
:return: None :return: None
Example: Example::
::
def my_command(*command_parameters: str) -> None: def my_command(*command_parameters: str) -> None:
prof.cons_show(f"Received: {command_parameters}") prof.cons_show(f"Received: {command_parameters}")
""" """
def __call__(self, *command_parameters: str) -> None: ... def __call__(self, *command_parameters: str) -> None: ...
@@ -32,10 +33,11 @@ class TimedCallback(Protocol):
:return: None :return: None
Example: Example::
::
def my_timed_callback() -> None: def my_timed_callback() -> None:
prof.cons_show("Timer triggered") prof.cons_show("Timer triggered")
""" """
def __call__(self) -> None: ... def __call__(self) -> None: ...
@@ -46,10 +48,11 @@ class WindowCallback(Protocol):
:param message: The message to process. :param message: The message to process.
:return: None :return: None
Example: Example::
::
def my_window_callback(win_id: str, message: str) -> None: def my_window_callback(win_id: str, message: str) -> None:
prof.win_show(win_id, f"Processed: {message}") prof.win_show(win_id, f"Processed: {message}")
""" """
def __call__(self, win_id: str, message: str) -> None: ... def __call__(self, win_id: str, message: str) -> None: ...
@@ -61,9 +64,10 @@ def cons_alert() -> None:
:return: None :return: None
Example: Example::
::
prof.cons_alert() # Highlights the console window prof.cons_alert() # Highlights the console window
""" """
pass pass
@@ -73,9 +77,10 @@ def cons_show(message: str) -> None:
:param message: The message to display. :param message: The message to display.
:return: None :return: None
Example: Example::
::
prof.cons_show("This appears in the console window") prof.cons_show("This appears in the console window")
""" """
pass pass
@@ -91,9 +96,10 @@ def cons_show_themed(group: str | None, key: str | None, default: str | None, me
:param message: The message to display. :param message: The message to display.
:return: None :return: None
Example: Example::
::
prof.cons_show_themed("myplugin", "text", "white", "Themed message") prof.cons_show_themed("myplugin", "text", "white", "Themed message")
""" """
pass pass
@@ -103,9 +109,10 @@ def cons_bad_cmd_usage(command: str) -> None:
:param command: The command name, including the leading slash (e.g., ``/say``). :param command: The command name, including the leading slash (e.g., ``/say``).
:return: None :return: None
Example: Example::
::
prof.cons_bad_cmd_usage("/mycommand") # Shows usage error for /mycommand prof.cons_bad_cmd_usage("/mycommand") # Shows usage error for /mycommand
""" """
pass pass
@@ -138,8 +145,8 @@ def register_command(
:param callback: Function to call when the command is executed, taking variable string arguments. :param callback: Function to call when the command is executed, taking variable string arguments.
:return: None :return: None
Example: Example::
::
def command_handler(*args: str) -> None: def command_handler(*args: str) -> None:
prof.cons_show(f"Received: {args}") prof.cons_show(f"Received: {args}")
if len(args) == 1 and args[0] in ("on", "off"): if len(args) == 1 and args[0] in ("on", "off"):
@@ -159,6 +166,7 @@ def register_command(
prof.register_command( prof.register_command(
"/new_command", 1, 2, synopsis, description, arguments, examples, command_handler "/new_command", 1, 2, synopsis, description, arguments, examples, command_handler
) )
""" """
pass pass
@@ -172,12 +180,13 @@ def register_timed(callback: TimedCallback, interval: int) -> None:
:param interval: The time between calls, in seconds. :param interval: The time between calls, in seconds.
:return: None :return: None
Example: Example::
::
def periodic_task() -> None: def periodic_task() -> None:
prof.cons_show("Periodic update") prof.cons_show("Periodic update")
prof.register_timed(periodic_task, 30) # Calls every 30 seconds prof.register_timed(periodic_task, 30) # Calls every 30 seconds
""" """
pass pass
@@ -194,10 +203,11 @@ def completer_add(key: str, items: list[str]) -> None:
:param items: The items to return on autocompletion. :param items: The items to return on autocompletion.
:return: None :return: None
Example: Example::
::
prof.completer_add("/mycommand", ["action1", "action2"]) prof.completer_add("/mycommand", ["action1", "action2"])
prof.completer_add("/mycommand dosomething", ["thing1", "thing2"]) prof.completer_add("/mycommand dosomething", ["thing1", "thing2"])
""" """
pass pass
@@ -208,9 +218,10 @@ def completer_remove(key: str, items: list[str]) -> None:
:param items: The items to remove from the autocomplete list. :param items: The items to remove from the autocomplete list.
:return: None :return: None
Example: Example::
::
prof.completer_remove("/mycommand", ["action1", "action2"]) prof.completer_remove("/mycommand", ["action1", "action2"])
""" """
pass pass
@@ -220,9 +231,10 @@ def completer_clear(key: str) -> None:
:param key: The prefix to clear autocomplete items for (e.g., ``/mycommand``). :param key: The prefix to clear autocomplete items for (e.g., ``/mycommand``).
:return: None :return: None
Example: Example::
::
prof.completer_clear("/mycommand") prof.completer_clear("/mycommand")
""" """
pass pass
@@ -232,9 +244,10 @@ def filepath_completer_add(prefix: str) -> None:
:param prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``). :param prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``).
:return: None :return: None
Example: Example::
::
prof.filepath_completer_add("/filecmd") # Enables filepath completion prof.filepath_completer_add("/filecmd") # Enables filepath completion
""" """
pass pass
@@ -247,10 +260,11 @@ def win_exists(tag: str) -> bool:
:param tag: The tag identifying the plugin window. :param tag: The tag identifying the plugin window.
:return: True if the window exists, False otherwise. :return: True if the window exists, False otherwise.
Example: Example::
::
if prof.win_exists("MyPlugin"): if prof.win_exists("MyPlugin"):
prof.cons_show("Window exists") prof.cons_show("Window exists")
""" """
pass pass
@@ -264,12 +278,13 @@ def win_create(tag: str, callback: WindowCallback) -> None:
:param callback: Function to process window input, taking the window tag and message. :param callback: Function to process window input, taking the window tag and message.
:return: None :return: None
Example: Example::
::
def handler(win_id: str, message: str) -> None: def handler(win_id: str, message: str) -> None:
prof.win_show(win_id, f"Processed: {message}") prof.win_show(win_id, f"Processed: {message}")
prof.win_create("MyPlugin", handler) prof.win_create("MyPlugin", handler)
""" """
pass pass
@@ -279,9 +294,10 @@ def win_focus(tag: str) -> None:
:param tag: The tag identifying the plugin window. :param tag: The tag identifying the plugin window.
:return: None :return: None
Example: Example::
::
prof.win_focus("MyPlugin") # Focuses the MyPlugin window prof.win_focus("MyPlugin") # Focuses the MyPlugin window
""" """
pass pass
@@ -292,9 +308,10 @@ def win_show(tag: str, message: str) -> None:
:param message: The message to display. :param message: The message to display.
:return: None :return: None
Example: Example::
::
prof.win_show("MyPlugin", "Message in plugin window") prof.win_show("MyPlugin", "Message in plugin window")
""" """
pass pass
@@ -311,9 +328,10 @@ def win_show_themed(tag: str, group: str | None, key: str | None, default: str |
:param message: The message to display. :param message: The message to display.
:return: None :return: None
Example: Example::
::
prof.win_show_themed("MyPlugin", "myplugin", "text", "white", "Themed message") prof.win_show_themed("MyPlugin", "myplugin", "text", "white", "Themed message")
""" """
pass pass
@@ -327,10 +345,11 @@ def chat_show(barejid: str, message: str) -> bool:
:param message: The message to display. :param message: The message to display.
:return: True if the message was displayed, False if the chat window does not exist. :return: True if the message was displayed, False if the chat window does not exist.
Example: Example::
::
if prof.chat_show("bob@example.com", "Hello from plugin"): if prof.chat_show("bob@example.com", "Hello from plugin"):
prof.cons_show("Message displayed") prof.cons_show("Message displayed")
""" """
pass pass
@@ -355,9 +374,10 @@ def chat_show_themed(
:param message: The message to display. :param message: The message to display.
:return: True if the message was displayed, False if the chat window does not exist. :return: True if the message was displayed, False if the chat window does not exist.
Example: Example::
::
prof.chat_show_themed("bob@example.com", "myplugin", "text", None, "!", "Themed message") prof.chat_show_themed("bob@example.com", "myplugin", "text", None, "!", "Themed message")
""" """
pass pass
@@ -368,9 +388,10 @@ def room_show(roomjid: str, message: str) -> bool:
:param message: The message to display. :param message: The message to display.
:return: True if the message was displayed, False if the room window does not exist. :return: True if the message was displayed, False if the room window does not exist.
Example: Example::
::
prof.room_show("chat@conference.example.com", "Room message from plugin") prof.room_show("chat@conference.example.com", "Room message from plugin")
""" """
pass pass
@@ -395,9 +416,10 @@ def room_show_themed(
:param message: The message to display. :param message: The message to display.
:return: True if the message was displayed, False if the room window does not exist. :return: True if the message was displayed, False if the room window does not exist.
Example: Example::
::
prof.room_show_themed("chat@conference.example.com", "myplugin", "text", None, "!", "Themed room message") prof.room_show_themed("chat@conference.example.com", "myplugin", "text", None, "!", "Themed room message")
""" """
pass pass
@@ -410,9 +432,10 @@ def send_line(line: str) -> None:
:param line: The input line to execute (e.g., ``/who online``). :param line: The input line to execute (e.g., ``/who online``).
:return: None :return: None
Example: Example::
::
prof.send_line("/who online") # Executes the /who online command prof.send_line("/who online") # Executes the /who online command
""" """
pass pass
@@ -422,11 +445,12 @@ def send_stanza(stanza: str) -> bool:
:param stanza: The XMPP stanza to send (e.g., an IQ or message stanza). :param stanza: The XMPP stanza to send (e.g., an IQ or message stanza).
:return: True if the stanza was sent successfully, False if it was invalid or failed to send. :return: True if the stanza was sent successfully, False if it was invalid or failed to send.
Example: Example::
::
stanza = "<iq to='juliet@example.com' id='s2c1' type='get'><ping xmlns='urn:xmpp:ping'/></iq>" stanza = "<iq to='juliet@example.com' id='s2c1' type='get'><ping xmlns='urn:xmpp:ping'/></iq>"
if prof.send_stanza(stanza): if prof.send_stanza(stanza):
prof.cons_show("Stanza sent successfully") prof.cons_show("Stanza sent successfully")
""" """
pass pass
@@ -438,9 +462,10 @@ def incoming_message(barejid: str, resource: str, message: str) -> None:
:param message: The message text. :param message: The message text.
:return: None :return: None
Example: Example::
::
prof.incoming_message("bob@example.com", "laptop", "Hello from plugin") prof.incoming_message("bob@example.com", "laptop", "Hello from plugin")
""" """
pass pass
@@ -453,9 +478,10 @@ def disco_add_feature(feature: str) -> None:
:param feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``). :param feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``).
:return: None :return: None
Example: Example::
::
prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify") prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify")
""" """
pass pass
@@ -465,9 +491,10 @@ def encryption_reset(barejid: str) -> None:
:param barejid: The Jabber ID of the contact (e.g., ``alice@example.com``). :param barejid: The Jabber ID of the contact (e.g., ``alice@example.com``).
:return: None :return: None
Example: Example::
::
prof.encryption_reset("alice@example.com") # Resets encryption prof.encryption_reset("alice@example.com") # Resets encryption
""" """
pass pass
@@ -478,9 +505,10 @@ def chat_set_titlebar_enctext(barejid: str, enctext: str) -> bool:
:param enctext: The text to display in the titlebar. :param enctext: The text to display in the titlebar.
:return: True if the text was set, False if the chat window does not exist. :return: True if the text was set, False if the chat window does not exist.
Example: Example::
::
prof.chat_set_titlebar_enctext("bob@example.com", "secure") prof.chat_set_titlebar_enctext("bob@example.com", "secure")
""" """
pass pass
@@ -492,9 +520,10 @@ def chat_unset_titlebar_enctext(barejid: str) -> bool:
:param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
:return: True if the text was reset, False if the chat window does not exist. :return: True if the text was reset, False if the chat window does not exist.
Example: Example::
::
prof.chat_unset_titlebar_enctext("bob@example.com") prof.chat_unset_titlebar_enctext("bob@example.com")
""" """
pass pass
@@ -505,9 +534,10 @@ def chat_set_incoming_char(barejid: str, ch: str) -> bool:
:param ch: The prefix character to display. :param ch: The prefix character to display.
:return: True if the character was set, False if the chat window does not exist. :return: True if the character was set, False if the chat window does not exist.
Example: Example::
::
prof.chat_set_incoming_char("bob@example.com", "*") prof.chat_set_incoming_char("bob@example.com", "*")
""" """
pass pass
@@ -517,9 +547,10 @@ def chat_unset_incoming_char(barejid: str) -> bool:
:param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
:return: True if the character was reset, False if the chat window does not exist. :return: True if the character was reset, False if the chat window does not exist.
Example: Example::
::
prof.chat_unset_incoming_char("bob@example.com") prof.chat_unset_incoming_char("bob@example.com")
""" """
pass pass
@@ -530,9 +561,10 @@ def chat_set_outgoing_char(barejid: str, ch: str) -> bool:
:param ch: The prefix character to display. :param ch: The prefix character to display.
:return: True if the character was set, False if the chat window does not exist. :return: True if the character was set, False if the chat window does not exist.
Example: Example::
::
prof.chat_set_outgoing_char("bob@example.com", "+") prof.chat_set_outgoing_char("bob@example.com", "+")
""" """
pass pass
@@ -542,9 +574,10 @@ def chat_unset_outgoing_char(barejid: str) -> bool:
:param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
:return: True if the character was reset, False if the chat window does not exist. :return: True if the character was reset, False if the chat window does not exist.
Example: Example::
::
prof.chat_unset_outgoing_char("bob@example.com") prof.chat_unset_outgoing_char("bob@example.com")
""" """
pass pass
@@ -555,9 +588,10 @@ def room_set_titlebar_enctext(roomjid: str, enctext: str) -> bool:
:param enctext: The text to display in the titlebar. :param enctext: The text to display in the titlebar.
:return: True if the text was set, False if the room window does not exist. :return: True if the text was set, False if the room window does not exist.
Example: Example::
::
prof.room_set_titlebar_enctext("chat@conference.example.com", "secure") prof.room_set_titlebar_enctext("chat@conference.example.com", "secure")
""" """
pass pass
@@ -569,9 +603,10 @@ def room_unset_titlebar_enctext(roomjid: str) -> bool:
:param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
:return: True if the text was reset, False if the room window does not exist. :return: True if the text was reset, False if the room window does not exist.
Example: Example::
::
prof.room_unset_titlebar_enctext("chat@conference.example.com") prof.room_unset_titlebar_enctext("chat@conference.example.com")
""" """
pass pass
@@ -582,9 +617,10 @@ def room_set_message_char(roomjid: str, ch: str) -> bool:
:param ch: The prefix character to display. :param ch: The prefix character to display.
:return: True if the character was set, False if the room window does not exist. :return: True if the character was set, False if the room window does not exist.
Example: Example::
::
prof.room_set_message_char("chat@conference.example.com", "^") prof.room_set_message_char("chat@conference.example.com", "^")
""" """
pass pass
@@ -594,9 +630,10 @@ def room_unset_message_char(roomjid: str) -> bool:
:param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
:return: True if the character was reset, False if the room window does not exist. :return: True if the character was reset, False if the room window does not exist.
Example: Example::
::
prof.room_unset_message_char("chat@conference.example.com") prof.room_unset_message_char("chat@conference.example.com")
""" """
pass pass
@@ -613,9 +650,10 @@ def settings_boolean_get(group: str, key: str, default: bool) -> bool:
:param default: The default value if the setting is not found. :param default: The default value if the setting is not found.
:return: The setting value, or the default if not found. :return: The setting value, or the default if not found.
Example: Example::
::
notify = prof.settings_boolean_get("myplugin", "notify", False) notify = prof.settings_boolean_get("myplugin", "notify", False)
""" """
pass pass
@@ -629,9 +667,10 @@ def settings_boolean_set(group: str, key: str, value: bool) -> None:
:param value: The boolean value to set. :param value: The boolean value to set.
:return: None :return: None
Example: Example::
::
prof.settings_boolean_set("myplugin", "notify", True) prof.settings_boolean_set("myplugin", "notify", True)
""" """
pass pass
@@ -645,9 +684,10 @@ def settings_string_get(group: str, key: str, default: str) -> str:
:param default: The default value if the setting is not found. :param default: The default value if the setting is not found.
:return: The setting value, or the default if not found. :return: The setting value, or the default if not found.
Example: Example::
::
prefix = prof.settings_string_get("myplugin", "prefix", "myplugin>") prefix = prof.settings_string_get("myplugin", "prefix", "myplugin>")
""" """
pass pass
@@ -661,9 +701,10 @@ def settings_string_set(group: str, key: str, value: str) -> None:
:param value: The string value to set. :param value: The string value to set.
:return: None :return: None
Example: Example::
::
prof.settings_string_set("myplugin", "prefix", "myplugin>") prof.settings_string_set("myplugin", "prefix", "myplugin>")
""" """
pass pass
@@ -677,9 +718,10 @@ def settings_string_list_get(group: str, key: str) -> list[str]:
:param key: The item name within the group. :param key: The item name within the group.
:return: List of strings, or an empty list if the setting does not exist. :return: List of strings, or an empty list if the setting does not exist.
Example: Example::
::
items = prof.settings_string_list_get("myplugin", "items") items = prof.settings_string_list_get("myplugin", "items")
""" """
pass pass
@@ -694,9 +736,10 @@ def settings_string_list_add(group: str, key: str, value: str) -> None:
:param value: The string to add to the list. :param value: The string to add to the list.
:return: None :return: None
Example: Example::
::
prof.settings_string_list_add("myplugin", "items", "item1") prof.settings_string_list_add("myplugin", "items", "item1")
""" """
pass pass
@@ -710,9 +753,10 @@ def settings_string_list_remove(group: str, key: str, value: str) -> bool:
:param value: The string to remove from the list. :param value: The string to remove from the list.
:return: True if the item was removed or not in the list, False if the list does not exist. :return: True if the item was removed or not in the list, False if the list does not exist.
Example: Example::
::
prof.settings_string_list_remove("myplugin", "items", "item1") prof.settings_string_list_remove("myplugin", "items", "item1")
""" """
pass pass
@@ -725,9 +769,10 @@ def settings_string_list_clear(group: str, key: str) -> bool:
:param key: The item name within the group. :param key: The item name within the group.
:return: True if the list was cleared, False if the list does not exist. :return: True if the list was cleared, False if the list does not exist.
Example: Example::
::
prof.settings_string_list_clear("myplugin", "items") prof.settings_string_list_clear("myplugin", "items")
""" """
pass pass
@@ -741,9 +786,10 @@ def settings_int_get(group: str, key: str, default: int) -> int:
:param default: The default value if the setting is not found. :param default: The default value if the setting is not found.
:return: The setting value, or the default if not found. :return: The setting value, or the default if not found.
Example: Example::
::
timeout = prof.settings_int_get("myplugin", "timeout", 10) timeout = prof.settings_int_get("myplugin", "timeout", 10)
""" """
pass pass
@@ -757,9 +803,10 @@ def settings_int_set(group: str, key: str, value: int) -> None:
:param value: The integer value to set. :param value: The integer value to set.
:return: None :return: None
Example: Example::
::
prof.settings_int_set("myplugin", "timeout", 100) prof.settings_int_set("myplugin", "timeout", 100)
""" """
pass pass
@@ -771,11 +818,12 @@ def get_current_recipient() -> str | None:
:return: The Jabber ID of the recipient (e.g., ``bob@example.com``), or None if not in a chat window. :return: The Jabber ID of the recipient (e.g., ``bob@example.com``), or None if not in a chat window.
Example: Example::
::
recipient = prof.get_current_recipient() recipient = prof.get_current_recipient()
if recipient: if recipient:
prof.cons_show(f"Chatting with: {recipient}") prof.cons_show(f"Chatting with: {recipient}")
""" """
pass pass
@@ -784,11 +832,12 @@ def get_current_muc() -> str | None:
:return: The Jabber ID of the room (e.g., ``chat@conference.example.com``), or None if not in a chat room window. :return: The Jabber ID of the room (e.g., ``chat@conference.example.com``), or None if not in a chat room window.
Example: Example::
::
room = prof.get_current_muc() room = prof.get_current_muc()
if room: if room:
prof.cons_show(f"In room: {room}") prof.cons_show(f"In room: {room}")
""" """
pass pass
@@ -797,11 +846,12 @@ def get_current_nick() -> str | None:
:return: The user's nickname (e.g., ``alice``), or None if not in a chat room window. :return: The user's nickname (e.g., ``alice``), or None if not in a chat room window.
Example: Example::
::
nick = prof.get_current_nick() nick = prof.get_current_nick()
if nick: if nick:
prof.cons_show(f"Nickname: {nick}") prof.cons_show(f"Nickname: {nick}")
""" """
pass pass
@@ -811,10 +861,11 @@ def get_name_from_roster(barejid: str) -> str:
:param barejid: The Jabber ID to look up (e.g., ``bob@example.com``). :param barejid: The Jabber ID to look up (e.g., ``bob@example.com``).
:return: The nickname from the roster, or the input barejid if not found. :return: The nickname from the roster, or the input barejid if not found.
Example: Example::
::
name = prof.get_name_from_roster("bob@example.com") name = prof.get_name_from_roster("bob@example.com")
prof.cons_show(f"Name: {name}") prof.cons_show(f"Name: {name}")
""" """
pass pass
@@ -824,11 +875,12 @@ def get_barejid_from_roster(name: str) -> str | None:
:param name: The nickname to look up. :param name: The nickname to look up.
:return: The Jabber ID (e.g., ``bob@example.com``), or None if the nickname is not in the roster. :return: The Jabber ID (e.g., ``bob@example.com``), or None if the nickname is not in the roster.
Example: Example::
::
jid = prof.get_barejid_from_roster("bob") jid = prof.get_barejid_from_roster("bob")
if jid: if jid:
prof.cons_show(f"JID: {jid}") prof.cons_show(f"JID: {jid}")
""" """
pass pass
@@ -837,10 +889,11 @@ def get_current_occupants() -> list[str]:
:return: List of occupant nicknames, or an empty list if not in a chat room window. :return: List of occupant nicknames, or an empty list if not in a chat room window.
Example: Example::
::
occupants = prof.get_current_occupants() occupants = prof.get_current_occupants()
prof.cons_show(f"Occupants: {', '.join(occupants)}") prof.cons_show(f"Occupants: {', '.join(occupants)}")
""" """
pass pass
@@ -850,10 +903,11 @@ def get_room_nick(barejid: str) -> str:
:param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
:return: The user's nickname in the room. :return: The user's nickname in the room.
Example: Example::
::
nick = prof.get_room_nick("chat@conference.example.com") nick = prof.get_room_nick("chat@conference.example.com")
prof.cons_show(f"Room nick: {nick}") prof.cons_show(f"Room nick: {nick}")
""" """
pass pass
@@ -862,10 +916,11 @@ def current_win_is_console() -> bool:
:return: True if the console window is focused, False otherwise. :return: True if the console window is focused, False otherwise.
Example: Example::
::
if prof.current_win_is_console(): if prof.current_win_is_console():
prof.cons_show("Console is focused") prof.cons_show("Console is focused")
""" """
pass pass
@@ -880,9 +935,10 @@ def notify(message: str, timeout: int, category: str) -> None:
:param category: The notification category, displayed with the message. :param category: The notification category, displayed with the message.
:return: None :return: None
Example: Example::
::
prof.notify("New message received", 5000, "MyPlugin") prof.notify("New message received", 5000, "MyPlugin")
""" """
pass pass
@@ -892,9 +948,10 @@ def log_debug(message: str) -> None:
:param message: The message to log. :param message: The message to log.
:return: None :return: None
Example: Example::
::
prof.log_debug("Debugging plugin initialization") prof.log_debug("Debugging plugin initialization")
""" """
pass pass
@@ -904,9 +961,10 @@ def log_info(message: str) -> None:
:param message: The message to log. :param message: The message to log.
:return: None :return: None
Example: Example::
::
prof.log_info("Plugin started successfully") prof.log_info("Plugin started successfully")
""" """
pass pass
@@ -916,9 +974,10 @@ def log_warning(message: str) -> None:
:param message: The message to log. :param message: The message to log.
:return: None :return: None
Example: Example::
::
prof.log_warning("Configuration issue detected") prof.log_warning("Configuration issue detected")
""" """
pass pass
@@ -928,8 +987,9 @@ def log_error(message: str) -> None:
:param message: The message to log. :param message: The message to log.
:return: None :return: None
Example: Example::
::
prof.log_error("Failed to connect to server") prof.log_error("Failed to connect to server")
""" """
pass pass