draftwright 0.3.8__tar.gz → 0.3.9__tar.gz

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

@@ -1,5 +1,73 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.3.8
+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
@@ -694,7 +694,9 @@ 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)
@@ -832,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.8 → draftwright-0.3.9}/README.md

@@ -1,4 +1,6 @@
-# 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)
@@ -136,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.8 → draftwright-0.3.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.3.8"
+version = "0.3.9"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }

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

@@ -604,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

{draftwright-0.3.8 → 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.8 → draftwright-0.3.9}/src/draftwright/annotations/from_model.py

@@ -778,14 +778,15 @@ def _diameter_row_below(dwg, items, start: int = 0, trace=None, *, ctx) -> int:
         if ev is not None:
             ev["items"].extend(
                 {"label": f"ø{_fmt(d)}", "outcome": "dropped", "reason": "no_room_below"}
-                for _, d, _, _ in items
+                for _, d, _, _, _ in items
             )
         return 0
     specs = []  # (tip_page, dia, label, feature), tip on the step's bottom silhouette,
-    for anchor, dia, feat, dtol in items:  # centred along the feature's length (not a corner)
+    for anchor, dia, feat, dtol, thr in items:  # centred along the feature's length (not a corner)
         ax, ay, az = anchor
         tip = dwg.at("front", ax, ay, az - dia / 2)
-        specs.append((tip, dia, f"ø{_fmt(dia)}{_tol_suffix(dtol, draft)}", feat))
+        label = f"ø{_fmt(dia)}{_tol_suffix(dtol, draft)}" + (f" {thr}" if thr else "")  # #859
+        specs.append((tip, dia, label, feat))
     # Real measured width, not the per-char estimate: helpers >=0.14 label boxes are
     # honest about the rendered string, so an underestimated min_gap here surfaces as a
     # visible annotation_overlap between adjacent labels (hypothesis tier).
@@ -811,7 +812,7 @@ def _diameter_row_below(dwg, items, start: int = 0, trace=None, *, ctx) -> int:
     # when direction-aware label intervals actually collide, enforce elbow ≥ tip with
     # a left-to-right min_gap cascade; overflow drops the smallest ø (#298) and
     # re-solves. No-op for ordinary rows.
-    _SHELF = 2.0  # helpers Leader: the label hangs one shelf-length off the elbow
+    _SHELF = draft.pad_around_text  # helpers Leader shelf_len = gap = draft.pad_around_text
 
     def _label_ivals(svs, positions):
         out = []
@@ -882,24 +883,36 @@ def _diameter_column_left(dwg, items, start: int = 0, trace=None, *, ctx) -> int
     ev = trace.pass_event("diameter_column_left", view="front") if trace is not None else None
     draft = dwg.draft
     fx0, fy0, _, fy1 = dwg.view_bounds("front")
-    label_w = (
-        max(len(f"ø{_fmt(dia)}{_tol_suffix(dtol, draft)}") for _, dia, _, dtol in items)
-        * draft.font_size
-        * _EST_CHAR_WIDTH_EM
+    # Real measured width, not the per-char estimate (#859): a thread spec is arbitrary text,
+    # so `len * 0.62 em` can underestimate a wide label and let it cross the margin
+    # (annotation_out_of_bounds). Measure the completed label like the row-below path does.
+    label_w = max(
+        _text_size(
+            f"ø{_fmt(dia)}{_tol_suffix(dtol, draft)}" + (f" {thr}" if thr else ""),
+            draft.font_size,
+            getattr(draft, "font_path", DEFAULT_FONT_PATH),
+            getattr(draft, "font", "Arial"),
+        )[0]
+        for _, dia, _, dtol, thr in items
     )
     elbow_x = fx0 - (draft.font_size + 2 * draft.pad_around_text)
-    if elbow_x - label_w < _MARGIN:
+    # A left-directed leader hangs its label a shelf-length PAST the elbow, so the label's left
+    # edge sits at elbow_x - shelf - label_w; the guard must reserve the shelf or a near-boundary
+    # label overshoots the margin. The shelf is the helpers Leader's gap = draft.pad_around_text,
+    # not a fixed 2.0 (#859, Codex #862 r4/r5).
+    if elbow_x - draft.pad_around_text - label_w < _MARGIN:
         if ev is not None:
             ev["items"].extend(
                 {"label": f"ø{_fmt(d)}", "outcome": "dropped", "reason": "no_room_left"}
-                for _, d, _, _ in items
+                for _, d, _, _, _ in items
             )
         return 0
     specs = []  # (tip_page, dia, label, feature), tip on the step's left silhouette,
-    for anchor, dia, feat, dtol in items:  # centred along the feature's length (not a corner)
+    for anchor, dia, feat, dtol, thr in items:  # centred along the feature's length (not a corner)
         ax, ay, az = anchor
         tip = dwg.at("front", ax - dia / 2, ay, az)
-        specs.append((tip, dia, f"ø{_fmt(dia)}{_tol_suffix(dtol, draft)}", feat))
+        label = f"ø{_fmt(dia)}{_tol_suffix(dtol, draft)}" + (f" {thr}" if thr else "")  # #859
+        specs.append((tip, dia, label, feat))
     half_h = draft.font_size / 2 + draft.pad_around_text
     min_gap = 2 * half_h
     # Place what fits; drop the smallest ø first, never the whole column (#298).
@@ -1006,24 +1019,30 @@ def render_diameters(dwg, groups, tol: float = 0.15, *, ctx, only=None) -> int:
         if dpd is None:
             continue
         dia = dpd.param.value
-        if any(abs(dia - m) <= tol for m in mentioned):
+        # An EXTERNAL thread (#859) makes a distinct callout: a threaded ⌀6 ("ø6 M6x1") and a
+        # plain ⌀6 are NOT the same label, so the bucket keys on (⌀, thread) — this never drops a
+        # thread on a shared ⌀, and a threadless model keys every entry on (⌀, None) exactly as
+        # before (byte-identical). entry = [anchor, dia, {features}, ± tolerance, thread]. A
+        # callout is per (axis, ⌀, thread); the first authored tolerance on a shared ⌀ wins.
+        thr = getattr(g.feature, "thread", None)
+        # A coincident plain ⌀ already drawn (a bore, another step) dedups only an UNTHREADED ⌀;
+        # a threaded ⌀ is a distinct callout, so a bare ⌀8 mention must not suppress ø8 M8x1.25.
+        if thr is None and any(abs(dia - m) <= tol for m in mentioned):
             continue
         bucket = {"x": row_buckets, "z": col_buckets}.get(g.feature.frame.axis)
         if bucket is None:
             continue
-        dkey = round(dia, 2)
         dtol = dpd.param.tolerance
-        # entry = [anchor, dia, {features}, ± tolerance]. A callout is per (axis, ⌀); the
-        # first authored tolerance on a shared ⌀ wins (P2a — a single callout, one label).
-        entry = bucket.setdefault(dkey, [g.anchor, dia, set(), dtol])
+        dkey = (round(dia, 2), thr)
+        entry = bucket.setdefault(dkey, [g.anchor, dia, set(), dtol, thr])
         entry[2].add(g.feature)
         if entry[3] is None:
             entry[3] = dtol
 
     def _items(buckets):
         return [
-            (_diameter_step_anchor(a, fs), d, next(iter(fs)) if len(fs) == 1 else None, t)
-            for a, d, fs, t in buckets.values()
+            (_diameter_step_anchor(a, fs), d, next(iter(fs)) if len(fs) == 1 else None, t, thr)
+            for a, d, fs, t, thr in buckets.values()
         ]
 
     # The placers name leaders m_dia_{x,z}{start+i} CONTIGUOUSLY from one start. The auto-pass
@@ -1541,6 +1560,13 @@ def _pocket_label(width, length, depth, wsfx="", lsfx="", dsfx="") -> str:
     return f"{_fmt(width)}{wsfx} × {_fmt(length)}{lsfx} × {_fmt(depth)}{dsfx} DEEP"
 
 
+def _slot_label(width, length, wsfx="", lsfx="") -> str:
+    """The grouped slot-array callout string: ``SLOT {width} × {length}`` (#841). A slot has no
+    depth, so — unlike :func:`_pocket_label` — there is no ``× depth DEEP``; the ``SLOT`` prefix
+    names the feature the way a lone slot's linear dims otherwise would."""
+    return f"SLOT {_fmt(width)}{wsfx} × {_fmt(length)}{lsfx}"
+
+
 # Unit lead directions tried (nearest-clear wins), diagonals first so a central pocket's
 # leader exits toward a corner (usually the emptiest margin) before an edge.
 _POCKET_LEAD_DIRS = (
@@ -1730,8 +1756,11 @@ def render_boss_diameters(dwg, groups, a, *, ctx) -> int:
             continue
         dia = dpd.param.value
         dtol = dpd.param.tolerance
-        if any(abs(dia - m) <= 0.15 for m in mentioned):
-            continue  # a coincident bore / step already carries this ø
+        thr = getattr(b, "thread", None)  # external thread appends to the OD callout (#859)
+        # A coincident plain ⌀ dedups only an UNTHREADED boss; a threaded ⌀ is a distinct callout,
+        # so a bare ⌀8 mention (a bore, a step) must not suppress ø8 M8x1.25 (#859).
+        if thr is None and any(abs(dia - m) <= 0.15 for m in mentioned):
+            continue
         view = view_of.get(b.frame.axis)
         if view is None:
             continue
@@ -1743,7 +1772,7 @@ def render_boss_diameters(dwg, groups, a, *, ctx) -> int:
                 f"m_bossdia_{b.frame.axis}{bi}",
                 view,
                 vb,
-                f"ø{_fmt(dia)}{_tol_suffix(dtol, draft)}",
+                f"ø{_fmt(dia)}{_tol_suffix(dtol, draft)}" + (f" {thr}" if thr else ""),
                 # arrowhead on the boss circle's rim, not its centre
                 _radial_candidates(dwg, view, vb, b, reach, rim=dia / 2 * a.SCALE),
             )
@@ -2298,9 +2327,15 @@ def render_step_lengths(dwg, groups, *, ctx, only=None) -> int:
                     (dwg.at("front", hlo, 0, 0), dwg.at("front", hhi, 0, 0), hhi - hlo, None)
                 )
 
-                def _redraw(dwg, view, detail_scale, _hw=ra):
+                def _redraw(dwg, view, coords, detail_scale, _hw=ra):
                     # View-scoped name prefix so two detail views never collide (#307 review).
-                    hsegs = [(dwg.at(view, *a), dwg.at(view, *b), v, t) for a, b, v, t in _hw]
+                    # Map world→page against the detail coords (not a live dwg.at) so the view can be
+                    # committed only after these dims land — no place-then-roll-back (#840).
+                    def _at(x, y, z):
+                        px, py = coords.pp(x, y, z)
+                        return (px, py, 0.0)
+
+                    hsegs = [(_at(*a), _at(*b), v, t) for a, b, v, t in _hw]
                     return _draw_step_chain(
                         dwg, view, hsegs, f"dim_{view}_steplen", detail_scale, ctx=ctx
                     )
@@ -3435,28 +3470,50 @@ def render_gdt(dwg, model, a, *, ctx) -> int:
                 _zones=_zones,
                 _px=_px,
                 _py=_py,
-                _hz=_hz,
                 _sz=_sz,
                 _bld=_bld,
                 _feat=_feat,
                 _tb=_tb,
             ):
-                alt = {"above": "below", "below": "above", "left": "right", "right": "left"}[_s]
-                alt_strip = getattr(_zones, alt, None)
-                if alt_strip is not None:
-                    axis2 = "y" if alt in ("above", "below") else "x"
+                # Auto-relax the requested side (#841 outcome C): the requested strip is full, so
+                # try the OPPOSITE side, then the two PERPENDICULAR sides, placing on the first
+                # with room. A note the caller asked to see should appear somewhere legible
+                # rather than vanish; when the requested strip has no room, an explicit `side=`
+                # is a preference, not a hard constraint. A perpendicular side flips the leader
+                # orientation (`_bld(pos, _hz=hz)`). If the placement lands on a side other than
+                # requested, record an INFO issue so the relaxation is visible, not silent — the
+                # #841 goal is that a requested annotation is never *silently* lost.
+                relax_order = {
+                    "above": ("below", "right", "left"),
+                    "below": ("above", "right", "left"),
+                    "left": ("right", "above", "below"),
+                    "right": ("left", "above", "below"),
+                }[_s]
+                for alt in relax_order:
+                    alt_strip = getattr(_zones, alt, None)
+                    if alt_strip is None:
+                        continue
+                    hz = alt in ("above", "below")  # perpendicular sides flip the leader axis
+                    axis2 = "y" if hz else "x"
                     extent = _sz[1] if axis2 == "y" else _sz[0]  # the glyph's stacking-axis size
-                    perp = (_px, _px + _sz[0]) if _hz else (_py - _sz[1] / 2, _py + _sz[1] / 2)
+                    perp = (_px, _px + _sz[0]) if hz else (_py - _sz[1] / 2, _py + _sz[1] / 2)
                     pos = carve_free_position(dwg, alt_strip, _v, axis2, max(tier, extent), perp)
-                    if pos is not None:
-                        dim = _bld(pos)
-                        if not _box_hits(_anno_box(dim), (_tb,)):  # clear of the title block
-                            ctx.place(dim, nm, view=_v, feature=_feat)  # alternate side
-                            return
+                    if pos is None:
+                        continue
+                    dim = _bld(pos, _hz=hz)
+                    if _box_hits(_anno_box(dim), (_tb,)):  # would overlap the title block — skip
+                        continue
+                    ctx.place(dim, nm, view=_v, feature=_feat)  # relaxed side
+                    ctx.record_issue(
+                        "info",
+                        "gdt_side_relaxed",
+                        f"{nm}: the {_v} {_s} strip was full — placed on {alt} instead",
+                    )
+                    return
                 ctx.record_issue(
                     "warning",
                     "gdt_dropped",
-                    f"{nm} not placed (no room in the {_v} {_s} strip or its opposite)",
+                    f"{nm} not placed (no room in any {_v} strip)",
                 )
 
             ctx.post_drain.append(_retry)