Skip to content

Commit 417c538

Browse files
GSstarGamerGSstarGamer
committed
Rework Python docs into usage-first multi-page reference
1 parent a290a4f commit 417c538

20 files changed

+5214
-96
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@ jobs:
4040
run: |
4141
python -m pip install --upgrade pip
4242
python -m pip install pytest pytest-asyncio build twine
43+
- name: Verify generated Python command/docs outputs
44+
working-directory: python
45+
run: python tools/generate_baritone_commands.py --check
4346
- name: Run tests
4447
working-directory: python
4548
run: python -m pytest

‎python/README.md‎

Lines changed: 55 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -8,118 +8,80 @@
88
pip install pyritone
99
```
1010

11-
## Beginner usage
11+
## Fastest Working Sync Example
1212

1313
```python
1414
from pyritone import PyritoneClient
1515

1616
with PyritoneClient() as client:
17+
print(client.ping())
1718
dispatch = client.goto(100, 70, 100)
18-
task_id = dispatch.get("task_id")
19-
if task_id:
20-
terminal = client.wait_for_task(task_id)
21-
print(terminal["event"])
19+
print(dispatch)
2220
```
2321

24-
## Command API
25-
26-
All top-level Baritone v1.15.0 commands are exposed as Python methods on:
27-
28-
- `PyritoneClient` (sync)
29-
- `AsyncPyritoneClient` (async)
30-
31-
Each command returns immediate dispatch info:
32-
33-
- `command_text`
34-
- `raw` bridge response
35-
- optional `task_id`
36-
- optional `accepted`
37-
38-
Command aliases are exposed too (`qmark`, `stop`, `wp`, etc). Full generated reference:
39-
40-
- `python/docs/baritone-commands.md`
41-
42-
## Settings API
43-
44-
You can control Baritone settings through a settings namespace.
45-
46-
```python
47-
from pyritone import PyritoneClient
48-
49-
with PyritoneClient() as client:
50-
client.settings.allowSprint = True
51-
client.settings.allowBreak = False
52-
53-
print(client.settings.allowSprint.get())
54-
print(client.settings.allowSprint.toggle())
55-
print(client.settings.allowSprint.reset())
56-
```
57-
58-
Async style:
22+
## Fastest Working Async Example
5923

6024
```python
25+
import asyncio
6126
from pyritone import AsyncPyritoneClient
6227

63-
client = AsyncPyritoneClient()
64-
await client.connect()
65-
try:
66-
await client.settings.allowSprint.set(True)
67-
await client.settings.allowSprint.get()
68-
finally:
69-
await client.close()
70-
```
7128

72-
## Low-level API still available
29+
async def main() -> None:
30+
client = AsyncPyritoneClient()
31+
await client.connect()
32+
try:
33+
print(await client.ping())
34+
dispatch = await client.goto(100, 70, 100)
35+
print(dispatch)
36+
finally:
37+
await client.close()
7338

74-
- `execute("...")`
75-
- `cancel()`
76-
- `ping()`
77-
- `status_get()`
78-
- `next_event()`
79-
- `wait_for_task(task_id)`
8039

81-
## Zero-setup discovery
40+
asyncio.run(main())
41+
```
8242

83-
By default, `pyritone` discovers bridge details from:
43+
## Docs
44+
45+
- Full docs index: `python/docs/index.md`
46+
- Quickstart: `python/docs/quickstart.md`
47+
- Sync client guide: `python/docs/sync-client.md`
48+
- Async client guide: `python/docs/async-client.md`
49+
- Settings API: `python/docs/settings-api.md`
50+
- Tasks/events/waiting: `python/docs/tasks-events-and-waiting.md`
51+
- Errors/troubleshooting: `python/docs/errors-and-troubleshooting.md`
52+
- CLI usage: `python/docs/cli.md`
53+
- Command docs:
54+
- `python/docs/commands/navigation.md`
55+
- `python/docs/commands/world.md`
56+
- `python/docs/commands/build.md`
57+
- `python/docs/commands/control.md`
58+
- `python/docs/commands/info.md`
59+
- `python/docs/commands/waypoints.md`
60+
- `python/docs/commands/aliases.md`
61+
- Raw Baritone appendix: `python/docs/baritone-commands.md`
62+
63+
## Public API Map
64+
65+
- Clients:
66+
- `PyritoneClient`
67+
- `AsyncPyritoneClient`
68+
- Low-level methods:
69+
- `ping`, `status_get`, `execute`, `cancel`, `next_event`, `wait_for_task`
70+
- Command wrappers:
71+
- All top-level Baritone commands exposed as methods.
72+
- Settings namespace:
73+
- Sync: `client.settings.allowPlace = True`
74+
- Async: `await client.settings.allowPlace.set(True)`
75+
76+
## Auto-Discovery (Zero-Setup)
77+
78+
By default, `pyritone` discovers bridge metadata from:
8479

8580
- `<minecraft>/config/pyritone_bridge/bridge-info.json`
8681

87-
Override priority:
82+
Override precedence:
8883

8984
1. Explicit constructor args
90-
2. Environment variables (`PYRITONE_BRIDGE_INFO`, `PYRITONE_TOKEN`, `PYRITONE_HOST`, `PYRITONE_PORT`)
91-
3. Default bridge info file
92-
93-
## CLI
94-
95-
```bash
96-
pyritone ping
97-
pyritone status
98-
pyritone exec "goto 100 70 100"
99-
pyritone cancel
100-
pyritone events
101-
```
102-
103-
## Regenerate command wrappers/docs
104-
105-
```bash
106-
python tools/generate_baritone_commands.py
107-
```
108-
109-
## End-to-End Dev Test
110-
111-
1. Start Minecraft dev client from the mod folder:
85+
2. Environment variables: `PYRITONE_BRIDGE_INFO`, `PYRITONE_TOKEN`, `PYRITONE_HOST`, `PYRITONE_PORT`
86+
3. Auto-discovered bridge info file
11287

113-
```powershell
114-
cd ..\mod
115-
.\gradlew.bat devClient
116-
```
117-
118-
2. Join a world.
119-
3. Run one of the example scripts:
120-
121-
```powershell
122-
cd ..\python
123-
python example_sync.py
124-
python example_async.py
125-
```

‎python/docs/async-client.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Async Client
2+
3+
Guide for `AsyncPyritoneClient` in asyncio code.
4+
5+
### When to use this
6+
7+
- Your app already uses asyncio.
8+
- You want event-stream friendly control flow.
9+
10+
### Sync example
11+
12+
```python
13+
# Use PyritoneClient instead; see sync-client.md.
14+
```
15+
16+
### Async example
17+
18+
```python
19+
import asyncio
20+
from pyritone import AsyncPyritoneClient
21+
22+
23+
async def main() -> None:
24+
client = AsyncPyritoneClient()
25+
await client.connect()
26+
try:
27+
print(await client.ping())
28+
print(await client.status_get())
29+
30+
dispatch = await client.goto(100, 70, 100)
31+
print(dispatch)
32+
33+
task_id = dispatch.get("task_id")
34+
if task_id:
35+
terminal = await client.wait_for_task(task_id)
36+
print(terminal)
37+
finally:
38+
await client.close()
39+
40+
41+
asyncio.run(main())
42+
```
43+
44+
### Return shape
45+
46+
```text
47+
Async low-level methods return awaitable dict[str, Any] payloads.
48+
Command wrappers return awaitable CommandDispatchResult.
49+
events()/next_event() return event envelope dictionaries.
50+
```
51+
52+
### Common mistakes
53+
54+
- Calling command methods before `await client.connect()`.
55+
- Not closing the client in `finally`.
56+
- Blocking event-loop threads with sync operations while waiting for events.
57+
58+
### Related methods
59+
60+
- `sync-client.md`
61+
- `tasks-events-and-waiting.md`
62+
- `settings-api.md`
63+

‎python/docs/cli.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# CLI
2+
3+
Use `pyritone` directly from terminal for quick checks and scripts.
4+
5+
### When to use this
6+
7+
- You want quick diagnostics without writing Python code.
8+
- You need shell scripts for simple bridge automation.
9+
10+
### Sync example
11+
12+
```bash
13+
pyritone ping
14+
pyritone status
15+
pyritone exec "goto 100 70 100"
16+
pyritone cancel
17+
```
18+
19+
### Async example
20+
21+
```text
22+
The CLI is internally async, but you use it as normal shell commands.
23+
```
24+
25+
### Return shape
26+
27+
```text
28+
CLI commands print JSON payloads from the bridge:
29+
- ping/status/exec/cancel: pretty JSON
30+
- events: streaming JSON lines
31+
```
32+
33+
### Common mistakes
34+
35+
- Not quoting command strings with spaces in `pyritone exec`.
36+
- Forgetting `--task-id` when canceling a specific task.
37+
- Running CLI without bridge metadata/token available.
38+
39+
### Related methods
40+
41+
- Python equivalent APIs: `sync-client.md`, `async-client.md`
42+
- Troubleshooting: `errors-and-troubleshooting.md`
43+
44+
## Commands
45+
46+
- `pyritone ping`
47+
- `pyritone status`
48+
- `pyritone exec "<baritone command>"`
49+
- `pyritone cancel [--task-id <id>]`
50+
- `pyritone events`
51+
52+
## Connection Overrides
53+
54+
- `--host`
55+
- `--port`
56+
- `--token`
57+
- `--bridge-info`
58+
- `--timeout`
59+

0 commit comments

Comments
 (0)