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

docs(plugin): update plugin.py to align with formatting required by Sphinx

Browse Source 
- 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.
This commit is contained in:
Jabber Developer
2025-09-15 11:53:49 +02:00
parent 7e4c60e2c3
commit 4cdcf9a8eb
1 changed files with 494 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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