draftwright 0.4.0__tar.gz → 0.4.2__tar.gz

{draftwright-0.4.0 → draftwright-0.4.2}/.gitignore

@@ -12,4 +12,5 @@ testenv/
 coverage.xml
 coverage*.json
 htmlcov/
+site/
 .DS_Store

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

@@ -2,6 +2,157 @@
 
 ## Unreleased
 
+## v0.4.2 — 2026-08-09
+
+**The trustworthy manufacturing drawings release.** AP242 PMI is now accounted for from its
+source records through lowering and rendering, imported datum faces retain an auditable topology
+identity, and several drawing paths that previously omitted, invented, or stalled on defining
+geometry now fail closed or produce the required annotation.
+
+### Added
+
+- **AP242 geometric tolerances and datum features survive as source-backed manufacturing
+  requirements** (#62/#675/#1094/#1095/#1099/#1100). The importer recovers range-encoded
+  dimensional tolerances, tolerance characteristics, magnitudes, datum chains, and supported
+  all-around/all-over modifiers. Datum representation-item faces are resolved to imported
+  topology through OCCT's exact transfer relationship rather than geometric resemblance, so the
+  NIST CTC-01 datum definitions `A`, `B`, and `C` lower and render without guessing.
+
+- **PMI completeness lint reconciles every AP242 source record through extraction, projection,
+  lowering, and rendering** (#623). Unsupported or incomplete requirements remain explicit with
+  source-specific outcomes instead of allowing a partial PMI transcription to report clean.
+
+- **Hexagonal and other regular polygonal bosses are recognised and dimensioned by their
+  across-flats size** (#676). Automatic and declared paths share the same feature model, and
+  mutation tests reject incomplete, unequal, non-planar, and ambiguous face sets.
+
+- **Generated `Sheet` scripts preserve references to named source objects where correspondence
+  is proven** (#1041). The `--script` path emits declarations such as
+  `sheet.hole(features.tap)` instead of copying detected numbers; ambiguous, stale, non-shape, or
+  unused mappings fail closed.
+
+- **A curated API reference is published at
+  <https://pzfreo.github.io/draftwright/>** (#846), covering the supported entry points,
+  `Sheet` declaration surface and fluent handles, `Drawing` results, and feature constructors.
+
+### Fixed
+
+- **Recognition no longer combines faces from different solids into phantom slots or pads**
+  (#958). Each physical solid is recognised independently before the results are combined.
+
+- **`Sheet.from_part(...).envelope()` reuses the detected whole-part envelope** (#1000) instead
+  of appending a duplicate feature whose dimensions were then silently deduplicated on the page.
+
+- **Crowded Z-turned step chains recover the independently approved overall height when the
+  chain cannot be placed** (#955), and placed step lengths retain measurement identity for
+  differential audit (#1004).
+
+- **All-over GD&T leaders and complex STEP B-spline paths have bounded, export-safe DXF
+  conversion** (#1097/#1070). All-over scope now reaches the existing export-safe leader
+  representation, while spline conversion reads OCCT knots, poles, and weights through its
+  indexed API instead of expensive sequence wrappers; visible curve geometry is preserved.
+
+### Changed
+
+- **Hosted CI retains every supported Python version and both dependency/kernel generations on
+  macOS and Windows with a smaller compatibility matrix** (#1103). PRs still require lint,
+  coverage, Codecov, and the compatibility gates; the slow standards tier runs once after merge.
+
+- **The pinned wheel fixture now records mutation-gated evidence for a repeating 13-fold radial
+  profile without claiming gear semantics** (#1085). Runtime recognition remains fail-closed
+  until a separate feature contract has independently sufficient evidence.
+
+## v0.4.1 — 2026-08-07
+
+**The recognition trust release.** Automatic drawings now fail closed on unsupported inner
+profiles, prove semantic coverage for flats, slots and patterns, and retain the measurement
+identity needed to explain placed, suppressed, dropped and missing definitions. Several real
+STEP case studies also move from clean-looking but incomplete output to complete drawings or
+actionable lint.
+
+### Discouraged (supported)
+
+- **`Sheet.auto_dimensions()` and `Sheet.add_dimension()` now emit
+  `SoftDeprecationWarning`** (#1043). They remain supported with no removal planned; the
+  warning steers declared scripts toward `authored_dimensions()` plus explicit
+  `dimension(feature, parameter_id)` lines, where omission can mean suppression. Automatic
+  `build_drawing(part)` and the `Sheet.from_part(part)` on-ramp remain silent. See
+  `docs/deprecations.md` for filtering and migration guidance.
+
+### Added
+
+- **Finished drawings expose why measurements were omitted and, on covered placement paths,
+  what an annotation measures** (#996/#1002). `Drawing.suppressions()` returns the compiler's
+  omission ledger, `Drawing.measurement_keys(name)` exposes recorded measurement provenance, and
+  `draftwright.audit.diff_builds(before, after)` reports losses, substitutions and candidate
+  suppression explanations. The differential is deliberately a triage aid, not a proof where
+  renderer identity remains incomplete.
+
+- **Physical-completeness lint now follows semantic correspondence for flats, lone slots and
+  slot patterns** (#1018). Coverage is joined through recognition, IR and compiler identities
+  rather than inferred from label text or page geometry, and distinguishes authored
+  suppression, placement drops, missing definitions and unverifiable provenance.
+
+- **Full-span floored open channels are recognised and dimensioned as first-class features**
+  (#917). Automatic and declared drawings state the independent overall extent, one wall and
+  channel width, suppress the derived opposite wall, and report any missing member of that
+  defining chain.
+
+### Fixed
+
+- **Square and near-square parts retain both independent planar extents** (#997). A plain
+  square plate could previously lose both plan dimensions, while parts up to five percent off
+  square could lose one and be silently represented as square. The unsafe suppression rule is
+  removed; explicit square notation remains tracked separately in #918.
+
+- **Machined flats retain their physical stock identity from recognition through placement
+  and completeness lint** (#1013/#1015/#1034/#1036). Flats on separate parallel, coaxial or
+  slanted stock no longer collapse into one definition or borrow an opposite face from another
+  stock region. Independent callouts receive clear-margin candidates, while double-D faces on
+  one stock still form one A/F requirement.
+
+- **Dense callout and step-detail cases keep their complete defining set** (#915). Hole
+  callout batches are reconciled as a queue, detail views fit their actual aspect, step levels
+  retain the supporting-face correspondence needed for truthful crops, and a detail redraws
+  only rungs omitted from its parent view.
+
+- **Pocket leaders start on the physical opening rim** (#916), removing the spurious inner
+  silhouette crossing while preserving the solved label corridor and approved dimensions on
+  X-, Y- and Z-depth pockets.
+
+- **Wedge-mounted raised pads survive recognition** (#909). Lower ledges that touch only in
+  plan no longer make the recogniser discard a valid upper pad; true staircase tiers remain
+  excluded.
+
+- **Annotation-dense detail placement no longer stalls the build** (#1065). Detail views
+  avoid every decomposed annotation shaft, witness, label and item footprint; CTC-02
+  supplies 571 such boxes. The free-rectangle search previously treated that set as tiny
+  and admitted roughly 34 billion candidate rectangles, exhausting the slow tier's
+  ten-minute test budget before export. A compressed-coordinate sweep preserves the same
+  deterministic winning rectangle while completing the real search in seconds.
+
+- **Through double-D bores are recognised and called out as first-class hole profiles**
+  (#1061). Automatic and declared builds preserve the parent-circle diameter, A/F size,
+  orientation and depth, and render one compound `DOUBLE-D ... A/F` bore callout. Physical
+  critique now accepts that supported inner profile while retaining a separate warning for
+  13 evenly spaced common-circle arcs on the unresolved outer boundary; it does not infer a
+  repeating full profile or a gear standard.
+
+- **Unsupported internal profiles no longer pass physical-completeness lint silently**
+  (#1058). Inner loops on principal boundary faces are checked against the current
+  circular-hole, rectangular-opening, true-obround, and proven through-double-D vocabulary.
+  Profiles outside it now produce
+  `unrecognised_defining_geometry` and reduce the lint score instead of allowing an
+  envelope-only drawing to score 1.0.
+
+### Changed
+
+- **Crowded prismatic step dimensions recover into an enlarged detail view by default**
+  (#909). The automatic `build_drawing` / `make_drawing` / CLI paths and generated
+  `Sheet` scripts now preserve the omitted dimensions instead of returning
+  `step_dim_dropped` unless the caller remembered `detail_view=True`. Pass
+  `detail_view=False` to retain the parent-view-only behavior and its lint warning.
+
 ## v0.4.0 — 2026-08-02
 
 **The compat-exit release.** Every surface whose documented removal target was 0.4.0 is gone,

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

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.4.0
+Version: 0.4.2
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
 Project-URL: Issues, https://github.com/pzfreo/draftwright/issues
 Project-URL: Changelog, https://github.com/pzfreo/draftwright/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://pzfreo.github.io/draftwright/
 Author-email: Paul Fremantle <pzfreo@gmail.com>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
                                Version 3, 19 November 2007
@@ -682,6 +683,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: <3.15,>=3.10
+Requires-Dist: antlr4-python3-runtime<4.10
 Requires-Dist: build123d-drafting-helpers>=0.14.1
 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'
@@ -689,6 +691,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: pillow>=10
 Requires-Dist: pypdfium2>=4
 Requires-Dist: reportlab>=4.0
+Requires-Dist: steputils==0.1
 Requires-Dist: svglib>=1.5
 Requires-Dist: typer>=0.12
 Requires-Dist: typing-extensions>=4.5; python_full_version < '3.13'
@@ -705,6 +708,9 @@ Description-Content-Type: text/markdown
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
+**[API reference](https://pzfreo.github.io/draftwright/)** ·
+**[Examples and source](https://github.com/pzfreo/draftwright#readme)**
+
 Automated technical-drawing generation for [build123d](https://github.com/gumyr/build123d).
 Point it at a solid (or a STEP file) and get a fully-annotated multi-view engineering
 drawing — orthographic views, dimensions, section A–A, ISO hatching, title block — ready
@@ -771,9 +777,12 @@ from draftwright import build_drawing
 
 dwg = build_drawing(part, title="Mounting Plate")
 issues = dwg.lint()                       # list[LintIssue] — coverage, page bounds, ISO
-svg_path, dxf_path = dwg.export("my_part")
+paths = dwg.export("my_part", formats=("svg", "dxf"))   # {"svg": ..., "dxf": ...}
 ```
 
+`export()` with no `formats=` returns the old `(svg, dxf)` tuple; that shape is deprecated
+and removed in 0.5.0 (see [docs/deprecations.md](docs/deprecations.md)).
+
 ### Declarative drawings — reference features, declare intent
 
 Instead of relying on detection, **reference the build123d objects you built** and declare
@@ -789,10 +798,16 @@ plate = Box(120, 80, 20)
 bore = Pos(0, 0, 0) * Cylinder(4, 20)
 
 sheet = Sheet(plate - bore, title="Plate", number="DWG-002")
-sheet.envelope()
+env = sheet.envelope()
 sheet.datum("A", plate.faces().sort_by()[-1])             # datum A on the top face
 hole = sheet.hole(bore).finish("1.6").note("M3x0.5 TAP")  # ⌀8 bore, Ra 1.6, tapped
 sheet.control(hole).position(0.1, to="A", diameter=True)  # ⌀0.1 position wrt A
+
+sheet.authored_dimensions()                               # THIS is the complete set
+sheet.dimension(env, "width.length")                      # (ADR 0016: a build says where
+sheet.dimension(env, "height.length")                     #  its dimensions come from, and
+sheet.dimension(hole, "bore.diameter")                    #  omitting one means suppress it)
+
 sheet.export("plate")                                     # writes plate.pdf
 ```
 

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

@@ -9,6 +9,9 @@
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
+**[API reference](https://pzfreo.github.io/draftwright/)** ·
+**[Examples and source](https://github.com/pzfreo/draftwright#readme)**
+
 Automated technical-drawing generation for [build123d](https://github.com/gumyr/build123d).
 Point it at a solid (or a STEP file) and get a fully-annotated multi-view engineering
 drawing — orthographic views, dimensions, section A–A, ISO hatching, title block — ready
@@ -75,9 +78,12 @@ from draftwright import build_drawing
 
 dwg = build_drawing(part, title="Mounting Plate")
 issues = dwg.lint()                       # list[LintIssue] — coverage, page bounds, ISO
-svg_path, dxf_path = dwg.export("my_part")
+paths = dwg.export("my_part", formats=("svg", "dxf"))   # {"svg": ..., "dxf": ...}
 ```
 
+`export()` with no `formats=` returns the old `(svg, dxf)` tuple; that shape is deprecated
+and removed in 0.5.0 (see [docs/deprecations.md](docs/deprecations.md)).
+
 ### Declarative drawings — reference features, declare intent
 
 Instead of relying on detection, **reference the build123d objects you built** and declare
@@ -93,10 +99,16 @@ plate = Box(120, 80, 20)
 bore = Pos(0, 0, 0) * Cylinder(4, 20)
 
 sheet = Sheet(plate - bore, title="Plate", number="DWG-002")
-sheet.envelope()
+env = sheet.envelope()
 sheet.datum("A", plate.faces().sort_by()[-1])             # datum A on the top face
 hole = sheet.hole(bore).finish("1.6").note("M3x0.5 TAP")  # ⌀8 bore, Ra 1.6, tapped
 sheet.control(hole).position(0.1, to="A", diameter=True)  # ⌀0.1 position wrt A
+
+sheet.authored_dimensions()                               # THIS is the complete set
+sheet.dimension(env, "width.length")                      # (ADR 0016: a build says where
+sheet.dimension(env, "height.length")                     #  its dimensions come from, and
+sheet.dimension(hole, "bore.diameter")                    #  omitting one means suppress it)
+
 sheet.export("plate")                                     # writes plate.pdf
 ```
 

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

@@ -33,6 +33,7 @@ architecture** table; open retired or superseded records only for design history
 | [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` |
+| [0017](0017-recognition-inventory-correspondence-and-measurement-provenance.md) | One recognition result per run; correspondence is evidence-gated | Produce one explicit recognition result owned by `BuildState`; require vertical-slice evidence before generalising correspondence, identity, requirements, outcomes, or reconciliation. | Accepted; ownership phase landed, extensions gated by #1018 | `test_recognition_manifest.py`, `test_recognition_result.py`, `test_declared_recognition_gate.py` |
 
 ## Historical records
 
@@ -49,5 +50,6 @@ architecture** table; open retired or superseded records only for design history
 - Layout and placement: 0004 → 0014 → 0012.
 - Declared intent and the editable surface: 0001 → 0011 → 0012 → 0016.
 - Quality and correction: 0002, with provenance from 0010.
+- Recognition correspondence and completeness: 0007 → 0013 → 0015 → 0017.
 
 Tracking issue: #745.

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.4.0"
+version = "0.4.2"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -25,6 +25,11 @@ dependencies = [
     "pillow>=10",
     "pypdfium2>=4",
     "reportlab>=4.0",
+    # Structured ISO 10303-21 access for AP242 facts that OCCT's XCAF transfer drops (#62).
+    # STEPutils 0.1 is the only release; isolate it behind _pmi_part21 and pin its README's
+    # ANTLR compatibility constraint explicitly because the package metadata omits the cap.
+    "steputils==0.1",
+    "antlr4-python3-runtime<4.10",
     "svglib>=1.5",
     "typer>=0.12",
     # PEP 702 @deprecated: stdlib `warnings.deprecated` lands in 3.13; backport for 3.10–3.12.
@@ -53,6 +58,7 @@ Homepage = "https://github.com/pzfreo/draftwright"
 Repository = "https://github.com/pzfreo/draftwright"
 Issues = "https://github.com/pzfreo/draftwright/issues"
 Changelog = "https://github.com/pzfreo/draftwright/blob/main/CHANGELOG.md"
+Documentation = "https://pzfreo.github.io/draftwright/"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/draftwright"]
@@ -80,6 +86,18 @@ markers = [
     "slow: heavy end-to-end CTC fixture builds (deselected by default)",
     "smoke: curated build-light subset for a fast local check (~30 s)",
 ]
+# `SoftDeprecationWarning` marks a surface that is discouraged but SUPPORTED and not going
+# away (#1043). The suite exercises `Sheet.auto_dimensions()` in ~170 places, deliberately —
+# it is still a supported path and its behaviour must keep being tested. Migrating those to
+# authored dimensions would be churn that tests less, so the category is silenced here rather
+# than at ~170 call sites.
+#
+# This does NOT weaken the guard: `tests/test_soft_deprecation.py` asserts the warning with
+# `pytest.warns`, which fires regardless of this filter. Real `DeprecationWarning`s are
+# untouched and still carry removal dates (`tests/test_deprecation_dates.py`).
+filterwarnings = [
+    "ignore::draftwright.SoftDeprecationWarning",
+]
 # Coverage is a CI concern (it adds ~13% locally and instruments every line); the
 # CI workflow passes the --cov flags explicitly. Keep the local default lean.
 addopts = "--tb=short -m 'not slow'"
@@ -87,6 +105,9 @@ addopts = "--tb=short -m 'not slow'"
 [tool.coverage.run]
 source = ["src/draftwright"]
 omit = ["src/draftwright/__init__.py"]
+# Keep XML paths anchored at the repository root so local diff coverage and Codecov
+# measure the same changed source lines rather than relying on runner-specific paths.
+relative_files = true
 # 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
@@ -94,8 +115,8 @@ 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.
+# Keep two points of headroom; ratchet upward only after the canonical coverage job
+# has stayed above the proposed floor.
 fail_under = 90
 precision = 1
 exclude_lines = [
@@ -129,6 +150,10 @@ select = ["E", "F", "I", "UP"]
 ignore = ["E501"]
 
 [dependency-groups]
+docs = [
+    "mkdocs>=1.6,<2",
+    "mkdocstrings[python]>=0.30,<1",
+]
 dev = [
     "codespell>=2.3.0",
     "hypothesis>=6",

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

@@ -29,9 +29,17 @@ _LAZY = {
     "FeatureInfo": "draftwright.drawing",
     "Sheet": "draftwright.sheet",
     "lint_feature_coverage": "draftwright.linting",
+    "PmiExtractionReport": "draftwright.pmi",
     "PmiRecord": "draftwright.pmi",
+    "PmiSourceEntity": "draftwright.pmi",
     "extract_pmi": "draftwright.pmi",
+    "extract_pmi_report": "draftwright.pmi",
     "choose_scale": "draftwright.compose",
+    # A warning category users are told to filter must be importable without reaching into a
+    # private module (#1043 review) — and without paying for the CAD kernel. It lives in the
+    # dependency-free `_warnings` leaf for that second reason: defined in `_core` it cost ~6 s
+    # to reach, and the pytest filterwarnings entry naming it paid that on every invocation.
+    "SoftDeprecationWarning": "draftwright._warnings",
 }
 
 
@@ -68,11 +76,18 @@ _sys.modules[__name__].__class__ = _DraftwrightModule
 
 
 if TYPE_CHECKING:  # static analysers / IDEs — no runtime import, no kernel cost
+    from draftwright._warnings import SoftDeprecationWarning
     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
-    from draftwright.pmi import PmiRecord, extract_pmi
+    from draftwright.pmi import (
+        PmiExtractionReport,
+        PmiRecord,
+        PmiSourceEntity,
+        extract_pmi,
+        extract_pmi_report,
+    )
     from draftwright.sheet import Sheet
 
 
@@ -85,12 +100,16 @@ def __dir__():
 
 __all__ = [
     "Drawing",
+    "SoftDeprecationWarning",
     "FeatureInfo",
+    "PmiExtractionReport",
     "PmiRecord",
+    "PmiSourceEntity",
     "Sheet",
     "build_drawing",
     "choose_scale",
     "extract_pmi",
+    "extract_pmi_report",
     "lint_feature_coverage",
     "make_drawing",
 ]