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

from typing import Protocol

# Callback Protocols
# -----------------
class CommandCallback(Protocol):
    """Protocol for command callbacks accepting variable string arguments.

    :param command_parameters: Variable string arguments passed to the callback.
    :return: None

    Example::

        def my_command(*command_parameters: str) -> None:
            prof.cons_show(f"Received: {command_parameters}")

    .. :noindex:
    """
    def __call__(self, *command_parameters: str) -> None: ...

class TimedCallback(Protocol):
    """Protocol for timed callbacks accepting no arguments.

    :return: None

    Example::

        def my_timed_callback() -> None:
            prof.cons_show("Timer triggered")

    .. :noindex:
    """
    def __call__(self) -> None: ...

class WindowCallback(Protocol):
    """Protocol for window callbacks accepting a window ID and message.

    :param win_id: The window tag identifying the plugin window.
    :param message: The message to process.
    :return: None

    Example::

        def my_window_callback(win_id: str, message: str) -> None:
            prof.win_show(win_id, f"Processed: {message}")

    .. :noindex:
    """
    def __call__(self, win_id: str, message: str) -> None: ...

# Console Functions
# -----------------

def cons_alert() -> None:
    """Highlights the console window in the CProof status bar to indicate activity.

    :return: None

    Example::

        prof.cons_alert()  # Highlights the console window

    """
    pass

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

    :param message: The message to display.
    :return: 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.

    :param group: The theme group name, or None to use default styling.
    :param key: The item name within the group, or None to use default styling.
    :param default: The default color if the theme is not found, or None for no color.
    :param message: The message to display.
    :return: 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.

    :param command: The command name, including the leading slash (e.g., ``/say``).
    :return: 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: CommandCallback,
) -> 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 accepts variable string arguments
    representing the command parameters.

    :param name: The command name, including the leading slash (e.g., ``/say``).
    :param min_args: Minimum number of arguments required.
    :param max_args: Maximum number of arguments allowed.
    :param synopsis: List of command usage strings.
    :param description: Short description of the command.
    :param arguments: List of [argument, description] pairs for help text.
    :param examples: List of example command invocations.
    :param callback: Function to call when the command is executed, taking variable string arguments.
    :return: None

    Example::

        def command_handler(*args: str) -> None:
            prof.cons_show(f"Received: {args}")
            if len(args) == 1 and args[0] in ("on", "off"):
                prof.cons_show(f"{args[0].capitalize()}ing something")
            elif len(args) == 2 and args[0] == "print":
                prof.cons_show(args[1])
            else:
                prof.cons_bad_cmd_usage("/new_command")

        synopsis = ["/new_command on|off", "/new_command print <arg>"]
        description = "Enables, disables, or prints an argument."
        arguments = [
            ["on|off", "Enable or disable something."],
            ["print <arg>", "Print the argument."]
        ]
        examples = ["/new_command on", "/new_command print 'test'"]
        prof.register_command(
            "/new_command", 1, 2, synopsis, description, arguments, examples, command_handler
        )

    """
    pass

# Periodic Callback
# -----------------

def register_timed(callback: TimedCallback, interval: int) -> None:
    """Registers a function to be called periodically by CProof.

    :param callback: The function to call periodically.
    :param interval: The time between calls, in seconds.
    :return: 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.

    :param key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or ``/mycommand action``).
    :param items: The items to return on autocompletion.
    :return: 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.

    :param key: The prefix from which to remove autocomplete items (e.g., ``/mycommand``).
    :param items: The items to remove from the autocomplete list.
    :return: 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.

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

    Example::

        prof.completer_clear("/mycommand")

    """
    pass

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

    :param prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``).
    :return: 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.

    :param tag: The tag identifying the plugin window.
    :return: 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: WindowCallback) -> None:
    """Creates a plugin window with the specified tag.

    The callback processes input messages, typically using the model from the window
    title, and is called with the window tag and message.

    :param tag: The tag identifying the plugin window.
    :param callback: Function to process window input, taking the window tag and message.
    :return: None

    Example::

        def handler(win_id: str, message: str) -> None:
            prof.win_show(win_id, f"Processed: {message}")

        prof.win_create("MyPlugin", handler)

    """
    pass

def win_focus(tag: str) -> None:
    """Focuses the plugin window with the specified tag.

    :param tag: The tag identifying the plugin window.
    :return: 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.

    :param tag: The tag identifying the plugin window.
    :param message: The message to display.
    :return: 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.

    :param tag: The tag identifying the plugin window.
    :param group: The theme group name, or None to use default styling.
    :param key: The item name within the group, or None to use default styling.
    :param default: The default color if the theme is not found, or None for no color.
    :param message: The message to display.
    :return: 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.

    :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
    :param message: The message to display.
    :return: 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.

    :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
    :param group: The theme group name, or None to use default styling.
    :param key: The item name within the group, or None to use default styling.
    :param default: The default color if the theme is not found, or None for no color.
    :param ch: The prefix character to display, or None for default behavior.
    :param message: The message to display.
    :return: 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.

    :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param message: The message to display.
    :return: 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.

    :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param group: The theme group name, or None to use default styling.
    :param key: The item name within the group, or None to use default styling.
    :param default: The default color if the theme is not found, or None for no color.
    :param ch: The prefix character to display, or None for default behavior.
    :param message: The message to display.
    :return: 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.

    :param line: The input line to execute (e.g., ``/who online``).
    :return: 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.

    :param stanza: The XMPP stanza to send (e.g., an IQ or message stanza).
    :return: 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.

    :param barejid: The Jabber ID of the sender (e.g., ``bob@example.com``).
    :param resource: The sender's resource (e.g., ``laptop``).
    :param message: The message text.
    :return: 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.

    :param feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``).
    :return: 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.

    :param barejid: The Jabber ID of the contact (e.g., ``alice@example.com``).
    :return: 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.

    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
    :param enctext: The text to display in the titlebar.
    :return: 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.

    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
    :return: 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.

    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
    :param ch: The prefix character to display.
    :return: 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.

    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
    :return: 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.

    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
    :param ch: The prefix character to display.
    :return: 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.

    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
    :return: 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.

    :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param enctext: The text to display in the titlebar.
    :return: 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.

    :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :return: 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.

    :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param ch: The prefix character to display.
    :return: 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.

    :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :return: 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``.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :param default: The default value if the setting is not found.
    :return: 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``.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :param value: The boolean value to set.
    :return: 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``.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :param default: The default value if the setting is not found.
    :return: 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``.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :param value: The string value to set.
    :return: 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.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :return: 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``.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :param value: The string to add to the list.
    :return: 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``.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :param value: The string to remove from the list.
    :return: 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``.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :return: 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``.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :param default: The default value if the setting is not found.
    :return: 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``.

    :param group: The group name in the settings file.
    :param key: The item name within the group.
    :param value: The integer value to set.
    :return: 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.

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

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

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

    :param barejid: The Jabber ID to look up (e.g., ``bob@example.com``).
    :return: 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.

    :param name: The nickname to look up.
    :return: 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.

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

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :return: 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.

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

    :param message: The notification message to display.
    :param timeout: The duration before the notification disappears, in milliseconds.
    :param category: The notification category, displayed with the message.
    :return: 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.

    :param message: The message to log.
    :return: 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.

    :param message: The message to log.
    :return: 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.

    :param message: The message to log.
    :return: 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.

    :param message: The message to log.
    :return: None

    Example::

        prof.log_error("Failed to connect to server")

    """
    pass