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.

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:
+def win_create(tag: str, callback: WindowCallback) -> None:
-    """Creates a new plugin window with the specified tag.
+    """Creates a plugin window with the specified tag.
 
-    The callback function is invoked when the window receives input, taking a
+    The callback processes input messages, typically using the model from the window
-    single string argument representing the input line.
+    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
+        callback: Function to process window input, taking the window tag and message.
-            argument.
 
     Returns:
         None
@@ -282,10 +282,10 @@ def win_create(tag: str, callback: callable) -> None:
 
         ::
 
-            def window_handler(line: str) -> None:
+            def handler(win_id: str, message: str) -> None:
-                prof.win_show("MyPlugin", f"Received: {line}")
+                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: ...