Add Python demo suite with docs and helper tests

Author: GSstarGamer

README.md

@@ -32,6 +32,31 @@ with PyritoneClient() as client:
     print(client.execute("goto 100 70 100"))
 ```
 
+## Demos / Videos
+
+Beginner-friendly demo scripts live in `python/demos/`.
+
+- Demo index: `python/demos/README.md`
+- Fast start from repo root:
+
+```bash
+python -m pip install -e ./python
+cd python
+python demos/01_connect_discovery.py
+```
+
+- Suggested recording set includes:
+  - connect/discovery
+  - basic commands
+  - goto + completion
+  - live event feed
+  - cancel flow
+  - settings mode switch
+  - interactive mini console
+  - async workflow
+  - local-path build helper
+  - CLI entrypoints
+
 ## One-Click Dev Client
 
 - Double-click `run_dev_client.bat` at repo root, or run it in terminal:

python/README.md

@@ -40,6 +40,22 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Demos
+
+The quick examples above are intentionally small.
+
+For full, recordable feature walkthroughs, see:
+
+- `python/demos/README.md`
+
+Run from repo root:
+
+```bash
+python -m pip install -e ./python
+cd python
+python demos/01_connect_discovery.py
+```
+
 ## Docs
 
 - Full docs index: `python/docs/index.md`

python/demos/01_connect_discovery.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from _common import print_json, run_sync_demo, step
+
+
+def demo(client):
+    step("Using default discovery: bridge-info file or PYRITONE_* overrides.")
+    print_json("ping()", client.ping())
+    print_json("status_get()", client.status_get())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_sync_demo("01 - Connect + Discovery", demo))

python/demos/02_basic_commands.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from _common import print_json, run_sync_demo, step, summarize_dispatch
+
+
+def demo(client):
+    step("High-level wrappers first: help(), version(), set(...).")
+
+    help_dispatch = client.help()
+    print(f"help() summary: {summarize_dispatch(help_dispatch)}")
+    print_json("help()", help_dispatch)
+
+    version_dispatch = client.version()
+    print(f"version() summary: {summarize_dispatch(version_dispatch)}")
+    print_json("version()", version_dispatch)
+
+    set_dispatch = client.set("allowPlace", True)
+    print(f"set('allowPlace', True) summary: {summarize_dispatch(set_dispatch)}")
+    print_json("set('allowPlace', True)", set_dispatch)
+
+    step("Raw fallback: execute('help').")
+    print_json("execute('help')", client.execute("help"))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_sync_demo("02 - Basic Commands", demo))

python/demos/03_goto_completion.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import argparse
+
+from _common import (
+    print_json,
+    run_sync_demo,
+    step,
+    summarize_dispatch,
+    summarize_event,
+    terminal_summary,
+)
+
+
+parser = argparse.ArgumentParser(description="Dispatch goto and wait for terminal task event")
+parser.add_argument("x", type=int, nargs="?", default=100)
+parser.add_argument("y", type=int, nargs="?", default=70)
+parser.add_argument("z", type=int, nargs="?", default=100)
+args = parser.parse_args()
+
+
+def demo(client):
+    step(f"Dispatching goto({args.x}, {args.y}, {args.z})")
+    dispatch = client.goto(args.x, args.y, args.z)
+    print(f"goto dispatch summary: {summarize_dispatch(dispatch)}")
+    print_json("goto dispatch", dispatch)
+
+    task_id = dispatch.get("task_id")
+    if not task_id:
+        step("No task_id was returned, so there is nothing to wait for.")
+        return 0
+
+    step(f"Waiting for terminal event for task_id={task_id}")
+    terminal_event = client.wait_for_task(task_id)
+    print(f"terminal event summary: {summarize_event(terminal_event)}")
+    print_json("terminal event", terminal_event)
+    step(terminal_summary(terminal_event))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_sync_demo("03 - Goto + Completion", demo))

python/demos/04_live_event_feed.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import argparse
+
+from _common import print_json, run_sync_demo, step, summarize_event
+
+
+parser = argparse.ArgumentParser(description="Print live bridge events")
+parser.add_argument("--max-events", type=int, default=20, help="0 means unlimited")
+parser.add_argument("--timeout", type=float, default=5.0)
+parser.add_argument("--full-json", action="store_true")
+args = parser.parse_args()
+
+
+def demo(client):
+    step(
+        "Listening for bridge events. Trigger Baritone commands in-game or from other scripts. Press Ctrl+C to stop."
+    )
+
+    seen = 0
+    while args.max_events <= 0 or seen < args.max_events:
+        try:
+            event = client.next_event(timeout=args.timeout)
+        except TimeoutError:
+            step("No event arrived in the timeout window. Still listening...")
+            continue
+
+        seen += 1
+        print(f"event #{seen}: {summarize_event(event)}")
+        if args.full_json:
+            print_json("event payload", event)
+
+    step(f"Reached max-events={args.max_events}; exiting.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_sync_demo("04 - Live Event Feed", demo))

python/demos/05_cancel_task.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import argparse
+import time
+
+from _common import (
+    print_json,
+    run_sync_demo,
+    step,
+    summarize_dispatch,
+    summarize_event,
+    terminal_summary,
+)
+
+
+parser = argparse.ArgumentParser(description="Start a task, cancel it, and inspect terminal state")
+parser.add_argument("--delay", type=float, default=1.5, help="Seconds to wait before cancel")
+args = parser.parse_args()
+
+
+def demo(client):
+    step("Starting a long-running task with high-level wrapper: explore()")
+    dispatch = client.explore()
+    print(f"explore() dispatch summary: {summarize_dispatch(dispatch)}")
+    print_json("explore() dispatch", dispatch)
+
+    task_id = dispatch.get("task_id")
+    if not task_id:
+        step("No task_id returned, cannot target a specific cancel. Sending global cancel instead.")
+        print_json("cancel()", client.cancel())
+        return 0
+
+    step(f"Waiting {args.delay:.1f}s before canceling task_id={task_id}")
+    time.sleep(max(args.delay, 0.0))
+
+    cancel_result = client.cancel(task_id=task_id)
+    print_json("cancel(task_id)", cancel_result)
+
+    step("Waiting for terminal task event after cancel")
+    terminal_event = client.wait_for_task(task_id)
+    print(f"terminal event summary: {summarize_event(terminal_event)}")
+    print_json("terminal event", terminal_event)
+    step(terminal_summary(terminal_event))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_sync_demo("05 - Cancel Task", demo))

python/demos/06_settings_mode_switch.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import argparse
+
+from _common import print_json, run_sync_demo, step
+from pyritone import BridgeError
+
+
+MODES: dict[str, dict[str, bool]] = {
+    "builder": {
+        "allowPlace": True,
+        "allowSprint": True,
+    },
+    "careful": {
+        "allowPlace": False,
+        "allowSprint": False,
+    },
+}
+
+
+parser = argparse.ArgumentParser(description="Show settings API and mode presets")
+parser.add_argument("--mode", choices=sorted(MODES.keys()), default="builder")
+args = parser.parse_args()
+
+
+def _apply_mode(client, mode_name: str) -> None:
+    mode = MODES[mode_name]
+    step(f"Applying mode '{mode_name}' with {len(mode)} settings")
+
+    for setting_name, value in mode.items():
+        try:
+            dispatch = client.settings.set(setting_name, value)
+            print_json(f"set {setting_name} {value}", dispatch)
+        except BridgeError as error:
+            print(
+                f"[warn] Could not set {setting_name!r}: {error.code} - {error.message}. "
+                "Continuing with remaining settings."
+            )
+
+
+def demo(client):
+    step("Property assignment style (sync): client.settings.allowPlace = True")
+    client.settings.allowPlace = True
+    if client.settings.last_dispatch is not None:
+        print_json("last_dispatch", client.settings.last_dispatch)
+
+    step("Handle methods: get/toggle/reset")
+    print_json("allowPlace.get()", client.settings.allowPlace.get())
+    print_json("allowPlace.toggle()", client.settings.allowPlace.toggle())
+    print_json("allowPlace.reset()", client.settings.allowPlace.reset())
+
+    _apply_mode(client, args.mode)
+
+    step("Final checks")
+    print_json("allowPlace.get()", client.settings.allowPlace.get())
+    print_json("allowSprint.get()", client.settings.allowSprint.get())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_sync_demo("06 - Settings Mode Switch", demo))