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")

prof module¶

Previous topic

Next topic

Navigation

prof module¶

Previous topic

Next topic

Quick search

Navigation