build123d

The Problem

Engineers building parametric CAD models in pure Python need a library that exposes the Open Cascade kernel without forcing them into a heavyweight GUI or a language they must learn. The pain point is stitching together low‑level B‑REP operations while keeping the codebase readable, testable, and reproducible across environments.

What This Does

build123d wraps Open Cascade in a fully Pythonic API. Core geometry lives under src/build123d/topology/ – e.g. one_d.py, two_d.py, three_d.py, and the shared shape_core.py. The __init__.py in src/build123d/ re‑exports the most‑used symbols so a typical script can start with from build123d import *. Documentation (≈457 RST files) and 66 example scripts live in docs/ and examples/, showing everything from simple edges to full assemblies.

How It Is Wired

The library has no dedicated CLI; the entry point for a user is the import of build123d. Importing triggers the package’s src/build123d/__init__.py, which pulls symbols from the topology sub‑package.

• Top‑level import → src/build123d/__init__.py
• pulls from .topology import *
• Topology modules – the most‑connected nodes (measured):

These modules form a tightly‑coupled core; a change in any of them can cascade through the 8‑module circular dependency. Most functional work (e.g. Solid, Plane, Rectangle) ultimately calls methods defined in shape_core.py, which then delegates to Open Cascade via the ocp bindings. Because the cycles are resolved at import time, the runtime path is short (≈3‑4 hops) but the static dependency graph is a maintenance hotspot.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/build123d
cd build123d

# Install in editable mode (pyproject.toml defines the build system)
pip install -e .

No additional configuration files are required; the library reads no environment variables. To run an example:

python examples/benchy.py   # generates a benchmark model and writes a STEP file

The example script imports the package (from build123d import *) and invokes high‑level constructors such as Box, Cylinder, and Assembly. The generated geometry is written via the export_step helper in src/build123d/export.py (implicitly called by the example).

Real‑World Use

A manufacturing pipeline can script part generation:

from build123d import *

def make_bracket():
    base = Rectangle(100, 20).extrude(5)
    hole = Circle(5).extrude(6).translate((30, 0, 0))
    return base - hole

bracket = make_bracket()
bracket.export_step("bracket.step")

The script is pure Python, version‑controlled, and produces a deterministic STEP file that downstream CAM tools consume.

Code Health & Issues

Static analysis findings (67 total, 26 high, 41 medium)

• High cognitive load – Deep nesting (24 files, e.g. src/build123d/topology/shape_core.py) – max indentation depth 8.
• High cognitive load – Oversized files (17 files, e.g. src/build123d/topology/three_d.py) – up to 2 793 LOC.
• Medium resilience – Broad exception handling (10 files, e.g. src/build123d/topology/constrained_lines.py) – catch‑all except: blocks.
• High soundness – Import cycles (8 files, e.g. src/build123d/topology/zero_d.py) – circular imports increase refactor risk.
• High clarity – Duplicated code blocks (≈659 repeated 6‑line snippets across docs/examples) – DRY violation.

Code‑health audit

• High – No lockfile (pyproject.toml only).
• Medium – No Dependabot/Renovate configuration.
• Medium – CI lacks a dependency‑vulnerability scan.
• Medium – Large binary (docs/reference_assembly.svg, 6.5 MB) not stored in LFS.
• Low – Workflow jobs lack explicit timeout-minutes.

All findings are deterministic outputs of the repository‑wide static scan; no additional subjective issues are added.

The Bottom Line

build123d offers a mature, well‑documented Python façade over Open Cascade, making CAD‑as‑code approachable for Python teams. The core topology modules are functional but suffer from size, nesting, and circular imports, which will increase maintenance effort. Adding a lockfile, automating dependency updates, and refactoring the large, inter‑dependent modules would markedly improve reproducibility and developer velocity. Suitable for teams comfortable with Python who need a scriptable CAD kernel and can allocate effort to address the identified technical debt.