draftwright 0.3.6__tar.gz → 0.3.8__tar.gz

{draftwright-0.3.6 → draftwright-0.3.8}/.gitignore

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

{draftwright-0.3.6 → draftwright-0.3.8}/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 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
+
+- **Turned ⌀ leaders point at the feature, not a corner or across the body**
+  (#794/#798): the diameter callouts on a turned part now centre on the step's
+  mid-length (a boss keeps its frame origin; a ⌀ shared by disjoint steps centres
+  on the longest run), so the arrow lands on the middle of the feature's edge
+  rather than a step corner. A leader that would otherwise cut diagonally through
+  the body — a nested or end feature such as a ⌀6 boss stub — is re-routed out to
+  the nearest clear margin (axis-aware: X-turned → left/right, Z-turned → top/
+  bottom), pointing straight at the feature instead of clipping the silhouette. A
+  re-route that can't be placed clear-and-safe is restored and flagged, and a
+  pinned leader is never moved.
+
+### Added
+
+- **`leader_crosses_silhouette` lint notice** (#796): an info-level structural
+  notice when a leader shaft passes *through* the projected part body (as opposed
+  to a hole callout legitimately exiting an internal hole), so the gap is
+  observable even where routing cannot clear it.
+
 ## v0.3.6 — 2026-07-21
 
 ### Fixed

{draftwright-0.3.6 → draftwright-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.3.6
+Version: 0.3.8
 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,13 @@ 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
 
 [![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)

{draftwright-0.3.6 → draftwright-0.3.8}/README.md

@@ -1,6 +1,7 @@
 # draftwright
 
 [![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)

{draftwright-0.3.6 → draftwright-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.3.6"
+version = "0.3.8"
 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.6 → draftwright-0.3.8}/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
@@ -841,7 +857,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 +882,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 +909,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 +942,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.6 → draftwright-0.3.8}/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.6 → draftwright-0.3.8}/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,