Python CAD Tools

Python CAD Tools is an installable, typed Python package for defining shared CAD/BIM models and producing STEP, IFC4, GLB, conceptual SVG/DXF/PDF drawings, quantity schedules, validation reports, and manifests in a headless workflow.

The canonical project identities are:

• distribution: python-cad-tools;
• import namespace: python_cad_tools;
• command: python-cad;
• repository: https://github.com/brandon-benge/python-cad-tools.

Licensed under AGPL-3.0-only. Published on PyPI.

Install for development

Python 3.12 or 3.13 is required.

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

An ordinary non-editable installation exposes the same package and command:

python3 -m pip install ./dist/python_cad_tools-*.whl
python-cad --version

Create a new project

python-cad init --destination my-cad-project
cd my-cad-project
python -m venv .venv
.venv/bin/pip install python-cad-tools
.venv/bin/python-cad build

The scaffold includes model.py, config.py, pyproject.toml, README.md, .gitignore, and generated/.gitkeep. Edit config.py for dimensions and materials; edit model.py for design elements.

Command line

python-cad --version reports the version from installed distribution metadata. Project operations use explicit subcommands:

python-cad init --destination my-project
python-cad validate --project-root .
python-cad build --project-root . --format step --format quantities
python-cad verify --project-root .
python-cad prepare-site --project-root . --destination _site --base-path /
python-cad serve --project-root . --port 0
python-cad clean --project-root .

The project root defaults to the current directory. Builds use project locks, unique staging, final-byte verification, and recoverable journaled promotion. validate writes no artifacts; verify independently reproduces the manifest inventory, sizes, SHA-256 values, schemas, and parser checks. prepare-site deploys the packaged model-free viewer without Node, and serve binds to loopback by default. See docs/viewer-delivery.md for ownership, caching, offline, and deployment details.

Python API

Public symbols are imported from their documented modules:

from pathlib import Path

from python_cad_tools.build import BuildOptions, build_project

result = build_project(BuildOptions(project_root=Path(".")))

Project code should preserve stable semantic IDs, keep geometry parametric, and create geometry and metadata together. Generated artifacts are outputs, never design inputs.

Project-owned drawing annotations use the typed, renderer-independent boundary documented in docs/drawing-extensions.md. One annotation set is validated and rendered consistently to SVG, DXF, and PDF before artifact hashes are recorded.

Verification

.venv/bin/ruff check .
.venv/bin/mypy
.venv/bin/pytest -q
.venv/bin/pytest tests/integration -q
.venv/bin/pytest tests/packaging -q
.venv/bin/pytest tests/typing -q
.venv/bin/python -m build --wheel --sdist --outdir dist .
.venv/bin/python -m twine check dist/*

The default pytest command runs the fast unit suite. Integration, packaging, and external typing suites are explicit release gates. Packaging tests inspect wheel and sdist inventories, install the wheel non-editably into an isolated environment outside the checkout, prove the import resolves from that environment's site-packages, and run python-cad --version.

Viewer TypeScript is maintainer source in viewer/; only its verified, model-free production shell is included in the wheel. See docs/build-semantics.md, docs/manifests.md, docs/project-configuration.md, docs/public-api.md, and docs/viewer-delivery.md for detailed reference.