prof module

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.

prof.chat_set_incoming_char(barejid, ch)

Set the incoming message prefix character for specified contact.

Parameters:
  • barejid (str or unicode) – Jabber ID of the recipient
  • enctext (str or unicode) – The character to display
Returns:

True if the character was set successfully, False otherwise

Return type:

boolean

Example:

prof.chat_set_incoming_char("kristine@chat.org", "*")
prof.chat_set_outgoing_char(barejid, ch)

Set the outgoing message prefix character for specified contact.

Parameters:
  • barejid (str or unicode) – Jabber ID of the recipient
  • enctext (str or unicode) – The character to display
Returns:

True if the character was set successfully, False otherwise

Return type:

boolean

Example:

prof.chat_set_outgoing_char("david@chat.org", "+")
prof.chat_set_titlebar_enctext(barejid, enctext)

Set the text to display in the titlebar encryption indicator for recipient.

Parameters:
  • barejid (str or unicode) – Jabber ID of the recipient
  • enctext (str or unicode) – The text to display
Returns:

True if the text was set successfully, False otherwise

Return type:

boolean

Example:

prof.chat_set_titlebar_enctext("bob@chat.org", "safe")
prof.chat_show(barejid, message)

Show a message in a chat window.

Parameters:
  • barejid (str or unicode) – Jabber ID of the recipient
  • message (str or unicode) – the message to print
Returns:

True if the message was printed, False otherwise

Return type:

boolean

Example:

prof.chat_show("bob@server.org", "From a plugin in the chat window for bob")
prof.chat_show_themed(barejid, group, key, default, ch, message)

Show a message a chat window, using the specified theme and prefix character.

Themes are specified in ~/.local/share/profanity/plugin_themes

Parameters:
  • barejid (str or unicode) – Jabber ID of the recipient
  • group (str, unicode or None) – the group name in the themes file or None
  • key (str, unicode or None) – the item name within the group or None
  • default (str, unicode or None) – default colour if the theme cannot be found or None
  • ch (str or unicode) – The prefix character to show, or None for default behaviour
  • message (str or unicode) – the message to print
Returns:

True if the message was printed, False otherwise

Return type:

boolean

Example:

prof.chat_show_themed("bob@server.org", "myplugin", "text", None, "!", "Plugin themed message")
prof.chat_unset_incoming_char(barejid)

Reset the incoming message prefix character for specified contact.

Parameters:barejid (str or unicode) – Jabber ID of the recipient
Returns:True if the char was unset successfully, False otherwise
Return type:boolean

Example:

prof.chat_unset_incoming_char("kristine@chat.org")
prof.chat_unset_outgoing_char(barejid)

Reset the outgoing message prefix character for specified contact.

Parameters:barejid (str or unicode) – Jabber ID of the recipient
Returns:True if the char was unset successfully, False otherwise
Return type:boolean

Example:

prof.chat_unset_outgoing_char("david@chat.org")
prof.chat_unset_titlebar_enctext(barejid)

Let profanity decide what to show in the titlebar encryption indicator for recipient.

Parameters:barejid (str or unicode) – Jabber ID of the recipient
Returns:True if the text was unset successfully, False otherwise
Return type:boolean

Example:

prof.chat_unset_titlebar_enctext("bob@chat.org")
prof.completer_add(key, items)

Add values to be autocompleted by Profanity for a command, or command argument. If the key already exists, Profanity will add the items to the existing autocomplete items for that key.

Parameters:
  • key (str or unicode) – the prefix to trigger autocompletion
  • items (list of str or unicode) – the items to return on autocompletion

Examples:

prof.completer_add("/mycommand", [ 
    "action1",
    "action2", 
    "dosomething" 
])

prof.completer_add("/mycommand dosomething", [
    "thing1",
    "thing2" 
])
prof.completer_clear(key)

Remove all values from autocompletion for a command, or command argument.

Parameters:key – the prefix from which to clear the autocompletion items

Examples:

prof.completer_clear("/mycommand")

prof.completer_add("/mycommand dosomething")
prof.completer_remove(key, items)

Remove values from autocompletion for a command, or command argument.

Parameters:
  • key (str or unicode) – the prefix from which to remove the autocompletion items
  • items (list of str or unicode) – the items to remove

Examples:

prof.completer_remove("/mycommand", [ 
    "action1",
    "action2"
])

prof.completer_add("/mycommand dosomething", [
    "thing1"
])
prof.cons_alert()

Highlights the console window in the status bar.

prof.cons_bad_cmd_usage(command)

Show a message indicating the command has been called incorrectly.

Parameters:command (str or unicode) – the command name with leading slash, e.g. "/say"

Example:

prof.cons_bad_cmd_usage("/mycommand")
prof.cons_show(message)

Show a message in the console window.

Parameters:message (str or unicode) – the message to print

Example:

prof.cons_show("This will appear in the console window")
prof.cons_show_themed(group, key, default, message)

Show a message in the console, using the specified theme.

Themes are specified in ~/.local/share/profanity/plugin_themes

Parameters:
  • group (str, unicode or None) – the group name in the themes file
  • key (str, unicode or None) – the item name within the group
  • default (str, unicode or None) – default colour if the theme cannot be found
  • message (str or unicode) – the message to print

Example:

prof.cons_show_themed("myplugin", "text", None, "Plugin themed message")
prof.current_win_is_console()

Determine whether or not the Console window is currently focussed.

Returns:True if the user is currently in the Console window, False otherwise.
Return type:boolean
prof.disco_add_feature(feature)

Add a service discovery feature the list supported by Profanity.

If a session is already connected, a presence update will be sent to allow any client/server caches to update their feature list for Profanity

Parameters:feature (str) – the service discovery feature to be added

Example:

prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify")
prof.encryption_reset(barejid)

End any encrypted session with the specified user

Parameters:barejid (str or unicode) – Jabber ID of the recipient

Example:

prof.encryption_reset("alice@server.org")
prof.filepath_completer_add(prefix)

Add filepath autocompletion for a command, or command argument.

Parameters:prefix – the prefix from which filepath autocompletion will be triggered

Examples:

prof.filepath_completer_add("/filecmd")

prof.filepath_completer_add("/mycommand open")
prof.get_current_muc()

Retrieve the Jabber ID of the current room, when in a chat room window.

Returns:the Jabber ID of the current chat room e.g. "metalchat@conference.chat.org", or None if not in a chat room window.
Return type:str
prof.get_current_nick()

Retrieve the users nickname in a chat room, when in a chat room window.

Returns:the users nickname in the current chat room e.g. "eddie", or None if not in a chat room window.
Return type:str
prof.get_current_occupants()

Retrieve nicknames of all occupants in a chat room, when in a chat room window.

Returns:nicknames of all occupants in the current room or an empty list if not in a chat room window.
Return type:list of str
prof.get_current_recipient()

Retrieve the Jabber ID of the current chat recipient, when in a chat window.

Returns:the Jabber ID of the current chat recipient e.g. "buddy@chat.org", or None if not in a chat window.
Return type:str
prof.get_room_nick(barejid)

Retrieve current nickname used in chat room.

Returns:Room nickname.
Return type:str
prof.incoming_message(barejid, resource, message)

Trigger incoming message handling, this plugin will make profanity act as if the message has been received

Parameters:
  • barejid (str or unicode) – Jabber ID of the sender of the message
  • resource (str or unicode) – resource of the sender of the message
  • message (str or unicode) – the message text

Example:

prof.incoming_message("bob@server.org", "laptop", "Hello there")
prof.log_debug(message)

Write to the Profanity log at level DEBUG.

Parameters:message (str or unicode) – the message to log
prof.log_error()

Write to the Profanity log at level ERROR.

Parameters:message (str or unicode) – the message to log
prof.log_info()

Write to the Profanity log at level INFO.

Parameters:message (str or unicode) – the message to log
prof.log_warning()

Write to the Profanity log at level WARNING.

Parameters:message (str or unicode) – the message to log
prof.notify(message, timeout, category)

Send a desktop notification.

Parameters:
  • message (str or unicode) – the message to display in the notification
  • timeout (int) – the length of time before the notification disappears in milliseconds
  • category (str or unicode) – the category of the notification, also displayed

Example:

prof.notify("Example notification for 5 seconds", 5000, "Example plugin")
prof.register_command(name, min_args, max_args, synopsis, description, arguments, examples, callback)

Register a new command, with help information, and callback for command execution.

Profanity will do some basic validation when the command is called using the argument range.

Parameters:
  • name (str or unicode) – the command name with leading slash, e.g. "/say"
  • min_args (int) – minimum number or arguments that the command considers to be a valid call
  • max_args (int) – maximum number or arguments that the command considers to be a valid call
  • synopsis (list of str or unicode) – command usages
  • description (str or unicode) – a short description of the command
  • arguments (list of list of str or unicode) – argument descriptions, each element should be of the form [arguments, description]
  • examples (list of str or unicode) – example usages
  • callback (function) – function to call when the command is executed

Example:

synopsis = [
    "/newcommand action1|action2",
    "/newcommand print <argument>",
    "/newcommand dosomething [<optional_argument>]"
]
description = "An example for the documentation"
args = [
    [ "action1|action2", "Perform action1 or action2" ],
    [ "print <argument>", "Print argument" ],
    [ "dosomething [<optional_argument>]", "Do something, optionally with the argument" ]
]
examples = [
    "/newcommand action1",
    "/newcommand print \"Test debug message\"",
    "/newcommand dosomething"
]        

prof.register_command("/newcommand", 1, 2, synopsis, description, args, examples, my_function)
prof.register_timed(callback, interval)

Register a function that Profanity will call periodically.

Parameters:
  • callback (function) – the function to call
  • interval (int) – the time between each call to the function, in seconds

Example:

prof.register_timed(some_function, 30)
prof.room_set_message_char(roomjid, ch)

Set the message prefix character for specified room.

Parameters:
  • roomjid (str or unicode) – Jabber ID of the room
  • enctext (str or unicode) – The character to display
Returns:

True if the character was set successfully, False otherwise

Return type:

boolean

Example:

prof.room_set_message_char("ohnoes@conference.chat.org", "^")
prof.room_set_titlebar_enctext(roomjid, enctext)

Set the text to display in the titlebar encryption indicator for room.

Parameters:
  • roomjid (str or unicode) – Jabber ID of the room
  • enctext (str or unicode) – The text to display
Returns:

True if the text was set successfully, False otherwise

Return type:

boolean

Example:

prof.room_set_titlebar_enctext("generalchat@conference.service.com", "secret")
prof.room_show(roomjid, message)

Show a message in a chat room window.

Parameters:
  • roomjid (str or unicode) – Jabber ID of the room
  • message (str or unicode) – the message to print
Returns:

True if the message was printed, False otherwise

Return type:

boolean

Example:

prof.room_show("chat@conference.chat.org", "From a plugin in the chat room window")
prof.room_show_themed(roomjid, group, key, default, ch, message)

Show a message a chat room window, using the specified theme and prefix character.

Themes are specified in ~/.local/share/profanity/plugin_themes

Parameters:
  • roomjid (str or unicode) – Jabber ID of the room
  • group (str, unicode or None) – the group name in the themes file or None
  • key (str, unicode or None) – the item name within the group or None
  • default (str, unicode or None) – default colour if the theme cannot be found or None
  • ch (str or unicode) – The prefix character to show, or None for default behaviour
  • message (str or unicode) – the message to print
Returns:

True if the message was printed, False otherwise

Return type:

boolean

Example:

prof.room_show_themed("chat@conference.chat.org", "myplugin", "text", None, "!", "Plugin themed message")
prof.room_unset_message_char(roomjid)

Reset the message prefix character for specified room.

Parameters:roomjid (str or unicode) – Jabber ID of the room
Returns:True if the char was unset successfully, False otherwise
Return type:boolean

Example:

prof.room_unset_message_char("ohnoes@conference.chat.org")
prof.room_unset_titlebar_enctext(roomjid)

Let profanity decide what to show in the titlebar encryption indicator for room.

Parameters:roomjid (str or unicode) – Jabber ID of the room
Returns:True if the text was unset successfully, False otherwise
Return type:boolean

Example:

prof.room_unset_titlebar_enctext("generalchat@conference.service.com")
prof.send_line(line)

Send a line of input to Profanity to execute.

Parameters:line (str or unicode) – the line to send

Example:

prof.send_line("/who online")
prof.send_stanza(stanza)

Send an XMPP stanza

Parameters:stanza (str or unicode) – An XMPP stanza
Returns:True if the stanza was sent successfully, False otherwise
Return type:boolean

Example:

prof.send_stanza("<iq to='juliet@capulet.lit/balcony' id='s2c1' type='get'><ping xmlns='urn:xmpp:ping'/></iq>")
prof.settings_boolean_get(group, key, default)

Get a boolean setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
  • default (boolean) – default value if setting not found

Example:

prof.settings_get_boolean("myplugin", "notify", False)
prof.settings_boolean_set(group, key, value)

Set a boolean setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
  • value (boolean) – value to set

Example:

prof.settings_set_boolean("myplugin", "activate", True)
prof.settings_int_get(group, key, default)

Get an integer setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
  • default (int) – default value if setting not found

Example:

prof.settings_get_int("myplugin", "timeout", 10)
prof.settings_int_set(group, key, value)

Set an integer setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
  • value (int) – value to set

Example:

prof.settings_set_int("myplugin", "timeout", 100)
prof.settings_string_get(group, key, default)

Get a string setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
  • default (str) – default value if setting not found

Example:

prof.settings_get_string("myplugin", "prefix", "prefix-->")
prof.settings_string_list_add(group, key, value)

Add an item to a string list setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

If the list does not exist, a new one will be created with the element added

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
  • value (str) – item to add

Example:

prof.settings_string_list_add("someplugin", "somelist", "anelement")
prof.settings_string_list_clear(group, key)

Remove all items from a string list setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
Returns:

True if the list was cleared, False if the list does not exist

Return type:

boolean

Example:

prof.settings_string_list_remove_all("someplugin", "somelist")
prof.settings_string_list_get(group, key)

Get a string list setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

The string list setting items are separated by semicolons.

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
Returns:

the list setting

Return type:

list of str or unicode

Example:

prof.settings_get_string_list("someplugin", "somelist")
prof.settings_string_list_remove(group, key, value)

Remove an item from a string list setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
  • value (str) – item to remove
Returns:

True if the item was removed, or is not in the list, False if the list does not exist

Return type:

boolean

Example:

prof.settings_string_list_remove("someplugin", "somelist", "anelement")
prof.settings_string_set(group, key, value)

Set a string setting

Settings must be specified in ~/.local/share/profanity/plugin_settings

Parameters:
  • group (str or unicode) – the group name in the settings file
  • key (str or unicode) – the item name within the group
  • value (str) – value to set

Example:

prof.settings_set_string("myplugin", "prefix", "myplugin, ")
prof.win_create(tag, callback)

Create a plugin window.

Parameters:
  • tag (str or unicode) – The tag used to refer to the window
  • callback (function) – function to call when the window receives input

Example:

prof.win_create("My Plugin", window_handler)
prof.win_exists(tag)

Determine whether or not a plugin window currently exists for the tag.

Parameters:tag (str or unicode) – The tag used when creating the plugin window
Returns:True if the window exists, False otherwise.
Return type:boolean

Example:

prof.win_exists("My Plugin")
prof.win_focus(tag)

Focus a plugin window.

Parameters:tag (str or unicode) – The tag of the window to focus

Example:

prof.win_focus("My Plugin")
prof.win_show(tag, message)

Show a message in the plugin window.

Parameters:
  • tag (str or unicode) – The tag of the window to display the message
  • message (str or unicode) – the message to print

Example:

prof.win_show("My Plugin", "This will appear in the plugin window")
prof.win_show_themed(tag, group, key, default, message)

Show a message in the plugin window, using the specified theme.

Themes are specified in ~/.local/share/profanity/plugin_themes

Parameters:
  • tag (str or unicode) – The tag of the window to display the message
  • group (str, unicode or None) – the group name in the themes file
  • key (str, unicode or None) – the item name within the group
  • default (str, unicode or None) – default colour if the theme cannot be found
  • message (str or unicode) – the message to print

Example:

prof.win_show_themed("My Plugin", "myplugin", "text", None, "Plugin themed message")

Previous topic

Profanity Python Plugins API

Next topic

plugin module