sketchforge3d 1.2.1__tar.gz

sketchforge3d-1.2.1/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: sketchforge3d
+Version: 1.2.1
+Summary: Typed client and macro runner for the SketchForge REST API.
+Author: SketchForge contributors
+License-Expression: AGPL-3.0-only
+Project-URL: Homepage, https://sketchforge3d.com
+Project-URL: Repository, https://github.com/constructorfleet/SketchForge-3D
+Keywords: sketchforge,cad,macro,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# sketchforge3d
+
+A Python client for the [SketchForge REST API](../../docs/REST_API.md), and a runner for **macros**: short parameterised scripts that build a part.
+
+```bash
+pip install sketchforge3d
+```
+
+The install name and the import name are the same, and there are no runtime dependencies: the client speaks HTTP through `urllib` from the standard library, so it installs anywhere Python does and adds nothing to a macro author's lockfile.
+
+The API is headless -- it reads and writes projects in server-side storage with no browser open -- so a macro is a build script for a design, the way a Makefile is for a binary.
+
+## Connecting
+
+```python
+from sketchforge3d import SketchForgeClient, client_from_environment
+
+client = SketchForgeClient(base_url="http://localhost:3000", token="...")
+client = client_from_environment()  # SKETCHFORGE_API_TOKEN, SKETCHFORGE_URL
+
+health = client.check()
+if not health["ok"]:
+    raise SystemExit(health["reason"])
+```
+
+Prefer the environment: the token is a password for every project on the server and does not belong in a script or in shell history. The server needs both `SKETCHFORGE_API_TOKEN` and `SKETCHFORGE_PROJECTS_DIR` set, or the API answers 404 and 503 respectively; `check()` says which.
+
+## The client
+
+```python
+SketchForgeClient(base_url, token, timeout=60.0, retry_on_busy=4, headers=None, opener=None)
+
+client.api_root -> str
+client.check() -> dict
+client.project(project_id) -> ProjectHandle
+
+client.projects.list() -> list[ProjectSummary]
+client.projects.get(project_id) -> ProjectDetail
+client.projects.create(name) -> ProjectSummary
+client.projects.delete(project_id) -> bool
+client.projects.find_by_name(name) -> ProjectSummary | None
+
+client.shapes.list(project_id) -> list[ShapeSummary]
+client.shapes.create(project_id, shape) -> ShapeSummary
+client.shapes.create_many(project_id, shapes) -> ShapeWriteResult
+client.shapes.update(project_id, shape_id, changes) -> ShapeSummary
+client.shapes.delete(project_id, shape_id) -> bool
+client.shapes.delete_all(project_id) -> int
+
+client.edges.list(project_id, shape_id) -> list[EdgeSummary]
+client.edges.filletable_indexes(project_id, shape_id) -> list[int]
+
+client.treatments.apply(project_id, shape_id, kind, amount, angle=None, edges=None) -> TreatmentResult
+client.treatments.fillet(project_id, shape_id, radius, edges=None) -> TreatmentResult
+client.treatments.chamfer(project_id, shape_id, distance, angle=None, edges=None) -> TreatmentResult
+```
+
+A `ProjectHandle` is the same surface with the project id bound, which is what a macro works through:
+
+```python
+project.get() | delete() | list_shapes() | add(shape) | add_many(shapes) | update(id, changes)
+project.remove(id) | clear() | edges(id) | filletable_edges(id)
+project.fillet(id, radius, edges=None) | chamfer(id, distance, angle=None, edges=None)
+```
+
+Requests are plain dicts, because the server takes a bag of parameters; responses are frozen dataclasses with snake_case fields, so `shape.rotation_x` is checked and a typo is an error rather than a `None`. A field this version does not know about is kept in `shape.extra` rather than dropped.
+
+```python
+project.add_many([
+    {"kind": "box", "name": "Plate", "width": 120, "depth": 40, "height": 6},
+    {"kind": "cylinder", "width": 8, "height": 12, "sides": 6, "x": -40, "elevation": -1, "hole": True},
+    {"kind": "thread", "size": "M8", "length": 10, "hole": True, "x": 40},
+    {"kind": "revolve", "profile": [[8, 0], [10, 0], [10, 2], [8, 2]], "pitch": 6, "turns": 6},
+])
+```
+
+`create_many` is one write of the project package per request and splits lists longer than the server's 200-shape limit -- which also means a longer list is no longer atomic.
+
+Failures are `SketchForgeApiError` (`status`, `detail`, plus `looks_disabled`, `needs_storage`, `is_project_busy`) or `SketchForgeTransportError`, both subclasses of `SketchForgeError`. A write that lost the project's lock is retried; a *locked shape*, which answers 409 for an unrelated reason, is not.
+
+`sketchforge3d.layout` has the arithmetic a parameterised part repeats: `row`, `grid`, `ring`, `centered_offsets`, `angle_of`, `mm`.
+
+## Macros
+
+A macro is a file that defines `MACRO` and builds something when it is handed a connected project:
+
+```python
+# macros/bolt_plate.py
+from sketchforge3d import MacroContext, define_macro
+
+
+def build(context: MacroContext) -> dict:
+    params, layout = context.params, context.layout
+    context.log(f"{params['holes']} {params['size']} holes")
+    context.project.add_many(
+        [{"kind": "box", "name": "Plate", "width": 200, "depth": 40, "height": params["thickness"]}]
+        + [
+            {
+                "kind": "thread",
+                "name": f"hole {index}",
+                "size": params["size"],
+                "length": params["thickness"] + 2,
+                "hole": True,
+                "x": at.x,
+                "z": at.z,
+                "elevation": -1,
+            }
+            for index, at in enumerate(layout.row(int(params["holes"]), float(params["spacing"])), start=1)
+        ]
+    )
+    return {"holes": params["holes"]}
+
+
+MACRO = define_macro(
+    name="Bolt plate",
+    project=("replace", "Bolt plate"),
+    params={"holes": 5, "spacing": 25.0, "size": "M8", "thickness": 8.0},
+    run=build,
+)
+```
+
+```bash
+SKETCHFORGE_API_TOKEN=... python -m sketchforge3d.macro macros/bolt_plate.py --holes=7 --spacing=30
+```
+
+`python -m sketchforge3d`, and the `sketchforge-macro` console script, run the same thing. The context carries everything the macro needs -- `client`, `project`, `params`, `layout`, `log` -- so a macro file imports only `define_macro`.
+
+### Project modes, and why there is no default
+
+The second run is what makes a macro useful or dangerous. A script that appends to a project it found doubles the part every time, and nobody notices until they open the project. So the mode is declared and the runner, not the macro body, acts on it:
+
+| `project` | What the runner does first | Use it for |
+| --- | --- | --- |
+| `"fresh"` | Creates a new project, name stamped with the time | Something you generate several of to compare |
+| `("replace", name)` | Finds that project and **empties** it, or creates it | A part you iterate on; re-running is idempotent |
+| `("reuse", name)` | Finds or creates it, and leaves the contents alone | Adding a feature to whatever is there |
+| `"target"` | Requires `SKETCHFORGE_PROJECT_ID` or `--project`, touches nothing else | Operating on a project someone else named |
+
+A module with a bare `run(context)` function instead of a `MACRO` runs in a `fresh` project, because that is the only mode that is safe to assume.
+
+### Parameters
+
+`params` is both the defaults and the schema. An override is coerced to the type of its default -- an `int` default refuses `4.5`, a `float` default takes it -- and a name the macro does not declare is refused, so `--hoels=7` is an error rather than a silently ignored typo. Parameters are resolved before the project is created, so a bad one costs nothing.
+
+## Examples
+
+`examples/` holds the three worked macros, which double as the integration tests:
+
+| Macro | Builds |
+| --- | --- |
+| `bolt_plate.py` | A plate sized around a computed row of tapped holes |
+| `bolt_circle.py` | A flange with N tapped holes on a ring of radius R |
+| `filleted_box.py` | A box from three numbers, with every roundable edge filleted on the server |
+
+Tapped holes are `{"kind": "thread", "hole": True}`: the form is cut wider by a clearance and the shape is marked as a hole, so grouping it with the plate in the editor taps the plate. The API has no grouping endpoint yet, so the macros stop at marked holes.
+
+## Development
+
+Tests are `unittest` from the standard library, so there is nothing to install:
+
+```bash
+PYTHONPATH=src:tests python3 -m unittest discover -s tests -t tests        # unit
+PYTHONPATH=src python3 -m unittest discover -s tests/integration -t tests/integration  # needs a live server
+```
+
+From the repository root those are `npm run client:test:py` and `npm run client:test:py:integration`. The integration tests need a real server:
+
+```bash
+SKETCHFORGE_PROJECTS_DIR=$(mktemp -d) SKETCHFORGE_API_TOKEN=test-token \
+  npx next dev apps/web -p 3100 &
+export SKETCHFORGE_API_TOKEN=test-token SKETCHFORGE_URL=http://127.0.0.1:3100
+npm run client:test:py:integration
+```
+
+## Publishing
+
+See [docs/PUBLISHING_CLIENTS.md](../../docs/PUBLISHING_CLIENTS.md) for the trusted-publisher settings PyPI needs before the release workflow can publish this package.

sketchforge3d-1.2.1/README.md

@@ -0,0 +1,177 @@
+# sketchforge3d
+
+A Python client for the [SketchForge REST API](../../docs/REST_API.md), and a runner for **macros**: short parameterised scripts that build a part.
+
+```bash
+pip install sketchforge3d
+```
+
+The install name and the import name are the same, and there are no runtime dependencies: the client speaks HTTP through `urllib` from the standard library, so it installs anywhere Python does and adds nothing to a macro author's lockfile.
+
+The API is headless -- it reads and writes projects in server-side storage with no browser open -- so a macro is a build script for a design, the way a Makefile is for a binary.
+
+## Connecting
+
+```python
+from sketchforge3d import SketchForgeClient, client_from_environment
+
+client = SketchForgeClient(base_url="http://localhost:3000", token="...")
+client = client_from_environment()  # SKETCHFORGE_API_TOKEN, SKETCHFORGE_URL
+
+health = client.check()
+if not health["ok"]:
+    raise SystemExit(health["reason"])
+```
+
+Prefer the environment: the token is a password for every project on the server and does not belong in a script or in shell history. The server needs both `SKETCHFORGE_API_TOKEN` and `SKETCHFORGE_PROJECTS_DIR` set, or the API answers 404 and 503 respectively; `check()` says which.
+
+## The client
+
+```python
+SketchForgeClient(base_url, token, timeout=60.0, retry_on_busy=4, headers=None, opener=None)
+
+client.api_root -> str
+client.check() -> dict
+client.project(project_id) -> ProjectHandle
+
+client.projects.list() -> list[ProjectSummary]
+client.projects.get(project_id) -> ProjectDetail
+client.projects.create(name) -> ProjectSummary
+client.projects.delete(project_id) -> bool
+client.projects.find_by_name(name) -> ProjectSummary | None
+
+client.shapes.list(project_id) -> list[ShapeSummary]
+client.shapes.create(project_id, shape) -> ShapeSummary
+client.shapes.create_many(project_id, shapes) -> ShapeWriteResult
+client.shapes.update(project_id, shape_id, changes) -> ShapeSummary
+client.shapes.delete(project_id, shape_id) -> bool
+client.shapes.delete_all(project_id) -> int
+
+client.edges.list(project_id, shape_id) -> list[EdgeSummary]
+client.edges.filletable_indexes(project_id, shape_id) -> list[int]
+
+client.treatments.apply(project_id, shape_id, kind, amount, angle=None, edges=None) -> TreatmentResult
+client.treatments.fillet(project_id, shape_id, radius, edges=None) -> TreatmentResult
+client.treatments.chamfer(project_id, shape_id, distance, angle=None, edges=None) -> TreatmentResult
+```
+
+A `ProjectHandle` is the same surface with the project id bound, which is what a macro works through:
+
+```python
+project.get() | delete() | list_shapes() | add(shape) | add_many(shapes) | update(id, changes)
+project.remove(id) | clear() | edges(id) | filletable_edges(id)
+project.fillet(id, radius, edges=None) | chamfer(id, distance, angle=None, edges=None)
+```
+
+Requests are plain dicts, because the server takes a bag of parameters; responses are frozen dataclasses with snake_case fields, so `shape.rotation_x` is checked and a typo is an error rather than a `None`. A field this version does not know about is kept in `shape.extra` rather than dropped.
+
+```python
+project.add_many([
+    {"kind": "box", "name": "Plate", "width": 120, "depth": 40, "height": 6},
+    {"kind": "cylinder", "width": 8, "height": 12, "sides": 6, "x": -40, "elevation": -1, "hole": True},
+    {"kind": "thread", "size": "M8", "length": 10, "hole": True, "x": 40},
+    {"kind": "revolve", "profile": [[8, 0], [10, 0], [10, 2], [8, 2]], "pitch": 6, "turns": 6},
+])
+```
+
+`create_many` is one write of the project package per request and splits lists longer than the server's 200-shape limit -- which also means a longer list is no longer atomic.
+
+Failures are `SketchForgeApiError` (`status`, `detail`, plus `looks_disabled`, `needs_storage`, `is_project_busy`) or `SketchForgeTransportError`, both subclasses of `SketchForgeError`. A write that lost the project's lock is retried; a *locked shape*, which answers 409 for an unrelated reason, is not.
+
+`sketchforge3d.layout` has the arithmetic a parameterised part repeats: `row`, `grid`, `ring`, `centered_offsets`, `angle_of`, `mm`.
+
+## Macros
+
+A macro is a file that defines `MACRO` and builds something when it is handed a connected project:
+
+```python
+# macros/bolt_plate.py
+from sketchforge3d import MacroContext, define_macro
+
+
+def build(context: MacroContext) -> dict:
+    params, layout = context.params, context.layout
+    context.log(f"{params['holes']} {params['size']} holes")
+    context.project.add_many(
+        [{"kind": "box", "name": "Plate", "width": 200, "depth": 40, "height": params["thickness"]}]
+        + [
+            {
+                "kind": "thread",
+                "name": f"hole {index}",
+                "size": params["size"],
+                "length": params["thickness"] + 2,
+                "hole": True,
+                "x": at.x,
+                "z": at.z,
+                "elevation": -1,
+            }
+            for index, at in enumerate(layout.row(int(params["holes"]), float(params["spacing"])), start=1)
+        ]
+    )
+    return {"holes": params["holes"]}
+
+
+MACRO = define_macro(
+    name="Bolt plate",
+    project=("replace", "Bolt plate"),
+    params={"holes": 5, "spacing": 25.0, "size": "M8", "thickness": 8.0},
+    run=build,
+)
+```
+
+```bash
+SKETCHFORGE_API_TOKEN=... python -m sketchforge3d.macro macros/bolt_plate.py --holes=7 --spacing=30
+```
+
+`python -m sketchforge3d`, and the `sketchforge-macro` console script, run the same thing. The context carries everything the macro needs -- `client`, `project`, `params`, `layout`, `log` -- so a macro file imports only `define_macro`.
+
+### Project modes, and why there is no default
+
+The second run is what makes a macro useful or dangerous. A script that appends to a project it found doubles the part every time, and nobody notices until they open the project. So the mode is declared and the runner, not the macro body, acts on it:
+
+| `project` | What the runner does first | Use it for |
+| --- | --- | --- |
+| `"fresh"` | Creates a new project, name stamped with the time | Something you generate several of to compare |
+| `("replace", name)` | Finds that project and **empties** it, or creates it | A part you iterate on; re-running is idempotent |
+| `("reuse", name)` | Finds or creates it, and leaves the contents alone | Adding a feature to whatever is there |
+| `"target"` | Requires `SKETCHFORGE_PROJECT_ID` or `--project`, touches nothing else | Operating on a project someone else named |
+
+A module with a bare `run(context)` function instead of a `MACRO` runs in a `fresh` project, because that is the only mode that is safe to assume.
+
+### Parameters
+
+`params` is both the defaults and the schema. An override is coerced to the type of its default -- an `int` default refuses `4.5`, a `float` default takes it -- and a name the macro does not declare is refused, so `--hoels=7` is an error rather than a silently ignored typo. Parameters are resolved before the project is created, so a bad one costs nothing.
+
+## Examples
+
+`examples/` holds the three worked macros, which double as the integration tests:
+
+| Macro | Builds |
+| --- | --- |
+| `bolt_plate.py` | A plate sized around a computed row of tapped holes |
+| `bolt_circle.py` | A flange with N tapped holes on a ring of radius R |
+| `filleted_box.py` | A box from three numbers, with every roundable edge filleted on the server |
+
+Tapped holes are `{"kind": "thread", "hole": True}`: the form is cut wider by a clearance and the shape is marked as a hole, so grouping it with the plate in the editor taps the plate. The API has no grouping endpoint yet, so the macros stop at marked holes.
+
+## Development
+
+Tests are `unittest` from the standard library, so there is nothing to install:
+
+```bash
+PYTHONPATH=src:tests python3 -m unittest discover -s tests -t tests        # unit
+PYTHONPATH=src python3 -m unittest discover -s tests/integration -t tests/integration  # needs a live server
+```
+
+From the repository root those are `npm run client:test:py` and `npm run client:test:py:integration`. The integration tests need a real server:
+
+```bash
+SKETCHFORGE_PROJECTS_DIR=$(mktemp -d) SKETCHFORGE_API_TOKEN=test-token \
+  npx next dev apps/web -p 3100 &
+export SKETCHFORGE_API_TOKEN=test-token SKETCHFORGE_URL=http://127.0.0.1:3100
+npm run client:test:py:integration
+```
+
+## Publishing
+
+See [docs/PUBLISHING_CLIENTS.md](../../docs/PUBLISHING_CLIENTS.md) for the trusted-publisher settings PyPI needs before the release workflow can publish this package.

sketchforge3d-1.2.1/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sketchforge3d"
+version = "1.2.1"
+description = "Typed client and macro runner for the SketchForge REST API."
+readme = "README.md"
+license = "AGPL-3.0-only"
+requires-python = ">=3.9"
+authors = [{ name = "SketchForge contributors" }]
+keywords = ["sketchforge", "cad", "macro", "client"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Graphics :: 3D Modeling",
+  "Typing :: Typed",
+]
+# Deliberately empty: the client uses urllib from the standard library, so it
+# installs anywhere Python does and adds nothing to a macro author's lockfile.
+dependencies = []
+
+[project.urls]
+Homepage = "https://sketchforge3d.com"
+Repository = "https://github.com/constructorfleet/SketchForge-3D"
+
+[project.scripts]
+sketchforge-macro = "sketchforge3d.macro:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sketchforge3d = ["py.typed"]

sketchforge3d-1.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sketchforge3d-1.2.1/src/sketchforge3d/__init__.py

@@ -0,0 +1,105 @@
+"""
+A client for the SketchForge REST API, and a runner for macros written against it.
+
+    from sketchforge3d import client_from_environment
+
+    client = client_from_environment()
+    project = client.project(client.projects.create("Bracket").id)
+    project.add({"kind": "box", "width": 60, "depth": 40, "height": 8})
+
+Installed as ``sketchforge3d``; imported the same way.
+"""
+
+from __future__ import annotations
+
+from . import layout
+from .client import Edges, ProjectHandle, Projects, Shapes, SketchForgeClient, Treatments, chunk
+from .environment import (
+    BASE_URL_ENV,
+    DEFAULT_BASE_URL,
+    PROJECT_ENV,
+    TOKEN_ENV,
+    client_from_environment,
+    target_project_from_environment,
+)
+from .errors import (
+    MissingConfigurationError,
+    SketchForgeApiError,
+    SketchForgeError,
+    SketchForgeTransportError,
+)
+from .layout import Point2, angle_of, centered_offsets, grid, mm, ring, row
+from ._macro import (
+    PROJECT_MODES,
+    Macro,
+    MacroContext,
+    MacroRunReport,
+    define_macro,
+    load_macro_file,
+    resolve_macro_params,
+    resolve_macro_project,
+    run_macro,
+    run_stamp,
+)
+from .types import (
+    MAX_SHAPES_PER_REQUEST,
+    PARAMETRIC_SHAPE_KINDS,
+    SHAPE_KINDS,
+    THREAD_DESIGNATIONS,
+    EdgeSummary,
+    ProjectDetail,
+    ProjectSummary,
+    ShapeSummary,
+    ShapeWriteResult,
+    TreatmentResult,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BASE_URL_ENV",
+    "DEFAULT_BASE_URL",
+    "Edges",
+    "EdgeSummary",
+    "MAX_SHAPES_PER_REQUEST",
+    "Macro",
+    "MacroContext",
+    "MacroRunReport",
+    "MissingConfigurationError",
+    "PARAMETRIC_SHAPE_KINDS",
+    "PROJECT_ENV",
+    "PROJECT_MODES",
+    "Point2",
+    "ProjectDetail",
+    "ProjectHandle",
+    "ProjectSummary",
+    "Projects",
+    "SHAPE_KINDS",
+    "Shapes",
+    "ShapeSummary",
+    "ShapeWriteResult",
+    "SketchForgeApiError",
+    "SketchForgeClient",
+    "SketchForgeError",
+    "SketchForgeTransportError",
+    "THREAD_DESIGNATIONS",
+    "TOKEN_ENV",
+    "TreatmentResult",
+    "Treatments",
+    "angle_of",
+    "centered_offsets",
+    "chunk",
+    "client_from_environment",
+    "define_macro",
+    "grid",
+    "layout",
+    "load_macro_file",
+    "mm",
+    "resolve_macro_params",
+    "resolve_macro_project",
+    "ring",
+    "row",
+    "run_macro",
+    "run_stamp",
+    "target_project_from_environment",
+]

sketchforge3d-1.2.1/src/sketchforge3d/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m sketchforge3d <file>``, the same runner as ``sketchforge-macro``."""
+
+from ._macro import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sketchforge3d-1.2.1/src/sketchforge3d/_http.py

@@ -0,0 +1,117 @@
+"""
+The one place that talks HTTP, over ``urllib`` so the package has no dependencies.
+
+Ids travel in the query string rather than the path, which is a constraint of
+the server's static-export build rather than a style choice, so every call goes
+through ``query`` and no resource builds a path by hand.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Mapping, Optional
+
+from .errors import SketchForgeApiError, SketchForgeTransportError
+
+DEFAULT_TIMEOUT_SECONDS = 60.0
+DEFAULT_RETRY_ON_BUSY = 4
+_BUSY_RETRY_BASE_SECONDS = 0.06
+
+
+def normalize_base_url(base_url: str) -> str:
+    """``http://host:3000``, with or without a trailing slash or the API prefix."""
+    trimmed = base_url.strip().rstrip("/")
+    if not trimmed:
+        raise ValueError("A base_url is required, for example http://localhost:3000.")
+    return trimmed if trimmed.endswith("/api/v1") else trimmed + "/api/v1"
+
+
+def build_url(root: str, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+    pairs = [(key, str(value)) for key, value in (query or {}).items() if value is not None]
+    suffix = "?" + urllib.parse.urlencode(pairs) if pairs else ""
+    return root + path + suffix
+
+
+class Transport:
+    """Sends one request and parses one answer, retrying only a lost project lock."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        retry_on_busy: int = DEFAULT_RETRY_ON_BUSY,
+        headers: Optional[Mapping[str, str]] = None,
+        opener: Optional[Any] = None,
+    ) -> None:
+        self.api_root = normalize_base_url(base_url)
+        self._token = token
+        self._timeout = timeout
+        self._retry_on_busy = retry_on_busy
+        self._headers = dict(headers or {})
+        #: Injectable so tests need no socket; anything with ``open(request, timeout=)``.
+        self._opener = opener or urllib.request.build_opener()
+
+    def send(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Optional[Any] = None,
+        retryable: bool = False,
+    ) -> Any:
+        url = build_url(self.api_root, path, query)
+        attempts = self._retry_on_busy + 1 if retryable else 1
+
+        for attempt in range(1, attempts + 1):
+            try:
+                return self._send_once(method, url, body)
+            except SketchForgeApiError as error:
+                # A locked *shape* also answers 409 and must not be retried,
+                # which is why the message rather than the status decides.
+                if not error.is_project_busy or attempt == attempts:
+                    raise
+                time.sleep(_BUSY_RETRY_BASE_SECONDS * attempt)
+        raise AssertionError("unreachable")
+
+    def _send_once(self, method: str, url: str, body: Optional[Any]) -> Any:
+        headers: Dict[str, str] = dict(self._headers)
+        headers["Authorization"] = "Bearer " + self._token
+        headers["Accept"] = "application/json"
+        payload = None
+        if body is not None:
+            payload = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        request = urllib.request.Request(url, data=payload, headers=headers, method=method)
+        try:
+            with self._opener.open(request, timeout=self._timeout) as response:
+                return _decode(response.read())
+        except urllib.error.HTTPError as error:
+            parsed = _decode(error.read())
+            detail = parsed.get("error") if isinstance(parsed, dict) else None
+            raise SketchForgeApiError(
+                method,
+                url,
+                error.code,
+                detail if isinstance(detail, str) else None,
+                parsed,
+            ) from None
+        except urllib.error.URLError as error:
+            raise SketchForgeTransportError(method, url, error) from None
+        except OSError as error:
+            raise SketchForgeTransportError(method, url, error) from None
+
+
+def _decode(raw: bytes) -> Any:
+    if not raw:
+        return None
+    text = raw.decode("utf-8", errors="replace")
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text