draftwright 0.3.9__tar.gz → 0.4.0__tar.gz

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

@@ -1,5 +1,161 @@
 # Changelog
 
+## Unreleased
+
+## v0.4.0 — 2026-08-02
+
+**The compat-exit release.** Every surface whose documented removal target was 0.4.0 is gone,
+and every deprecation that remains now says when it goes — in the message the caller sees, not
+only in a release note. ADR 0005 §4's rule is that an alias carries a tracking issue *and* a
+removal date, because "a facade with no exit date is a failure mode"; this release is that rule
+being kept rather than restated. `docs/deprecations.md` is the new index, and
+`tests/test_deprecation_dates.py` fails any deprecation that names no removal.
+
+Also lands ADR 0016's declared-dimensioning work (#867): a `dimension(feature, role)` is
+referential — it names a measurement and carries no number — and an authored set means omission
+is suppression, enforced at the compiled-plan boundary rather than by a flag renderers check.
+
+**Read this before upgrading:** two removals break *without a release that warned you*, because
+their deprecation never appeared in a shipped version. See *Removed (breaking)* below and
+`docs/deprecations.md`.
+
+### Removed (breaking)
+
+Compat surfaces whose documented removal target was 0.4.0 (#720, ADR 0005 §4 — every alias
+carries a tracking issue *and* a removal date, or the facade is permanent by accident):
+
+- **The seven `Drawing` compat aliases** — `_named` / `_anno_view` / `_pinned` /
+  `_build_issues`, and `_pattern_callouts` / `_patterned_holes` / `_dropped_callout_diams`.
+  These were private, and the public reads have existed since #699: use `dwg.registry`
+  (`in reg`, `names()`, `issues`, `pinned_names()`) and `dwg.coverage`, or the `Drawing` verbs
+  `annotations()` / `iter_annotations()` / `get_annotation()` / `view_of()`.
+  **Note the asymmetry.** A *read* — `dwg._named` — now raises `AttributeError`. A *write* —
+  `dwg._pinned = {...}` — does **not**: these were properties with setters, and `Drawing` has
+  no `__slots__`, so assignment now quietly creates an unrelated instance attribute that no
+  longer reaches the registry or coverage owner. Writes therefore fail silently rather than
+  loudly. Grep for `\._(named|anno_view|pinned|build_issues|pattern_callouts|patterned_holes|dropped_callout_diams)\b`
+  before upgrading; mutate through `registry.add()` / `pin()` / `record_issue()` /
+  `restore_issues()` and the `CoverageState` methods instead.
+- **The `draftwright.sheet_dsl` module** — an import alias for `draftwright.sheet` since the
+  #640 rename. Import `Sheet` from `draftwright` or `draftwright.sheet`.
+- **`generate_script`**, including its `draftwright.__all__` entry. It has raised since #940
+  retired the imperative emitter; it is now simply absent, so the failure is an `ImportError`
+  at the top of a script rather than a `RuntimeError` part-way through one. Use
+  `--script` / `emit_sheet_script`.
+- **The bespoke `--style imperative` error message.** `--style` itself is unchanged and still
+  accepts its sole value `sheet`; `imperative` is now an unrecognised value like any typo,
+  rather than one carrying its own explanation of the #940 retirement.
+
+- **Bare dimension-role spellings** — `sheet.dimension(f, "width")`. Use the parameter id,
+  `"width.length"`; `dimension_ids()` on a handle lists the valid ones. The bare role is the
+  *family* spelling: it selects every parameter carrying it, which is how
+  `dimension(step, "step")` quietly declared two measurements. In an authored set, where
+  omission means suppression, silently declaring an extra one is the mirror image of the rule
+  — so it now raises rather than resolving. (A *discriminated* bare role, used with `axis=`,
+  is unaffected: that is how variants like `grid_pitch.length.row` are addressed, and it never
+  warned.)
+- **The `Sheet.dimension(kind=…, value=…)` call shape** — use `Sheet.measured_dimension(...)`.
+  `dimension` is now solely the ADR 0016 referential verb: it names a feature and a parameter
+  id and reads the value off the geometry.
+
+Those last two break **without a release that warns you**. They were deprecated after v0.3.9
+and removed in 0.4.0, so the `DeprecationWarning` never appeared in a released version —
+upgrading from v0.3.9 or earlier goes straight from working to a raise. That is deliberate
+(ADR 0016); this entry and `docs/deprecations.md` are the only notice you get, so both
+failures name their replacement rather than raising about argument counts.
+
+### Deprecated
+
+- **The legacy `Drawing.export` shapes now emit `DeprecationWarning`** (#987) — they were
+  announced as deprecated in v0.3.1 and then said nothing at runtime for four minor releases,
+  which would have made their 0.5.0 removal a silent break. Three cases warn:
+  - `export()` with `formats=` **omitted or `None`** — the legacy default, which writes
+    SVG + DXF and returns an `(svg, dxf)` **tuple** rather than the `{format: path}` dict.
+  - the **`svg=` / `dxf=` booleans**. The suggested replacement names the formats *that call*
+    selected, so following it cannot change what gets written.
+  - passing a boolean **alongside** `formats=`, where it is silently ignored — `formats` wins,
+    and now says so.
+
+  **If you promote `DeprecationWarning` to an error, previously-passing exports will now
+  raise.** Migration: `export(out, formats=("svg", "dxf"))` and read the dict. `make_drawing`
+  is unaffected — it returns the same tuple and does not warn.
+
+### Added
+
+- **`sheet.add_dimension(feature, role)` — ask the planner to carry one more
+  measurement** (ADR 0016 / #872). Referential: it names a feature and a role and
+  carries **no number**, so the value still comes from the geometry and a size lives in
+  exactly one place. It changes *selection*, not derivation — a request can never
+  introduce a number the part does not have. Requesting something the planner already
+  emits is a deliberate no-op, so a script can ask without first knowing the rule set's
+  mind. `sheet.auto_dimensions()` states the source explicitly (optional in this
+  release; #874 makes it mandatory).
+- **Suppressing a dimension marks it; it no longer leaks into the callout** (ADR 0016 /
+  #875). `PlannedDimension.suppressed` was honoured at thirteen render sites but not by
+  the compound hole-callout path, so a suppressed counterbore still printed. The group
+  keeps its engineering data either way — what changes is whether a value reaches the
+  page. Suppressing the bore ⌀ while a counterbore, spotface or countersink segment
+  remains now **raises** and names the orphan: `⌀20 THRU ⌴ ⌀32 ↓ 1.5` has no reading with
+  its leading term removed, and silently dropping the segments would discard authored
+  intent while silently restoring the head would make the drawing say something the
+  script does not.
+- **Addressable dimension identity** (#869/#870/#871): every planned measurement now has
+  a stable `DimensionId(feature, parameter)`, and correlated measurements that must be
+  named as one — a grid pattern's row and column pitch, a step ladder — group into an
+  `AddressableDimension`. This is what a `dimension(...)` line will name, and what
+  suppression and provenance key on.
+
+### Changed
+
+- **`Sheet.dimension(kind=…, value=…)` is now `Sheet.measured_dimension(...)`**
+  (ADR 0016 / #873), and `model.declare.authored_dimension` is
+  `model.declare.measured_dimension` to match. This **reserves** the name `dimension` for
+  the referential verb ADR 0016 defines — name a feature and a role, carry no number, let
+  the engine read the value off the geometry — which `Drawing.dimension` already is and
+  `Sheet.dimension` will become. The verb that carries an explicit number needed a name
+  saying so first. The old spelling was a transitional overload during development and is
+  **removed in this same release** (#720) rather than shipping — `Sheet.dimension` is solely
+  the referential verb, and the old keyword call raises with `measured_dimension` named. See
+  *Removed (breaking)* above. Generated AP242 scripts emit `measured_dimension` and so arrive
+  un-deprecated.
+- **`Sheet` handles address features by identity, not position** (#908/#910/#912). A
+  handle, tolerance, GD&T origin, section request or dimension intent now follows *its*
+  feature through a `features` reorder instead of naming whatever took the slot.
+  Reordering with `reverse()`/`sort()` preserves every reference; deleting or replacing
+  a referenced feature raises rather than silently retargeting a neighbour. `of()` now
+  accepts a handle, and negative indices resolve uniformly across `of()`,
+  `add_dimension()` and the GD&T verbs.
+
+### Fixed
+
+- **`sheet.envelope()` measured the file, not the part** (#977). An AP242 STEP import is a
+  compound of the solid *plus its PMI presentation geometry* — annotation planes, leader
+  curves — and the declared verb measured all of it. On the NIST CTC-01 fixture it declared
+  1170 × 650 where the part is 800 × 450: an envelope 370 mm too wide, silently, in anything
+  declared by hand. `step_level()` had the same exposure, offsetting every step position by
+  the annotation overhang. Both now measure the solid body, sharing the helper the engine
+  already used for exactly this (`_analyse` and `Sheet.model`).
+- **A declared envelope's frame origin sat a half-height below a detected one** (#977). It
+  used `bbox_min.Z` where the detector uses the bbox centre. **Dimension output is unchanged** —
+  envelope sizes derive from `bbox_min`/`bbox_max`, and the overall height is compiled from the
+  model bbox — but `frame.origin` is the generic feature *site*, so **a GD&T control frame,
+  surface finish or note targeting a hand-declared `sheet.envelope()` was anchored at the
+  bottom face rather than the centre, and its leader now moves to the centre**. That is a
+  visible change on drawings carrying such an annotation; drawings without one are unaffected.
+  Scripts generated by `--script` were never affected either way: they bake the detected frame
+  explicitly rather than calling the verb.
+
+
+- **Front-view dimensions join the placement solve instead of committing to the strip**
+  (#894): they previously took strip space before the global solve ran, so a
+  higher-ranked dimension could find its space already gone. Priority only ranks
+  candidates that are *in* the solve.
+- **A hole callout reads the feature's own `through` fact** (#868) rather than inferring
+  it from whether a depth parameter happens to be present — so a suppressed depth can no
+  longer make a blind hole print `THRU`.
+- **The balloon ring clears the view it annotates after a hole-table escalation**
+  (#901/#903).
+
 ## v0.3.9 — 2026-07-26
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.3.9
+Version: 0.4.0
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -834,6 +834,20 @@ 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).
 
+Every generated script ends by naming the drawing it built, so you can critique or inspect it
+before (or instead of) exporting — one build, not two:
+
+```python
+drawing = sheet.build()
+
+for issue in drawing.lint():                  # ISO/coverage critique of THIS drawing
+    print(issue.severity, issue.code, issue.message)
+
+drawing.export("part", formats=("pdf",))
+```
+
+`sheet.export(...)` remains the one-liner for handwritten scripts that just want the file.
+
 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 —

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

@@ -138,6 +138,20 @@ 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).
 
+Every generated script ends by naming the drawing it built, so you can critique or inspect it
+before (or instead of) exporting — one build, not two:
+
+```python
+drawing = sheet.build()
+
+for issue in drawing.lint():                  # ISO/coverage critique of THIS drawing
+    print(issue.severity, issue.code, issue.message)
+
+drawing.export("part", formats=("pdf",))
+```
+
+`sheet.export(...)` remains the one-liner for handwritten scripts that just want the file.
+
 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 —

{draftwright-0.3.9 → draftwright-0.4.0}/docs/adr/README.md

@@ -32,6 +32,7 @@ architecture** table; open retired or superseded records only for design history
 | [0013](0013-uniform-recognition-and-shared-package.md) | A uniform recogniser/feature contract (with `b123d-recognisers` as its deferred shared deployment) | Enforce a uniform geometry-only recogniser contract internally; defer package extraction until there is a second consumer. | Accepted; Phase 1 in progress; extraction deferred | `test_recogniser_contract.py`, `test_import_boundaries.py` |
 | [0014](0014-collect-then-solve-annotation-placement.md) | Collect-then-solve annotation placement (as built) | Collect, select, assign, and deterministically solve annotations per corridor before rendering. | Accepted; supersedes 0009 | `test_carve_free_position_callers.py`, `test_strip_layout.py`, `test_layout_property.py`, `test_import_boundaries.py` |
 | [0015](0015-part-drawing-compiler-as-built.md) | The part-drawing compiler, as built | Use one detected-or-declared feature IR and planner-fed dimension groups as the compiler waist. | Accepted; supersedes 0008 | `test_part_model.py`, `test_detect_once.py`, `test_import_boundaries.py` |
+| [0016](0016-declared-dimensioning-intent.md) | Declared dimensioning intent: capture what to measure, let the engine place it | Declare which measurements matter as scale-independent intent routed through the planner and corridor solve; never hardcode dimension geometry. | Accepted; epic #867 complete; phase 6 landed (#940) | `test_compiled_plan_boundary.py`, `test_label_provenance.py`, `test_sheet_emit.py`, `test_add_dimension.py` |
 
 ## Historical records
 
@@ -46,6 +47,7 @@ architecture** table; open retired or superseded records only for design history
 - Compiler and state ownership: 0001 → 0005 → 0015.
 - Recognition and public declaration: 0007 → 0013 → 0011 → 0015.
 - Layout and placement: 0004 → 0014 → 0012.
+- Declared intent and the editable surface: 0001 → 0011 → 0012 → 0016.
 - Quality and correction: 0002, with provenance from 0010.
 
 Tracking issue: #745.

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.3.9"
+version = "0.4.0"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -101,6 +101,9 @@ precision = 1
 exclude_lines = [
     "pragma: no cover",
     "if TYPE_CHECKING:",
+    # `@overload` stubs are typing declarations: Python discards the bodies, so they can
+    # never execute and counting them as missed coverage measures nothing (#963).
+    "@overload",
 ]
 
 [tool.mypy]

{draftwright-0.3.9 → draftwright-0.4.0}/skills/SKILL.md

@@ -17,9 +17,12 @@ to be installed in the execution environment.
 2. **Builder (`build_drawing`)** — the same pipeline, but it hands back a live
    `Drawing` you can edit before export.
 
-Requires `draftwright >= 0.1.9` and `build123d-drafting-helpers >= 0.10.1`.
+Requires `draftwright >= 0.4.0` and `build123d-drafting-helpers >= 0.14.1`.
 Install: `pip install draftwright`.
 
+(The old floor said 0.1.9, which cannot run this guide: none of the feature-backed
+verbs existed then, and the dotted parameter ids in Step 2 are new in 0.4.0.)
+
 **Design model (worth knowing before you edit):** the engine is *deterministic*
 — no AI inside it — and you refine a drawing by **stating domain intent**
 (dimension this feature, section through here) and letting the engine **place
@@ -79,13 +82,16 @@ Then verify (Step 3). For most parts you are done here.
 
 ## Step 2 — Customise with the Drawing builder
 
-`build_drawing(...)` returns a live `Drawing`. **Edit it in *domain* vocabulary
-— locate things with `features()`, add dimensions with `place_dim()`, choose a
-side and view.** You give *what* and *where on the part*; the engine decides the
-*offset, stacking, and strip slot* (placement is automatic and constraint-based).
-You still pass page-point endpoints, but you get them from `features()` or
-`dwg.at(...)` — you never compute offsets or pick a strip. Hand-building a raw
-`Leader` at `dwg.at(...)` coordinates is the escape hatch, not the default.
+`build_drawing(...)` returns a live `Drawing`. **Edit it in *domain* vocabulary —
+name a detected *feature* and the measurement you want; the engine decides the
+offset, stacking, and strip slot.** You give *what*, never *where on the page*:
+placement is automatic and constraint-based.
+
+Prefer the feature-backed verbs (`dimension` / `locate` / `callout` / `note` /
+`drop`) over the raw page-coordinate primitives. The low-level API (`place_dim`,
+`add`, `add_view`, the view-coordinate plumbing) is **deprecated** — see
+`docs/deprecations.md` — because a raw coordinate does not route through the
+layout solve, so it cannot be re-flowed when anything around it moves.
 
 ```python
 from draftwright import build_drawing
@@ -107,61 +113,103 @@ dwg.views                   # {"front","plan","side","iso"} → (visible, hidden
 dwg.draft / dwg.scale / dwg.page_w / dwg.page_h
 ```
 
-**Add a linear dimension with `place_dim`** — it allocates the offset and stacks
-clear of existing dims; you give two page-point endpoints and a side/view:
+**Add a dimension by naming a feature and a measurement** — the engine derives the
+value from the geometry and owns the placement:
 
 ```python
 # side ∈ {"above","below","left","right"}; view ∈ {"front","plan","side"}.
-p1 = dwg.at("front", 0, 0, 0)          # world → page point
-p2 = dwg.at("front", 40, 0, 0)
-dwg.place_dim(p1, p2, "above", "front", dwg.draft, name="dim_len")
+env  = next(f for f in dwg.model().features if f.kind == "envelope")
+hole = next(f for f in dwg.model().features if f.kind == "hole")
+
+dwg.dimension(env, "length", role="width", side="above", view="front")
+dwg.locate(hole)                         # locating dimensions for the feature
+dwg.callout(hole)                        # a ⌀ callout the auto-pass missed
 
-dwg.remove("dim_od")                    # drop an automatic annotation by name
+dwg.drop(hole)                           # stop dimensioning this feature
+
+name = next(iter(dwg.annotations()))     # names come from annotations(); they are
+dwg.remove(name)                         # engine-assigned, so don't guess one
 ```
 
-**Add a diameter callout on a hole the auto-pass missed** — locate it with
-`features()` and attach a `HoleCallout` (this is what the `feature_not_dimensioned`
-lint suggestion hands you verbatim — see the loop below):
+**Mind the two spellings.** On `Drawing.dimension` the second argument is the
+parameter *kind* (`"length"`, `"diameter"`) and `role=` discriminates between
+same-kind parameters — an envelope has three `length` params with roles `width` /
+`height` / `depth`, so `dimension(env, "length")` alone is ambiguous and raises,
+naming them. `feature.parameters()` returns `DimParameter` objects carrying
+`.kind` and `.role`, so `[(p.kind, p.role) for p in feature.parameters()]` is how
+to see what a feature accepts.
+
+On the `Sheet` facade the same measurement is one dotted **parameter id** —
+`"width.length"` — and `dimension_ids()` on a handle lists them. Use the id there
+rather than the bare family role (`"width"`): the bare spelling is deprecated,
+because it is what let a single call silently declare two dimensions.
+
+`place_dim(p1, p2, side, view, …)` still exists for raw page coordinates, but it is
+the **escape hatch of last resort** (ADR 0012) and is deprecated: it bypasses the
+layout solve, so nothing re-flows around it.
+
+**Add a diameter callout on a hole the auto-pass missed** — find the bore in the
+model IR and hand it to `callout()`. This is what the `feature_not_dimensioned`
+lint suggestion hands you (it emits `dwg.callout(f)` — say *what*, not *where*):
 
 ```python
-from build123d_drafting import HoleCallout, Leader
-
-for f in dwg.features("plan"):          # plan→Z holes, front→Y, side→X
-    if abs(f.diameter - 4.0) < 0.2:
-        callout = HoleCallout(f.diameter, count=f.count, through=f.through,
-                              depth=f.depth, draft=dwg.draft)
-        elbow = (f.page_pos[0] + 15, f.page_pos[1] + 10, 0)
-        dwg.add(Leader((*f.page_pos, 0), elbow, "", dwg.draft, callout=callout),
-                name="hole_4")
+for f in dwg.model().features:
+    if f.kind == "hole" and abs(f.diameter - 4.0) < 0.2:
+        dwg.callout(f)                   # engine picks the view, leader and elbow
 ```
 
-**Escape hatch** — only when no domain verb fits (e.g. a free-form note at an
-exact spot). Prefer the above; this couples you to page mechanics:
+**Free text** at a chosen point is `note()` — a domain verb, not an escape hatch:
 
 ```python
-from build123d_drafting import Leader
-dwg.add(Leader(tip=dwg.at("front", 10, 0, 5), elbow=(8, 40, 0),
-               label="ø4 BORE", draft=dwg.draft), "ldr_bore")
+dwg.note("ø4 BORE", dwg.at("front", 10, 0, 5), view="front")
 ```
 
 Then re-lint and export:
 
 ```python
 issues = dwg.lint()                       # list of LintIssue; [] when clean
-svg, dxf = dwg.export("drawings/bracket")
+paths = dwg.export("drawings/bracket", formats=("svg", "dxf", "pdf"))
+svg, dxf = paths["svg"], paths["dxf"]
 ```
 
-`make_drawing(...)` is exactly `build_drawing(...).export()`.
+Pass `formats=` and read the `{format: path}` dict. Calling `export()` with no
+`formats` — or with the `svg=`/`dxf=` booleans — takes the legacy path and returns
+a `(svg, dxf)` tuple. Both are deprecated (v0.3.1) and removed in 0.5.0, and both
+warn from 0.4.0. See `docs/deprecations.md`.
+
+`make_drawing(...)` is unaffected and does not warn: it still returns
+`(svg_path, dxf_path)`, and passes `formats=` internally to get them.
+
+`make_drawing(...)` is `build_drawing(...).export(formats=("svg", "dxf"))`, unpacked to a
+tuple — not a bare `.export()`, which is the deprecated shape above.
 
-**Add a section or auxiliary view** with `add_view()`:
+**Section views** come from the section verb rather than from projecting a view by
+hand. The two entry points are *not* equivalent:
 
 ```python
-look = dwg.look_at
-bottom = (look[0], look[1], look[2] - dwg.dist)
-vc = dwg.add_view("bottom", part, bottom, (0, 1, 0), (260.0, 60.0))
-px, py = vc.pp(world_x, world_y, world_z)
+from draftwright import Sheet
+
+# Sheet.section() FORCES a cut, wherever you point it.
+cut = Sheet.from_part(part, number="DWG-042").section().build()
+"section_aa" in cut.views                 # True
+# section(feature) cuts through that feature; section(at=y) at an explicit Y.
+
+# Drawing.section() adds only the AUTOMATIC A–A, which fires just for qualifying
+# hidden internal geometry (a counterbore, spotface, or blind bottom). It returns
+# the placed annotation names, or [] when no section is warranted — so on a plain
+# through-holed block it does nothing at all.
+dwg.section()
 ```
 
+Arbitrary **auxiliary** views have no public verb: `add_view()` was the way to
+project one and is deprecated, so a custom viewing direction is not currently part
+of the supported surface.
+
+`add_view()` and the view-coordinate plumbing (`set_view_coordinates`,
+`drop_view_coordinates`, and the `vc.pp(...)` projector) are **deprecated** (#817):
+view projection is engine plumbing, and hand-placed views do not participate in the
+compose-then-pack layout.
+
 ---
 
 ## Step 3 — Verify
@@ -179,9 +227,9 @@ mcp__build123d-mcp__inspect_drawing(svg_path='drawings/part_name.svg')
 **A — Drawing from a STEP file**:
 
 ```python
-from draftwright import generate_script
+from draftwright.sheet_emit import generate_sheet_script
 
-generate_script(
+generate_sheet_script(
     "path/to/part.step",
     out="scripts/drawings/bracket",
     title="BRACKET", number="DWG-042",
@@ -189,6 +237,13 @@ generate_script(
 )
 ```
 
+This writes a declarative `Sheet` script: one named line per detected feature, then the
+dimension set it draws. Comment a feature line out to drop that feature; edit a value
+freely; re-run the file. (`generate_script`, the older imperative flavour, was retired in
+#940 and deleted in 0.4.0 — importing it now fails; use `generate_sheet_script` above.) The
+CLI equivalent is `draftwright part.step
+--script --out scripts/drawings/bracket`.
+
 **B — Drawing an in-session object** (hand-write the script):
 
 ```python
@@ -235,7 +290,7 @@ crit = dwg.lint_summary()
 for i in dwg.lint():
     print(i.severity, i.code, i.message)
     if getattr(i, "suggestion", None):
-        print("  fix:", i.suggestion)   # e.g. dwg.place_dim(...) / dwg.add_view(...)
+        print("  fix:", i.suggestion)   # e.g. dwg.callout(...) / dwg.dimension(...)
 
 # 3. Self-repair — auto-applies the mechanically-fixable issues (overlapping
 #    labels pushed apart, wrong-side dims flipped). Runs by default inside
@@ -249,8 +304,9 @@ dwg.pin(name)             # name from dwg.annotations(); dwg.unpin(name) to rele
 
 Codes are domain-meaningful (`feature_not_dimensioned`, `feature_count_mismatch`,
 `callout_dropped`, `location_ref_dropped`, `step_dim_dropped`, …), so a fix is
-always expressible through the domain API (`place_dim`, `features`, `add_view`),
-never the page-layout internals. Loop until `passed` (or the score plateaus).
+always expressible through the domain API (`dimension`, `locate`, `callout`,
+`features`), never the page-layout internals. Loop until `passed` (or the score
+plateaus).
 
 Coverage-only check, standalone:
 

{draftwright-0.3.9 → draftwright-0.4.0}/src/draftwright/__init__.py

@@ -24,7 +24,6 @@ from typing import TYPE_CHECKING
 # on every TAB press (#313). Each name maps to the submodule that provides it.
 _LAZY = {
     "build_drawing": "draftwright.builder",
-    "generate_script": "draftwright.builder",
     "make_drawing": "draftwright.builder",
     "Drawing": "draftwright.drawing",
     "FeatureInfo": "draftwright.drawing",
@@ -69,7 +68,7 @@ _sys.modules[__name__].__class__ = _DraftwrightModule
 
 
 if TYPE_CHECKING:  # static analysers / IDEs — no runtime import, no kernel cost
-    from draftwright.builder import build_drawing, generate_script, make_drawing
+    from draftwright.builder import build_drawing, make_drawing
     from draftwright.compose import choose_scale
     from draftwright.drawing import Drawing, FeatureInfo
     from draftwright.linting import lint_feature_coverage
@@ -92,7 +91,6 @@ __all__ = [
     "build_drawing",
     "choose_scale",
     "extract_pmi",
-    "generate_script",
     "lint_feature_coverage",
     "make_drawing",
 ]