Metadata-Version: 2.4
Name: python-cad-tools
Version: 0.1.27
Summary: Typed, headless Python tooling for CAD/BIM models and artifacts
Author: Brandon Benge
License: AGPL-3.0-only
Project-URL: Homepage, https://github.com/brandon-benge/python-cad-tools
Project-URL: Repository, https://github.com/brandon-benge/python-cad-tools
Project-URL: Issues, https://github.com/brandon-benge/python-cad-tools/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: build123d<0.12,>=0.11.1
Requires-Dist: cadquery-ocp-novtk<7.10,>=7.9.3.1.1
Requires-Dist: ifcopenshell<0.9,>=0.8.5
Requires-Dist: trimesh<5,>=4.12
Requires-Dist: numpy<3,>=2.3
Requires-Dist: ezdxf<2,>=1.4
Requires-Dist: reportlab<5,>=4.4
Requires-Dist: pypdf<7,>=6
Provides-Extra: cad
Requires-Dist: build123d<0.12,>=0.11.1; extra == "cad"
Requires-Dist: cadquery-ocp-novtk<7.10,>=7.9.3.1.1; extra == "cad"
Provides-Extra: bim
Requires-Dist: ifcopenshell<0.9,>=0.8.5; extra == "bim"
Provides-Extra: mesh
Requires-Dist: trimesh<5,>=4.12; extra == "mesh"
Requires-Dist: numpy<3,>=2.3; extra == "mesh"
Provides-Extra: drawings
Requires-Dist: ezdxf<2,>=1.4; extra == "drawings"
Requires-Dist: reportlab<5,>=4.4; extra == "drawings"
Requires-Dist: pypdf<7,>=6; extra == "drawings"
Provides-Extra: engineering
Requires-Dist: shapely<3,>=2.1; extra == "engineering"
Requires-Dist: manifold3d<4,>=3; extra == "engineering"
Requires-Dist: meshio<6,>=5.3; extra == "engineering"
Provides-Extra: visualization
Provides-Extra: all
Requires-Dist: python-cad-tools[bim,cad,drawings,engineering,mesh,visualization]; extra == "all"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Requires-Dist: pytest<9,>=8.4; extra == "dev"
Requires-Dist: pytest-cov<8,>=7; extra == "dev"
Requires-Dist: ruff<0.15,>=0.14; extra == "dev"
Requires-Dist: mypy<2,>=1.18; extra == "dev"
Dynamic: license-file

# 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](LICENSE). Published on [PyPI](https://pypi.org/project/python-cad-tools/).

## Install

```bash
pip install "python-cad-tools[all]"
```

Capability-based extras (`cad`, `bim`, `mesh`, `drawings`, `engineering`,
`visualization`) install a subset of the curated, version-tested toolchain.
See [`docs/toolchain.md`](docs/toolchain.md) for the supported-library table,
the dependency license policy, and the compatibility verification matrix.

## Install for development

Python 3.12 or 3.13 is required.

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

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

```bash
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.

```bash
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:

```bash
python-cad build
python-cad serve
```

## Create a new project

```bash
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:

```bash
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 render-ring --project-root . --destination ring
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.
`render-ring` writes 16 perspective PNGs of the model (8 directions at two
heights) and a numbered 4×4 sheet of them into a new directory outside the
build output, for comparing the model with a photo; they are not build
artifacts. `prepare-site` deploys the packaged model-free viewer without Node, and `serve`
binds to loopback by default. See
[`docs/viewer-delivery.md`](docs/viewer-delivery.md) for ownership, caching,
offline, and deployment details.

## Python API

Public symbols are imported from their documented modules:

```python
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.

`python_cad_tools.recipes` lets an element opt into parametric BREP IFC
geometry (`IfcExtrudedAreaSolid`/`SweptSolid`, `IfcBooleanResult`/`CSG`)
instead of the default tessellated mesh, verified by a topology round-trip
after every build. See
[`docs/neutral-model.md#construction-recipes`](docs/neutral-model.md#construction-recipes).

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

Python CAD Tools is a curated engineering platform with a two-tier authoring
contract: verified authoring through the neutral model (Tier 1), and
supported-but-unverified direct use of a pinned library such as
`ifcopenshell` or `trimesh` (Tier 2). See
[`docs/two-tier-contract.md`](docs/two-tier-contract.md),
[`docs/neutral-model.md`](docs/neutral-model.md), and
[`docs/toolchain.md`](docs/toolchain.md).

## Verification

```bash
.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/build-semantics.md),
[`docs/manifests.md`](docs/manifests.md),
[`docs/project-configuration.md`](docs/project-configuration.md),
[`docs/public-api.md`](docs/public-api.md), and
[`docs/viewer-delivery.md`](docs/viewer-delivery.md) for detailed reference.
