From c8d231fc75b1e700630b92c5073233ebefa4edda Mon Sep 17 00:00:00 2001 From: James Booth Date: Sat, 30 Jul 2016 19:06:21 +0100 Subject: Update python API docs --- apidocs/python/src/plugin.py | 250 +++++++++++++++++++++++++++++++++++++++++-- apidocs/python/src/prof.py | 8 +- 2 files changed, 250 insertions(+), 8 deletions(-) (limited to 'apidocs/python') diff --git a/apidocs/python/src/plugin.py b/apidocs/python/src/plugin.py index ab7df146..f975a342 100644 --- a/apidocs/python/src/plugin.py +++ b/apidocs/python/src/plugin.py @@ -1,119 +1,355 @@ """ -Profanity plugin Hooks +This page describes functions that plugins may implement to be called from Profanity on certain events. All functions are optional. + +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 + + def prof_on_contact_presence(barejid, resource, presence, status, priority): + notify_message = barejid + " is " + presence + prof.notify(notify_message, 5, "Presence") """ 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 + + :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 + """ pass def prof_on_start(): + """Called when Profanity is started + """ pass def prof_on_shutdown(): + """Called when the user quits Profanity + """ pass def prof_on_unload(): + """Called when a plugin is unloaded with the ``/plugins unload`` command + """ pass def prof_on_connect(account_name, fulljid): + """Called when the user connects with an 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 + """ pass def prof_on_disconnect(account_name, fulljid): + """Called when the user disconnects an 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 + """ pass -def prof_pre_chat_message_display(jid, message): +def prof_pre_chat_message_display(barejid, message): + """Called before a chat message is displayed + + :param barejid: Jabber ID of the message sender + :param message: the received message + :type barejid: 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 + """ pass -def prof_post_chat_message_display(jid, message): +def prof_post_chat_message_display(barejid, message): + """Called after a chat message is displayed + + :param barejid: Jabber ID of the message sender + :param message: the received message + :type barejid: str or unicode + :type message: str or unicode + """ pass -def prof_pre_chat_message_send(jid, message): +def prof_pre_chat_message_send(barejid, message): + """Called before a chat message is sent + + :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 new message to send, or ``None`` to preserve the original message + :rtype: str or unicode + """ pass -def prof_post_chat_message_send(jid, message): +def prof_post_chat_message_send(barejid, message): + """Called after a chat message has been sent + + :param barejid: Jabber ID of the message recipient + :param message: the sent message + :type barejid: str or unicode + :type message: str or unicode + """ pass def prof_pre_room_message_display(room, nick, message): + """Called before a chat room message is displayed + + :param room: Jabber ID of the room + :param nick: nickname of message sender + :param message: the received message + :type room: 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 + """ pass def prof_post_room_message_display(room, nick, message): + """Called after a chat room message is displayed + + :param room: Jabber ID of the room + :param nick: nickname of the message sender + :param message: the received message + :type room: str or unicode + :type nick: str or unicode + :type message: str or unicode + """ pass def prof_pre_room_message_send(room, message): + """Called before a chat room message is sent + + :param room: Jabber ID of the room + :param message: the message to be sent + :type room: str or unicode + :type message: str or unicode + :return: the new message to send, or ``None`` to preserve the original message + :rtype: str or unicode + """ pass def prof_post_room_message_send(room, message): + """Called after a chat room message has been sent + + :param room: Jabber ID of the room + :param message: the sent message + :type room: str or unicode + :type message: str or unicode + """ pass def prof_on_room_history_message(room, nick, message, timestamp): + """Called when the server sends a chat room history message + + :param room: 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 room: str or unicode + :type nick: str or unicode + :type message: str or unicode + :type timestamp: str or unicode + """ pass def prof_pre_priv_message_display(room, nick, message): + """Called before a private chat room message is displayed + + :param room: Jabber ID of the room + :param nick: nickname of message sender + :param message: the received message + :type room: 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 + """ pass def prof_post_priv_message_display(room, nick, message): + """Called after a private chat room message is displayed + + :param room: Jabber ID of the room + :param nick: nickname of the message sender + :param message: the received message + :type room: str or unicode + :type nick: str or unicode + :type message: str or unicode + """ pass def prof_pre_priv_message_send(room, nick, message): + """Called before a private chat room message is sent + + :param room: Jabber ID of the room + :param nick: nickname of message recipient + :param message: the message to be sent + :type room: str or unicode + :type nick: str or unicode + :type message: str or unicode + :return: the new message to send, or ``None`` to preserve the original message + :rtype: str or unicode + """ pass def prof_post_priv_message_send(room, nick, message): + """Called after a private chat room message has been sent + + :param room: Jabber ID of the room + :param nick: nickname of the message recipient + :param message: the sent message + :type room: str or unicode + :type message: str or unicode + """ pass def prof_on_message_stanza_send(stanza): + """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 + """ pass def prof_on_message_stanza_receive(stanza): + """Called when an XMPP message stanza is received + + :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 + """ pass def prof_on_presence_stanza_send(stanza): + """Called before an XMPP presence 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 + """ pass def prof_on_presence_stanza_receive(stanza): + """Called when an XMPP presence stanza is received + + :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 + """ pass def prof_on_iq_stanza_send(stanza): + """Called before an XMPP iq 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 + """ pass def prof_on_iq_stanza_receive(stanza): + """Called when an XMPP iq stanza is received + + :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 + """ pass def prof_on_contact_offline(barejid, resource, status): + """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 + """ pass def prof_on_contact_presence(barejid, resource, presence, status, priority): + """Called when a presence notification is received from a contact + + :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 + """ pass def prof_on_chat_win_focus(barejid): + """Called when a chat window is focussed + + :param barejid: Jabber ID of the chat window recipient + :type barejid: str or unicode + """ pass -def prof_on_room_win_focus(roomjid): - pass +def prof_on_room_win_focus(room): + """Called when a chat room window is focussed + :param room: Jabber ID of the room + :type room: str or unicode + """ + pass diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index 99d00a94..297960e6 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -1,5 +1,11 @@ """ -Profanity plugin API +This module contains the functions available to plugins to interact with Profanity. + +The ``prof`` module must be imported +:: + import prof + +Profanity accepts both ``str`` and ``unicode`` objects as string arguments, to allow plugins to work with both Python 2 and 3. """ -- cgit 1.4.1-2-gfad0