sketchforge3d 1.2.1__py3-none-any.whl

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/__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/_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

sketchforge3d/_macro.py

@@ -0,0 +1,357 @@
+"""
+Macros: a script that is handed a connected project and builds something in it.
+
+The hard part of a macro is not the geometry, it is what happens the second time
+it runs. A script that appends shapes to a project it found is a script that
+doubles the part on every run, and the mistake is invisible until someone opens
+the project. So a macro cannot choose a project implicitly: it declares a
+project mode, and the runner -- not the macro body -- does what that mode says
+before the macro sees anything.
+
+    fresh     a new project every run, named uniquely. Nothing is ever reused,
+              so a run can never corrupt an earlier one.
+    replace   one project of that name, emptied first. Re-running gives the same
+              result, which is what "idempotent" means for a build script.
+    reuse     one project of that name, left as it is. For a macro that adds a
+              feature to whatever is already there; it is the caller's problem
+              if that runs twice.
+    target    the project id the operator names, never created and never
+              cleared. Refuses to run without one.
+
+Run one with ``python -m sketchforge3d.macro <file> [--name=value ...]``. The
+file is imported from a path the person running the command typed; nothing here
+accepts code over a socket.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _datetime
+import importlib.util
+import json
+import os
+import sys
+import time
+from dataclasses import dataclass, field
+from types import ModuleType
+from typing import Any, Callable, Dict, Mapping, Optional, Sequence, Union
+
+from . import layout as layout_module
+from .client import ProjectHandle, SketchForgeClient
+from .environment import PROJECT_ENV, client_from_environment, target_project_from_environment
+from .errors import SketchForgeApiError, SketchForgeError, SketchForgeTransportError
+
+MacroParameterValue = Union[int, float, str, bool]
+
+PROJECT_MODES = ("fresh", "replace", "reuse", "target")
+
+
+@dataclass
+class MacroContext:
+    client: SketchForgeClient
+    #: The project the mode resolved to, already created or emptied as declared.
+    project: ProjectHandle
+    params: Dict[str, MacroParameterValue]
+    #: The layout arithmetic, handed to the macro rather than imported by it.
+    layout: ModuleType
+    #: Progress, on stderr, so a macro's own result can be piped.
+    log: Callable[[str], None]
+
+
+@dataclass
+class Macro:
+    name: str
+    run: Callable[[MacroContext], Any]
+    #: One of PROJECT_MODES, optionally as ``(mode, project name)``.
+    project: Union[str, Sequence[str]] = "fresh"
+    description: str = ""
+    #: Defaults for every parameter the macro takes. They double as the schema:
+    #: an override is coerced to the type of the default, and an undeclared name
+    #: is refused rather than passed through as a string the macro misreads.
+    params: Dict[str, MacroParameterValue] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        mode, _ = _project_spec(self.project)
+        if mode not in PROJECT_MODES:
+            raise ValueError(
+                'A macro\'s project must be one of "' + '", "'.join(PROJECT_MODES) + f'", not "{mode}".'
+            )
+
+
+def define_macro(
+    name: str,
+    run: Callable[[MacroContext], Any],
+    project: Union[str, Sequence[str]] = "fresh",
+    description: str = "",
+    params: Optional[Mapping[str, MacroParameterValue]] = None,
+) -> Macro:
+    return Macro(
+        name=name,
+        run=run,
+        project=project,
+        description=description,
+        params=dict(params or {}),
+    )
+
+
+def _project_spec(project: Union[str, Sequence[str]]) -> "tuple[str, Optional[str]]":
+    if isinstance(project, str):
+        return project, None
+    parts = list(project)
+    return (parts[0] if parts else "fresh"), (parts[1] if len(parts) > 1 else None)
+
+
+def run_stamp(now: Optional[_datetime.datetime] = None) -> str:
+    """A stamp that sorts chronologically and survives a project name: ``20260102-114530``."""
+    moment = now or _datetime.datetime.now(_datetime.timezone.utc)
+    return moment.strftime("%Y%m%d-%H%M%S")
+
+
+@dataclass
+class ResolvedProject:
+    project: ProjectHandle
+    created: bool
+    cleared: int
+
+
+def resolve_macro_project(
+    client: SketchForgeClient,
+    macro: Macro,
+    target_project_id: Optional[str] = None,
+    now: Optional[_datetime.datetime] = None,
+) -> ResolvedProject:
+    """
+    The project a macro runs in, per its declared mode.
+
+    ``replace`` and ``reuse`` look the project up by name, which the API does not
+    index -- so they list every project and match. That is fine for the handful
+    a workshop has and would not be for thousands.
+    """
+    mode, declared_name = _project_spec(macro.project)
+    wanted_name = declared_name or macro.name
+
+    if mode == "target":
+        if not target_project_id:
+            raise SketchForgeError(
+                f'Macro "{macro.name}" runs in an existing project: set {PROJECT_ENV} or pass --project.'
+            )
+        # Read it before the macro starts, so a wrong id fails as a 404 here
+        # rather than halfway through a part.
+        client.projects.get(target_project_id)
+        return ResolvedProject(project=client.project(target_project_id), created=False, cleared=0)
+
+    if mode == "fresh":
+        created = client.projects.create(f"{wanted_name} {run_stamp(now)}")
+        return ResolvedProject(project=client.project(created.id), created=True, cleared=0)
+
+    existing = client.projects.find_by_name(wanted_name)
+    if existing is None:
+        created = client.projects.create(wanted_name)
+        return ResolvedProject(project=client.project(created.id), created=True, cleared=0)
+
+    handle = client.project(existing.id)
+    cleared = handle.clear() if mode == "replace" else 0
+    return ResolvedProject(project=handle, created=False, cleared=cleared)
+
+
+_TRUE = ("true", "1", "yes")
+_FALSE = ("false", "0", "no")
+
+
+def resolve_macro_params(
+    defaults: Mapping[str, MacroParameterValue],
+    overrides: Mapping[str, str],
+) -> Dict[str, MacroParameterValue]:
+    """A macro's parameters, with overrides coerced to the type of each default."""
+    resolved: Dict[str, MacroParameterValue] = dict(defaults)
+    for key, raw in overrides.items():
+        if key not in resolved:
+            known = ", ".join(sorted(resolved)) or "no parameters"
+            raise SketchForgeError(f'Unknown parameter "{key}". This macro takes: {known}.')
+        fallback = resolved[key]
+        if isinstance(fallback, bool):
+            if raw.lower() not in _TRUE + _FALSE:
+                raise SketchForgeError(f'Parameter "{key}" must be true or false, not "{raw}".')
+            resolved[key] = raw.lower() in _TRUE
+        elif isinstance(fallback, int):
+            try:
+                resolved[key] = int(raw, 10)
+            except ValueError:
+                raise SketchForgeError(f'Parameter "{key}" must be a whole number, not "{raw}".') from None
+        elif isinstance(fallback, float):
+            try:
+                resolved[key] = float(raw)
+            except ValueError:
+                raise SketchForgeError(f'Parameter "{key}" must be a number, not "{raw}".') from None
+        else:
+            resolved[key] = raw
+    return resolved
+
+
+@dataclass
+class MacroRunReport:
+    macro: str
+    project_id: str
+    project_created: bool
+    shapes_cleared: int
+    shape_count: int
+    duration_ms: int
+    result: Any
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "macro": self.macro,
+            "projectId": self.project_id,
+            "projectCreated": self.project_created,
+            "shapesCleared": self.shapes_cleared,
+            "shapeCount": self.shape_count,
+            "durationMs": self.duration_ms,
+            "result": self.result,
+        }
+
+
+def run_macro(
+    client: SketchForgeClient,
+    macro: Macro,
+    params: Optional[Mapping[str, str]] = None,
+    target_project_id: Optional[str] = None,
+    log: Optional[Callable[[str], None]] = None,
+    now: Optional[_datetime.datetime] = None,
+) -> MacroRunReport:
+    """Runs a macro and reports what it did to the project, as the CLI prints it."""
+    emit = log or (lambda message: None)
+    resolved_params = resolve_macro_params(macro.params, params or {})
+    started = time.monotonic()
+    resolved = resolve_macro_project(client, macro, target_project_id=target_project_id, now=now)
+
+    if resolved.created:
+        emit(f"project {resolved.project.id} created")
+    if resolved.cleared:
+        emit(f"{resolved.cleared} existing shape(s) removed")
+
+    result = macro.run(
+        MacroContext(
+            client=client,
+            project=resolved.project,
+            params=resolved_params,
+            layout=layout_module,
+            log=emit,
+        )
+    )
+    shapes = resolved.project.list_shapes()
+
+    return MacroRunReport(
+        macro=macro.name,
+        project_id=resolved.project.id,
+        project_created=resolved.created,
+        shapes_cleared=resolved.cleared,
+        shape_count=len(shapes),
+        duration_ms=int((time.monotonic() - started) * 1000),
+        result=result,
+    )
+
+
+def macro_from_module(module: Any, fallback_name: str) -> Macro:
+    """
+    A macro module's export, whichever way it was written.
+
+    ``MACRO = define_macro(...)`` is the documented form; a module with a bare
+    ``run`` function is accepted as the smallest thing that can work, and runs in
+    a fresh project because that is the only mode safe to assume.
+    """
+    candidate = getattr(module, "MACRO", None) or getattr(module, "macro", None)
+    if isinstance(candidate, Macro):
+        return candidate if candidate.name else define_macro(fallback_name, candidate.run)
+
+    runner = getattr(module, "run", None)
+    if callable(runner):
+        return define_macro(fallback_name, runner, project="fresh")
+
+    raise SketchForgeError(
+        f"{fallback_name} does not look like a macro: set MACRO = define_macro(...), "
+        "or define run(context)."
+    )
+
+
+def load_macro_file(path: str) -> Macro:
+    """Imports a macro file by path, under its own module name."""
+    absolute = os.path.abspath(path)
+    if not os.path.isfile(absolute):
+        raise SketchForgeError(f"No macro file at {absolute}.")
+    stem = os.path.splitext(os.path.basename(absolute))[0]
+    spec = importlib.util.spec_from_file_location(f"sketchforge_macro_{stem.replace('-', '_')}", absolute)
+    if spec is None or spec.loader is None:
+        raise SketchForgeError(f"{absolute} could not be imported as a Python module.")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return macro_from_module(module, stem)
+
+
+def parse_parameters(pairs: Sequence[str]) -> Dict[str, str]:
+    """``--count=5`` style overrides, as argparse leaves them."""
+    parsed: Dict[str, str] = {}
+    for pair in pairs:
+        name, separator, value = pair.lstrip("-").partition("=")
+        if not separator or not name:
+            raise SketchForgeError(f'Expected --name=value, got "{pair}".')
+        parsed[name] = value
+    return parsed
+
+
+def describe_report(report: MacroRunReport) -> str:
+    lines = [
+        f"macro      {report.macro}",
+        f"project    {report.project_id}{' (created)' if report.project_created else ''}",
+    ]
+    if report.shapes_cleared:
+        lines.append(f"cleared    {report.shapes_cleared}")
+    lines.append(f"shapes     {report.shape_count}")
+    lines.append(f"took       {report.duration_ms} ms")
+    if report.result is not None:
+        lines.append(f"result     {json.dumps(report.result, default=str)}")
+    return "\n".join(lines)
+
+
+def _explain(error: BaseException) -> str:
+    """A failure a macro author can act on, rather than a stack trace through urllib."""
+    if isinstance(error, SketchForgeTransportError):
+        return f"{error}\nIs the server running, and is SKETCHFORGE_URL pointing at it?"
+    if isinstance(error, SketchForgeApiError):
+        if error.looks_disabled:
+            return "The server has no SKETCHFORGE_API_TOKEN set, so its REST API is switched off."
+        if error.needs_storage:
+            return "The server has no SKETCHFORGE_PROJECTS_DIR set, so it has nowhere to store projects."
+    return str(error)
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m sketchforge3d.macro",
+        description="Run a SketchForge macro file against the server named by the environment.",
+        epilog=(
+            "Environment: SKETCHFORGE_API_TOKEN (required), SKETCHFORGE_URL "
+            "(default http://127.0.0.1:3000), SKETCHFORGE_PROJECT_ID (for a target macro)."
+        ),
+    )
+    parser.add_argument("file", help="the macro file to run")
+    parser.add_argument("--project", dest="project_id", help="the project for a target macro")
+    parser.add_argument("--json", action="store_true", help="print the run report as JSON")
+    parsed, extra = parser.parse_known_args(list(argv) if argv is not None else sys.argv[1:])
+
+    try:
+        overrides = parse_parameters(extra)
+        macro = load_macro_file(parsed.file)
+        client = client_from_environment()
+        report = run_macro(
+            client,
+            macro,
+            params=overrides,
+            target_project_id=parsed.project_id or target_project_from_environment(),
+            log=lambda message: print(message, file=sys.stderr),
+        )
+    except SketchForgeError as error:
+        print(_explain(error), file=sys.stderr)
+        return 1
+
+    print(json.dumps(report.as_dict(), indent=2, default=str) if parsed.json else describe_report(report))
+    return 0