From cb6f30220875e70918258297737bb1cb0b8aa3ec Mon Sep 17 00:00:00 2001 From: Jabber Developer Date: Mon, 15 Sep 2025 14:31:16 +0200 Subject: [PATCH] docs(prof.py): add CommandCallback, TimedCallback, WindowCallback protocols - Defined callback protocols for register_command, register_timed, win_create. - Fixed Sphinx callable warnings with proper type hints. - Align docs with the code --- apidocs/python/src/prof.py | 66 ++++++++++++++++++++++++-------------- 1 file changed, 42 insertions(+), 24 deletions(-) diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index ea64ee67..1902faaf 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -10,6 +10,21 @@ 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.""" + def __call__(self, *command_parameters: str) -> None: ... + +class TimedCallback(Protocol): + """Protocol for timed callbacks accepting no arguments.""" + def __call__(self) -> None: ... + +class WindowCallback(Protocol): + """Protocol for window callbacks accepting a window ID and message.""" + def __call__(self, win_id: str, message: str) -> None: ... # Console Functions # ----------------- @@ -99,13 +114,13 @@ def register_command( description: str, arguments: list[list[str]], examples: list[str], - callback: callable, + 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 should accept a list of strings - representing the command arguments. + the command is invoked. The callback function accepts variable string arguments + representing the command parameters. Args: name: The command name, including the leading slash (e.g., ``/say``). @@ -115,8 +130,7 @@ def register_command( 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. + callback: Function to call when the command is executed, taking variable string arguments. Returns: None @@ -125,18 +139,24 @@ def register_command( :: - def my_command(args: list[str]) -> None: + 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 = ["/newcommand action1|action2", "/newcommand print "] - description = "Performs an action or prints an argument." + synopsis = ["/new_command on|off", "/new_command print "] + description = "Enables, disables, or prints an argument." arguments = [ - ["action1|action2", "Perform action1 or action2"], - ["print ", "Print the argument"] + ["on|off", "Enable or disable something."], + ["print ", "Print the argument."] ] - examples = ["/newcommand action1", "/newcommand print 'test'"] + examples = ["/new_command on", "/new_command print 'test'"] prof.register_command( - "/newcommand", 1, 2, synopsis, description, arguments, examples, my_command + "/new_command", 1, 2, synopsis, description, arguments, examples, command_handler ) """ pass @@ -144,7 +164,7 @@ def register_command( # Periodic Callback # ----------------- -def register_timed(callback: callable, interval: int) -> None: +def register_timed(callback: TimedCallback, interval: int) -> None: """Registers a function to be called periodically by CProof. Args: @@ -175,8 +195,7 @@ def completer_add(key: str, items: list[str]) -> None: list. Args: - key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or - ``/mycommand action``). + key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or ``/mycommand action``). items: The items to return on autocompletion. Returns: @@ -264,16 +283,15 @@ def win_exists(tag: str) -> bool: """ pass -def win_create(tag: str, callback: callable) -> None: - """Creates a new plugin window with the specified tag. +def win_create(tag: str, callback: WindowCallback) -> None: + """Creates a 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. + The callback processes input messages, typically using the model from the window + title, and is called with the window tag and message. Args: tag: The tag identifying the plugin window. - callback: Function to call when the window receives input, taking a string - argument. + callback: Function to process window input, taking the window tag and message. Returns: None @@ -282,10 +300,10 @@ def win_create(tag: str, callback: callable) -> None: :: - def window_handler(line: str) -> None: - prof.win_show("MyPlugin", f"Received: {line}") + def handler(win_id: str, message: str) -> None: + prof.win_show(win_id, f"Processed: {message}") - prof.win_create("MyPlugin", window_handler) + prof.win_create("MyPlugin", handler) """ pass