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