Add local schematic build_file API and docs coverage

Author: GSstarGamer

python/README.md

@@ -15,7 +15,7 @@ from pyritone import PyritoneClient
 
 with PyritoneClient() as client:
     print(client.ping())
-    dispatch = client.goto(100, 70, 100)
+    dispatch = client.build_file("schematics/base.schem", 100, 70, 100)
     print(dispatch)
 ```
 
@@ -31,7 +31,7 @@ async def main() -> None:
     await client.connect()
     try:
         print(await client.ping())
-        dispatch = await client.goto(100, 70, 100)
+        dispatch = await client.build_file("schematics/base.schem", 100, 70, 100)
         print(dispatch)
     finally:
         await client.close()
@@ -69,6 +69,9 @@ asyncio.run(main())
   - `ping`, `status_get`, `execute`, `cancel`, `next_event`, `wait_for_task`
 - Command wrappers:
   - All top-level Baritone commands exposed as methods.
+- Local schematic helpers:
+  - `build_file(path, *coords, base_dir=None)`
+  - `build_file_wait(path, *coords, base_dir=None)`
 - Settings namespace:
   - Sync: `client.settings.allowPlace = True`
   - Async: `await client.settings.allowPlace.set(True)`
@@ -84,4 +87,3 @@ Override precedence:
 1. Explicit constructor args
 2. Environment variables: `PYRITONE_BRIDGE_INFO`, `PYRITONE_TOKEN`, `PYRITONE_HOST`, `PYRITONE_PORT`
 3. Auto-discovered bridge info file
-

python/docs/async-client.md

@@ -27,13 +27,16 @@ async def main() -> None:
         print(await client.ping())
         print(await client.status_get())
 
-        dispatch = await client.goto(100, 70, 100)
+        dispatch = await client.build_file("schematics/base.schem", 100, 70, 100)
         print(dispatch)
 
         task_id = dispatch.get("task_id")
         if task_id:
             terminal = await client.wait_for_task(task_id)
             print(terminal)
+
+        # Convenience helper that dispatches + waits in one call
+        print(await client.build_file_wait("schematics/base.schem", 100, 70, 100))
     finally:
         await client.close()
 
@@ -47,17 +50,22 @@ asyncio.run(main())
 Async low-level methods return awaitable dict[str, Any] payloads.
 Command wrappers return awaitable CommandDispatchResult.
 events()/next_event() return event envelope dictionaries.
+
+Build helpers:
+- await build_file(...) -> CommandDispatchResult
+- await build_file_wait(...) -> terminal event envelope dict[str, Any]
 ```
 
 ### Common mistakes
 
 - Calling command methods before `await client.connect()`.
 - Not closing the client in `finally`.
+- Passing 1 or 2 coordinates to `build_file` (must be 0 or 3).
+- Assuming relative paths are from cwd; default is caller file directory.
 - Blocking event-loop threads with sync operations while waiting for events.
 
 ### Related methods
 
 - `sync-client.md`
 - `tasks-events-and-waiting.md`
 - `settings-api.md`
-

python/docs/commands/build.md

@@ -29,6 +29,46 @@ CommandDispatchResult
 - [Errors and troubleshooting](../errors-and-troubleshooting.md)
 - [Alias methods](aliases.md)
 
+## Pyritone Build Helpers
+
+Extra helpers for local schematic files relative to your Python script.
+
+### Sync example
+```python
+from pyritone import PyritoneClient
+
+with PyritoneClient() as client:
+    dispatch = client.build_file("schematics/base", 100, 70, 100)
+    print(dispatch)
+    terminal = client.build_file_wait("schematics/base", 100, 70, 100)
+    print(terminal)
+```
+
+### Async example
+```python
+import asyncio
+from pyritone import AsyncPyritoneClient
+
+async def main() -> None:
+    client = AsyncPyritoneClient()
+    await client.connect()
+    try:
+        dispatch = await client.build_file("schematics/base", 100, 70, 100)
+        print(dispatch)
+        terminal = await client.build_file_wait("schematics/base", 100, 70, 100)
+        print(terminal)
+    finally:
+        await client.close()
+
+asyncio.run(main())
+```
+
+### Notes
+- Relative paths are resolved from the calling Python file directory by default.
+- Pass `base_dir` to override path base.
+- No extension uses probing order: `.schem`, `.schematic`, `.litematic`.
+- If no file matches, extension-less path is sent so Baritone fallback extension still applies.
+
 ## `build`
 
 Build a schematic
@@ -92,6 +132,8 @@ If `task_id` exists, wait for a terminal event:
 ### Common mistakes
 - Passing separate string tokens when one argument contains spaces. Use one Python string.
 - Treating dispatch as completion. Dispatch is immediate; wait on `task_id` when needed.
+- For local Python-file-relative schematic paths, use `build_file(...)`.
+- Use `build_file_wait(...)` when you want dispatch + wait in one call.
 
 ### Source provenance
 - Baritone version: `v1.15.0`

python/docs/quickstart.md

@@ -15,8 +15,12 @@ from pyritone import PyritoneClient
 with PyritoneClient() as client:
     print(client.ping())
     print(client.status_get())
-    dispatch = client.goto(100, 70, 100)
+    dispatch = client.build_file("schematics/base.schem", 100, 70, 100)
     print(dispatch)
+
+    task_id = dispatch.get("task_id")
+    if task_id:
+        print(client.wait_for_task(task_id))
 ```
 
 ### Async example
@@ -32,8 +36,12 @@ async def main() -> None:
     try:
         print(await client.ping())
         print(await client.status_get())
-        dispatch = await client.goto(100, 70, 100)
+        dispatch = await client.build_file("schematics/base.schem", 100, 70, 100)
         print(dispatch)
+
+        task_id = dispatch.get("task_id")
+        if task_id:
+            print(await client.wait_for_task(task_id))
     finally:
         await client.close()
 
@@ -45,7 +53,7 @@ asyncio.run(main())
 
 ```text
 ping/status_get return dict[str, Any] payloads.
-goto and other command wrappers return CommandDispatchResult:
+build_file and other command wrappers return CommandDispatchResult:
 - command_text
 - raw
 - task_id (optional)
@@ -55,12 +63,12 @@ goto and other command wrappers return CommandDispatchResult:
 ### Common mistakes
 
 - Running Python before Minecraft has started with `pyritone_bridge`.
-- Calling command wrappers before joining a world (may return `NOT_IN_WORLD`).
+- Calling build commands before joining a world (may return `NOT_IN_WORLD`).
+- Using relative paths that are not relative to your script file (set `base_dir` to override).
 - Treating dispatch as completion; use `wait_for_task` when `task_id` exists.
 
 ### Related methods
 
 - `connection-and-discovery.md`
 - `tasks-events-and-waiting.md`
 - `commands/navigation.md`
-

python/docs/sync-client.md

@@ -16,13 +16,16 @@ with PyritoneClient() as client:
     print(client.ping())
     print(client.status_get())
 
-    dispatch = client.goto(100, 70, 100)
+    dispatch = client.build_file("schematics/base.schem", 100, 70, 100)
     print(dispatch)
 
     task_id = dispatch.get("task_id")
     if task_id:
         terminal = client.wait_for_task(task_id)
         print(terminal)
+
+    # Convenience helper that dispatches + waits in one call
+    print(client.build_file_wait("schematics/base.schem", 100, 70, 100))
 ```
 
 ### Async example
@@ -40,17 +43,22 @@ Low-level methods:
 
 Command methods:
 - CommandDispatchResult
+
+build helpers:
+- build_file(...) -> CommandDispatchResult
+- build_file_wait(...) -> terminal event envelope dict[str, Any]
 ```
 
 ### Common mistakes
 
 - Creating a sync client and forgetting to close it outside a `with` block.
 - Assuming command wrappers block until completion by default.
+- Passing 1 or 2 coordinates to `build_file` (must be 0 or 3).
+- Assuming relative paths are from cwd; default is caller file directory.
 - Passing invalid argument shapes to command wrappers.
 
 ### Related methods
 
 - `async-client.md`
 - `tasks-events-and-waiting.md`
 - `settings-api.md`
-

python/src/pyritone/client_async.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import contextlib
+from pathlib import Path
 from typing import Any
 
 from .commands.async_build import AsyncBuildCommands
@@ -10,9 +11,11 @@
 from .commands.async_navigation import AsyncNavigationCommands
 from .commands.async_waypoints import AsyncWaypointsCommands
 from .commands.async_world import AsyncWorldCommands
+from .commands._types import CommandDispatchResult
 from .discovery import resolve_bridge_info
 from .models import BridgeError, BridgeInfo
 from .protocol import decode_line, encode_line, new_request
+from .schematic_paths import normalize_build_coords, normalize_schematic_path
 from .settings import AsyncSettingsNamespace
 
 
@@ -139,6 +142,42 @@ async def wait_for_task(self, task_id: str) -> dict[str, Any]:
             if isinstance(event_name, str) and event_name in self.TERMINAL_TASK_EVENTS:
                 return event
 
+    async def build_file(
+        self,
+        path: str | Path,
+        *coords: int,
+        base_dir: str | Path | None = None,
+    ) -> CommandDispatchResult:
+        """Dispatch Baritone `build` using a local schematic path.
+
+        Relative paths resolve from the calling Python file directory by default.
+        Use `base_dir` to override that base path.
+
+        Coordinate args must be either:
+        - none (build at player position), or
+        - exactly three ints `(x, y, z)`.
+        """
+        normalized_path = normalize_schematic_path(path, base_dir=base_dir)
+        normalized_coords = normalize_build_coords(coords)
+        return await self.build(normalized_path, *normalized_coords)
+
+    async def build_file_wait(
+        self,
+        path: str | Path,
+        *coords: int,
+        base_dir: str | Path | None = None,
+    ) -> dict[str, Any]:
+        """Dispatch `build_file` and wait for terminal task event.
+
+        Raises `BridgeError(code=\"BAD_RESPONSE\", ...)` when dispatch response
+        does not include a `task_id`.
+        """
+        dispatch = await self.build_file(path, *coords, base_dir=base_dir)
+        task_id = dispatch.get("task_id")
+        if not task_id:
+            raise BridgeError("BAD_RESPONSE", "No task_id returned for command: build", dispatch["raw"])
+        return await self.wait_for_task(task_id)
+
     async def _request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
         self._ensure_connected()
         assert self._writer is not None

python/src/pyritone/client_sync.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import threading
+from pathlib import Path
 from typing import Any
 
 from .client_async import AsyncPyritoneClient
@@ -11,6 +12,9 @@
 from .commands.sync_navigation import SyncNavigationCommands
 from .commands.sync_waypoints import SyncWaypointsCommands
 from .commands.sync_world import SyncWorldCommands
+from .commands._types import CommandDispatchResult
+from .models import BridgeError
+from .schematic_paths import normalize_build_coords, normalize_schematic_path
 from .settings import SyncSettingsNamespace
 
 
@@ -108,3 +112,39 @@ def next_event(self, timeout: float | None = None) -> dict[str, Any]:
 
     def wait_for_task(self, task_id: str) -> dict[str, Any]:
         return self._runner.run(self._client.wait_for_task(task_id))
+
+    def build_file(
+        self,
+        path: str | Path,
+        *coords: int,
+        base_dir: str | Path | None = None,
+    ) -> CommandDispatchResult:
+        """Dispatch Baritone `build` using a local schematic path.
+
+        Relative paths resolve from the calling Python file directory by default.
+        Use `base_dir` to override that base path.
+
+        Coordinate args must be either:
+        - none (build at player position), or
+        - exactly three ints `(x, y, z)`.
+        """
+        normalized_path = normalize_schematic_path(path, base_dir=base_dir)
+        normalized_coords = normalize_build_coords(coords)
+        return self.build(normalized_path, *normalized_coords)
+
+    def build_file_wait(
+        self,
+        path: str | Path,
+        *coords: int,
+        base_dir: str | Path | None = None,
+    ) -> dict[str, Any]:
+        """Dispatch `build_file` and wait for terminal task event.
+
+        Raises `BridgeError(code=\"BAD_RESPONSE\", ...)` when dispatch response
+        does not include a `task_id`.
+        """
+        dispatch = self.build_file(path, *coords, base_dir=base_dir)
+        task_id = dispatch.get("task_id")
+        if not task_id:
+            raise BridgeError("BAD_RESPONSE", "No task_id returned for command: build", dispatch["raw"])
+        return self.wait_for_task(task_id)