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

Build locally

Building the complete distribution requires Python 3.12 or 3.13 and Node.js 22.15.0. From a fresh checkout, create and activate the Python environment before building the viewer. Activation is important because the viewer staging script reads the installed python-cad-tools version from that environment.

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

cd viewer
npm ci
npm test
npm run build
cd ..

python -m build --wheel --sdist --outdir dist .
python -m twine check dist/*

The viewer build compiles the private TypeScript source and stages its verified, model-free static shell under src/python_cad_tools/_viewer_static/. The final wheel and source archive are written to dist/. To inspect the viewer while developing its source, run npm run preview from viewer/ after npm run build and open the local URL printed by Vite.

To build and serve an actual CAD project with the locally installed editable package, change to that project's directory and run:

python-cad build
python-cad serve

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.