draftwright 0.3.7__tar.gz → 0.3.9__tar.gz

{draftwright-0.3.7 → draftwright-0.3.9}/.gitignore

@@ -8,5 +8,8 @@ build/
 .pytest_cache/
 testenv/
 .coverage
+.coverage.*
 coverage.xml
+coverage*.json
+htmlcov/
 .DS_Store

{draftwright-0.3.7 → draftwright-0.3.9}/CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## v0.3.9 — 2026-07-26
+
+### Added
+
+- **Repeated recesses are dimensioned as one pattern, not N competing callouts**
+  (#841): identical blind pockets and identical through-slots now collapse to a single
+  grouped `5× 7.9 × 13.6 × 19 DEEP` / `4× SLOT 8 × 30` leader plus `(n-1)× pitch`
+  dim(s). Previously each member competed for its own size dims and some silently
+  dropped for want of strip room — five declared slots rendered only three length dims.
+  Both new kinds (`PocketPatternFeature`, `SlotPatternFeature`) round-trip every
+  surface: declare (`sheet.pocket_pattern(...)` / `sheet.slot_pattern(...)`),
+  recognition from a real solid (coplanar, same-facing members only), the emitted
+  Sheet script, and the editable surface (`dwg.callout(feature)` + `finalize()`).
+- **`Sheet.section()` and `Sheet.detail()` — ask for the view you need** (#841/#847):
+  a section A–A auto-fires only for a Z-axis hole with a counterbore, spotface, or
+  blind bottom, so a blind pocket's floor and depth stayed hidden-line-only with no
+  supported way to request a cut. `sheet.section(feature)` / `section(at=y)` /
+  bare `section()` force one (the cut plane is validated to lie strictly inside the
+  part), and `sheet.detail()` exposes the existing `detail_view=True` opt-in as a
+  chainable verb.
+- **External threads are a first-class declared aspect** (#859): the turned analog of
+  the #764 internal thread — `sheet.step(shaft).thread("M3x0.5")`,
+  `sheet.diameter(...).thread(...)`, and `sheet.boss(...).thread(...)` append the
+  spec to the ⌀ callout (`ø3 M3x0.5`) instead of needing a free-text `.note()`. It
+  composes with `.finish()` for Ra-on-thread, keys the callout bucket on `(⌀, thread)`
+  so a threaded and a plain ø6 stay distinct, and now round-trips through the Sheet
+  emitter — including pattern-member holes, closing the symmetric latent #764 gap.
+  Declaration-only: a plain cylinder is geometrically indistinguishable from a
+  threaded one, so there is no recogniser. *(Known limitation: the incremental
+  `callout`/`finalize(only=…)` paths still dedup thread-blind — #863.)*
+- **Blind obround pocket recognition, including imported STEP** (#837): the blind
+  counterpart of the #816 through-slot work. A stubby floored obround has side walls
+  too short to pair, so it is recovered from its semicircular end caps — clustering
+  faces by axis proximity so the quarter-cylinder split a STEP importer commonly
+  produces recognises as well as build123d's half-cylinder. A sealed internal void
+  (capped at both ends) is correctly *not* a pocket. A real tuner-jig STEP with five
+  blind pockets ships as a fixture.
+- **`sheet.slot(...).note(...)` / `sheet.pocket(...).note(...)`** (#841/#845): the
+  slot/pocket handle now anchors a note to its own feature, with no `ref=` needed
+  (an explicit `ref` still forwards, as before).
+
+### Changed
+
+- **An anchored note, GD&T frame, or finish relaxes its side instead of silently
+  vanishing** (#841/#855): an annotation declared with an explicit `view=`/`side=`
+  used to drop with only a warning when that strip was full, while the export still
+  reported success. The requested side is now a *preference* — when the strip has no
+  room the placer tries the opposite side, then the two perpendicular sides, taking
+  the first with room (via the same bounds and title-block checks, so it never
+  overshoots). A relaxed placement records an INFO `gdt_side_relaxed` issue naming
+  requested versus actual. Only when no strip fits does it drop.
+
+### Internal
+
+- **The state-bus endgame is closed to its permanent seam** (#830/#840): the
+  solve trace is filled into `BuildState` at the one construction site, the redundant
+  part-model re-attach is gone, and the detail view is now *transactional* — geometry
+  is projected at the detail scale and committed only if dimensions land, so
+  `_drop_view_coordinates` has zero engine callers. With those removed, the #817
+  decision-D method-call exemption narrows from a blanket pass to a named
+  `_LAYOUT_SEAM` allowlist (`_add_view`, `_set_view_coordinates`), accepted as the
+  permanent interactive-layout seam; every other private-method call on the drawing
+  is now flagged.
+- **A draftwright logo set** (#843) — drafting-idiom mark, all text outlined so the
+  SVGs render font-independently; the README now leads with the lockup.
+- **A worked multi-feature object-reference example** (#853) in
+  `docs/multi-feature-object-reference-workflow.md`.
+
+## v0.3.8 — 2026-07-23
+
+### Added
+
+- **`Drawing.note()` — a public free-text note verb** (#817/#820): place a free-form
+  `Note` at a page point without reaching for the low-level placement primitive —
+  `dwg.note("SEE NOTE 1", at=(x, y))`. This is the safe door for free text that the
+  privatisation below needs.
+- **Obround (racetrack) through-slot recognition** (#816): a part whose only features
+  are obround through-slots is now recognised, dimensioned, and referenceable for GD&T.
+  Previously such slots were silently undetected — and lint falsely reported the drawing
+  complete. Stubby obrounds, whose straight side walls are too short to pair, are recovered
+  from their two semicircular end caps (a round hole is never mistaken for a slot end).
+
+### Changed
+
+- **The generated Sheet script is now self-describing** (#833): `--script --style sheet`
+  emits a feature-census header, section sub-headers with repeat tallies (`8× R50`), and a
+  plain-language comment on each verb line (`# ⌀8 THRU ×4`, `# slot 40 × 120`, `# R50`).
+  All additions are comment-only, so re-run fidelity is unchanged.
+
+### Deprecated
+
+- **The low-level `Drawing` placement API is now private — the public surface is
+  safe-by-default** (#817): `add`, `place_dim`, and the view-coordinate / build-state
+  plumbing (`set_view_coordinates`, `drop_view_coordinates`, `attach_part_model`,
+  `attach_solve_trace`, `add_view`, `clear_annotations`) are deprecated in favour of the
+  feature-backed verbs (`callout` / `dimension` / `locate` / `note` / …), which route
+  through the layout solve. Each keeps a `@deprecated` (PEP 702) shim for one release —
+  so type-checkers and IDEs flag call sites, not just a runtime warning — and is slated
+  for removal in ~0.5.0.
+
+### Internal
+
+- **`AGENTS.md` — an AI-agent usage guide** (#818) with an executable check, steering
+  agents toward the safe declarative surface rather than the low-level primitives.
+- **Coverage reporting is governed and a Codecov badge added** (#825/#832).
+
 ## v0.3.7 — 2026-07-21
 
 ### Fixed

{draftwright-0.3.7 → draftwright-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.3.7
+Version: 0.3.9
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -691,11 +691,15 @@ Requires-Dist: pypdfium2>=4
 Requires-Dist: reportlab>=4.0
 Requires-Dist: svglib>=1.5
 Requires-Dist: typer>=0.12
+Requires-Dist: typing-extensions>=4.5; python_full_version < '3.13'
 Description-Content-Type: text/markdown
 
-# draftwright
+<h1 align="center">
+  <img src="docs/images/draftwright-logo.png" alt="draftwright" width="460">
+</h1>
 
 [![CI](https://github.com/pzfreo/draftwright/actions/workflows/ci.yml/badge.svg)](https://github.com/pzfreo/draftwright/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/pzfreo/draftwright/branch/main/graph/badge.svg)](https://codecov.io/gh/pzfreo/draftwright)
 [![PyPI](https://img.shields.io/pypi/v/draftwright.svg)](https://pypi.org/project/draftwright/)
 [![Python](https://img.shields.io/pypi/pyversions/draftwright.svg)](https://pypi.org/project/draftwright/)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
@@ -830,6 +834,12 @@ sheet.hole(features.m3_bore).thread("M3x0.5").finish("1.6")   # tapped + Ra on t
 An object-sourced script carries an inline tip pointing at exactly this edit; a STEP-sourced
 script keeps the detected numbers (there's no object to reference).
 
+See [`docs/multi-feature-object-reference-workflow.md`](docs/multi-feature-object-reference-workflow.md)
+for a complete, runnable walkthrough of this pattern on a multi-feature turned part —
+including the backward-compatible refactor, external threads (no `.thread()` on a step —
+use `.note(...)`), and why an object-sourced script should point at the cheap geometry
+variant of your source.
+
 ## What it produces
 
 - **Three orthographic views** (front, plan, side) sized and scaled automatically to the

{draftwright-0.3.7 → draftwright-0.3.9}/README.md

@@ -1,6 +1,9 @@
-# draftwright
+<h1 align="center">
+  <img src="docs/images/draftwright-logo.png" alt="draftwright" width="460">
+</h1>
 
 [![CI](https://github.com/pzfreo/draftwright/actions/workflows/ci.yml/badge.svg)](https://github.com/pzfreo/draftwright/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/pzfreo/draftwright/branch/main/graph/badge.svg)](https://codecov.io/gh/pzfreo/draftwright)
 [![PyPI](https://img.shields.io/pypi/v/draftwright.svg)](https://pypi.org/project/draftwright/)
 [![Python](https://img.shields.io/pypi/pyversions/draftwright.svg)](https://pypi.org/project/draftwright/)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
@@ -135,6 +138,12 @@ sheet.hole(features.m3_bore).thread("M3x0.5").finish("1.6")   # tapped + Ra on t
 An object-sourced script carries an inline tip pointing at exactly this edit; a STEP-sourced
 script keeps the detected numbers (there's no object to reference).
 
+See [`docs/multi-feature-object-reference-workflow.md`](docs/multi-feature-object-reference-workflow.md)
+for a complete, runnable walkthrough of this pattern on a multi-feature turned part —
+including the backward-compatible refactor, external threads (no `.thread()` on a step —
+use `.note(...)`), and why an object-sourced script should point at the cheap geometry
+variant of your source.
+
 ## What it produces
 
 - **Three orthographic views** (front, plan, side) sized and scaled automatically to the

{draftwright-0.3.7 → draftwright-0.3.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.3.7"
+version = "0.3.9"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -27,6 +27,8 @@ dependencies = [
     "reportlab>=4.0",
     "svglib>=1.5",
     "typer>=0.12",
+    # PEP 702 @deprecated: stdlib `warnings.deprecated` lands in 3.13; backport for 3.10–3.12.
+    "typing_extensions>=4.5 ; python_full_version < '3.13'",
 ]
 keywords = ["build123d", "cad", "drafting", "engineering-drawing", "technical-drawing", "automation"]
 classifiers = [
@@ -85,8 +87,17 @@ addopts = "--tb=short -m 'not slow'"
 [tool.coverage.run]
 source = ["src/draftwright"]
 omit = ["src/draftwright/__init__.py"]
+# Branch coverage makes the regression gate sensitive to untested decision paths,
+# which matter more than raw statement execution in the recognition/layout code.
+branch = true
 
 [tool.coverage.report]
+# Baseline measured on the full fast tier on Linux/Python 3.13 (#825):
+# 92.05% combined line+branch coverage (93.90% statements, 86.89% branches).
+# Keep two points of cross-platform/kernel headroom; ratchet upward only after the
+# lowest CI matrix result has stayed above the proposed floor.
+fail_under = 90
+precision = 1
 exclude_lines = [
     "pragma: no cover",
     "if TYPE_CHECKING:",

{draftwright-0.3.7 → draftwright-0.3.9}/src/draftwright/_core.py

@@ -32,6 +32,7 @@ from build123d import Align, BoundBox, Compound, Edge, Location, Mode, Shape, Te
 from build123d_drafting.helpers import (
     Dimension,
     TitleBlock,
+    annotate,
     draft_preset,
     format_drawing_scale,
 )
@@ -48,6 +49,21 @@ from draftwright.layout import _greedy_strip_1d, _solve_strip_1d
 _log = logging.getLogger(__name__)
 
 
+def place_annotation(registry, items, obj, name=None, view=None, feature=None):
+    """The annotation-placement primitive (#817): register *obj* under *name* — replacing any
+    prior object of that name (dropped from the render list *items*) so a name maps to one
+    object — append it to *items*, and record its owning *view* + source *feature* in *registry*.
+    Shared by :meth:`Drawing._add` and :meth:`PlacementContext.place` so the render passes place
+    annotations without reaching into the ``Drawing``. Returns *obj*."""
+    displaced = registry.named(name) if name is not None else None
+    if displaced is not None:
+        items.remove(displaced)
+    annotate(obj, name)
+    items.append(obj)
+    registry.add(obj, name, view, feature)
+    return obj
+
+
 _MARGIN = 10.0
 
 # When a sheet frame is drawn (#767), content reserves this extra band inside the border so
@@ -588,13 +604,14 @@ class DetailRequest:
         axis:         part axis the band spans / is cropped along ("x"/"y"/"z").
         lo, hi:       band bounds along ``axis`` (world mm).
         scale_needed: detail world→page scale that makes the region legible.
-        redraw:       ``redraw(dwg, view_name, detail_scale) -> int`` — draws the
-                      detail's dimensions in the placed detail view's coordinate system
-                      and returns the count placed (0 → the detailer rolls the view
-                      back rather than leave an empty box). Called once the detail is
-                      placed; the main view always carries the located head/block
-                      inline regardless, so a placement failure loses no coverage (lint
-                      reports the un-located interior instead).
+        redraw:       ``redraw(dwg, view_name, coords, detail_scale) -> int`` — draws the
+                      detail's dimensions against *coords* (the detail's
+                      :class:`ViewCoordinates`, mapped via ``coords.pp``) and returns the count
+                      placed (0 → the detailer drops the detail without committing a view, #840).
+                      Called on the SCRATCH-projected coords before the view is committed, so a
+                      zero result needs no rollback; the main view always carries the located
+                      head/block inline regardless, so a placement failure loses no coverage
+                      (lint reports the un-located interior instead).
         pad_top:      page-mm band reserved above the detail view (a horizontal
                       chain); reserved in the fit + placement.
         pads:         optional ``pads(detail_scale) -> (pad_right, pad_top)`` for a
@@ -841,7 +858,7 @@ def _add_title_block(dwg, a: Analysis):
         bx + cell["max_x"],
         _TB_CLEAR + cell["max_y"],
     )
-    dwg.add(tb, "title_block")
+    place_annotation(dwg.registry, dwg.items, tb, "title_block")
 
 
 def _make_sheet_frame(a: Analysis) -> Compound:
@@ -866,7 +883,7 @@ def _make_sheet_frame(a: Analysis) -> Compound:
 def _add_sheet_frame(dwg, a: Analysis):
     """Add the sheet border (#767), drawn last like the title block. No-op is the caller's
     (gated on ``a.frame``)."""
-    dwg.add(_make_sheet_frame(a), "sheet_frame")
+    place_annotation(dwg.registry, dwg.items, _make_sheet_frame(a), "sheet_frame")
 
 
 def _add_projection_symbol(dwg, a: Analysis):
@@ -893,7 +910,7 @@ def _add_projection_symbol(dwg, a: Analysis):
     cy = _TB_CLEAR + _TB_H - h / 2 - 2
     sym = sym.locate(Location((cx - bx, cy - by, 0)))
     sym.is_projection_symbol = True
-    dwg.add(sym, "projection_symbol")
+    place_annotation(dwg.registry, dwg.items, sym, "projection_symbol")
 
 
 def _add_zone_grid(dwg, a: Analysis):
@@ -926,12 +943,12 @@ def _add_zone_grid(dwg, a: Analysis):
         ticks.append(Edge.make_line(Vector(x1, yb, 0), Vector(x1 + tick, yb, 0)))
     grid = Compound(children=ticks)
     grid.is_zone_grid = True
-    dwg.add(grid, "zone_grid")
+    place_annotation(dwg.registry, dwg.items, grid, "zone_grid")
 
     def _label(text, cx, cy, name):
         note = Note(text, (cx, cy), draft, align=(Align.CENTER, Align.CENTER))
         note.is_zone_label = True
-        dwg.add(note, name)
+        place_annotation(dwg.registry, dwg.items, note, name)
 
     for i in range(cols):  # numbers 1.. left→right, in the bottom + top bands
         cx = x0 + (i + 0.5) * cw

{draftwright-0.3.7 → draftwright-0.3.9}/src/draftwright/analysis.py

@@ -93,6 +93,10 @@ def _will_section(model, *, is_rotational=False, cx=0.0, cy=0.0) -> bool:
 
     if model is None:
         return False
+    # An explicit Sheet.section() request (ADR 0011, #841) reserves the row even when no
+    # hole gate qualifies — a blind pocket's floor/depth section has no driving Z hole.
+    if getattr(model, "decorations", {}).get("section") is not None:
+        return True
     features = getattr(model, "features", model)
 
     def feature_member(pt) -> bool:

{draftwright-0.3.7 → draftwright-0.3.9}/src/draftwright/annotations/_common.py

@@ -18,7 +18,11 @@ from typing import Any
 
 from build123d_drafting.helpers import DEFAULT_FONT_PATH, Dimension, SafeDimension
 
-from draftwright._core import _anno_box, _text_size  # noqa: F401 — _anno_box re-exported (#700)
+from draftwright._core import (  # noqa: F401 — _anno_box re-exported (#700)
+    _anno_box,
+    _text_size,
+    place_annotation,
+)
 from draftwright._geometry import _boxes_overlap, _segment_crosses_box  # noqa: F401
 from draftwright.layout import StripCandidate, plan_strip
 from draftwright.linting.issues import LintIssue
@@ -908,6 +912,7 @@ def solve_corridor(dwg, strip, view, axis, cands, tier, corner_reserves=(), *, k
             axis,
             pairs,
             tier,
+            ctx=ctx,
             features=feats,
             sizes=sizes,
             forbid=forbid,
@@ -930,6 +935,7 @@ def solve_corridor(dwg, strip, view, axis, cands, tier, corner_reserves=(), *, k
                 axis,
                 force_pairs,
                 tier,
+                ctx=ctx,
                 force=True,
                 footprints=foots,
                 corner_reserves=corner_reserves,
@@ -996,6 +1002,9 @@ class PlacementContext:
     # so mypy does not reject the delegating calls below.
     registry: Any = None  # the drawing's AnnotationRegistry: build-issue sink + names
     coverage: Any = None  # the drawing's CoverageState
+    # The drawing's render list (#817): :meth:`place` appends here, so a render pass places an
+    # annotation through the ctx seam (``ctx.place(...)``) instead of reaching into the drawing.
+    items: Any = None
     # The ensured PartModel (ADR 0008 IR) the run's passes read, threaded off the drawing so
     # they no longer reach into ``dwg._part_model`` (#639). Both entry paths set it from the
     # PUBLIC ``dwg.model()`` after the model is ensured/attached.
@@ -1007,6 +1016,19 @@ class PlacementContext:
     # per-ctx (per-run) index is correct (mirrors the old ``Drawing._hole_feature_index``).
     _hole_feature_index: Any = field(default=None, repr=False)
 
+    def place(self, obj, name=None, view=None, feature=None):
+        """Place an annotation onto the drawing through this context (#817) — the render passes'
+        door to the placement primitive, so a pass never reaches into the ``Drawing`` (ADR 0005
+        §2). Registers *obj* under *name* (owning *view* + source *feature*) and appends it to the
+        render list. Returns *obj*."""
+        if self.items is None:
+            raise ValueError(
+                "PlacementContext.place() needs the drawing's render list — construct the context "
+                "with items=dwg.items (the orchestrator and Drawing verbs already do; a unit test "
+                "calling a render helper must pass it too)."
+            )
+        return place_annotation(self.registry, self.items, obj, name, view, feature)
+
     def feature_of_hole_at(self, location):
         """The IR hole/pattern feature whose member sits at model-space *location*, or ``None``
         (#408/#639). Attributes a balloon (which carries a recognition hole, not the IR feature)
@@ -1107,6 +1129,7 @@ def place_strip_candidates(
     cands,
     tier,
     *,
+    ctx,
     force=False,
     features=None,
     sizes=None,
@@ -1416,7 +1439,7 @@ def place_strip_candidates(
         for name, dim in placed:
             # Record feature provenance (ADR 0010): the drain-time seam for corridor-placed
             # dims — `features` maps this batch's names to their source IR feature.
-            dwg.add(dim, name, view=view, feature=(features or {}).get(name))
+            ctx.place(dim, name, view=view, feature=(features or {}).get(name))
     if tp is not None:
         tp["unplaced"] = [n for n, _ in todo]
         trace.end_pass(tp)  # folds a standalone pass's items; no-op when corridor-nested

{draftwright-0.3.7 → draftwright-0.3.9}/src/draftwright/annotations/balloons.py

@@ -234,7 +234,7 @@ def _render_balloon(dwg, view, tag, j, hole, cx, cy, bx, by, fs, r, ctx):
     # Furniture that legitimately sits on the view geometry — exempt from the
     # annotation-overlap / centreline lint, as the section arrows do.
     balloon.is_centerline = True
-    dwg.add(
+    ctx.place(
         balloon,
         f"balloon_{view}_{tag}_{j}",
         view=view,