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 in
  • fulljid (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 focussed

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 focussed

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

Previous topic

prof module