From c94263486f69111d904864538c9cd8b02c2bdc5a Mon Sep 17 00:00:00 2001 From: Jabber Developer Date: Wed, 17 Sep 2025 00:34:37 +0200 Subject: [PATCH] docs(python): fix formatting to ensure correct parsing Fixes issues introduced in 052e168, 4cdcf9a, and other commits from PR #31. --- apidocs/python/src/plugin.py | 340 ++++-------- apidocs/python/src/prof.py | 964 +++++++++++++---------------------- 2 files changed, 441 insertions(+), 863 deletions(-) diff --git a/apidocs/python/src/plugin.py b/apidocs/python/src/plugin.py index 59f07328..b393622a 100644 --- a/apidocs/python/src/plugin.py +++ b/apidocs/python/src/plugin.py @@ -3,12 +3,14 @@ The plugin module defines optional callback functions that CProof plugins can implement to handle events such as startup, shutdown, message processing, and presence updates. -:: - - import prof - All functions are optional and are called by CProof when the corresponding event -occurs. String parameters and return values are Python 3 str types. +occurs. You need to define them in your module and they will automatically be used +for callback events. + +To utilize full functionality, such as the ``prof.cons_show`` function, see ``prof`` +documentation and use: + :: + import prof """ # Initialization and Lifecycle @@ -20,19 +22,14 @@ def prof_init(version: str, status: str, account_name: str | None, fulljid: str Called when CProof starts or when the plugin is loaded via the ``/plugins load`` or ``/plugins install`` commands. - Args: - version: The version of CProof (e.g., ``"1.0.0"``). - status: The package status of CProof (``"development"`` or ``"release"``). - account_name: The account name of the logged-in user, or None if not logged in. - fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in. - - Returns: - None + :param version: The version of CProof (e.g., ``"1.0.0"``). + :param status: The package status of CProof (``"development"`` or ``"release"``). + :param account_name: The account name 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 Example: - :: - 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}") """ @@ -43,16 +40,10 @@ def prof_on_start() -> None: Use this to perform setup tasks that should occur at application startup. - Args: - None - - Returns: - None + :return: None Example: - :: - def prof_on_start() -> None: prof.cons_show("CProof has started...") """ @@ -63,16 +54,10 @@ def prof_on_shutdown() -> None: Use this to perform cleanup tasks before the application exits. - Args: - None - - Returns: - None + :return: None Example: - :: - def prof_on_shutdown() -> None: prof.cons_show("CProof is shutting down...") """ @@ -83,16 +68,10 @@ def prof_on_unload() -> None: Use this to clean up plugin-specific resources. - Args: - None - - Returns: - None + :return: None Example: - :: - def prof_on_unload() -> None: prof.cons_show("Plugin unloaded") """ @@ -101,17 +80,12 @@ def prof_on_unload() -> None: def prof_on_connect(account_name: str, fulljid: str) -> None: """Called when a user connects to CProof with an account. - Args: - account_name: The account name used for login. - fulljid: The full Jabber ID (barejid/resource) of the connected account. - - Returns: - None + :param account_name: The account name used for login. + :param fulljid: The full Jabber ID (barejid/resource) of the connected account. + :return: None Example: - :: - def prof_on_connect(account_name: str, fulljid: str) -> None: prof.cons_show(f"Connected as {account_name} ({fulljid})") """ @@ -120,17 +94,12 @@ def prof_on_connect(account_name: str, fulljid: str) -> None: def prof_on_disconnect(account_name: str, fulljid: str) -> None: """Called when a user disconnects an account from CProof. - Args: - account_name: The account name being disconnected. - fulljid: The full Jabber ID (barejid/resource) of the disconnected account. - - Returns: - None + :param account_name: The account name being disconnected. + :param fulljid: The full Jabber ID (barejid/resource) of the disconnected account. + :return: None Example: - :: - def prof_on_disconnect(account_name: str, fulljid: str) -> None: prof.cons_show(f"Disconnected {account_name} ({fulljid})") """ @@ -144,18 +113,13 @@ def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> Allows the plugin to modify or cancel the message display. - Args: - barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). - resource: The sender's resource (e.g., ``laptop``). - message: The received message. - - Returns: - str | None: The modified message to display, or None to preserve the original. + :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). + :param resource: The sender's resource (e.g., ``laptop``). + :param message: The received message. + :return: The modified message to display, or None to preserve the original. Example: - :: - def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None: new_message = f"{message} (from {barejid})" return new_message @@ -167,18 +131,13 @@ def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> Use this to perform actions after the message is shown. - Args: - barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). - resource: The sender's resource (e.g., ``laptop``). - message: The displayed message. - - Returns: - None + :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). + :param resource: The sender's resource (e.g., ``laptop``). + :param message: The displayed message. + :return: None Example: - :: - def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None: prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}") """ @@ -189,17 +148,12 @@ def prof_pre_chat_message_send(barejid: str, message: str) -> str | None: Allows the plugin to modify or cancel the message. - Args: - barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). - message: The message to be sent. - - Returns: - str | None: The modified message to send, or None to cancel sending. + :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + :param message: The message to be sent. + :return: The modified message to send, or None to cancel sending. Example: - :: - def prof_pre_chat_message_send(barejid: str, message: str) -> str | None: return f"{message} (sent by plugin)" """ @@ -210,17 +164,12 @@ def prof_post_chat_message_send(barejid: str, message: str) -> None: Use this to log or react to sent messages. - Args: - barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). - message: The sent message. - - Returns: - None + :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + :param message: The sent message. + :return: None Example: - :: - def prof_post_chat_message_send(barejid: str, message: str) -> None: prof.cons_show(f"Sent to {barejid}: {message}") """ @@ -234,18 +183,13 @@ def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str Allows the plugin to modify or cancel the message display. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message sender. - message: The received message. - - Returns: - str | None: The modified message to display, or None to preserve the original. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The received message. + :return: The modified message to display, or None to preserve the original. Example: - :: - def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None: return f"{message} (from {nick})" """ @@ -256,18 +200,13 @@ def prof_post_room_message_display(barejid: str, nick: str, message: str) -> Non Use this to perform actions after the message is shown. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message sender. - message: The displayed message. - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The displayed message. + :return: None Example: - :: - def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None: prof.cons_show(f"Displayed in {barejid} from {nick}: {message}") """ @@ -278,17 +217,12 @@ def prof_pre_room_message_send(barejid: str, message: str) -> str | None: Allows the plugin to modify or cancel the message. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - message: The message to be sent. - - Returns: - str | None: The modified message to send, or None to cancel sending. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param message: The message to be sent. + :return: The modified message to send, or None to cancel sending. Example: - :: - def prof_pre_room_message_send(barejid: str, message: str) -> str | None: return f"{message} (sent by plugin)" """ @@ -299,17 +233,12 @@ def prof_post_room_message_send(barejid: str, message: str) -> None: Use this to log or react to sent messages. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - message: The sent message. - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param message: The sent message. + :return: None Example: - :: - def prof_post_room_message_send(barejid: str, message: str) -> None: prof.cons_show(f"Sent to {barejid}: {message}") """ @@ -318,19 +247,14 @@ def prof_post_room_message_send(barejid: str, message: str) -> None: def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None: """Called when a chat room history message is received from the server. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message sender. - message: The received message. - timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``). - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The received message. + :param timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``). + :return: None Example: - :: - 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}") """ @@ -344,18 +268,13 @@ def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str Allows the plugin to modify or cancel the message display. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message sender. - message: The received message. - - Returns: - str | None: The modified message to display, or None to preserve the original. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The received message. + :return: The modified message to display, or None to preserve the original. Example: - :: - def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None: return f"{message} (private from {nick})" """ @@ -366,18 +285,13 @@ def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> Non Use this to perform actions after the message is shown. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message sender. - message: The displayed message. - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The displayed message. + :return: None Example: - :: - def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None: prof.cons_show(f"Displayed private in {barejid} from {nick}: {message}") """ @@ -388,18 +302,13 @@ def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | N Allows the plugin to modify or cancel the message. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message recipient. - message: The message to be sent. - - Returns: - str | None: The modified message to send, or None to cancel sending. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message recipient. + :param message: The message to be sent. + :return: The modified message to send, or None to cancel sending. Example: - :: - def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None: return f"{message} (private to {nick})" """ @@ -410,18 +319,13 @@ def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None: Use this to log or react to sent messages. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message recipient. - message: The sent message. - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message recipient. + :param message: The sent message. + :return: None Example: - :: - def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None: prof.cons_show(f"Sent private to {nick} in {barejid}: {message}") """ @@ -435,16 +339,11 @@ def prof_on_message_stanza_send(stanza: str) -> str | None: Allows the plugin to modify or cancel the stanza. - Args: - stanza: The XMPP message stanza to send. - - Returns: - str | None: The modified stanza to send, or None to preserve the original. + :param stanza: The XMPP message stanza to send. + :return: The modified stanza to send, or None to preserve the original. Example: - :: - def prof_on_message_stanza_send(stanza: str) -> str | None: prof.cons_show(f"Sending message stanza: {stanza}") return stanza @@ -456,16 +355,11 @@ def prof_on_message_stanza_receive(stanza: str) -> bool: Allows the plugin to control whether CProof processes the stanza. - Args: - stanza: The received XMPP message stanza. - - Returns: - bool: True to allow CProof to process the stanza, False to block processing. + :param stanza: The received XMPP message stanza. + :return: True to allow CProof to process the stanza, False to block processing. Example: - :: - def prof_on_message_stanza_receive(stanza: str) -> bool: prof.cons_show(f"Received message stanza: {stanza}") return True @@ -477,16 +371,11 @@ def prof_on_presence_stanza_send(stanza: str) -> str | None: Allows the plugin to modify or cancel the stanza. - Args: - stanza: The XMPP presence stanza to send. - - Returns: - str | None: The modified stanza to send, or None to preserve the original. + :param stanza: The XMPP presence stanza to send. + :return: The modified stanza to send, or None to preserve the original. Example: - :: - def prof_on_presence_stanza_send(stanza: str) -> str | None: prof.cons_show(f"Sending presence stanza: {stanza}") return stanza @@ -498,16 +387,11 @@ def prof_on_presence_stanza_receive(stanza: str) -> bool: Allows the plugin to control whether CProof processes the stanza. - Args: - stanza: The received XMPP presence stanza. - - Returns: - bool: True to allow CProof to process the stanza, False to block processing. + :param stanza: The received XMPP presence stanza. + :return: True to allow CProof to process the stanza, False to block processing. Example: - :: - def prof_on_presence_stanza_receive(stanza: str) -> bool: prof.cons_show(f"Received presence stanza: {stanza}") return True @@ -519,16 +403,11 @@ def prof_on_iq_stanza_send(stanza: str) -> str | None: Allows the plugin to modify or cancel the stanza. - Args: - stanza: The XMPP IQ stanza to send. - - Returns: - str | None: The modified stanza to send, or None to preserve the original. + :param stanza: The XMPP IQ stanza to send. + :return: The modified stanza to send, or None to preserve the original. Example: - :: - def prof_on_iq_stanza_send(stanza: str) -> str | None: prof.cons_show(f"Sending IQ stanza: {stanza}") return stanza @@ -540,16 +419,11 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool: Allows the plugin to control whether CProof processes the stanza. - Args: - stanza: The received XMPP IQ stanza. - - Returns: - bool: True to allow CProof to process the stanza, False to block processing. + :param stanza: The received XMPP IQ stanza. + :return: True to allow CProof to process the stanza, False to block processing. Example: - :: - def prof_on_iq_stanza_receive(stanza: str) -> bool: prof.cons_show(f"Received IQ stanza: {stanza}") return True @@ -562,18 +436,13 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool: def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None: """Called when a contact goes offline. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - resource: The resource being disconnected (e.g., ``laptop``). - status: The status message received with the offline presence, or None. - - Returns: - None + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param resource: The resource being disconnected (e.g., ``laptop``). + :param status: The status message received with the offline presence, or None. + :return: None Example: - :: - 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'}") """ @@ -582,20 +451,15 @@ def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None: """Called when a presence notification is received from a contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - resource: The resource of the contact (e.g., ``laptop``). - presence: The contact's presence (``"chat"``, ``"online"``, ``"away"``, ``"xa"``, or ``"dnd"``). - status: The status message received with the presence, or None. - priority: The priority associated with the resource. - - Returns: - None + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param resource: The resource of the contact (e.g., ``laptop``). + :param presence: The contact's presence (``"chat"``, ``"online"``, ``"away"``, ``"xa"``, or ``"dnd"``). + :param status: The status message received with the presence, or None. + :param priority: The priority associated with the resource. + :return: None Example: - :: - 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") """ @@ -607,16 +471,11 @@ def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: def prof_on_chat_win_focus(barejid: str) -> None: """Called when a chat window is focused. - Args: - barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``). - - Returns: - None + :param barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``). + :return: None Example: - :: - def prof_on_chat_win_focus(barejid: str) -> None: prof.cons_show(f"Focused chat window for {barejid}") """ @@ -625,17 +484,12 @@ def prof_on_chat_win_focus(barejid: str) -> None: def prof_on_room_win_focus(barejid: str) -> None: """Called when a chat room window is focused. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :return: None Example: - :: - def prof_on_room_win_focus(barejid: str) -> None: prof.cons_show(f"Focused room window for {barejid}") """ - pass + pass \ No newline at end of file diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index 1902faaf..d42168ee 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -3,27 +3,54 @@ The prof module provides a Python API for plugins to interact with CProof. Plugins must import this module to access its functions: :: - import prof Functions are grouped into sections for console interaction, command management, autocompletion, window management, chat and room messaging, XMPP operations, settings, user/room information, and notifications/logging. """ + from typing import Protocol # Callback Protocols # ----------------- class CommandCallback(Protocol): - """Protocol for command callbacks accepting variable string arguments.""" + """Protocol for command callbacks accepting variable string arguments. + + :param command_parameters: Variable string arguments passed to the callback. + :return: None + + Example: + :: + def my_command(*command_parameters: str) -> None: + prof.cons_show(f"Received: {command_parameters}") + """ def __call__(self, *command_parameters: str) -> None: ... class TimedCallback(Protocol): - """Protocol for timed callbacks accepting no arguments.""" + """Protocol for timed callbacks accepting no arguments. + + :return: None + + Example: + :: + def my_timed_callback() -> None: + prof.cons_show("Timer triggered") + """ def __call__(self) -> None: ... class WindowCallback(Protocol): - """Protocol for window callbacks accepting a window ID and message.""" + """Protocol for window callbacks accepting a window ID and message. + + :param win_id: The window tag identifying the plugin window. + :param message: The message to process. + :return: None + + Example: + :: + def my_window_callback(win_id: str, message: str) -> None: + prof.win_show(win_id, f"Processed: {message}") + """ def __call__(self, win_id: str, message: str) -> None: ... # Console Functions @@ -32,34 +59,23 @@ class WindowCallback(Protocol): def cons_alert() -> None: """Highlights the console window in the CProof status bar to indicate activity. - Args: - None - - Returns: - None + :return: None Example: - - :: - - prof.cons_alert() # Highlights the console window + :: + prof.cons_alert() # Highlights the console window """ pass def cons_show(message: str) -> None: """Displays a message in the CProof console window. - Args: - message: The message to display. - - Returns: - None + :param message: The message to display. + :return: None Example: - - :: - - prof.cons_show("This appears in the console window") + :: + prof.cons_show("This appears in the console window") """ pass @@ -69,37 +85,27 @@ def cons_show_themed(group: str | None, key: str | None, default: str | None, me Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is not found, the default color is used. - Args: - group: The theme group name, or None to use default styling. - key: The item name within the group, or None to use default styling. - default: The default color if the theme is not found, or None for no color. - message: The message to display. - - Returns: - None + :param group: The theme group name, or None to use default styling. + :param key: The item name within the group, or None to use default styling. + :param default: The default color if the theme is not found, or None for no color. + :param message: The message to display. + :return: None Example: - - :: - - prof.cons_show_themed("myplugin", "text", "white", "Themed message") + :: + prof.cons_show_themed("myplugin", "text", "white", "Themed message") """ pass def cons_bad_cmd_usage(command: str) -> None: """Displays an error message in the console for incorrect command usage. - Args: - command: The command name, including the leading slash (e.g., ``/say``). - - Returns: - None + :param command: The command name, including the leading slash (e.g., ``/say``). + :return: None Example: - - :: - - prof.cons_bad_cmd_usage("/mycommand") # Shows usage error for /mycommand + :: + prof.cons_bad_cmd_usage("/mycommand") # Shows usage error for /mycommand """ pass @@ -122,42 +128,37 @@ def register_command( the command is invoked. The callback function accepts variable string arguments representing the command parameters. - Args: - name: The command name, including the leading slash (e.g., ``/say``). - min_args: Minimum number of arguments required. - max_args: Maximum number of arguments allowed. - synopsis: List of command usage strings. - description: Short description of the command. - arguments: List of [argument, description] pairs for help text. - examples: List of example command invocations. - callback: Function to call when the command is executed, taking variable string arguments. - - Returns: - None + :param name: The command name, including the leading slash (e.g., ``/say``). + :param min_args: Minimum number of arguments required. + :param max_args: Maximum number of arguments allowed. + :param synopsis: List of command usage strings. + :param description: Short description of the command. + :param arguments: List of [argument, description] pairs for help text. + :param examples: List of example command invocations. + :param callback: Function to call when the command is executed, taking variable string arguments. + :return: None Example: + :: + def command_handler(*args: str) -> None: + prof.cons_show(f"Received: {args}") + if len(args) == 1 and args[0] in ("on", "off"): + prof.cons_show(f"{args[0].capitalize()}ing something") + elif len(args) == 2 and args[0] == "print": + prof.cons_show(args[1]) + else: + prof.cons_bad_cmd_usage("/new_command") - :: - - def command_handler(*args: str) -> None: - prof.cons_show(f"Received: {args}") - if len(args) == 1 and args[0] in ("on", "off"): - prof.cons_show(f"{args[0].capitalize()}ing something") - elif len(args) == 2 and args[0] == "print": - prof.cons_show(args[1]) - else: - prof.cons_bad_cmd_usage("/new_command") - - synopsis = ["/new_command on|off", "/new_command print "] - description = "Enables, disables, or prints an argument." - arguments = [ - ["on|off", "Enable or disable something."], - ["print ", "Print the argument."] - ] - examples = ["/new_command on", "/new_command print 'test'"] - prof.register_command( - "/new_command", 1, 2, synopsis, description, arguments, examples, command_handler - ) + synopsis = ["/new_command on|off", "/new_command print "] + description = "Enables, disables, or prints an argument." + arguments = [ + ["on|off", "Enable or disable something."], + ["print ", "Print the argument."] + ] + examples = ["/new_command on", "/new_command print 'test'"] + prof.register_command( + "/new_command", 1, 2, synopsis, description, arguments, examples, command_handler + ) """ pass @@ -167,21 +168,16 @@ def register_command( def register_timed(callback: TimedCallback, interval: int) -> None: """Registers a function to be called periodically by CProof. - Args: - callback: The function to call periodically. - interval: The time between calls, in seconds. - - Returns: - None + :param callback: The function to call periodically. + :param interval: The time between calls, in seconds. + :return: None Example: + :: + def periodic_task() -> None: + prof.cons_show("Periodic update") - :: - - def periodic_task() -> None: - 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 @@ -194,71 +190,51 @@ def completer_add(key: str, items: list[str]) -> None: If the key already exists, the items are appended to the existing autocomplete list. - Args: - key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or ``/mycommand action``). - items: The items to return on autocompletion. - - Returns: - None + :param key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or ``/mycommand action``). + :param items: The items to return on autocompletion. + :return: None Example: - - :: - - prof.completer_add("/mycommand", ["action1", "action2"]) - prof.completer_add("/mycommand dosomething", ["thing1", "thing2"]) + :: + prof.completer_add("/mycommand", ["action1", "action2"]) + prof.completer_add("/mycommand dosomething", ["thing1", "thing2"]) """ pass def completer_remove(key: str, items: list[str]) -> None: """Removes values from autocompletion for a command or command argument. - Args: - key: The prefix from which to remove autocomplete items (e.g., ``/mycommand``). - items: The items to remove from the autocomplete list. - - Returns: - None + :param key: The prefix from which to remove autocomplete items (e.g., ``/mycommand``). + :param items: The items to remove from the autocomplete list. + :return: None Example: - - :: - - prof.completer_remove("/mycommand", ["action1", "action2"]) + :: + prof.completer_remove("/mycommand", ["action1", "action2"]) """ pass def completer_clear(key: str) -> None: """Clears all autocomplete values for a command or command argument. - Args: - key: The prefix to clear autocomplete items for (e.g., ``/mycommand``). - - Returns: - None + :param key: The prefix to clear autocomplete items for (e.g., ``/mycommand``). + :return: None Example: - - :: - - prof.completer_clear("/mycommand") + :: + prof.completer_clear("/mycommand") """ pass def filepath_completer_add(prefix: str) -> None: """Enables filepath autocompletion for a command or command argument. - Args: - prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``). - - Returns: - None + :param prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``). + :return: None Example: - - :: - - prof.filepath_completer_add("/filecmd") # Enables filepath completion + :: + prof.filepath_completer_add("/filecmd") # Enables filepath completion """ pass @@ -268,18 +244,13 @@ def filepath_completer_add(prefix: str) -> None: def win_exists(tag: str) -> bool: """Checks if a plugin window with the specified tag exists. - Args: - tag: The tag identifying the plugin window. - - Returns: - bool: True if the window exists, False otherwise. + :param tag: The tag identifying the plugin window. + :return: True if the window exists, False otherwise. Example: - - :: - - if prof.win_exists("MyPlugin"): - prof.cons_show("Window exists") + :: + if prof.win_exists("MyPlugin"): + prof.cons_show("Window exists") """ pass @@ -289,56 +260,41 @@ def win_create(tag: str, callback: WindowCallback) -> None: The callback processes input messages, typically using the model from the window title, and is called with the window tag and message. - Args: - tag: The tag identifying the plugin window. - callback: Function to process window input, taking the window tag and message. - - Returns: - None + :param tag: The tag identifying the plugin window. + :param callback: Function to process window input, taking the window tag and message. + :return: None Example: + :: + def handler(win_id: str, message: str) -> None: + prof.win_show(win_id, f"Processed: {message}") - :: - - def handler(win_id: str, message: str) -> None: - prof.win_show(win_id, f"Processed: {message}") - - prof.win_create("MyPlugin", handler) + prof.win_create("MyPlugin", handler) """ pass def win_focus(tag: str) -> None: """Focuses the plugin window with the specified tag. - Args: - tag: The tag identifying the plugin window. - - Returns: - None + :param tag: The tag identifying the plugin window. + :return: None Example: - - :: - - prof.win_focus("MyPlugin") # Focuses the MyPlugin window + :: + prof.win_focus("MyPlugin") # Focuses the MyPlugin window """ pass def win_show(tag: str, message: str) -> None: """Displays a message in the plugin window with the specified tag. - Args: - tag: The tag identifying the plugin window. - message: The message to display. - - Returns: - None + :param tag: The tag identifying the plugin window. + :param message: The message to display. + :return: None Example: - - :: - - prof.win_show("MyPlugin", "Message in plugin window") + :: + prof.win_show("MyPlugin", "Message in plugin window") """ pass @@ -348,21 +304,16 @@ def win_show_themed(tag: str, group: str | None, key: str | None, default: str | Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is not found, the default color is used. - Args: - tag: The tag identifying the plugin window. - group: The theme group name, or None to use default styling. - key: The item name within the group, or None to use default styling. - default: The default color if the theme is not found, or None for no color. - message: The message to display. - - Returns: - None + :param tag: The tag identifying the plugin window. + :param group: The theme group name, or None to use default styling. + :param key: The item name within the group, or None to use default styling. + :param default: The default color if the theme is not found, or None for no color. + :param message: The message to display. + :return: None Example: - - :: - - prof.win_show_themed("MyPlugin", "myplugin", "text", "white", "Themed message") + :: + prof.win_show_themed("MyPlugin", "myplugin", "text", "white", "Themed message") """ pass @@ -372,20 +323,14 @@ def win_show_themed(tag: str, group: str | None, key: str | None, default: str | def chat_show(barejid: str, message: str) -> bool: """Displays a message in the chat window for the specified contact. - Args: - barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). - message: The message to display. - - Returns: - bool: True if the message was displayed, False if the chat window does not - exist. + :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + :param message: The message to display. + :return: True if the message was displayed, False if the chat window does not exist. Example: - - :: - - if prof.chat_show("bob@example.com", "Hello from plugin"): - prof.cons_show("Message displayed") + :: + if prof.chat_show("bob@example.com", "Hello from plugin"): + prof.cons_show("Message displayed") """ pass @@ -402,42 +347,30 @@ def chat_show_themed( Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is not found, the default color is used. - Args: - barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). - group: The theme group name, or None to use default styling. - key: The item name within the group, or None to use default styling. - default: The default color if the theme is not found, or None for no color. - ch: The prefix character to display, or None for default behavior. - message: The message to display. - - Returns: - bool: True if the message was displayed, False if the chat window does not - exist. + :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + :param group: The theme group name, or None to use default styling. + :param key: The item name within the group, or None to use default styling. + :param default: The default color if the theme is not found, or None for no color. + :param ch: The prefix character to display, or None for default behavior. + :param message: The message to display. + :return: True if the message was displayed, False if the chat window does not exist. 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 def room_show(roomjid: str, message: str) -> bool: """Displays a message in the chat room window for the specified room. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - message: The message to display. - - Returns: - bool: True if the message was displayed, False if the room window does not - exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param message: The message to display. + :return: True if the message was displayed, False if the room window does not exist. Example: - - :: - - prof.room_show("chat@conference.example.com", "Room message from plugin") + :: + prof.room_show("chat@conference.example.com", "Room message from plugin") """ pass @@ -454,23 +387,17 @@ def room_show_themed( Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is not found, the default color is used. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - group: The theme group name, or None to use default styling. - key: The item name within the group, or None to use default styling. - default: The default color if the theme is not found, or None for no color. - ch: The prefix character to display, or None for default behavior. - message: The message to display. - - Returns: - bool: True if the message was displayed, False if the room window does not - exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param group: The theme group name, or None to use default styling. + :param key: The item name within the group, or None to use default styling. + :param default: The default color if the theme is not found, or None for no color. + :param ch: The prefix character to display, or None for default behavior. + :param message: The message to display. + :return: True if the message was displayed, False if the room window does not exist. 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 @@ -480,16 +407,11 @@ def room_show_themed( def send_line(line: str) -> None: """Sends a line of input to CProof for execution, as if typed by the user. - Args: - line: The input line to execute (e.g., ``/who online``). - - Returns: - None + :param line: The input line to execute (e.g., ``/who online``). + :return: None Example: - :: - prof.send_line("/who online") # Executes the /who online command """ pass @@ -497,39 +419,28 @@ def send_line(line: str) -> None: def send_stanza(stanza: str) -> bool: """Sends an XMPP stanza to the server. - Args: - stanza: The XMPP stanza to send (e.g., an IQ or message stanza). - - Returns: - bool: True if the stanza was sent successfully, False if it was invalid or - failed to send. + :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. Example: - - :: - - stanza = "" - if prof.send_stanza(stanza): - prof.cons_show("Stanza sent successfully") + :: + stanza = "" + if prof.send_stanza(stanza): + prof.cons_show("Stanza sent successfully") """ pass def incoming_message(barejid: str, resource: str, message: str) -> None: """Triggers CProof to handle an incoming message as if received from a contact. - Args: - barejid: The Jabber ID of the sender (e.g., ``bob@example.com``). - resource: The sender's resource (e.g., ``laptop``). - message: The message text. - - Returns: - None + :param barejid: The Jabber ID of the sender (e.g., ``bob@example.com``). + :param resource: The sender's resource (e.g., ``laptop``). + :param message: The message text. + :return: None Example: - - :: - - prof.incoming_message("bob@example.com", "laptop", "Hello from plugin") + :: + prof.incoming_message("bob@example.com", "laptop", "Hello from plugin") """ pass @@ -539,52 +450,37 @@ def disco_add_feature(feature: str) -> None: If a session is active, a presence update is sent to refresh client/server feature caches. - Args: - feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``). - - Returns: - None + :param feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``). + :return: None Example: - - :: - - prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify") + :: + prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify") """ pass def encryption_reset(barejid: str) -> None: """Ends any encrypted session with the specified contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``alice@example.com``). - - Returns: - None + :param barejid: The Jabber ID of the contact (e.g., ``alice@example.com``). + :return: None Example: - - :: - - prof.encryption_reset("alice@example.com") # Resets encryption + :: + prof.encryption_reset("alice@example.com") # Resets encryption """ pass def chat_set_titlebar_enctext(barejid: str, enctext: str) -> bool: """Sets the encryption indicator text in the titlebar for a contact's chat window. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - enctext: The text to display in the titlebar. - - Returns: - bool: True if the text was set, False if the chat window does not exist. + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param enctext: The text to display in the titlebar. + :return: True if the text was set, False if the chat window does not exist. Example: - - :: - - prof.chat_set_titlebar_enctext("bob@example.com", "secure") + :: + prof.chat_set_titlebar_enctext("bob@example.com", "secure") """ pass @@ -593,34 +489,24 @@ def chat_unset_titlebar_enctext(barejid: str) -> bool: CProof will determine the default text to display. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - - Returns: - bool: True if the text was reset, False if the chat window does not exist. + :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. Example: - - :: - - prof.chat_unset_titlebar_enctext("bob@example.com") + :: + prof.chat_unset_titlebar_enctext("bob@example.com") """ pass def chat_set_incoming_char(barejid: str, ch: str) -> bool: """Sets the prefix character for incoming messages from a contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - ch: The prefix character to display. - - Returns: - bool: True if the character was set, False if the chat window does not exist. + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param ch: The prefix character to display. + :return: True if the character was set, False if the chat window does not exist. Example: - :: - prof.chat_set_incoming_char("bob@example.com", "*") """ pass @@ -628,70 +514,50 @@ def chat_set_incoming_char(barejid: str, ch: str) -> bool: def chat_unset_incoming_char(barejid: str) -> bool: """Resets the prefix character for incoming messages from a contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - - Returns: - bool: True if the character was reset, False if the chat window does not exist. + :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. Example: - - :: - - prof.chat_unset_incoming_char("bob@example.com") + :: + prof.chat_unset_incoming_char("bob@example.com") """ pass def chat_set_outgoing_char(barejid: str, ch: str) -> bool: """Sets the prefix character for outgoing messages to a contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - ch: The prefix character to display. - - Returns: - bool: True if the character was set, False if the chat window does not exist. + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param ch: The prefix character to display. + :return: True if the character was set, False if the chat window does not exist. Example: - - :: - - prof.chat_set_outgoing_char("bob@example.com", "+") + :: + prof.chat_set_outgoing_char("bob@example.com", "+") """ pass def chat_unset_outgoing_char(barejid: str) -> bool: """Resets the prefix character for outgoing messages to a contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - - Returns: - bool: True if the character was reset, False if the chat window does not exist. + :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. Example: - - :: - - prof.chat_unset_outgoing_char("bob@example.com") + :: + prof.chat_unset_outgoing_char("bob@example.com") """ pass def room_set_titlebar_enctext(roomjid: str, enctext: str) -> bool: """Sets the encryption indicator text in the titlebar for a room's chat window. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - enctext: The text to display in the titlebar. - - Returns: - bool: True if the text was set, False if the room window does not exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param enctext: The text to display in the titlebar. + :return: True if the text was set, False if the room window does not exist. Example: - - :: - - prof.room_set_titlebar_enctext("chat@conference.example.com", "secure") + :: + prof.room_set_titlebar_enctext("chat@conference.example.com", "secure") """ pass @@ -700,52 +566,37 @@ def room_unset_titlebar_enctext(roomjid: str) -> bool: CProof will determine the default text to display. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - - Returns: - bool: True if the text was reset, False if the room window does not exist. + :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. Example: - - :: - - prof.room_unset_titlebar_enctext("chat@conference.example.com") + :: + prof.room_unset_titlebar_enctext("chat@conference.example.com") """ pass def room_set_message_char(roomjid: str, ch: str) -> bool: """Sets the prefix character for messages in a chat room. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - ch: The prefix character to display. - - Returns: - bool: True if the character was set, False if the room window does not exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param ch: The prefix character to display. + :return: True if the character was set, False if the room window does not exist. Example: - - :: - - prof.room_set_message_char("chat@conference.example.com", "^") + :: + prof.room_set_message_char("chat@conference.example.com", "^") """ pass def room_unset_message_char(roomjid: str) -> bool: """Resets the prefix character for messages in a chat room. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - - Returns: - bool: True if the character was reset, False if the room window does not exist. + :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. Example: - - :: - - prof.room_unset_message_char("chat@conference.example.com") + :: + prof.room_unset_message_char("chat@conference.example.com") """ pass @@ -757,19 +608,14 @@ def settings_boolean_get(group: str, key: str, default: bool) -> bool: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - default: The default value if the setting is not found. - - Returns: - bool: The setting value, or the default if not found. + :param group: The group name in the settings file. + :param key: The item name within the group. + :param default: The default value if the setting is not found. + :return: The setting value, or the default if not found. Example: - - :: - - notify = prof.settings_boolean_get("myplugin", "notify", False) + :: + notify = prof.settings_boolean_get("myplugin", "notify", False) """ pass @@ -778,18 +624,13 @@ def settings_boolean_set(group: str, key: str, value: bool) -> None: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The boolean value to set. - - Returns: - None + :param group: The group name in the settings file. + :param key: The item name within the group. + :param value: The boolean value to set. + :return: None Example: - :: - prof.settings_boolean_set("myplugin", "notify", True) """ pass @@ -799,19 +640,14 @@ def settings_string_get(group: str, key: str, default: str) -> str: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - default: The default value if the setting is not found. - - Returns: - str: The setting value, or the default if not found. + :param group: The group name in the settings file. + :param key: The item name within the group. + :param default: The default value if the setting is not found. + :return: The setting value, or the default if not found. Example: - - :: - - prefix = prof.settings_string_get("myplugin", "prefix", "myplugin>") + :: + prefix = prof.settings_string_get("myplugin", "prefix", "myplugin>") """ pass @@ -820,19 +656,14 @@ def settings_string_set(group: str, key: str, value: str) -> None: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The string value to set. - - Returns: - None + :param group: The group name in the settings file. + :param key: The item name within the group. + :param value: The string value to set. + :return: None Example: - - :: - - prof.settings_string_set("myplugin", "prefix", "myplugin>") + :: + prof.settings_string_set("myplugin", "prefix", "myplugin>") """ pass @@ -842,19 +673,13 @@ def settings_string_list_get(group: str, key: str) -> list[str]: Settings are stored in ``~/.local/share/cproof/plugin_settings``, with list items separated by semicolons. - Args: - group: The group name in the settings file. - key: The item name within the group. - - Returns: - list[str]: The list of strings, or an empty list if the setting does not - exist. + :param group: The group name in the settings file. + :param key: The item name within the group. + :return: List of strings, or an empty list if the setting does not exist. Example: - - :: - - items = prof.settings_string_list_get("myplugin", "items") + :: + items = prof.settings_string_list_get("myplugin", "items") """ pass @@ -864,19 +689,14 @@ def settings_string_list_add(group: str, key: str, value: str) -> None: If the list does not exist, it is created with the new item. Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The string to add to the list. - - Returns: - None + :param group: The group name in the settings file. + :param key: The item name within the group. + :param value: The string to add to the list. + :return: None Example: - - :: - - prof.settings_string_list_add("myplugin", "items", "item1") + :: + prof.settings_string_list_add("myplugin", "items", "item1") """ pass @@ -885,20 +705,14 @@ def settings_string_list_remove(group: str, key: str, value: str) -> bool: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The string to remove from the list. - - Returns: - bool: True if the item was removed or not in the list, False if the list - does not exist. + :param group: The group name in the settings file. + :param key: The item name within the group. + :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. Example: - - :: - - prof.settings_string_list_remove("myplugin", "items", "item1") + :: + prof.settings_string_list_remove("myplugin", "items", "item1") """ pass @@ -907,18 +721,13 @@ def settings_string_list_clear(group: str, key: str) -> bool: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - - Returns: - bool: True if the list was cleared, False if the list does not exist. + :param group: The group name in the settings file. + :param key: The item name within the group. + :return: True if the list was cleared, False if the list does not exist. Example: - - :: - - prof.settings_string_list_clear("myplugin", "items") + :: + prof.settings_string_list_clear("myplugin", "items") """ pass @@ -927,19 +736,14 @@ def settings_int_get(group: str, key: str, default: int) -> int: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - default: The default value if the setting is not found. - - Returns: - int: The setting value, or the default if not found. + :param group: The group name in the settings file. + :param key: The item name within the group. + :param default: The default value if the setting is not found. + :return: The setting value, or the default if not found. Example: - - :: - - timeout = prof.settings_int_get("myplugin", "timeout", 10) + :: + timeout = prof.settings_int_get("myplugin", "timeout", 10) """ pass @@ -948,19 +752,14 @@ def settings_int_set(group: str, key: str, value: int) -> None: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The integer value to set. - - Returns: - None + :param group: The group name in the settings file. + :param key: The item name within the group. + :param value: The integer value to set. + :return: None Example: - - :: - - prof.settings_int_set("myplugin", "timeout", 100) + :: + prof.settings_int_set("myplugin", "timeout", 100) """ pass @@ -970,153 +769,103 @@ def settings_int_set(group: str, key: str, value: int) -> None: def get_current_recipient() -> str | None: """Retrieves the Jabber ID of the current chat recipient. - Args: - None - - Returns: - str | None: 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: - - :: - - recipient = prof.get_current_recipient() - if recipient: - prof.cons_show(f"Chatting with: {recipient}") + :: + recipient = prof.get_current_recipient() + if recipient: + prof.cons_show(f"Chatting with: {recipient}") """ pass def get_current_muc() -> str | None: """Retrieves the Jabber ID of the current chat room. - Args: - None - - Returns: - str | None: 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: - - :: - - room = prof.get_current_muc() - if room: - prof.cons_show(f"In room: {room}") + :: + room = prof.get_current_muc() + if room: + prof.cons_show(f"In room: {room}") """ pass def get_current_nick() -> str | None: """Retrieves the user's nickname in the current chat room. - Args: - None - - Returns: - str | None: 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: - - :: - - nick = prof.get_current_nick() - if nick: - prof.cons_show(f"Nickname: {nick}") + :: + nick = prof.get_current_nick() + if nick: + prof.cons_show(f"Nickname: {nick}") """ pass def get_name_from_roster(barejid: str) -> str: """Retrieves the nickname for a Jabber ID from the roster. - Args: - barejid: The Jabber ID to look up (e.g., ``bob@example.com``). - - Returns: - str: The nickname from the roster, or the input barejid if not found. + :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. Example: - - :: - - name = prof.get_name_from_roster("bob@example.com") - prof.cons_show(f"Name: {name}") + :: + name = prof.get_name_from_roster("bob@example.com") + prof.cons_show(f"Name: {name}") """ pass def get_barejid_from_roster(name: str) -> str | None: """Retrieves the Jabber ID for a nickname from the roster. - Args: - name: The nickname to look up. - - Returns: - str | None: The Jabber ID (e.g., ``bob@example.com``), or None if the - nickname is not in the roster. + :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. Example: - - :: - - jid = prof.get_barejid_from_roster("bob") - if jid: - prof.cons_show(f"JID: {jid}") + :: + jid = prof.get_barejid_from_roster("bob") + if jid: + prof.cons_show(f"JID: {jid}") """ pass def get_current_occupants() -> list[str]: """Retrieves the nicknames of all occupants in the current chat room. - Args: - None - - Returns: - list[str]: 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: - - :: - - occupants = prof.get_current_occupants() - prof.cons_show(f"Occupants: {', '.join(occupants)}") + :: + occupants = prof.get_current_occupants() + prof.cons_show(f"Occupants: {', '.join(occupants)}") """ pass def get_room_nick(barejid: str) -> str: """Retrieves the user's nickname in the specified chat room. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - - Returns: - str: The user's nickname in the room. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :return: The user's nickname in the room. Example: - - :: - - nick = prof.get_room_nick("chat@conference.example.com") - prof.cons_show(f"Room nick: {nick}") + :: + nick = prof.get_room_nick("chat@conference.example.com") + prof.cons_show(f"Room nick: {nick}") """ pass def current_win_is_console() -> bool: """Checks if the console window is currently focused. - Args: - None - - Returns: - bool: True if the console window is focused, False otherwise. + :return: True if the console window is focused, False otherwise. Example: - - :: - - if prof.current_win_is_console(): - prof.cons_show("Console is focused") + :: + if prof.current_win_is_console(): + prof.cons_show("Console is focused") """ pass @@ -1126,86 +875,61 @@ def current_win_is_console() -> bool: def notify(message: str, timeout: int, category: str) -> None: """Sends a desktop notification through CProof. - Args: - message: The notification message to display. - timeout: The duration before the notification disappears, in milliseconds. - category: The notification category, displayed with the message. - - Returns: - None + :param message: The notification message to display. + :param timeout: The duration before the notification disappears, in milliseconds. + :param category: The notification category, displayed with the message. + :return: None Example: - - :: - - prof.notify("New message received", 5000, "MyPlugin") + :: + prof.notify("New message received", 5000, "MyPlugin") """ pass def log_debug(message: str) -> None: """Logs a message to the CProof log at the DEBUG level. - Args: - message: The message to log. - - Returns: - None + :param message: The message to log. + :return: None Example: - - :: - - prof.log_debug("Debugging plugin initialization") + :: + prof.log_debug("Debugging plugin initialization") """ pass def log_info(message: str) -> None: """Logs a message to the CProof log at the INFO level. - Args: - message: The message to log. - - Returns: - None + :param message: The message to log. + :return: None Example: - - :: - - prof.log_info("Plugin started successfully") + :: + prof.log_info("Plugin started successfully") """ pass def log_warning(message: str) -> None: """Logs a message to the CProof log at the WARNING level. - Args: - message: The message to log. - - Returns: - None + :param message: The message to log. + :return: None Example: - - :: - - prof.log_warning("Configuration issue detected") + :: + prof.log_warning("Configuration issue detected") """ pass def log_error(message: str) -> None: """Logs a message to the CProof log at the ERROR level. - Args: - message: The message to log. - - Returns: - None + :param message: The message to log. + :return: None Example: - - :: - - prof.log_error("Failed to connect to server") + :: + prof.log_error("Failed to connect to server") """ - pass + pass \ No newline at end of file