python-cad-tools 0.1.18__tar.gz → 0.1.19__tar.gz

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/.github/workflows/ci.yml

@@ -17,6 +17,12 @@
 # creates the tag and triggers this run. Keeping publish logic in one
 # gated place (instead of duplicating it in release.yml) avoids two
 # workflows racing to publish the same version.
+#
+# Test tiers (workspace test-cost-reduction, 2026-10-12): pushes and pull
+# requests run the checks a code change can break on Linux, plus one macOS
+# platform job. Version tags and manual dispatch (the release path, before
+# PyPI) also run Windows, the per-extra toolchain matrix on macOS and Linux,
+# and the platform locks. macOS minutes bill 10x on this private repository.
 name: CI
 
 on:
@@ -227,15 +233,15 @@ jobs:
           done
           echo "All tree shape checks passed."
 
-  # Confirms init/build works on Linux, macOS, and Windows. Windows
-  # skips ruff/mypy since static checks aren't part of the
-  # cross-platform contract, just the CLI behavior.
+  # Confirms init/build works on Linux, macOS, and Windows (Windows only
+  # on the release tier). Windows skips ruff/mypy since static checks
+  # aren't part of the cross-platform contract, just the CLI behavior.
   supported-platforms:
     name: Supported platforms (${{ matrix.os }})
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: ${{ fromJSON((startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch') && '["ubuntu-latest","macos-latest","windows-latest"]' || '["ubuntu-latest","macos-latest"]') }}
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
@@ -263,9 +269,10 @@ jobs:
 
   # Generates a per-OS `pip freeze` lockfile as a downloadable
   # artifact for reference. Informational only — not enforced or
-  # committed anywhere automatically.
+  # committed anywhere automatically. Release tier only.
   platform-locks:
     name: Platform lock generation (${{ matrix.os }})
+    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
     strategy:
       fail-fast: false
       matrix:
@@ -297,40 +304,27 @@ jobs:
           path: ${{ matrix.lock }}
 
   # Confirms every optional dependency group (cad, bim, mesh, ...)
-  # installs cleanly and imports across OS/Python combinations. PRs
-  # only run a fast subset (core+all on ubuntu/py3.13) via the gate
-  # step below; main and tag pushes run the full matrix.
+  # installs cleanly and imports across OS/Python combinations. Pushes
+  # and PRs run core and all on Linux for both Pythons; the release tier
+  # runs every group on Linux and macOS. The matrix itself is narrowed,
+  # so no runner starts for a cell that would be skipped.
   toolchain-matrix:
     name: Toolchain matrix (${{ matrix.os }}, py${{ matrix.python }}, ${{ matrix.group }})
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: ${{ fromJSON((startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch') && '["ubuntu-latest","macos-latest"]' || '["ubuntu-latest"]') }}
         python: ["3.12", "3.13"]
-        group: [core, cad, bim, mesh, drawings, engineering, visualization, all]
+        group: ${{ fromJSON((startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch') && '["core","cad","bim","mesh","drawings","engineering","visualization","all"]' || '["core","all"]') }}
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-      # Full matrix on main/tags/release-candidates; a fast core+all subset on pull requests.
-      - name: Determine whether this matrix cell runs
-        id: gate
-        run: |
-          if [ "${{ github.event_name }}" = "pull_request" ] && \
-             ! { [ "${{ matrix.os }}" = "ubuntu-latest" ] && [ "${{ matrix.python }}" = "3.13" ] && \
-                 { [ "${{ matrix.group }}" = "core" ] || [ "${{ matrix.group }}" = "all" ]; }; }; then
-            echo "run=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "run=true" >> "$GITHUB_OUTPUT"
-          fi
       - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
-        if: steps.gate.outputs.run == 'true'
         with:
           python-version: ${{ matrix.python }}
           cache: pip
       - run: python -m pip install --upgrade pip
-        if: steps.gate.outputs.run == 'true'
       - name: Install capability group
-        if: steps.gate.outputs.run == 'true'
         run: |
           if [ "${{ matrix.group }}" = "core" ]; then
             pip install -e .
@@ -338,9 +332,7 @@ jobs:
             pip install -e ".[${{ matrix.group }}]"
           fi
       - run: pip check
-        if: steps.gate.outputs.run == 'true'
       - name: Import declared libraries for this group
-        if: steps.gate.outputs.run == 'true'
         run: |
           python - <<'PY'
           import importlib
@@ -384,7 +376,7 @@ jobs:
           print(json.dumps(report, indent=2, sort_keys=True))
           PY
       - name: Tier-2 interop smoke and no-GUI assertion
-        if: steps.gate.outputs.run == 'true' && matrix.group == 'all'
+        if: matrix.group == 'all'
         run: |
           python - <<'PY'
           import sys
@@ -413,7 +405,6 @@ jobs:
           print("Tier-2 interop smoke and no-GUI assertion passed.")
           PY
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
-        if: steps.gate.outputs.run == 'true'
         with:
           name: toolchain-compatibility-${{ matrix.os }}-py${{ matrix.python }}-${{ matrix.group }}
           path: toolchain-compatibility.json

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/CHANGELOG.md

@@ -7,6 +7,24 @@ stable release is published.
 
 ## [Unreleased]
 
+## [0.1.19] - 2026-10-19
+
+### Changed
+
+- Every public function and class in the authoring modules (`artifacts`,
+  `build`, `context`, `drawings`, `elements`, `geometry`, `units`,
+  `validation`) has a one-line docstring stating its units and, for
+  geometry, its placement:
+  - `box` puts its minimum corner at the origin;
+  - `prism_between` starts at a bottom corner, with its width to the left
+    of the run;
+  - `Placement` is recorded only and never moves geometry.
+
+  Tools that list the public API with signatures and first docstring
+  lines now describe each helper. Behavior is unchanged.
+- Routine CI runs a smaller platform and extras matrix. Version tags and
+  manual dispatch still run the full release matrix.
+
 ## [0.1.18] - 2026-10-08
 
 ### Fixed

{python_cad_tools-0.1.18/src/python_cad_tools.egg-info → python_cad_tools-0.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cad-tools
-Version: 0.1.18
+Version: 0.1.19
 Summary: Typed, headless Python tooling for CAD/BIM models and artifacts
 Author: Brandon Benge
 License: AGPL-3.0-only

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/docs/toolchain.md

@@ -90,7 +90,9 @@ See `docs/two-tier-contract.md` for what "Tier 1" and "Tier 2" mean.
 ## Compatibility verification
 
 The `toolchain-matrix` CI job (`.github/workflows/ci.yml`) installs every
-capability group across `{ubuntu-latest, macos-latest} × {3.12, 3.13}`, runs
+capability group across `{ubuntu-latest, macos-latest} × {3.12, 3.13}` on
+version tags and manual runs (the release path; pushes and pull requests
+run `core` and `all` on Linux for both Pythons), runs
 `pip check`, imports every library the group declares, and — for `all` — runs
 a Tier-2 interop smoke (a shape crosses build123d → `geometry.tessellate` →
 trimesh → ifcopenshell read-back → ezdxf) plus the no-GUI assertion. It

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/src/python_cad_tools/artifacts.py

@@ -25,6 +25,7 @@ _EXPECTED_REPRESENTATION_TYPE = {None: "Tessellation", "extruded_profile": "Swep
 
 @dataclass(frozen=True, slots=True)
 class ArtifactRecord:
+    """One generated file: its path, size, SHA-256, media type and producer."""
     path: str
     size: int
     sha256: str
@@ -37,6 +38,7 @@ class ArtifactRecord:
 
 @dataclass(frozen=True, slots=True)
 class VerificationResult:
+    """The outcome of ``verify_build_output``: whether the output matches its manifest, and any issues."""
     ok: bool
     output_root: Path
     issues: tuple[ValidationIssue, ...]
@@ -48,6 +50,7 @@ class VerificationResult:
 
 @dataclass(frozen=True, slots=True)
 class PackageBuildInfo:
+    """The installed python-cad-tools distribution's version and build provenance."""
     schema_id: Literal["urn:python-cad-tools:schema:package-build-info:1"]
     schema_version: Literal[1]
     distribution: Literal["python-cad-tools"]
@@ -58,6 +61,7 @@ class PackageBuildInfo:
 
 
 def load_build_manifest(path: Path) -> dict[str, Any]:
+    """Read and schema-check a build manifest JSON file."""
     value = validate_json_document(path)
     if value["schema_id"] != "urn:python-cad-tools:schema:build-manifest:1":
         raise ArtifactIntegrityError(f"Not a build manifest: {path}")
@@ -65,6 +69,7 @@ def load_build_manifest(path: Path) -> dict[str, Any]:
 
 
 def load_design_manifest(path: Path) -> dict[str, Any]:
+    """Read and schema-check a design manifest JSON file."""
     value = validate_json_document(path)
     if value["schema_id"] != "urn:python-cad-tools:schema:design-manifest:1":
         raise ArtifactIntegrityError(f"Not a design manifest: {path}")
@@ -171,6 +176,7 @@ def verify_output_root(output_root: Path, project_root: Path | None = None) -> V
 
 
 def verify_build_output(project_root: Path) -> VerificationResult:
+    """Check that a project's generated output still matches its build manifest."""
     from ._locking import project_lock
     from ._transaction import recover_promotion
     from .project_config import load_project_config, output_path, resolve_project_root
@@ -184,6 +190,7 @@ def verify_build_output(project_root: Path) -> VerificationResult:
 
 
 def get_package_build_info() -> PackageBuildInfo:
+    """Return the installed distribution's build information."""
     try:
         document = json.loads(resources.files("python_cad_tools").joinpath("build-info.json").read_text(encoding="utf-8"))
     except (FileNotFoundError, json.JSONDecodeError) as error:

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/src/python_cad_tools/build.py

@@ -32,18 +32,21 @@ type FormatName = Literal["step", "ifc", "glb", "drawings", "quantities"]
 
 @dataclass(frozen=True, slots=True)
 class BuildOptions:
+    """Options for ``build_project``: the project root and the formats to build (default: the project's own)."""
     project_root: Path
     formats: tuple[FormatName, ...] | None = None
 
 
 @dataclass(frozen=True, slots=True)
 class ValidationOptions:
+    """Options for ``validate_project``: the project root and the formats to check (default: the project's own)."""
     project_root: Path
     formats: tuple[FormatName, ...] | None = None
 
 
 @dataclass(frozen=True, slots=True)
 class BuildResult:
+    """What ``build_project`` produced: its output folder, artifacts, build manifest and hashes."""
     project_root: Path
     output_root: Path
     formats: tuple[FormatName, ...]
@@ -57,6 +60,7 @@ class BuildResult:
 
 @dataclass(frozen=True, slots=True)
 class ValidationReport:
+    """The issues ``validate_project`` found; ``ok`` is true when none is fatal."""
     project_root: Path
     formats: tuple[FormatName, ...]
     issues: tuple[ValidationIssue, ...]
@@ -79,6 +83,7 @@ EXPORTERS: dict[str, type[Any]] = {
 
 
 def build_project(options: BuildOptions) -> BuildResult:
+    """Build the project's requested formats into its output folder and return the result."""
     if not isinstance(options, BuildOptions):
         raise TypeError("build_project expects BuildOptions")
     requested = _validate_requested_formats(options.formats)
@@ -159,6 +164,7 @@ def build_project(options: BuildOptions) -> BuildResult:
 
 
 def validate_project(options: ValidationOptions) -> ValidationReport:
+    """Load the project's model and check it without writing any artifacts."""
     if not isinstance(options, ValidationOptions):
         raise TypeError("validate_project expects ValidationOptions")
     requested = _validate_requested_formats(options.formats)
@@ -182,6 +188,7 @@ def validate_project(options: ValidationOptions) -> ValidationReport:
 
 
 def clean_project(project_root: Path) -> None:
+    """Remove the project's generated output folder."""
     reject_nested_project_execution()
     root = resolve_project_root(project_root)
     config = load_project_config(root)

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/src/python_cad_tools/context.py

@@ -15,6 +15,7 @@ if TYPE_CHECKING:
 
 @dataclass(frozen=True, slots=True)
 class BuildContext:
+    """What ``build_model`` receives: the project root, its loaded ``config`` and source revision, with recorded read-only access to declared sources."""
     project_root: Path
     config: Any
     source_revision: str | None
@@ -57,6 +58,7 @@ class BuildContext:
 
 @dataclass(frozen=True, slots=True)
 class DrawingContext:
+    """What a drawing annotation provider receives: the built model and its sheets, in millimetres."""
     project_root: Path
     config: Any
     model: DesignModel

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/src/python_cad_tools/drawings/__init__.py

@@ -19,6 +19,8 @@ type DrawingStyleToken = Literal[
 
 @dataclass(frozen=True, slots=True)
 class DrawingSheet:
+    """One drawing view: its id, view kind, projection origin and axes, and projected bounds in millimetres."""
+
     sheet_id: str
     view_id: Literal["plan", "front", "side", "section"]
     origin_mm: tuple[float, float, float]
@@ -29,6 +31,8 @@ class DrawingSheet:
 
 @dataclass(frozen=True, slots=True)
 class Line:
+    """A straight annotation line on a sheet, in projected millimetres."""
+
     id: str
     sheet_id: str
     start: Point2
@@ -38,6 +42,8 @@ class Line:
 
 @dataclass(frozen=True, slots=True)
 class Polyline:
+    """An open or closed annotation polyline on a sheet, in projected millimetres."""
+
     id: str
     sheet_id: str
     points: tuple[Point2, ...]
@@ -47,6 +53,8 @@ class Polyline:
 
 @dataclass(frozen=True, slots=True)
 class Text:
+    """Annotation text placed on a sheet, with its height in millimetres and rotation in degrees."""
+
     id: str
     sheet_id: str
     position: Point2
@@ -58,6 +66,8 @@ class Text:
 
 @dataclass(frozen=True, slots=True)
 class Dimension:
+    """A labelled dimension between two sheet points, offset in millimetres."""
+
     id: str
     sheet_id: str
     start: Point2
@@ -69,6 +79,8 @@ class Dimension:
 
 @dataclass(frozen=True, slots=True)
 class SectionCallout:
+    """A section cut line on a sheet that refers to the sheet showing that section."""
+
     id: str
     sheet_id: str
     start: Point2
@@ -80,6 +92,8 @@ class SectionCallout:
 
 @dataclass(frozen=True, slots=True)
 class ElevationMarker:
+    """A marker on a sheet that refers to the sheet showing that elevation."""
+
     id: str
     sheet_id: str
     position: Point2
@@ -90,12 +104,16 @@ class ElevationMarker:
 
 @dataclass(frozen=True, slots=True)
 class TableRow:
+    """One row of an annotation ``Table``."""
+
     id: str
     cells: tuple[str, ...]
 
 
 @dataclass(frozen=True, slots=True)
 class Table:
+    """A titled annotation table placed on a sheet."""
+
     id: str
     sheet_id: str
     position: Point2
@@ -109,12 +127,16 @@ type AnnotationPrimitive = Line | Polyline | Text | Dimension | SectionCallout |
 
 @dataclass(frozen=True, slots=True)
 class SheetAnnotations:
+    """All annotations for one sheet."""
+
     sheet_id: str
     annotations: tuple[AnnotationPrimitive, ...]
 
 
 @dataclass(frozen=True, slots=True)
 class DrawingAnnotationSet:
+    """What a drawing annotation provider returns: annotations per sheet."""
+
     provider_id: str
     sheets: tuple[SheetAnnotations, ...]
 

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/src/python_cad_tools/elements.py

@@ -15,6 +15,8 @@ GeometryKind = Literal["solid", "shell", "wire", "edge", "reference"]
 
 @dataclass(frozen=True, slots=True)
 class MaterialSpec:
+    """A material: id, display name, category, RGB colour in 0-1 and optional density in kg/m3."""
+
     id: str
     name: str
     category: str
@@ -25,12 +27,16 @@ class MaterialSpec:
 
 @dataclass(frozen=True, slots=True)
 class Placement:
+    """An element's recorded position (millimetres) and XYZ rotation (degrees); it does not move the geometry, which must already be in place."""
+
     translation_mm: tuple[float, float, float] = (0.0, 0.0, 0.0)
     rotation_deg_xyz: tuple[float, float, float] = (0.0, 0.0, 0.0)
 
 
 @dataclass(frozen=True, slots=True)
 class Dimensions:
+    """An element's declared size in millimetres; every value given must be finite and positive."""
+
     length_mm: float | None = None
     width_mm: float | None = None
     height_mm: float | None = None
@@ -46,6 +52,8 @@ class Dimensions:
 
 @dataclass(frozen=True, slots=True)
 class IfcMapping:
+    """The IFC class and predefined type an element exports as, or why it is excluded from IFC."""
+
     ifc_class: str | None
     predefined_type: str | None = None
     exclude_reason: str | None = None
@@ -68,6 +76,8 @@ class Opening:
 
 @dataclass(slots=True)
 class DesignElement:
+    """One model element with a stable id; physical elements need solid geometry and a material, and colours use RGB in 0-1."""
+
     id: str
     name: str
     category: str
@@ -98,6 +108,8 @@ class DesignElement:
 
 @dataclass(slots=True)
 class DesignModel:
+    """The whole model a project's ``build_model`` returns: its elements in millimetres, X right, Y away, Z up."""
+
     id: str
     name: str
     artifact_stem: str

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/src/python_cad_tools/geometry.py

@@ -21,6 +21,7 @@ def box(
     *,
     origin: tuple[Length, Length, Length] | None = None,
 ) -> Solid:
+    """Return a solid box length (X) by width (Y) by height (Z) with its minimum corner at ``origin`` (default the world origin), not its centre."""
     _positive_lengths((length, width, height), "Box dimensions")
     if origin is not None:
         _point(origin, "Box origin")
@@ -42,6 +43,7 @@ def reference_line(
     start: tuple[Length, Length, Length],
     end: tuple[Length, Length, Length],
 ) -> Edge:
+    """Return a straight edge from ``start`` to ``end`` for non-physical reference geometry."""
     start_mm = _point(start, "Reference-line start")
     end_mm = _point(end, "Reference-line end")
     if start_mm == end_mm:
@@ -79,6 +81,7 @@ def prism_between(
     width: Length,
     height: Length,
 ) -> Solid:
+    """Return a solid of ``width`` by ``height`` running from ``start`` to ``end``, with ``start`` as a bottom corner, width to the left of the run and height upward."""
     _positive_lengths((width, height), "Prism dimensions")
     start_mm = _point(start, "Prism start")
     end_mm = _point(end, "Prism end")
@@ -103,6 +106,7 @@ def sloped_pool(
     *,
     origin: tuple[Length, Length, Length],
 ) -> Solid:
+    """Return a pool body ``length`` along X and ``width`` along Y whose top edge starts at ``origin``, sloping from ``shallow_depth`` to ``deep_depth`` below it along X."""
     _positive_lengths((length, width, shallow_depth, deep_depth), "Sloped-pool dimensions")
     if to_mm(deep_depth) < to_mm(shallow_depth):
         raise ModelValidationError("Sloped-pool deep depth must be at least the shallow depth")
@@ -124,6 +128,7 @@ def sloped_pool(
 
 
 def bounds(shape: Any) -> tuple[float, float, float, float, float, float]:
+    """Return a shape's bounding box as ``(xmin, ymin, zmin, xmax, ymax, zmax)`` in millimetres."""
     box_value = shape.bounding_box()
     return (
         float(box_value.min.X),
@@ -136,6 +141,7 @@ def bounds(shape: Any) -> tuple[float, float, float, float, float, float]:
 
 
 def combined_bounds(shapes: list[Any]) -> tuple[float, float, float, float, float, float]:
+    """Return the bounding box of all ``shapes`` in millimetres (all zeros when empty)."""
     values = [bounds(shape) for shape in shapes]
     if not values:
         return (0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
@@ -176,6 +182,7 @@ def shared_tessellation() -> Iterator[None]:
 
 
 def tessellate(shape: Any, linear_deflection: float, angular_deflection: float) -> tuple[list[list[float]], list[list[int]]]:
+    """Return a shape's triangle mesh as ``(vertices, triangles)``, reusing one mesh per shape within a build."""
     cache = _TESSELLATIONS.get()
     key = (id(shape), float(linear_deflection), float(angular_deflection))
     if cache is not None:
@@ -226,10 +233,12 @@ def single_wrapped_solid(shape: Any) -> Solid | None:
 
 
 def is_valid_solid(shape: Any) -> bool:
+    """Return whether ``shape`` is a valid build123d ``Solid`` with positive volume."""
     return isinstance(shape, Solid) and bool(shape.is_valid) and float(shape.volume) > 0
 
 
 def diagonal(bounds_value: tuple[float, float, float, float, float, float]) -> float:
+    """Return the diagonal length of a ``bounds`` box in millimetres."""
     return sqrt(sum((bounds_value[index + 3] - bounds_value[index]) ** 2 for index in range(3)))
 
 

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/src/python_cad_tools/units.py

@@ -9,6 +9,7 @@ from typing import overload
 
 @dataclass(frozen=True, slots=True, order=True)
 class Length:
+    """A length stored in millimetres (``mm``); build values with ``mm``, ``inches``, ``feet`` or ``feet_inches`` and convert with ``to_mm``."""
     mm: float
 
     def __post_init__(self) -> None:
@@ -66,6 +67,7 @@ class Length:
 
 @dataclass(frozen=True, slots=True)
 class Area:
+    """An area in square millimetres (``mm2``), the product of two ``Length`` values."""
     mm2: float
 
     def __post_init__(self) -> None:
@@ -91,6 +93,7 @@ class Area:
 
 @dataclass(frozen=True, slots=True)
 class Volume:
+    """A volume in cubic millimetres (``mm3``), an ``Area`` times a ``Length``."""
     mm3: float
 
     def __post_init__(self) -> None:
@@ -111,50 +114,60 @@ FOOT = 12 * INCH
 
 
 def to_mm(value: Length) -> float:
+    """Return a ``Length`` as a float of millimetres, the geometry kernel's unit."""
     if not isinstance(value, Length):
         raise TypeError(f"Expected Length, got {type(value).__name__}")
     return float(value.mm)
 
 
 def mm(value: float) -> Length:
+    """Return a ``Length`` of ``value`` millimetres."""
     return value * MM
 
 
 def inches(value: float) -> Length:
+    """Return a ``Length`` of ``value`` inches."""
     return value * INCH
 
 
 def feet(value: float) -> Length:
+    """Return a ``Length`` of ``value`` feet."""
     return value * FOOT
 
 
 def feet_inches(feet_value: float, inches_value: float = 0) -> Length:
+    """Return a ``Length`` of ``feet_value`` feet plus ``inches_value`` inches."""
     return feet_value * FOOT + inches_value * INCH
 
 
 def square_feet(value: Area) -> float:
+    """Return an ``Area`` in square feet."""
     if not isinstance(value, Area):
         raise TypeError("square_feet expects Area")
     return value.mm2 / (304.8**2)
 
 
 def cubic_feet(value: Volume) -> float:
+    """Return a ``Volume`` in cubic feet."""
     if not isinstance(value, Volume):
         raise TypeError("cubic_feet expects Volume")
     return value.mm3 / (304.8**3)
 
 
 def cubic_yards(value: Volume) -> float:
+    """Return a ``Volume`` in cubic yards."""
     if not isinstance(value, Volume):
         raise TypeError("cubic_yards expects Volume")
     return value.mm3 / (914.4**3)
 
 
 def metres(value: Length) -> float:
+    """Return a ``Length`` in metres."""
     return to_mm(value) / 1000.0
 
 
 def square_metres(value: Area) -> float:
+    """Return an ``Area`` in square metres."""
     if not isinstance(value, Area):
         raise TypeError("square_metres expects Area")
     return value.mm2 / 1_000_000.0

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19}/src/python_cad_tools/validation.py

@@ -50,6 +50,7 @@ _STABLE_ID = re.compile(r"[A-Za-z0-9._-]+\Z", re.ASCII)
 
 @dataclass(frozen=True, slots=True)
 class ValidationIssue:
+    """One model or build problem: a code, ``warning`` or ``error`` severity, a message and where it applies."""
     code: str
     severity: Literal["warning", "error"]
     message: str

{python_cad_tools-0.1.18 → python_cad_tools-0.1.19/src/python_cad_tools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cad-tools
-Version: 0.1.18
+Version: 0.1.19
 Summary: Typed, headless Python tooling for CAD/BIM models and artifacts
 Author: Brandon Benge
 License: AGPL-3.0-only

python_cad_tools-0.1.19/src/python_cad_tools.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.19",
+  "distance": 0,
+  "node": "gb3c8c85999c0abbb3136117d037dd1229a20dccb",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-20"
+}

python_cad_tools-0.1.18/src/python_cad_tools.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.1.18",
-  "distance": 0,
-  "node": "ge909d6f9394ae6f2a5ee80d99f5a8cac772d09de",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-09"
-}