cproof/apidocs/python/src/prof.py

"""
The prof module provides a Python API for plugins to interact with CProof.
Plugins must import this module to access its functions:

::

    import prof

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() -> None:
    """Highlights the console window in the CProof status bar to indicate activity.

    Args:
        None

    Returns:
        None

    Example:

        ::

            prof.cons_alert()  # Highlights the console window
    """
    pass

def cons_show(message: str) -> None:
    """Displays a message in the CProof console window.

    Args:
        message: The message to display.

    Returns:
        None

    Example:

        ::

            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.

    Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is
    not found, the default color is used.

    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_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.

    Args:
        command: The command name, including the leading slash (e.g., ``/say``).

    Returns:
        None

    Example:

        ::

            prof.cons_bad_cmd_usage("/mycommand")  # Shows usage error for /mycommand
    """
    pass

# Command Management
# ------------------

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.

    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:

        ::

            def my_command(args: list[str]) -> None:
                prof.cons_show(f"Received: {args}")

            synopsis = ["/newcommand action1|action2", "/newcommand print <arg>"]
            description = "Performs an action or prints an argument."
            arguments = [
                ["action1|action2", "Perform action1 or action2"],
                ["print <arg>", "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 register_timed(callback: callable, interval: int) -> None:
    """Registers a function to be called periodically by CProof.

    Args:
        callback: The function to call periodically.
        interval: The time between calls, in seconds.

    Returns:
        None

    Example:

        ::

            def periodic_task() -> None:
                prof.cons_show("Periodic update")

            prof.register_timed(periodic_task, 30)  # Calls every 30 seconds
    """
    pass

# Autocompletion
# --------------

def completer_add(key: str, items: list[str]) -> None:
    """Adds values for autocompletion of a command or command argument.

    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.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.

    Args:
        key: The prefix from which to remove autocomplete items (e.g., ``/mycommand``).
        items: The items to remove from the autocomplete list.

    Returns:
        None

    Example:

        ::

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

def completer_clear(key: str) -> None:
    """Clears all autocomplete values for a command or command argument.

    Args:
        key: The prefix to clear autocomplete items for (e.g., ``/mycommand``).

    Returns:
        None

    Example:

        ::

            prof.completer_clear("/mycommand")
    """
    pass

def filepath_completer_add(prefix: str) -> None:
    """Enables filepath autocompletion for a command or command argument.

    Args:
        prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``).

    Returns:
        None

    Example:

        ::

            prof.filepath_completer_add("/filecmd")  # Enables filepath completion
    """
    pass

# Window Management
# -----------------

def win_exists(tag: str) -> bool:
    """Checks if a plugin window with the specified tag exists.

    Args:
        tag: The tag identifying the plugin window.

    Returns:
        bool: True if the window exists, False otherwise.

    Example:

        ::

            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.

    The callback function is invoked when the window receives input, taking a
    single string argument representing the input line.

    Args:
        tag: The tag identifying the plugin window.
        callback: Function to call when the window receives input, taking a string
            argument.

    Returns:
        None

    Example:

        ::

            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.

    Args:
        tag: The tag identifying the plugin window.

    Returns:
        None

    Example:

        ::

            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.

    Args:
        tag: The tag identifying the plugin window.
        message: The message to display.

    Returns:
        None

    Example:

        ::

            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.

    Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is
    not found, the default color is used.

    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.win_show_themed("MyPlugin", "myplugin", "text", "white", "Themed message")
    """
    pass

# Chat and Room Messaging
# -----------------------

def chat_show(barejid: str, message: str) -> bool:
    """Displays a message in the chat window for the specified contact.

    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:

        ::

            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.

    Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is
    not found, the default color is used.

    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.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.

    Args:
        roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
        message: The message to display.

    Returns:
        bool: True if the message was displayed, False if the room window does not
            exist.

    Example:

        ::

            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.

    Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is
    not found, the default color is used.

    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.room_show_themed("chat@conference.example.com", "myplugin", "text", None, "!", "Themed room message")
    """
    pass

# XMPP Operations
# ---------------

def send_line(line: str) -> None:
    """Sends a line of input to CProof for execution, as if typed by the user.

    Args:
        line: The input line to execute (e.g., ``/who online``).

    Returns:
        None

    Example:

        ::

            prof.send_line("/who online")  # Executes the /who online command
    """
    pass

def send_stanza(stanza: str) -> bool:
    """Sends an XMPP stanza to the server.

    Args:
        stanza: The XMPP stanza to send (e.g., an IQ or message stanza).

    Returns:
        bool: True if the stanza was sent successfully, False if it was invalid or
            failed to send.

    Example:

        ::

            stanza = "<iq to='juliet@example.com' id='s2c1' type='get'><ping xmlns='urn:xmpp:ping'/></iq>"
            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.

    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.

    Returns:
        None

    Example:

        ::

            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.

    If a session is active, a presence update is sent to refresh client/server
    feature caches.

    Args:
        feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``).

    Returns:
        None

    Example:

        ::

            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.

    Args:
        barejid: The Jabber ID of the contact (e.g., ``alice@example.com``).

    Returns:
        None

    Example:

        ::

            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.

    Args:
        barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
        enctext: The text to display in the titlebar.

    Returns:
        bool: True if the text was set, False if the chat window does not exist.

    Example:

        ::

            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.

    CProof will determine the default text to display.

    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.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.

    Args:
        barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
        ch: The prefix character to display.

    Returns:
        bool: True if the character was set, False if the chat window does not exist.

    Example:

        ::

            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.

    Args:
        barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).

    Returns:
        bool: True if the character was reset, False if the chat window does not exist.

    Example:

        ::

            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.

    Args:
        barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
        ch: The prefix character to display.

    Returns:
        bool: True if the character was set, False if the chat window does not exist.

    Example:

        ::

            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.

    Args:
        barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).

    Returns:
        bool: True if the character was reset, False if the chat window does not exist.

    Example:

        ::

            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.

    Args:
        roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
        enctext: The text to display in the titlebar.

    Returns:
        bool: True if the text was set, False if the room window does not exist.

    Example:

        ::

            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.

    CProof will determine the default text to display.

    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.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.

    Args:
        roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
        ch: The prefix character to display.

    Returns:
        bool: True if the character was set, False if the room window does not exist.

    Example:

        ::

            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.

    Args:
        roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).

    Returns:
        bool: True if the character was reset, False if the room window does not exist.

    Example:

        ::

            prof.room_unset_message_char("chat@conference.example.com")
    """
    pass

# Settings Management
# -------------------

def settings_boolean_get(group: str, key: str, default: bool) -> bool:
    """Retrieves a boolean 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:
        bool: The setting value, or the default if not found.

    Example:

        ::

            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.

    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 boolean value to set.

    Returns:
        None

    Example:

        ::

            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.

    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:
        str: The setting value, or the default if not found.

    Example:

        ::

            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.

    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 value to set.

    Returns:
        None

    Example:

        ::

            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.

    Settings are stored in ``~/.local/share/cproof/plugin_settings``, with list items
    separated by semicolons.

    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:

        ::

            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.

    If the list does not exist, it is created with the new item. 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 add to the list.

    Returns:
        None

    Example:

        ::

            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