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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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 focused.
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_barejid_from_roster
(name)¶ Retrieve the barejid for a given nickname if it is in the roster.
Returns: the users barejid e.g. “eddie@server.tld”, or None
if the nickname is not in the roster.Return type: str
-
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"
, orNone
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"
, orNone
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"
, orNone
if not in a chat window.Return type: str
-
prof.
get_name_from_roster
(barejid)¶ Retrieve a nickname from a barejid if it is in the roster.
Returns: the users nickname e.g. “eddie”, or the input barejid if it is not in the roster. 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)
- name (str or unicode) – the command name with leading slash, e.g.
-
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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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
otherwiseReturn 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_boolean_get("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_boolean_set("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_int_get("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_int_set("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_string_get("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 existReturn type: boolean
Example:
prof.settings_string_list_clear("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_string_list_get("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 existReturn 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_string_set("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")