diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index 64b3ab13..ea64ee67 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -1,903 +1,1193 @@ """ -This module contains the functions available to plugins to interact with Profanity. +The prof module provides a Python API for plugins to interact with CProof. +Plugins must import this module to access its functions: -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. +Functions are grouped into sections for console interaction, command management, +autocompletion, window management, chat and room messaging, XMPP operations, +settings, user/room information, and notifications/logging. """ +# Console Functions +# ----------------- -def cons_alert(): - """ - Highlights the console window in the status bar. - """ - pass +def cons_alert() -> None: + """Highlights the console window in the CProof status bar to indicate activity. + Args: + None -def cons_show(message): - """Show a message in the console window. - - :param message: the message to print - :type message: str or unicode + Returns: + None Example: - :: - prof.cons_show("This will appear in the console window") + + :: + + prof.cons_alert() # Highlights the console window """ pass +def cons_show(message: str) -> None: + """Displays a message in the CProof console window. -def cons_show_themed(group, key, default, message): - """Show a message in the console, using the specified theme.\n - Themes are specified in ``~/.local/share/profanity/plugin_themes`` + Args: + message: The message to display. - :param group: the group name in the themes file - :param key: the item name within the group - :param default: default colour if the theme cannot be found - :param message: the message to print - :type group: str, unicode or None - :type key: str, unicode or None - :type default: str, unicode or None - :type message: str or unicode + Returns: + None Example: - :: - prof.cons_show_themed("myplugin", "text", None, "Plugin themed message") + + :: + + prof.cons_show("This appears in the console window") """ pass +def cons_show_themed(group: str | None, key: str | None, default: str | None, message: str) -> None: + """Displays a message in the console window using a specified theme. -def cons_bad_cmd_usage(command): - """Show a message indicating the command has been called incorrectly. + Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is + not found, the default color is used. - :param command: the command name with leading slash, e.g. ``"/say"`` - :type command: str or unicode + Args: + group: The theme group name, or None to use default styling. + key: The item name within the group, or None to use default styling. + default: The default color if the theme is not found, or None for no color. + message: The message to display. + + Returns: + None Example: - :: - prof.cons_bad_cmd_usage("/mycommand") + + :: + + prof.cons_show_themed("myplugin", "text", "white", "Themed message") """ pass +def cons_bad_cmd_usage(command: str) -> None: + """Displays an error message in the console for incorrect command usage. -def register_command(name, min_args, max_args, synopsis, description, arguments, examples, callback): - """Register a new command, with help information, and callback for command execution.\n - Profanity will do some basic validation when the command is called using the argument range. + Args: + command: The command name, including the leading slash (e.g., ``/say``). - :param name: the command name with leading slash, e.g. ``"/say"`` - :param min_args: minimum number or arguments that the command considers to be a valid call - :param max_args: maximum number or arguments that the command considers to be a valid call - :param synopsis: command usages - :param description: a short description of the command - :param arguments: argument descriptions, each element should be of the form [arguments, description] - :param examples: example usages - :param callback: function to call when the command is executed - :type name: str or unicode - :type min_args: int - :type max_args: int - :type synopsis: list of str or unicode - :type description: str or unicode - :type arguments: list of list of str or unicode - :type examples: list of str or unicode - :type callback: function + Returns: + None Example: - :: - synopsis = [ - "/newcommand action1|action2", - "/newcommand print ", - "/newcommand dosomething []" - ] - description = "An example for the documentation" - args = [ - [ "action1|action2", "Perform action1 or action2" ], - [ "print ", "Print argument" ], - [ "dosomething []", "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.cons_bad_cmd_usage("/mycommand") # Shows usage error for /mycommand """ pass +# Command Management +# ------------------ -def register_timed(callback, interval): - """Register a function that Profanity will call periodically. +def register_command( + name: str, + min_args: int, + max_args: int, + synopsis: list[str], + description: str, + arguments: list[list[str]], + examples: list[str], + callback: callable, +) -> None: + """Registers a new command in CProof with help information and a callback. - :param callback: the function to call - :param interval: the time between each call to the function, in seconds - :type callback: function - :type interval: int + CProof validates the number of arguments (between min_args and max_args) when + the command is invoked. The callback function should accept a list of strings + representing the command arguments. + + Args: + name: The command name, including the leading slash (e.g., ``/say``). + min_args: Minimum number of arguments required. + max_args: Maximum number of arguments allowed. + synopsis: List of command usage strings. + description: Short description of the command. + arguments: List of [argument, description] pairs for help text. + examples: List of example command invocations. + callback: Function to call when the command is executed, taking a list of + strings as arguments. + + Returns: + None Example: - :: - prof.register_timed(some_function, 30) + + :: + + def my_command(args: list[str]) -> None: + prof.cons_show(f"Received: {args}") + + synopsis = ["/newcommand action1|action2", "/newcommand print "] + description = "Performs an action or prints an argument." + arguments = [ + ["action1|action2", "Perform action1 or action2"], + ["print ", "Print the argument"] + ] + examples = ["/newcommand action1", "/newcommand print 'test'"] + prof.register_command( + "/newcommand", 1, 2, synopsis, description, arguments, examples, my_command + ) """ pass +# Periodic Callback +# ----------------- -def 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. +def register_timed(callback: callable, interval: int) -> None: + """Registers a function to be called periodically by CProof. - :param key: the prefix to trigger autocompletion - :param items: the items to return on autocompletion - :type key: str or unicode - :type items: list of str or unicode + Args: + callback: The function to call periodically. + interval: The time between calls, in seconds. - Examples: - :: - prof.completer_add("/mycommand", [ - "action1", - "action2", - "dosomething" - ]) - - prof.completer_add("/mycommand dosomething", [ - "thing1", - "thing2" - ]) - """ - pass - - -def completer_remove(key, items): - """Remove values from autocompletion for a command, or command argument. - - :param key: the prefix from which to remove the autocompletion items - :param items: the items to remove - :type key: str or unicode - :type items: list of str or unicode - - Examples: - :: - prof.completer_remove("/mycommand", [ - "action1", - "action2" - ]) - - prof.completer_add("/mycommand dosomething", [ - "thing1" - ]) - """ - pass - - -def completer_clear(key): - """Remove all values from autocompletion for a command, or command argument. - - :param key: the prefix from which to clear the autocompletion items - - Examples: - :: - prof.completer_clear("/mycommand") - - prof.completer_add("/mycommand dosomething") - """ - pass - - -def filepath_completer_add(prefix): - """Add filepath autocompletion for a command, or command argument. - - :param prefix: the prefix from which filepath autocompletion will be triggered - - Examples: - :: - prof.filepath_completer_add("/filecmd") - - prof.filepath_completer_add("/mycommand open") - """ - pass - - -def send_line(line): - """Send a line of input to Profanity to execute. - - :param line: the line to send - :type line: str or unicode + Returns: + None Example: - :: - prof.send_line("/who online") + + :: + + def periodic_task() -> None: + prof.cons_show("Periodic update") + + prof.register_timed(periodic_task, 30) # Calls every 30 seconds """ pass +# Autocompletion +# -------------- -def notify(message, timeout, category): - """Send a desktop notification. +def completer_add(key: str, items: list[str]) -> None: + """Adds values for autocompletion of a command or command argument. - :param message: the message to display in the notification - :param timeout: the length of time before the notification disappears in milliseconds - :param category: the category of the notification, also displayed - :type message: str or unicode - :type timeout: int - :type category: str or unicode + If the key already exists, the items are appended to the existing autocomplete + list. + + Args: + key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or + ``/mycommand action``). + items: The items to return on autocompletion. + + Returns: + None Example: - :: - prof.notify("Example notification for 5 seconds", 5000, "Example plugin") + + :: + + prof.completer_add("/mycommand", ["action1", "action2"]) + prof.completer_add("/mycommand dosomething", ["thing1", "thing2"]) """ pass +def completer_remove(key: str, items: list[str]) -> None: + """Removes values from autocompletion for a command or command argument. -def get_current_recipient(): - """Retrieve the Jabber ID of the current chat recipient, when in a chat window. + Args: + key: The prefix from which to remove autocomplete items (e.g., ``/mycommand``). + items: The items to remove from the autocomplete list. - :return: the Jabber ID of the current chat recipient e.g. ``"buddy@chat.org"``, or ``None`` if not in a chat window. - :rtype: str - """ - pass - - -def get_current_muc(): - """Retrieve the Jabber ID of the current room, when in a chat room window. - - :return: the Jabber ID of the current chat room e.g. ``"metalchat@conference.chat.org"``, or ``None`` if not in a chat room window. - :rtype: str - """ - pass - - -def get_current_nick(): - """Retrieve the users nickname in a chat room, when in a chat room window. - - :return: the users nickname in the current chat room e.g. ``"eddie"``, or ``None`` if not in a chat room window. - :rtype: str - """ - pass - - -def get_name_from_roster(barejid): - """Retrieve a nickname from a barejid if it is in the roster. - - :return: the users nickname e.g. "eddie", or the input barejid if it is not in the roster. - :rtype: str - """ - pass - - -def get_barejid_from_roster(name): - """Retrieve the barejid for a given nickname if it is in the roster. - - :return: the users barejid e.g. "eddie@server.tld", or ``None`` if the nickname is not in the roster. - :rtype: str - """ - pass - - -def get_current_occupants(): - """Retrieve nicknames of all occupants in a chat room, when in a chat room window. - - :return: nicknames of all occupants in the current room or an empty list if not in a chat room window. - :rtype: list of str - """ - pass - - -def get_room_nick(barejid): - """Retrieve current nickname used in chat room. - - :return: Room nickname. - :rtype: str - """ - pass - - -def current_win_is_console(): - """Determine whether or not the Console window is currently focused. - - :return: ``True`` if the user is currently in the Console window, ``False`` otherwise. - :rtype: boolean - """ - pass - - -def log_debug(message): - """Write to the Profanity log at level ``DEBUG``. - - :param message: the message to log - :type message: str or unicode - """ - pass - - -def log_info(): - """Write to the Profanity log at level ``INFO``. - - :param message: the message to log - :type message: str or unicode - """ - pass - - -def log_warning(): - """Write to the Profanity log at level ``WARNING``. - - :param message: the message to log - :type message: str or unicode - """ - pass - - -def log_error(): - """Write to the Profanity log at level ``ERROR``. - - :param message: the message to log - :type message: str or unicode - """ - pass - - -def win_exists(tag): - """Determine whether or not a plugin window currently exists for the tag. - - :param tag: The tag used when creating the plugin window - :type tag: str or unicode - :return: ``True`` if the window exists, ``False`` otherwise. - :rtype: boolean + Returns: + None Example: - :: - prof.win_exists("My Plugin") + + :: + + prof.completer_remove("/mycommand", ["action1", "action2"]) """ pass +def completer_clear(key: str) -> None: + """Clears all autocomplete values for a command or command argument. -def win_create(tag, callback): - """Create a plugin window. + Args: + key: The prefix to clear autocomplete items for (e.g., ``/mycommand``). - :param tag: The tag used to refer to the window - :type tag: str or unicode - :param callback: function to call when the window receives input - :type callback: function + Returns: + None Example: - :: - prof.win_create("My Plugin", window_handler) + + :: + + prof.completer_clear("/mycommand") """ pass +def filepath_completer_add(prefix: str) -> None: + """Enables filepath autocompletion for a command or command argument. -def win_focus(tag): - """Focus a plugin window. + Args: + prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``). - :param tag: The tag of the window to focus - :type tag: str or unicode + Returns: + None Example: - :: - prof.win_focus("My Plugin") + + :: + + prof.filepath_completer_add("/filecmd") # Enables filepath completion """ pass +# Window Management +# ----------------- -def win_show(tag, message): - """Show a message in the plugin window. +def win_exists(tag: str) -> bool: + """Checks if a plugin window with the specified tag exists. - :param tag: The tag of the window to display the message - :type tag: str or unicode - :param message: the message to print - :type message: str or unicode + Args: + tag: The tag identifying the plugin window. + + Returns: + bool: True if the window exists, False otherwise. Example: - :: - prof.win_show("My Plugin", "This will appear in the plugin window") + + :: + + if prof.win_exists("MyPlugin"): + prof.cons_show("Window exists") """ pass +def win_create(tag: str, callback: callable) -> None: + """Creates a new plugin window with the specified tag. -def win_show_themed(tag, group, key, default, message): - """Show a message in the plugin window, using the specified theme.\n - Themes are specified in ``~/.local/share/profanity/plugin_themes`` + The callback function is invoked when the window receives input, taking a + single string argument representing the input line. - :param tag: The tag of the window to display the message - :type tag: str or unicode - :param group: the group name in the themes file - :param key: the item name within the group - :param default: default colour if the theme cannot be found - :param message: the message to print - :type group: str, unicode or None - :type key: str, unicode or None - :type default: str, unicode or None - :type message: str or unicode + Args: + tag: The tag identifying the plugin window. + callback: Function to call when the window receives input, taking a string + argument. + + Returns: + None Example: - :: - prof.win_show_themed("My Plugin", "myplugin", "text", None, "Plugin themed message") + + :: + + def window_handler(line: str) -> None: + prof.win_show("MyPlugin", f"Received: {line}") + + prof.win_create("MyPlugin", window_handler) """ pass +def win_focus(tag: str) -> None: + """Focuses the plugin window with the specified tag. -def send_stanza(stanza): - """Send an XMPP stanza + Args: + tag: The tag identifying the plugin window. - :param stanza: An XMPP stanza - :type stanza: str or unicode - :return: ``True`` if the stanza was sent successfully, ``False`` otherwise - :rtype: boolean + Returns: + None Example: - :: - prof.send_stanza("") + + :: + + prof.win_focus("MyPlugin") # Focuses the MyPlugin window """ pass +def win_show(tag: str, message: str) -> None: + """Displays a message in the plugin window with the specified tag. -def settings_boolean_get(group, key, default): - """Get a boolean setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings`` + Args: + tag: The tag identifying the plugin window. + message: The message to display. - :param group: the group name in the settings file - :param key: the item name within the group - :param default: default value if setting not found - :type group: str or unicode - :type key: str or unicode - :type default: boolean + Returns: + None Example: - :: - prof.settings_boolean_get("myplugin", "notify", False) + + :: + + prof.win_show("MyPlugin", "Message in plugin window") """ pass +def win_show_themed(tag: str, group: str | None, key: str | None, default: str | None, message: str) -> None: + """Displays a message in the plugin window using a specified theme. -def settings_boolean_set(group, key, value): - """Set a boolean setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings`` + Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is + not found, the default color is used. - :param group: the group name in the settings file - :param key: the item name within the group - :param value: value to set - :type group: str or unicode - :type key: str or unicode - :type value: boolean + Args: + tag: The tag identifying the plugin window. + group: The theme group name, or None to use default styling. + key: The item name within the group, or None to use default styling. + default: The default color if the theme is not found, or None for no color. + message: The message to display. + + Returns: + None Example: - :: - prof.settings_boolean_set("myplugin", "activate", True) + + :: + + prof.win_show_themed("MyPlugin", "myplugin", "text", "white", "Themed message") """ pass +# Chat and Room Messaging +# ----------------------- -def settings_string_get(group, key, default): - """Get a string setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings`` +def chat_show(barejid: str, message: str) -> bool: + """Displays a message in the chat window for the specified contact. - :param group: the group name in the settings file - :param key: the item name within the group - :param default: default value if setting not found - :type group: str or unicode - :type key: str or unicode - :type default: str + Args: + barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + message: The message to display. + + Returns: + bool: True if the message was displayed, False if the chat window does not + exist. Example: - :: - prof.settings_string_get("myplugin", "prefix", "prefix-->") + + :: + + if prof.chat_show("bob@example.com", "Hello from plugin"): + prof.cons_show("Message displayed") """ pass +def chat_show_themed( + barejid: str, + group: str | None, + key: str | None, + default: str | None, + ch: str | None, + message: str, +) -> bool: + """Displays a message in the chat window with a theme and prefix character. -def settings_string_set(group, key, value): - """Set a string setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings`` + Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is + not found, the default color is used. - :param group: the group name in the settings file - :param key: the item name within the group - :param value: value to set - :type group: str or unicode - :type key: str or unicode - :type value: str + Args: + barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + group: The theme group name, or None to use default styling. + key: The item name within the group, or None to use default styling. + default: The default color if the theme is not found, or None for no color. + ch: The prefix character to display, or None for default behavior. + message: The message to display. + + Returns: + bool: True if the message was displayed, False if the chat window does not + exist. Example: - :: - prof.settings_string_set("myplugin", "prefix", "myplugin, ") + + :: + + prof.chat_show_themed("bob@example.com", "myplugin", "text", None, "!", "Themed message") """ pass +def room_show(roomjid: str, message: str) -> bool: + """Displays a message in the chat room window for the specified room. -def settings_string_list_get(group, key): - """Get a string list setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings``\n - The string list setting items are separated by semicolons. + Args: + roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + message: The message to display. - :param group: the group name in the settings file - :param key: the item name within the group - :type group: str or unicode - :type key: str or unicode - :return: the list setting - :rtype: list of str or unicode + Returns: + bool: True if the message was displayed, False if the room window does not + exist. Example: - :: - prof.settings_string_list_get("someplugin", "somelist") + + :: + + prof.room_show("chat@conference.example.com", "Room message from plugin") """ pass +def room_show_themed( + roomjid: str, + group: str | None, + key: str | None, + default: str | None, + ch: str | None, + message: str, +) -> bool: + """Displays a message in the chat room window with a theme and prefix character. -def settings_string_list_add(group, key, value): - """Add an item to a string list setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings``\n - If the list does not exist, a new one will be created with the element added + Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is + not found, the default color is used. - :param group: the group name in the settings file - :param key: the item name within the group - :param value: item to add - :type group: str or unicode - :type key: str or unicode - :type value: str + Args: + roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + group: The theme group name, or None to use default styling. + key: The item name within the group, or None to use default styling. + default: The default color if the theme is not found, or None for no color. + ch: The prefix character to display, or None for default behavior. + message: The message to display. + + Returns: + bool: True if the message was displayed, False if the room window does not + exist. Example: - :: - prof.settings_string_list_add("someplugin", "somelist", "anelement") + + :: + + prof.room_show_themed("chat@conference.example.com", "myplugin", "text", None, "!", "Themed room message") """ pass +# XMPP Operations +# --------------- -def settings_string_list_remove(group, key, value): - """Remove an item from a string list setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings``\n +def send_line(line: str) -> None: + """Sends a line of input to CProof for execution, as if typed by the user. - :param group: the group name in the settings file - :param key: the item name within the group - :param value: item to remove - :type group: str or unicode - :type key: str or unicode - :type value: str - :return: ``True`` if the item was removed, or is not in the list, ``False`` if the list does not exist - :rtype: boolean + Args: + line: The input line to execute (e.g., ``/who online``). + + Returns: + None Example: - :: - prof.settings_string_list_remove("someplugin", "somelist", "anelement") + + :: + + prof.send_line("/who online") # Executes the /who online command """ pass +def send_stanza(stanza: str) -> bool: + """Sends an XMPP stanza to the server. -def settings_string_list_clear(group, key): - """Remove all items from a string list setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings``\n + Args: + stanza: The XMPP stanza to send (e.g., an IQ or message stanza). - :param group: the group name in the settings file - :param key: the item name within the group - :type group: str or unicode - :type key: str or unicode - :return: ``True`` if the list was cleared, ``False`` if the list does not exist - :rtype: boolean + Returns: + bool: True if the stanza was sent successfully, False if it was invalid or + failed to send. Example: - :: - prof.settings_string_list_clear("someplugin", "somelist") + + :: + + stanza = "" + if prof.send_stanza(stanza): + prof.cons_show("Stanza sent successfully") """ pass +def incoming_message(barejid: str, resource: str, message: str) -> None: + """Triggers CProof to handle an incoming message as if received from a contact. -def settings_int_get(group, key, default): - """Get an integer setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings`` + Args: + barejid: The Jabber ID of the sender (e.g., ``bob@example.com``). + resource: The sender's resource (e.g., ``laptop``). + message: The message text. - :param group: the group name in the settings file - :param key: the item name within the group - :param default: default value if setting not found - :type group: str or unicode - :type key: str or unicode - :type default: int + Returns: + None Example: - :: - prof.settings_int_get("myplugin", "timeout", 10) + + :: + + prof.incoming_message("bob@example.com", "laptop", "Hello from plugin") """ pass +def disco_add_feature(feature: str) -> None: + """Adds a service discovery feature to CProof's supported features. -def settings_int_set(group, key, value): - """Set an integer setting\n - Settings must be specified in ``~/.local/share/profanity/plugin_settings`` + If a session is active, a presence update is sent to refresh client/server + feature caches. - :param group: the group name in the settings file - :param key: the item name within the group - :param value: value to set - :type group: str or unicode - :type key: str or unicode - :type value: int + Args: + feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``). + + Returns: + None Example: - :: - prof.settings_int_set("myplugin", "timeout", 100) + + :: + + prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify") """ pass +def encryption_reset(barejid: str) -> None: + """Ends any encrypted session with the specified contact. -def incoming_message(barejid, resource, message): - """Trigger incoming message handling, this plugin will make profanity act as if the message has been received + Args: + barejid: The Jabber ID of the contact (e.g., ``alice@example.com``). - :param barejid: Jabber ID of the sender of the message - :param resource: resource of the sender of the message - :param message: the message text - :type barejid: str or unicode - :type resource: str or unicode - :type message: str or unicode + Returns: + None Example: - :: - prof.incoming_message("bob@server.org", "laptop", "Hello there") + + :: + + prof.encryption_reset("alice@example.com") # Resets encryption """ pass +def chat_set_titlebar_enctext(barejid: str, enctext: str) -> bool: + """Sets the encryption indicator text in the titlebar for a contact's chat window. -def disco_add_feature(feature): - """Add a service discovery feature the list supported by Profanity.\n - 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 + Args: + barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + enctext: The text to display in the titlebar. - :param feature: the service discovery feature to be added - :type feature: str + Returns: + bool: True if the text was set, False if the chat window does not exist. Example: - :: - prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify") + + :: + + prof.chat_set_titlebar_enctext("bob@example.com", "secure") """ pass +def chat_unset_titlebar_enctext(barejid: str) -> bool: + """Resets the encryption indicator text in the titlebar for a contact's chat window. -def encryption_reset(barejid): - """End any encrypted session with the specified user + CProof will determine the default text to display. - :param barejid: Jabber ID of the recipient - :type barejid: str or unicode + Args: + barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + + Returns: + bool: True if the text was reset, False if the chat window does not exist. Example: - :: - prof.encryption_reset("alice@server.org") + + :: + + prof.chat_unset_titlebar_enctext("bob@example.com") """ pass +def chat_set_incoming_char(barejid: str, ch: str) -> bool: + """Sets the prefix character for incoming messages from a contact. -def chat_set_titlebar_enctext(barejid, enctext): - """Set the text to display in the titlebar encryption indicator for recipient. + Args: + barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + ch: The prefix character to display. - :param barejid: Jabber ID of the recipient - :param enctext: The text to display - :type barejid: str or unicode - :type enctext: str or unicode - :return: ``True`` if the text was set successfully, ``False`` otherwise - :rtype: boolean + Returns: + bool: True if the character was set, False if the chat window does not exist. Example: - :: - prof.chat_set_titlebar_enctext("bob@chat.org", "safe") + + :: + + prof.chat_set_incoming_char("bob@example.com", "*") """ pass +def chat_unset_incoming_char(barejid: str) -> bool: + """Resets the prefix character for incoming messages from a contact. -def chat_unset_titlebar_enctext(barejid): - """Let profanity decide what to show in the titlebar encryption indicator for recipient. + Args: + barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - :param barejid: Jabber ID of the recipient - :type barejid: str or unicode - :return: ``True`` if the text was unset successfully, ``False`` otherwise - :rtype: boolean + Returns: + bool: True if the character was reset, False if the chat window does not exist. Example: - :: - prof.chat_unset_titlebar_enctext("bob@chat.org") + + :: + + prof.chat_unset_incoming_char("bob@example.com") """ pass +def chat_set_outgoing_char(barejid: str, ch: str) -> bool: + """Sets the prefix character for outgoing messages to a contact. -def chat_set_incoming_char(barejid, ch): - """Set the incoming message prefix character for specified contact. + Args: + barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + ch: The prefix character to display. - :param barejid: Jabber ID of the recipient - :param enctext: The character to display - :type barejid: str or unicode - :type enctext: str or unicode - :return: ``True`` if the character was set successfully, ``False`` otherwise - :rtype: boolean + Returns: + bool: True if the character was set, False if the chat window does not exist. Example: - :: - prof.chat_set_incoming_char("kristine@chat.org", "*") + + :: + + prof.chat_set_outgoing_char("bob@example.com", "+") """ pass +def chat_unset_outgoing_char(barejid: str) -> bool: + """Resets the prefix character for outgoing messages to a contact. -def chat_unset_incoming_char(barejid): - """Reset the incoming message prefix character for specified contact. + Args: + barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - :param barejid: Jabber ID of the recipient - :type barejid: str or unicode - :return: ``True`` if the char was unset successfully, ``False`` otherwise - :rtype: boolean + Returns: + bool: True if the character was reset, False if the chat window does not exist. Example: - :: - prof.chat_unset_incoming_char("kristine@chat.org") + + :: + + prof.chat_unset_outgoing_char("bob@example.com") """ pass +def room_set_titlebar_enctext(roomjid: str, enctext: str) -> bool: + """Sets the encryption indicator text in the titlebar for a room's chat window. -def chat_set_outgoing_char(barejid, ch): - """Set the outgoing message prefix character for specified contact. + Args: + roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + enctext: The text to display in the titlebar. - :param barejid: Jabber ID of the recipient - :param enctext: The character to display - :type barejid: str or unicode - :type enctext: str or unicode - :return: ``True`` if the character was set successfully, ``False`` otherwise - :rtype: boolean + Returns: + bool: True if the text was set, False if the room window does not exist. Example: - :: - prof.chat_set_outgoing_char("david@chat.org", "+") + + :: + + prof.room_set_titlebar_enctext("chat@conference.example.com", "secure") """ pass +def room_unset_titlebar_enctext(roomjid: str) -> bool: + """Resets the encryption indicator text in the titlebar for a room's chat window. -def chat_unset_outgoing_char(barejid): - """Reset the outgoing message prefix character for specified contact. + CProof will determine the default text to display. - :param barejid: Jabber ID of the recipient - :type barejid: str or unicode - :return: ``True`` if the char was unset successfully, ``False`` otherwise - :rtype: boolean + Args: + roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + + Returns: + bool: True if the text was reset, False if the room window does not exist. Example: - :: - prof.chat_unset_outgoing_char("david@chat.org") + + :: + + prof.room_unset_titlebar_enctext("chat@conference.example.com") """ pass +def room_set_message_char(roomjid: str, ch: str) -> bool: + """Sets the prefix character for messages in a chat room. -def room_set_titlebar_enctext(roomjid, enctext): - """Set the text to display in the titlebar encryption indicator for room. + Args: + roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + ch: The prefix character to display. - :param roomjid: Jabber ID of the room - :param enctext: The text to display - :type roomjid: str or unicode - :type enctext: str or unicode - :return: ``True`` if the text was set successfully, ``False`` otherwise - :rtype: boolean + Returns: + bool: True if the character was set, False if the room window does not exist. Example: - :: - prof.room_set_titlebar_enctext("generalchat@conference.service.com", "secret") + + :: + + prof.room_set_message_char("chat@conference.example.com", "^") """ pass +def room_unset_message_char(roomjid: str) -> bool: + """Resets the prefix character for messages in a chat room. -def room_unset_titlebar_enctext(roomjid): - """Let profanity decide what to show in the titlebar encryption indicator for room. + Args: + roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - :param roomjid: Jabber ID of the room - :type roomjid: str or unicode - :return: ``True`` if the text was unset successfully, ``False`` otherwise - :rtype: boolean + Returns: + bool: True if the character was reset, False if the room window does not exist. Example: - :: - prof.room_unset_titlebar_enctext("generalchat@conference.service.com") + + :: + + prof.room_unset_message_char("chat@conference.example.com") """ pass +# Settings Management +# ------------------- -def room_set_message_char(roomjid, ch): - """Set the message prefix character for specified room. +def settings_boolean_get(group: str, key: str, default: bool) -> bool: + """Retrieves a boolean setting from the CProof settings file. - :param roomjid: Jabber ID of the room - :param enctext: The character to display - :type roomjid: str or unicode - :type enctext: str or unicode - :return: ``True`` if the character was set successfully, ``False`` otherwise - :rtype: boolean + Settings are stored in ``~/.local/share/cproof/plugin_settings``. + + Args: + group: The group name in the settings file. + key: The item name within the group. + default: The default value if the setting is not found. + + Returns: + bool: The setting value, or the default if not found. Example: - :: - prof.room_set_message_char("ohnoes@conference.chat.org", "^") + + :: + + notify = prof.settings_boolean_get("myplugin", "notify", False) """ pass +def settings_boolean_set(group: str, key: str, value: bool) -> None: + """Sets a boolean setting in the CProof settings file. -def room_unset_message_char(roomjid): - """Reset the message prefix character for specified room. + Settings are stored in ``~/.local/share/cproof/plugin_settings``. - :param roomjid: Jabber ID of the room - :type roomjid: str or unicode - :return: ``True`` if the char was unset successfully, ``False`` otherwise - :rtype: boolean + Args: + group: The group name in the settings file. + key: The item name within the group. + value: The boolean value to set. + + Returns: + None Example: - :: - prof.room_unset_message_char("ohnoes@conference.chat.org") + + :: + + prof.settings_boolean_set("myplugin", "notify", True) """ pass +def settings_string_get(group: str, key: str, default: str) -> str: + """Retrieves a string setting from the CProof settings file. -def chat_show(barejid, message): - """Show a message in a chat window. + Settings are stored in ``~/.local/share/cproof/plugin_settings``. - :param barejid: Jabber ID of the recipient - :param message: the message to print - :type barejid: str or unicode - :type message: str or unicode - :return: ``True`` if the message was printed, ``False`` otherwise - :rtype: boolean + Args: + group: The group name in the settings file. + key: The item name within the group. + default: The default value if the setting is not found. + + Returns: + str: The setting value, or the default if not found. Example: - :: - prof.chat_show("bob@server.org", "From a plugin in the chat window for bob") + + :: + + prefix = prof.settings_string_get("myplugin", "prefix", "myplugin>") """ pass +def settings_string_set(group: str, key: str, value: str) -> None: + """Sets a string setting in the CProof settings file. -def chat_show_themed(barejid, group, key, default, ch, message): - """Show a message a chat window, using the specified theme and prefix character.\n - Themes are specified in ``~/.local/share/profanity/plugin_themes`` + Settings are stored in ``~/.local/share/cproof/plugin_settings``. - :param barejid: Jabber ID of the recipient - :param group: the group name in the themes file or ``None`` - :param key: the item name within the group or ``None`` - :param default: default colour if the theme cannot be found or ``None`` - :param ch: The prefix character to show, or ``None`` for default behaviour - :param message: the message to print - :type barejid: str or unicode - :type group: str, unicode or None - :type key: str, unicode or None - :type default: str, unicode or None - :type ch: str or unicode - :type message: str or unicode - :return: ``True`` if the message was printed, ``False`` otherwise - :rtype: boolean + Args: + group: The group name in the settings file. + key: The item name within the group. + value: The string value to set. + + Returns: + None Example: - :: - prof.chat_show_themed("bob@server.org", "myplugin", "text", None, "!", "Plugin themed message") + + :: + + prof.settings_string_set("myplugin", "prefix", "myplugin>") """ pass +def settings_string_list_get(group: str, key: str) -> list[str]: + """Retrieves a list of strings from a setting in the CProof settings file. -def room_show(roomjid, message): - """Show a message in a chat room window. + Settings are stored in ``~/.local/share/cproof/plugin_settings``, with list items + separated by semicolons. - :param roomjid: Jabber ID of the room - :param message: the message to print - :type roomjid: str or unicode - :type message: str or unicode - :return: ``True`` if the message was printed, ``False`` otherwise - :rtype: boolean + Args: + group: The group name in the settings file. + key: The item name within the group. + + Returns: + list[str]: The list of strings, or an empty list if the setting does not + exist. Example: - :: - prof.room_show("chat@conference.chat.org", "From a plugin in the chat room window") + + :: + + items = prof.settings_string_list_get("myplugin", "items") """ pass +def settings_string_list_add(group: str, key: str, value: str) -> None: + """Adds a string to a list setting in the CProof settings file. -def room_show_themed(roomjid, group, key, default, ch, message): - """Show a message a chat room window, using the specified theme and prefix character.\n - Themes are specified in ``~/.local/share/profanity/plugin_themes`` + If the list does not exist, it is created with the new item. Settings are + stored in ``~/.local/share/cproof/plugin_settings``. - :param roomjid: Jabber ID of the room - :param group: the group name in the themes file or ``None`` - :param key: the item name within the group or ``None`` - :param default: default colour if the theme cannot be found or ``None`` - :param ch: The prefix character to show, or ``None`` for default behaviour - :param message: the message to print - :type roomjid: str or unicode - :type group: str, unicode or None - :type key: str, unicode or None - :type default: str, unicode or None - :type ch: str or unicode - :type message: str or unicode - :return: ``True`` if the message was printed, ``False`` otherwise - :rtype: boolean + Args: + group: The group name in the settings file. + key: The item name within the group. + value: The string to add to the list. + + Returns: + None Example: - :: - prof.room_show_themed("chat@conference.chat.org", "myplugin", "text", None, "!", "Plugin themed message") + + :: + + prof.settings_string_list_add("myplugin", "items", "item1") + """ + pass + +def settings_string_list_remove(group: str, key: str, value: str) -> bool: + """Removes a string from a list setting in the CProof settings file. + + Settings are stored in ``~/.local/share/cproof/plugin_settings``. + + Args: + group: The group name in the settings file. + key: The item name within the group. + value: The string to remove from the list. + + Returns: + bool: True if the item was removed or not in the list, False if the list + does not exist. + + Example: + + :: + + prof.settings_string_list_remove("myplugin", "items", "item1") + """ + pass + +def settings_string_list_clear(group: str, key: str) -> bool: + """Clears all items from a list setting in the CProof settings file. + + Settings are stored in ``~/.local/share/cproof/plugin_settings``. + + Args: + group: The group name in the settings file. + key: The item name within the group. + + Returns: + bool: True if the list was cleared, False if the list does not exist. + + Example: + + :: + + prof.settings_string_list_clear("myplugin", "items") + """ + pass + +def settings_int_get(group: str, key: str, default: int) -> int: + """Retrieves an integer setting from the CProof settings file. + + Settings are stored in ``~/.local/share/cproof/plugin_settings``. + + Args: + group: The group name in the settings file. + key: The item name within the group. + default: The default value if the setting is not found. + + Returns: + int: The setting value, or the default if not found. + + Example: + + :: + + timeout = prof.settings_int_get("myplugin", "timeout", 10) + """ + pass + +def settings_int_set(group: str, key: str, value: int) -> None: + """Sets an integer setting in the CProof settings file. + + Settings are stored in ``~/.local/share/cproof/plugin_settings``. + + Args: + group: The group name in the settings file. + key: The item name within the group. + value: The integer value to set. + + Returns: + None + + Example: + + :: + + prof.settings_int_set("myplugin", "timeout", 100) + """ + pass + +# User and Room Information +# ------------------------- + +def get_current_recipient() -> str | None: + """Retrieves the Jabber ID of the current chat recipient. + + Args: + None + + Returns: + str | None: The Jabber ID of the recipient (e.g., ``bob@example.com``), or + None if not in a chat window. + + Example: + + :: + + recipient = prof.get_current_recipient() + if recipient: + prof.cons_show(f"Chatting with: {recipient}") + """ + pass + +def get_current_muc() -> str | None: + """Retrieves the Jabber ID of the current chat room. + + Args: + None + + Returns: + str | None: The Jabber ID of the room (e.g., ``chat@conference.example.com``), + or None if not in a chat room window. + + Example: + + :: + + room = prof.get_current_muc() + if room: + prof.cons_show(f"In room: {room}") + """ + pass + +def get_current_nick() -> str | None: + """Retrieves the user's nickname in the current chat room. + + Args: + None + + Returns: + str | None: The user's nickname (e.g., ``alice``), or None if not in a chat + room window. + + Example: + + :: + + nick = prof.get_current_nick() + if nick: + prof.cons_show(f"Nickname: {nick}") + """ + pass + +def get_name_from_roster(barejid: str) -> str: + """Retrieves the nickname for a Jabber ID from the roster. + + Args: + barejid: The Jabber ID to look up (e.g., ``bob@example.com``). + + Returns: + str: The nickname from the roster, or the input barejid if not found. + + Example: + + :: + + name = prof.get_name_from_roster("bob@example.com") + prof.cons_show(f"Name: {name}") + """ + pass + +def get_barejid_from_roster(name: str) -> str | None: + """Retrieves the Jabber ID for a nickname from the roster. + + Args: + name: The nickname to look up. + + Returns: + str | None: The Jabber ID (e.g., ``bob@example.com``), or None if the + nickname is not in the roster. + + Example: + + :: + + jid = prof.get_barejid_from_roster("bob") + if jid: + prof.cons_show(f"JID: {jid}") + """ + pass + +def get_current_occupants() -> list[str]: + """Retrieves the nicknames of all occupants in the current chat room. + + Args: + None + + Returns: + list[str]: List of occupant nicknames, or an empty list if not in a chat + room window. + + Example: + + :: + + occupants = prof.get_current_occupants() + prof.cons_show(f"Occupants: {', '.join(occupants)}") + """ + pass + +def get_room_nick(barejid: str) -> str: + """Retrieves the user's nickname in the specified chat room. + + Args: + barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + + Returns: + str: The user's nickname in the room. + + Example: + + :: + + nick = prof.get_room_nick("chat@conference.example.com") + prof.cons_show(f"Room nick: {nick}") + """ + pass + +def current_win_is_console() -> bool: + """Checks if the console window is currently focused. + + Args: + None + + Returns: + bool: True if the console window is focused, False otherwise. + + Example: + + :: + + if prof.current_win_is_console(): + prof.cons_show("Console is focused") + """ + pass + +# Notifications and Logging +# ------------------------- + +def notify(message: str, timeout: int, category: str) -> None: + """Sends a desktop notification through CProof. + + Args: + message: The notification message to display. + timeout: The duration before the notification disappears, in milliseconds. + category: The notification category, displayed with the message. + + Returns: + None + + Example: + + :: + + prof.notify("New message received", 5000, "MyPlugin") + """ + pass + +def log_debug(message: str) -> None: + """Logs a message to the CProof log at the DEBUG level. + + Args: + message: The message to log. + + Returns: + None + + Example: + + :: + + prof.log_debug("Debugging plugin initialization") + """ + pass + +def log_info(message: str) -> None: + """Logs a message to the CProof log at the INFO level. + + Args: + message: The message to log. + + Returns: + None + + Example: + + :: + + prof.log_info("Plugin started successfully") + """ + pass + +def log_warning(message: str) -> None: + """Logs a message to the CProof log at the WARNING level. + + Args: + message: The message to log. + + Returns: + None + + Example: + + :: + + prof.log_warning("Configuration issue detected") + """ + pass + +def log_error(message: str) -> None: + """Logs a message to the CProof log at the ERROR level. + + Args: + message: The message to log. + + Returns: + None + + Example: + + :: + + prof.log_error("Failed to connect to server") """ pass