diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index ea64ee67..d69f00b5 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,7 +114,7 @@ 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. @@ -144,7 +159,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: @@ -264,16 +279,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 +296,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