diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index ea64ee67..73f3d0b1 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -10,6 +10,7 @@ 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 # Console Functions # ----------------- @@ -99,7 +100,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 +145,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 +265,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 +282,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 @@ -1191,3 +1191,17 @@ def log_error(message: str) -> None: prof.log_error("Failed to connect to server") """ pass + +# 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: ...