draftwright 0.2.6__tar.gz → 0.2.8__tar.gz

{draftwright-0.2.6 → draftwright-0.2.8}/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## v0.2.8 — 2026-07-06
+
+**`--script` now defaults to the declarative `Sheet` DSL.** The editable script the CLI
+writes is the beautiful-Python surface — one commentable line per feature — for both STEP and
+build123d-object input.
+
+### Changed
+
+- **`draftwright … --script` now emits the declarative `Sheet` script by default** (was the
+  imperative edit-verb reconstruction). The imperative reconstruction is still available via
+  `--script --style imperative`. For prismatic parts the generated script reproduces the same
+  drawing as a direct build; a turned shaft's centre lines and base-diameter style are not yet
+  identical (the remaining validity gap, tracked separately). `--style imperative` now errors
+  clearly on a `module:attr` object spec (it reads a STEP file; use the default `sheet`).
+  The Sheet DSL doesn't yet model the title-block / layout aspects the imperative script
+  embeds, so `--script --style sheet` **warns** when `--drawn-by`, `--tolerance`, `--scale`
+  or `--page` is set rather than silently ignoring it (use `--style imperative` to embed them).
+
+## v0.2.7 — 2026-07-05
+
+**The three authoring modes (ADR 0011 Amendment 1).** Naming how you drive draftwright —
+*just do it* / *auto then tweak* / *generate an editable script* — and filling in the third:
+a declarative `Sheet`-DSL generator, and number-free authoring against the build123d objects
+you built.
+
+### Added
+
+- **`draftwright part.step --script --style sheet`** — generate an **editable declarative
+  `Sheet` script** from a detected part: one commentable line per feature (hole / diameter /
+  step / slot / pattern / envelope), views noted, the auto-section flagged. Comment a line out
+  to drop that feature; the script re-runs to the drawing. The existing `--script` (imperative
+  edit-verb reconstruction) stays the default (#461).
+- **Object-reading `.cbore(tool)` / `.spotface(tool)`** on a declared hole — read the
+  counterbore/spotface's ⌀ **and** depth off the tool object + part (depth measured from the
+  local open face, so a rib/wall elsewhere doesn't skew it). A `Sheet`-declared drawing can now
+  carry **zero magic numbers** and track the geometry parametrically (#462).
+- **`Sheet.of(feature)`** — a fluent handle onto an **existing / detection-seeded** feature (by
+  the build123d object, an index, or the `Feature` itself), so you can `.fit(...)` /
+  `.tolerance(...)` a feature from `Sheet.from_part()` without re-declaring it (#463).
+
+### Docs
+
+- **ADR 0011 Amendment 1** — the three authoring modes and the mode-3 generation surface;
+  records the decision to emit **honest detected numbers** for a detected part rather than
+  fabricate a build123d reconstruction that misrepresents the geometry (#464).
+
 ## v0.2.6 — 2026-07-05
 
 **ADR 0011 — the IR as a public input: declare features, don't only detect them.**

{draftwright-0.2.6 → draftwright-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.2.6
+Version: 0.2.8
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -678,10 +678,13 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: <3.15,>=3.10
 Requires-Dist: build123d-drafting-helpers>=0.13.0
-Requires-Dist: build123d>=0.9.0
+Requires-Dist: build123d<0.11,>=0.9.0; python_full_version < '3.13'
+Requires-Dist: build123d<0.12,>=0.11; python_full_version >= '3.13'
 Requires-Dist: kiwisolver<2,>=1.4
 Requires-Dist: numpy>=1.24
 Requires-Dist: reportlab>=4.0
@@ -729,7 +732,7 @@ Choose formats, scale, and page; or emit an editable drawing script:
 ```
 draftwright my_part.step --format pdf,dxf     # also: svg, all
 draftwright my_part.step --scale 2 --page A3  # override the auto scale / page
-draftwright my_part.step --script             # write an editable .py drawing script
+draftwright my_part.step --script             # write an editable declarative Sheet script
 ```
 
 `draftwright --help` lists every flag; `--version` prints the version.

{draftwright-0.2.6 → draftwright-0.2.8}/README.md

@@ -38,7 +38,7 @@ Choose formats, scale, and page; or emit an editable drawing script:
 ```
 draftwright my_part.step --format pdf,dxf     # also: svg, all
 draftwright my_part.step --scale 2 --page A3  # override the auto scale / page
-draftwright my_part.step --script             # write an editable .py drawing script
+draftwright my_part.step --script             # write an editable declarative Sheet script
 ```
 
 `draftwright --help` lists every flag; `--version` prints the version.

{draftwright-0.2.6 → draftwright-0.2.8}/pyproject.toml

@@ -4,14 +4,19 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.2.6"
+version = "0.2.8"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
 authors = [{ name = "Paul Fremantle", email = "pzfreo@gmail.com" }]
 requires-python = ">=3.10,<3.15"
 dependencies = [
-    "build123d>=0.9.0",
+    # build123d ≤0.10 pulls cadquery-ocp (VTK), whose VTK caps at Python 3.12; 0.11 switched to
+    # cadquery-ocp-novtk, which ships 3.13/3.14 wheels and drops VTK entirely (draftwright is
+    # headless — it never imports VTK). Split by Python: keep the proven ≤3.12 stack, use 0.11 on
+    # 3.13+. Mirrors pzfreo/build123d-mcp's dependency handling.
+    "build123d>=0.9.0,<0.11 ; python_full_version < '3.13'",
+    "build123d>=0.11,<0.12 ; python_full_version >= '3.13'",
     "build123d-drafting-helpers>=0.13.0",
     "kiwisolver>=1.4,<2",
     "numpy>=1.24",
@@ -30,6 +35,8 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 
 [project.scripts]
@@ -112,3 +119,12 @@ dev = [
     "pytest-xdist>=3",
     "ruff>=0.4",
 ]
+
+[tool.uv]
+# On Python 3.13/3.14, build123d resolves to 0.11, whose OCP kernel is
+# cadquery-ocp-novtk (VTK dropped from the transitive tree — fine here, draftwright
+# renders headless and never imports VTK). Its 7.9.3.1.1 release ships a broken macOS
+# wheel (no OCP.GccEnt module → build123d fails to import), so pin it out. Only bites
+# when novtk is actually resolved (build123d 0.11); harmless on 0.10/cadquery-ocp.
+# Mirrors pzfreo/build123d-mcp. Remove once upstream fixes the wheel.
+constraint-dependencies = ["cadquery-ocp-novtk!=7.9.3.1.1"]

{draftwright-0.2.6 → draftwright-0.2.8}/src/draftwright/cli.py

@@ -73,6 +73,18 @@ def _emit(dwg, formats: list[str]) -> list[str]:
     return [paths[f] for f in formats]
 
 
+def _looks_like_object_spec(s: str) -> bool:
+    """True when *s* is a ``module:attr`` / ``file.py:attr`` object reference rather than a STEP
+    path (#469). An existing file is never a spec; a plain path — a STEP file, or a Windows
+    ``C:\\…\\part.step`` drive path — has no trailing ``:identifier``, so the pattern rejects it
+    (a Windows drive colon is followed by ``\\``, not an identifier; filenames can't contain ':')."""
+    import re
+
+    if os.path.exists(s):
+        return False
+    return re.match(r"^.+:[A-Za-z_][A-Za-z0-9_]*$", s) is not None
+
+
 def _installed_version() -> str:
     """The installed distribution version (the PyPI version once pip-installed);
     ``"unknown"`` when running from a source tree with no installed metadata."""
@@ -105,6 +117,12 @@ def main(
     script: bool = typer.Option(
         False, "--script", help="Write an editable .py drawing script instead of SVG+DXF"
     ),
+    style: str = typer.Option(
+        "sheet",
+        "--style",
+        help="--script flavour: 'sheet' (declarative Sheet DSL - one line per feature, "
+        "default) or 'imperative' (edit-verb reconstruction)",
+    ),
     pmi: PmiMode = typer.Option(
         PmiMode.off,
         help=(
@@ -136,6 +154,9 @@ def main(
     logging.basicConfig(level=logging.INFO if verbose else logging.WARNING, format="%(message)s")
 
     formats = _parse_formats(output_format)
+    if script and style not in ("imperative", "sheet"):
+        # validate before the ~5 s engine import so a typo fails fast
+        raise typer.BadParameter("--style must be 'imperative' or 'sheet'", param_hint="--style")
 
     # Import the engine lazily, only on the build path: it pulls in build123d/OCP
     # (~5 s of CAD-kernel import). Keeping it out of module scope means shell
@@ -144,17 +165,56 @@ def main(
     from draftwright.builder import build_drawing, generate_script
 
     if script:
-        py_path = generate_script(
-            step_file=step_file,
-            out=out,
-            title=title,
-            number=number,
-            tolerance=tolerance,
-            drawn_by=drawn_by,
-            pmi=pmi.value,
-            scale=scale,
-            page=page,
-        )
+        if style == "sheet":
+            from draftwright.sheet_emit import generate_sheet_script, resolve_object_spec
+
+            # The Sheet DSL doesn't yet model the title-block / layout aspects the
+            # imperative script embeds. Warn rather than silently drop them so a
+            # `--script --drawn-by … --scale …` invocation isn't quietly a no-op.
+            ignored = [
+                flag
+                for flag, set_ in (
+                    ("--tolerance", tolerance != "ISO 2768-m"),
+                    ("--drawn-by", bool(drawn_by)),
+                    ("--scale", scale is not None),
+                    ("--page", page is not None),
+                )
+                if set_
+            ]
+            if ignored:
+                typer.echo(
+                    f"warning: {', '.join(ignored)} not supported by --style sheet; ignored "
+                    "(use --style imperative to embed them)",
+                    err=True,
+                )
+            if _looks_like_object_spec(step_file):
+                # STEP_FILE is a `module:attr` / `file.py:attr` spec → reference a live object
+                obj, seam = resolve_object_spec(step_file)
+                py_path = generate_sheet_script(
+                    obj, out=out, title=title, number=number, part_expr=seam
+                )
+            else:
+                py_path = generate_sheet_script(
+                    step_file, out=out, title=title, number=number, pmi=pmi.value
+                )
+        else:
+            if _looks_like_object_spec(step_file):
+                raise typer.BadParameter(
+                    "the imperative reconstruction reads a STEP file; use --style sheet "
+                    "(the default) to reference a 'module:attr' object",
+                    param_hint="--style",
+                )
+            py_path = generate_script(
+                step_file=step_file,
+                out=out,
+                title=title,
+                number=number,
+                tolerance=tolerance,
+                drawn_by=drawn_by,
+                pmi=pmi.value,
+                scale=scale,
+                page=page,
+            )
         print(py_path)
         return
 

{draftwright-0.2.6 → draftwright-0.2.8}/src/draftwright/model/declare.py

@@ -128,6 +128,45 @@ def _read_cylinder(obj) -> tuple[str, float, Point]:
     return axis, dia, center
 
 
+def read_bore_step(part, tool, axis: str) -> tuple[float, float]:
+    """``(diameter, depth)`` of a counterbore / spotface *tool* cut into *part* (ADR 0011 #462).
+
+    ⌀ comes from the tool's cylindrical face (like :func:`_read_cylinder`); **depth** is measured
+    along the hole *axis* from the part's **open face at the hole** to the tool's inner (floor)
+    face — so both values track the geometry you built, restating no numbers.
+
+    The open face is found *locally*: the part is intersected with an axial prism over the tool's
+    cross-section, so a rib / wall / boss elsewhere on the part doesn't skew the reading (the
+    global bounding box would). The counterbore opens on whichever end of that local column the
+    tool sits nearer, even when the tool overhangs the part."""
+    from build123d import Box, Pos
+
+    axis = _norm_axis(axis)
+    dia = _read_cylinder(tool)[1]
+    i = "xyz".index(axis)
+    tb, pb = tool.bounding_box(), part.bounding_box()
+    t_lo, t_hi = [tb.min.X, tb.min.Y, tb.min.Z][i], [tb.max.X, tb.max.Y, tb.max.Z][i]
+
+    # A prism over the tool's cross-section, spanning the part along the axis; intersect it with
+    # the part to get the LOCAL material column under the tool (the open face is its axial edge).
+    size = [tb.size.X, tb.size.Y, tb.size.Z]
+    cen = [tb.center().X, tb.center().Y, tb.center().Z]
+    size[i] = [pb.size.X, pb.size.Y, pb.size.Z][i] * 3 or 1.0
+    cen[i] = [pb.center().X, pb.center().Y, pb.center().Z][i]
+    try:
+        column = part & (Pos(*cen) * Box(*size))
+        cb = column.bounding_box()
+        p_lo, p_hi = [cb.min.X, cb.min.Y, cb.min.Z][i], [cb.max.X, cb.max.Y, cb.max.Z][i]
+    except Exception:  # noqa: BLE001 — degenerate boolean; fall back to the global bbox
+        p_lo, p_hi = [pb.min.X, pb.min.Y, pb.min.Z][i], [pb.max.X, pb.max.Y, pb.max.Z][i]
+
+    if (t_lo + t_hi) / 2 >= (p_lo + p_hi) / 2:
+        depth = p_hi - t_lo  # floor at the tool bottom, open at the max face
+    else:
+        depth = t_hi - p_lo  # floor at the tool top, open at the min face
+    return (round(dia, 3), round(depth, 3))
+
+
 def _span(at: Point, axis: str, length: float) -> tuple[Point, Point]:
     """The two axial end-points of a segment of *length* centred at *at* along *axis*."""
     idx = "xyz".index(axis)

{draftwright-0.2.6 → draftwright-0.2.8}/src/draftwright/sheet_dsl.py

@@ -15,15 +15,17 @@ detection is skipped and the auto-pass dimensions exactly the declared features:
 **Scope (this module):** the *feature-declaration* surface over the renderers the
 engine has today — dimensions, ⌀ callouts, holes (through / blind), turned steps,
 slots, patterns, the overall envelope, and the auto section — plus the P2a
-**``.tolerance``** aspect (a ± / limit tolerance on a diameter, a step, or a hole
-bore). The remaining #445 aspect verbs that still need new rendering — ``.fit``
-(fit-class → ISO 286 deviation), ``.thread``, ``.finish`` (surface symbols) and
+**``.tolerance``** (a ± / limit tolerance on a diameter, a step, or a hole bore) and
+**``.fit``** (fit-class → ISO 286 deviation, P2a.2) aspects. The remaining #445 aspect
+verbs that still need new rendering — ``.thread``, ``.finish`` (surface symbols) and
 ``control(...)`` (GD&T) — are the later Phase-2 items (roadmap #446) and are
 deliberately **not** stubbed here, so the surface only exposes what actually draws.
 
 **Hybrid.** :meth:`Sheet.from_part` seeds the declared set from *detection*, so you
 can start from the detected model and override specific features (declaration is for
-where you know better than detection, not everywhere — ADR 0011 §3).
+where you know better than detection, not everywhere — ADR 0011 §3); :meth:`Sheet.of`
+returns a fluent handle onto one of those generated features (by object, index, or the
+feature itself) so you can ``.fit(...)`` / ``.tolerance(...)`` it without re-declaring (#463).
 """
 
 from __future__ import annotations
@@ -33,12 +35,15 @@ from dataclasses import replace
 from draftwright.analysis import _solids_body
 from draftwright.builder import _coerce_model, build_drawing, detect_part_model
 from draftwright.fits import fit_class
+from draftwright.model import Feature
 from draftwright.model import boss as _boss
 from draftwright.model import envelope as _envelope
 from draftwright.model import hole as _hole
 from draftwright.model import pattern as _pattern
 from draftwright.model import slot as _slot
 from draftwright.model import step as _step
+from draftwright.model.declare import _norm_axis, _read_cylinder, _require_positive
+from draftwright.model.declare import read_bore_step as _read_bore_step
 
 
 def _parse_scale(scale):
@@ -98,6 +103,34 @@ class _Hole:
         )
         return self
 
+    def cbore(
+        self, obj=None, *, diameter: float | None = None, depth: float | None = None
+    ) -> _Hole:
+        """A counterbore on this hole. ``.cbore(cbore_cyl)`` reads its ⌀ + depth off the
+        counterbore tool object (⌀ from the cylindrical face, depth from the part + tool along
+        the hole axis — no numbers restated), or pass explicit ``.cbore(diameter=…, depth=…)``.
+        An object supplies defaults; explicit kwargs override (#462)."""
+        return self._set(cbore=self._read_step("cbore", obj, diameter, depth))
+
+    def spotface(
+        self, obj=None, *, diameter: float | None = None, depth: float | None = None
+    ) -> _Hole:
+        """A spotface on this hole — same as :meth:`cbore` but a shallow facing (#462)."""
+        return self._set(spotface=self._read_step("spotface", obj, diameter, depth))
+
+    def _read_step(self, kind, obj, diameter, depth) -> tuple[float, float]:
+        if obj is not None:
+            rd, rdp = _read_bore_step(
+                self._sheet._part, obj, self._sheet._features[self._i].frame.axis
+            )
+            diameter = rd if diameter is None else diameter
+            depth = rdp if depth is None else depth
+        if diameter is None or depth is None:
+            raise ValueError(f"{kind} needs a tool object, or explicit diameter= and depth=")
+        # same positivity guard declare.hole() applies to cbore/spotface (#452/#462 review)
+        _require_positive(**{f"{kind} diameter": diameter, f"{kind} depth": depth})
+        return (diameter, depth)
+
     def _set(self, **kw) -> _Hole:
         self._sheet._features[self._i] = replace(self._sheet._features[self._i], **kw)
         return self
@@ -168,6 +201,57 @@ class Sheet:
         self._features.append(feature)
         return self
 
+    def of(self, ref) -> _Hole | _Dim:
+        """A decoratable handle onto an **existing** feature — the hybrid seam (#463).
+
+        *ref* is a feature index, a :class:`Feature` already in :attr:`features` (e.g. seeded by
+        :meth:`from_part`), or the build123d **object** you built (matched by ⌀ + in-plane
+        position). Returns the same fluent handle the declaration verbs do, so you can
+        ``.fit(...)`` / ``.tolerance(...)`` — and, for a hole, ``.cbore(...)`` — a feature you
+        did not declare from scratch. Raises if the object matches no feature or is ambiguous."""
+        i = self._index_of(ref)
+        kind = self._features[i].kind
+        if kind == "hole":
+            return _Hole(self, i)
+        if kind in ("boss", "step"):
+            return _Dim(self, i, "diameter" if kind == "boss" else "length")
+        raise ValueError(f"of(): no aspect handle for a {kind!r} feature (holes / bosses / steps)")
+
+    def _index_of(self, ref) -> int:
+        if isinstance(ref, bool):
+            raise TypeError("of(): ref must be an index, a Feature, or a build123d object")
+        if isinstance(ref, int):
+            n = len(self._features)
+            if not -n <= ref < n:
+                raise IndexError(f"of(): feature index {ref} out of range (have {n})")
+            return ref % n
+        if isinstance(ref, Feature):
+            for i, f in enumerate(self._features):
+                if f is ref:
+                    return i
+            raise ValueError("of(): that Feature is not in this sheet's features")
+        return self._match_object(ref)
+
+    def _match_object(self, obj) -> int:
+        """The index of the declared feature the build123d *obj* refers to, by axis + ⌀ + the
+        two in-plane coordinates (the axial position is where they legitimately differ)."""
+        axis, dia, center = _read_cylinder(obj)
+        axis = _norm_axis(axis)
+        perp = [k for k in range(3) if k != "xyz".index(axis)]
+        matches = [
+            i
+            for i, f in enumerate(self._features)
+            if getattr(f, "diameter", None) is not None
+            and _norm_axis(f.frame.axis) == axis  # same axis — a cross-hole must not match
+            and abs(f.diameter - dia) <= 0.2
+            and all(abs(f.frame.origin[k] - center[k]) <= 0.5 for k in perp)
+        ]
+        if not matches:
+            raise ValueError("of(): no declared feature matches that object (⌀ + position)")
+        if len(matches) > 1:
+            raise ValueError("of(): the object matches several features — pass an index instead")
+        return matches[0]
+
     def hole(self, obj=None, **kw) -> _Hole:
         """Declare a hole from the tool cylinder you subtracted (or explicit values).
         Returns a fluent handle: ``.through()`` (default) / ``.depth(d)``."""