plugin module¶
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")
-
plugin.
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- Parameters
version (str or unicode) – the version of Profanity
status (str or unicode) – the package status of Profanity,
"development"
or"release"
account_name (str, unicode or None) – account name of the currently logged in account, or
None
if not logged infulljid (str, unicode or None) – the users full Jabber ID (barejid and resource) if logged in,
None
otherwise
-
plugin.
prof_on_chat_win_focus
(barejid)¶ Called when a chat window is focused
- Parameters
barejid (str or unicode) – Jabber ID of the chat window recipient
-
plugin.
prof_on_connect
(account_name, fulljid)¶ Called when the user connects with an account
- Parameters
account_name (str or unicode) – account name of the account used for logging in
fulljid (str or unicode) – the full Jabber ID (barejid and resource) of the account
-
plugin.
prof_on_contact_offline
(barejid, resource, status)¶ Called when a contact goes offline
- Parameters
barejid (str or unicode) – Jabber ID of the contact
resource (str or unicode) – the resource being disconnected
status (str or unicode) – the status message received with the offline presence, or
None
-
plugin.
prof_on_contact_presence
(barejid, resource, presence, status, priority)¶ Called when a presence notification is received from a contact
- Parameters
barejid (str or unicode) – Jabber ID of the contact
resource (str or unicode) – the resource being disconnected
presence (str or unicode) – presence of the contact, one of
"chat"
,"online"
,"away"
,"xa"
or"dnd"
status (str or unicode) – the status message received with the presence, or
None
priority (int) – the priority associated with the resource
-
plugin.
prof_on_disconnect
(account_name, fulljid)¶ Called when the user disconnects an account
- Parameters
account_name (str or unicode) – account name of the account being disconnected
fulljid (str or unicode) – the full Jabber ID (barejid and resource) of the account
-
plugin.
prof_on_iq_stanza_receive
(stanza)¶ Called when an XMPP iq stanza is received
- Parameters
stanza (str or unicode) – The stanza received
- Returns
True
if Profanity should continue to process the iq stanza,False
otherwise- Return type
boolean
-
plugin.
prof_on_iq_stanza_send
(stanza)¶ Called before an XMPP iq stanza is sent
- Parameters
stanza (str or unicode) – The stanza to send
- Returns
The new stanza to send, or
None
to preserve the original stanza- Return type
str or unicode
-
plugin.
prof_on_message_stanza_receive
(stanza)¶ Called when an XMPP message stanza is received
- Parameters
stanza (str or unicode) – The stanza received
- Returns
True
if Profanity should continue to process the message stanza,False
otherwise- Return type
boolean
-
plugin.
prof_on_message_stanza_send
(stanza)¶ Called before an XMPP message stanza is sent
- Parameters
stanza (str or unicode) – The stanza to send
- Returns
The new stanza to send, or
None
to preserve the original stanza- Return type
str or unicode
-
plugin.
prof_on_presence_stanza_receive
(stanza)¶ Called when an XMPP presence stanza is received
- Parameters
stanza (str or unicode) – The stanza received
- Returns
True
if Profanity should continue to process the presence stanza,False
otherwise- Return type
boolean
-
plugin.
prof_on_presence_stanza_send
(stanza)¶ Called before an XMPP presence stanza is sent
- Parameters
stanza (str or unicode) – The stanza to send
- Returns
The new stanza to send, or
None
to preserve the original stanza- Return type
str or unicode
-
plugin.
prof_on_room_history_message
(barejid, nick, message, timestamp)¶ Called when the server sends a chat room history message
- Parameters
barejid (str or unicode) – Jabber ID of the room
nick (str or unicode) – nickname of the message sender
message (str or unicode) – the message to be sent
timestamp (str or unicode) – time the message was originally sent to the room, in ISO8601 format
-
plugin.
prof_on_room_win_focus
(barejid)¶ Called when a chat room window is focused
- Parameters
barejid (str or unicode) – Jabber ID of the room
-
plugin.
prof_on_shutdown
()¶ Called when the user quits Profanity
-
plugin.
prof_on_start
()¶ Called when Profanity is started
-
plugin.
prof_on_unload
()¶ Called when a plugin is unloaded with the
/plugins unload
command
-
plugin.
prof_post_chat_message_display
(barejid, resource, message)¶ Called after a chat message is displayed
- Parameters
barejid (str or unicode) – Jabber ID of the message sender
resource (str or unicode) – resource of the message sender
message (str or unicode) – the received message
-
plugin.
prof_post_chat_message_send
(barejid, message)¶ Called after a chat message has been sent
- Parameters
barejid (str or unicode) – Jabber ID of the message recipient
message (str or unicode) – the sent message
-
plugin.
prof_post_priv_message_display
(barejid, nick, message)¶ Called after a private chat room message is displayed
- Parameters
barejid (str or unicode) – Jabber ID of the room
nick (str or unicode) – nickname of the message sender
message (str or unicode) – the received message
-
plugin.
prof_post_priv_message_send
(barejid, nick, message)¶ Called after a private chat room message has been sent
- Parameters
barejid (str or unicode) – Jabber ID of the room
nick (str or unicode) – nickname of the message recipient
message (str or unicode) – the sent message
-
plugin.
prof_post_room_message_display
(barejid, nick, message)¶ Called after a chat room message is displayed
- Parameters
barejid (str or unicode) – Jabber ID of the room
nick (str or unicode) – nickname of the message sender
message (str or unicode) – the received message
-
plugin.
prof_post_room_message_send
(barejid, message)¶ Called after a chat room message has been sent
- Parameters
barejid (str or unicode) – Jabber ID of the room
message (str or unicode) – the sent message
-
plugin.
prof_pre_chat_message_display
(barejid, resource, message)¶ Called before a chat message is displayed
- Parameters
barejid (str or unicode) – Jabber ID of the message sender
resource (str or unicode) – resource of the message sender
message (str or unicode) – the received message
- Returns
the new message to display, or
None
to preserve the original message- Return type
str or unicode
-
plugin.
prof_pre_chat_message_send
(barejid, message)¶ Called before a chat message is sent
- Parameters
barejid (str or unicode) – Jabber ID of the message recipient
message (str or unicode) – the message to be sent
- Returns
the modified or original message to send, or
None
to cancel sending of the message- Return type
str or unicode
-
plugin.
prof_pre_priv_message_display
(barejid, nick, message)¶ Called before a private chat room message is displayed
- Parameters
barejid (str or unicode) – Jabber ID of the room
nick (str or unicode) – nickname of message sender
message (str or unicode) – the received message
- Returns
the new message to display, or
None
to preserve the original message- Return type
str or unicode
-
plugin.
prof_pre_priv_message_send
(barejid, nick, message)¶ Called before a private chat room message is sent
- Parameters
barejid (str or unicode) – Jabber ID of the room
nick (str or unicode) – nickname of message recipient
message (str or unicode) – the message to be sent
- Returns
the modified or original message to send, or
None
to cancel sending of the message- Return type
str or unicode
-
plugin.
prof_pre_room_message_display
(barejid, nick, message)¶ Called before a chat room message is displayed
- Parameters
barejid (str or unicode) – Jabber ID of the room
nick (str or unicode) – nickname of message sender
message (str or unicode) – the received message
- Returns
the new message to display, or
None
to preserve the original message- Return type
str or unicode
-
plugin.
prof_pre_room_message_send
(barejid, message)¶ Called before a chat room message is sent
- Parameters
barejid (str or unicode) – Jabber ID of the room
message (str or unicode) – the message to be sent
- Returns
the modified or original message to send, or
None
to cancel sending of the message- Return type
str or unicode