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 behaviourmessage (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 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)
- 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 behaviourmessage (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_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 exist- Return 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 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_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")