docs

src/api_hook_client.py

@@ -1,3 +1,36 @@
+"""
+API Hook Client - Python client for the Hook API.
+
+This module provides a Python client for interacting with the Hook API exposed by the application on port 8999.
+ It is used for:
+ - Automated GUI testing via the `live_gui` pytest fixture
+ - External tool integration
+ - Remote control of the application
+
+Architecture:
+ - Uses requests library for HTTP communication
+ - All methods return dict[str, Any] or None
+ - Handles connection errors gracefully (returns None on failure)
+
+Key Method Categories:
+ 1. Connection: wait_for_server, get_status
+ 2. State Query: get_project, get_session. get_performance, get_mma_status
+ 3. GUI Manipulation: click, set_value, select_tab, select_list_item
+ 4. Polling: wait_for_event
+ 5. HITL: request_confirmation
+
+Timeout Handling:
+ - Standard operations: 5s timeout
+ - HITL dialogs: 60s timeout (waits for human input)
+
+Integration:
+ - Used by simulation tests (tests/visual_sim_mma_v2.py)
+ - Used by external tools for automation
+
+See Also:
+ - src/api_hooks.py for the server implementation
+ - docs/guide_tools.md for Hook API documentation
+"""
 from __future__ import annotations
 import requests # type: ignore[import-untyped]
 import time