From 4cdcf9a8ebd61f38f4b3a4b4554f7c61d20f055b Mon Sep 17 00:00:00 2001 From: Jabber Developer Date: Mon, 15 Sep 2025 11:53:49 +0200 Subject: [PATCH] docs(plugin): update plugin.py to align with formatting required by Sphinx - Replace Profanity with CProof in all docstrings and examples. - Remove Python 2 and unicode references, using Python 3 str types. - Add type hints for all parameters and return types. - Use :: for code blocks with blank lines to fix Sphinx errors. - Improve wording for clarity and integrated examples into docstrings. - Organize functions into logical sections with RST comments. - Use double backticks for inline literals to resolve Sphinx warnings. --- apidocs/python/src/plugin.py | 707 ++++++++++++++++++++++++----------- 1 file changed, 494 insertions(+), 213 deletions(-) diff --git a/apidocs/python/src/plugin.py b/apidocs/python/src/plugin.py index 7a375c8a..59f07328 100644 --- a/apidocs/python/src/plugin.py +++ b/apidocs/python/src/plugin.py @@ -1,360 +1,641 @@ """ -This page describes functions that plugins may implement to be called from Profanity on certain events. All functions are optional. +The plugin module defines optional callback functions that CProof plugins can +implement to handle events such as startup, shutdown, message processing, and +presence updates. -Examples: :: - def prof_on_start(): - prof.cons_show("Profanity has started...") - def prof_pre_room_message_display(room, nick, message): - prof.cons_show("Manipulating chat room message before display...") - new_message = message + " (added by plugin)" - return new_message + import prof - def prof_on_contact_presence(barejid, resource, presence, status, priority): - notify_message = barejid + " is " + presence - prof.notify(notify_message, 5, "Presence") +All functions are optional and are called by CProof when the corresponding event +occurs. String parameters and return values are Python 3 str types. """ -def prof_init(version, status, account_name, fulljid): - """Called when a plugin is loaded, either when profanity is started, or when the ``/plugins load`` or ``/plugins install`` commands are called +# Initialization and Lifecycle +# --------------------------- - :param version: the version of Profanity - :param status: the package status of Profanity, ``"development"`` or ``"release"`` - :param account_name: account name of the currently logged in account, or ``None`` if not logged in - :param fulljid: the users full Jabber ID (barejid and resource) if logged in, ``None`` otherwise - :type version: str or unicode - :type status: str or unicode - :type account_name: str, unicode or None - :type fulljid: str, unicode or None +def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None: + """Initializes the plugin when loaded by CProof. + + 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 + + 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}") """ pass +def prof_on_start() -> None: + """Called when CProof starts. -def prof_on_start(): - """Called when Profanity is started + Use this to perform setup tasks that should occur at application startup. + + Args: + None + + Returns: + None + + Example: + + :: + + def prof_on_start() -> None: + prof.cons_show("CProof has started...") """ pass +def prof_on_shutdown() -> None: + """Called when CProof is shutting down. -def prof_on_shutdown(): - """Called when the user quits Profanity + Use this to perform cleanup tasks before the application exits. + + Args: + None + + Returns: + None + + Example: + + :: + + def prof_on_shutdown() -> None: + prof.cons_show("CProof is shutting down...") """ pass +def prof_on_unload() -> None: + """Called when the plugin is unloaded via the ``/plugins unload`` command. -def prof_on_unload(): - """Called when a plugin is unloaded with the ``/plugins unload`` command + Use this to clean up plugin-specific resources. + + Args: + None + + Returns: + None + + Example: + + :: + + def prof_on_unload() -> None: + prof.cons_show("Plugin unloaded") """ pass +def prof_on_connect(account_name: str, fulljid: str) -> None: + """Called when a user connects to CProof with an account. -def prof_on_connect(account_name, fulljid): - """Called when the user connects with an account + Args: + account_name: The account name used for login. + fulljid: The full Jabber ID (barejid/resource) of the connected account. - :param account_name: account name of the account used for logging in - :param fulljid: the full Jabber ID (barejid and resource) of the account - :type account_name: str or unicode - :type fulljid: str or unicode + Returns: + None + + Example: + + :: + + def prof_on_connect(account_name: str, fulljid: str) -> None: + prof.cons_show(f"Connected as {account_name} ({fulljid})") """ pass +def prof_on_disconnect(account_name: str, fulljid: str) -> None: + """Called when a user disconnects an account from CProof. -def prof_on_disconnect(account_name, fulljid): - """Called when the user disconnects an account + Args: + account_name: The account name being disconnected. + fulljid: The full Jabber ID (barejid/resource) of the disconnected account. - :param account_name: account name of the account being disconnected - :param fulljid: the full Jabber ID (barejid and resource) of the account - :type account_name: str or unicode - :type fulljid: str or unicode + Returns: + None + + Example: + + :: + + def prof_on_disconnect(account_name: str, fulljid: str) -> None: + prof.cons_show(f"Disconnected {account_name} ({fulljid})") """ pass +# Chat Message Handlers +# --------------------- -def prof_pre_chat_message_display(barejid, resource, message): - """Called before a chat message is displayed +def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None: + """Called before a chat message is displayed in a chat window. - :param barejid: Jabber ID of the message sender - :param resource: resource of the message sender - :param message: the received message - :type barejid: str or unicode - :type resource: str or unicode - :type message: str or unicode - :return: the new message to display, or ``None`` to preserve the original message - :rtype: str or unicode + 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. + + Example: + + :: + + def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None: + new_message = f"{message} (from {barejid})" + return new_message """ pass +def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None: + """Called after a chat message is displayed in a chat window. -def prof_post_chat_message_display(barejid, resource, message): - """Called after a chat message is displayed + Use this to perform actions after the message is shown. - :param barejid: Jabber ID of the message sender - :param resource: resource of the message sender - :param message: the received message - :type barejid: str or unicode - :type resource: str or unicode - :type message: str or unicode + 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 + + Example: + + :: + + def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None: + prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}") """ pass +def prof_pre_chat_message_send(barejid: str, message: str) -> str | None: + """Called before a chat message is sent from CProof. -def prof_pre_chat_message_send(barejid, message): - """Called before a chat message is sent + Allows the plugin to modify or cancel the message. - :param barejid: Jabber ID of the message recipient - :param message: the message to be sent - :type barejid: str or unicode - :type message: str or unicode - :return: the modified or original message to send, or ``None`` to cancel sending of the message - :rtype: str or unicode + 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. + + Example: + + :: + + def prof_pre_chat_message_send(barejid: str, message: str) -> str | None: + return f"{message} (sent by plugin)" """ pass +def prof_post_chat_message_send(barejid: str, message: str) -> None: + """Called after a chat message is sent from CProof. -def prof_post_chat_message_send(barejid, message): - """Called after a chat message has been sent + Use this to log or react to sent messages. - :param barejid: Jabber ID of the message recipient - :param message: the sent message - :type barejid: str or unicode - :type message: str or unicode + Args: + barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + message: The sent message. + + Returns: + None + + Example: + + :: + + def prof_post_chat_message_send(barejid: str, message: str) -> None: + prof.cons_show(f"Sent to {barejid}: {message}") """ pass +# Room Message Handlers +# --------------------- -def prof_pre_room_message_display(barejid, nick, message): - """Called before a chat room message is displayed +def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None: + """Called before a chat room message is displayed. - :param barejid: Jabber ID of the room - :param nick: nickname of message sender - :param message: the received message - :type barejid: str or unicode - :type nick: str or unicode - :type message: str or unicode - :return: the new message to display, or ``None`` to preserve the original message - :rtype: str or unicode + 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. + + Example: + + :: + + def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None: + return f"{message} (from {nick})" """ pass +def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None: + """Called after a chat room message is displayed. -def prof_post_room_message_display(barejid, nick, message): - """Called after a chat room message is displayed + Use this to perform actions after the message is shown. - :param barejid: Jabber ID of the room - :param nick: nickname of the message sender - :param message: the received message - :type barejid: str or unicode - :type nick: str or unicode - :type message: str or unicode + 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 + + Example: + + :: + + def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None: + prof.cons_show(f"Displayed in {barejid} from {nick}: {message}") """ pass +def prof_pre_room_message_send(barejid: str, message: str) -> str | None: + """Called before a chat room message is sent. -def prof_pre_room_message_send(barejid, message): - """Called before a chat room message is sent + Allows the plugin to modify or cancel the message. - :param barejid: Jabber ID of the room - :param message: the message to be sent - :type barejid: str or unicode - :type message: str or unicode - :return: the modified or original message to send, or ``None`` to cancel sending of the message - :rtype: str or unicode + 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. + + Example: + + :: + + def prof_pre_room_message_send(barejid: str, message: str) -> str | None: + return f"{message} (sent by plugin)" """ pass +def prof_post_room_message_send(barejid: str, message: str) -> None: + """Called after a chat room message is sent. -def prof_post_room_message_send(barejid, message): - """Called after a chat room message has been sent + Use this to log or react to sent messages. - :param barejid: Jabber ID of the room - :param message: the sent message - :type barejid: str or unicode - :type message: str or unicode + Args: + barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + message: The sent message. + + Returns: + None + + Example: + + :: + + def prof_post_room_message_send(barejid: str, message: str) -> None: + prof.cons_show(f"Sent to {barejid}: {message}") """ pass +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. -def prof_on_room_history_message(barejid, nick, message, timestamp): - """Called when the server sends a chat room history message + 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``). - :param barejid: Jabber ID of the room - :param nick: nickname of the message sender - :param message: the message to be sent - :param timestamp: time the message was originally sent to the room, in ISO8601 format - :type barejid: str or unicode - :type nick: str or unicode - :type message: str or unicode - :type timestamp: str or unicode + Returns: + 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}") """ pass +# Private Message Handlers +# ------------------------ -def prof_pre_priv_message_display(barejid, nick, message): - """Called before a private chat room message is displayed +def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None: + """Called before a private chat room message is displayed. - :param barejid: Jabber ID of the room - :param nick: nickname of message sender - :param message: the received message - :type barejid: str or unicode - :type nick: str or unicode - :type message: str or unicode - :return: the new message to display, or ``None`` to preserve the original message - :rtype: str or unicode + 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. + + Example: + + :: + + def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None: + return f"{message} (private from {nick})" """ pass +def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None: + """Called after a private chat room message is displayed. -def prof_post_priv_message_display(barejid, nick, message): - """Called after a private chat room message is displayed + Use this to perform actions after the message is shown. - :param barejid: Jabber ID of the room - :param nick: nickname of the message sender - :param message: the received message - :type barejid: str or unicode - :type nick: str or unicode - :type message: str or unicode + 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 + + 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}") """ pass +def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None: + """Called before a private chat room message is sent. -def prof_pre_priv_message_send(barejid, nick, message): - """Called before a private chat room message is sent + Allows the plugin to modify or cancel the message. - :param barejid: Jabber ID of the room - :param nick: nickname of message recipient - :param message: the message to be sent - :type barejid: str or unicode - :type nick: str or unicode - :type message: str or unicode - :return: the modified or original message to send, or ``None`` to cancel sending of the message - :rtype: str or unicode + 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. + + Example: + + :: + + def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None: + return f"{message} (private to {nick})" """ pass +def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None: + """Called after a private chat room message is sent. -def prof_post_priv_message_send(barejid, nick, message): - """Called after a private chat room message has been sent + Use this to log or react to sent messages. - :param barejid: Jabber ID of the room - :param nick: nickname of the message recipient - :param message: the sent message - :type barejid: str or unicode - :type nick: str or unicode - :type message: str or unicode + 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 + + 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}") """ pass +# Stanza Handlers +# --------------- -def prof_on_message_stanza_send(stanza): - """Called before an XMPP message stanza is sent +def prof_on_message_stanza_send(stanza: str) -> str | None: + """Called before an XMPP message stanza is sent. - :param stanza: The stanza to send - :type stanza: str or unicode - :return: The new stanza to send, or ``None`` to preserve the original stanza - :rtype: str or unicode + 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. + + Example: + + :: + + def prof_on_message_stanza_send(stanza: str) -> str | None: + prof.cons_show(f"Sending message stanza: {stanza}") + return stanza """ pass +def prof_on_message_stanza_receive(stanza: str) -> bool: + """Called when an XMPP message stanza is received. -def prof_on_message_stanza_receive(stanza): - """Called when an XMPP message stanza is received + Allows the plugin to control whether CProof processes the stanza. - :param stanza: The stanza received - :type stanza: str or unicode - :return: ``True`` if Profanity should continue to process the message stanza, ``False`` otherwise - :rtype: boolean + Args: + stanza: The received XMPP message stanza. + + Returns: + bool: 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 """ pass +def prof_on_presence_stanza_send(stanza: str) -> str | None: + """Called before an XMPP presence stanza is sent. -def prof_on_presence_stanza_send(stanza): - """Called before an XMPP presence stanza is sent + Allows the plugin to modify or cancel the stanza. - :param stanza: The stanza to send - :type stanza: str or unicode - :return: The new stanza to send, or ``None`` to preserve the original stanza - :rtype: str or unicode + Args: + stanza: The XMPP presence stanza to send. + + Returns: + str | None: 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 """ pass +def prof_on_presence_stanza_receive(stanza: str) -> bool: + """Called when an XMPP presence stanza is received. -def prof_on_presence_stanza_receive(stanza): - """Called when an XMPP presence stanza is received + Allows the plugin to control whether CProof processes the stanza. - :param stanza: The stanza received - :type stanza: str or unicode - :return: ``True`` if Profanity should continue to process the presence stanza, ``False`` otherwise - :rtype: boolean + Args: + stanza: The received XMPP presence stanza. + + Returns: + bool: 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 """ pass +def prof_on_iq_stanza_send(stanza: str) -> str | None: + """Called before an XMPP IQ stanza is sent. -def prof_on_iq_stanza_send(stanza): - """Called before an XMPP iq stanza is sent + Allows the plugin to modify or cancel the stanza. - :param stanza: The stanza to send - :type stanza: str or unicode - :return: The new stanza to send, or ``None`` to preserve the original stanza - :rtype: str or unicode + Args: + stanza: The XMPP IQ stanza to send. + + Returns: + str | None: 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 """ pass +def prof_on_iq_stanza_receive(stanza: str) -> bool: + """Called when an XMPP IQ stanza is received. -def prof_on_iq_stanza_receive(stanza): - """Called when an XMPP iq stanza is received + Allows the plugin to control whether CProof processes the stanza. - :param stanza: The stanza received - :type stanza: str or unicode - :return: ``True`` if Profanity should continue to process the iq stanza, ``False`` otherwise - :rtype: boolean + Args: + stanza: The received XMPP IQ stanza. + + Returns: + bool: 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 """ pass +# Contact Presence Handlers +# ------------------------- -def prof_on_contact_offline(barejid, resource, status): - """Called when a contact goes offline +def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None: + """Called when a contact goes offline. - :param barejid: Jabber ID of the contact - :param resource: the resource being disconnected - :param status: the status message received with the offline presence, or ``None`` - :type barejid: str or unicode - :type resource: str or unicode - :type status: str or unicode + 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 + + 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'}") """ pass +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. -def prof_on_contact_presence(barejid, resource, presence, status, priority): - """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. - :param barejid: Jabber ID of the contact - :param resource: the resource being disconnected - :param presence: presence of the contact, one of ``"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 - :type barejid: str or unicode - :type resource: str or unicode - :type presence: str or unicode - :type status: str or unicode - :type priority: int + Returns: + 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") """ pass +# Window Focus Handlers +# --------------------- -def prof_on_chat_win_focus(barejid): - """Called when a chat window is focused +def prof_on_chat_win_focus(barejid: str) -> None: + """Called when a chat window is focused. - :param barejid: Jabber ID of the chat window recipient - :type barejid: str or unicode + Args: + barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``). + + Returns: + None + + Example: + + :: + + def prof_on_chat_win_focus(barejid: str) -> None: + prof.cons_show(f"Focused chat window for {barejid}") """ pass +def prof_on_room_win_focus(barejid: str) -> None: + """Called when a chat room window is focused. -def prof_on_room_win_focus(barejid): - """Called when a chat room window is focused + Args: + barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - :param barejid: Jabber ID of the room - :type barejid: str or unicode + Returns: + None + + Example: + + :: + + def prof_on_room_win_focus(barejid: str) -> None: + prof.cons_show(f"Focused room window for {barejid}") """ pass