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

docs(python): fix formatting to ensure correct parsing

Browse Source 
Fixes issues introduced in 052e168, 4cdcf9a, and other commits from PR #31.
This commit is contained in:
Jabber Developer
2025-09-17 00:34:37 +02:00
parent 353b6bdb11
commit c94263486f
2 changed files with 441 additions and 863 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

File diff suppressed because it is too large Load Diff