The Problem
Engineers and researchers often need to generate parametric 3D geometry programmatically, but existing script‑based CAD tools either lack a full Python ecosystem or are tied to heavyweight GUI frameworks. The gap is a lightweight, pure‑Python API that can be driven from CI pipelines, notebooks, or server‑side processes without a graphical front‑end.
What This Does
cadquery provides a Pythonic wrapper around the Open‑CASCADE Technology (OCCT) kernel. Core functionality lives in cadquery/cq.py (the Workplane class) and cadquery/assembly.py (assembly handling). Export/import helpers are under cadquery/occimpl/exporters/ and cadquery/occimpl/importers/. The examples/ folder contains 30+ ready‑to‑run scripts that demonstrate solids, sweeps, lofts, and assembly creation. Documentation is extensive (doc/ with reST sources) and compiled on ReadTheDocs.
How To Use It
Setup
The project uses classic setuptools; install from source or PyPI:
From source
python -m pip install -e . Or from PyPI (recommended) python -m pip install cadquery
The azure-pipelines.yml and appveyor.yml files show the CI build steps; they invoke python -m pip install . followed by pytest. No Dockerfile or Makefile is provided, so container builds must be scripted by the consumer.
Configuration
No runtime configuration files are required. The optional Conda recipe lives in conda/meta.yaml for users preferring Conda environments. If the OCCT binary wheels are unavailable for the target platform, the conda/web-installer/ scripts (build.py, construct.yaml.jinja2) can be used to generate a custom installer.
Running it
Typical usage is via the Workplane API:
from cadquery import Workplane
result = ( Workplane("XY") .box(10, 20, 5) .faces(">Z") .hole(3) ) result.exportStl("output.stl")
The entry point for scripts is cadquery/cq.py; importing cadquery automatically exposes the Workplane class. Jupyter integration is supported through cadquery/cqgi.py and the cadquery/occimpl/jupytertools.py module, as demonstrated in examples/CQexamples.ipynb.
Real‑World Use
A manufacturing pipeline can generate a family of parts from a single parameter file:
import json from cadquery import Workplane
with open("params.json") as f: p = json.load(f)
part = ( Workplane("XY") .box(p["width"], p["depth"], p["height"]) .faces(">Z") .hole(p["holediameter"]) )
part.exportStep(f"{p['name']}.step")
The script can be invoked in a CI job to produce updated STEP files whenever the JSON changes.
Code Health & Issues
Low – Test coverage – 26 test modules (tests/) cover core modules, but cadquery/vis.py and cadquery/occimpl/sketchsolver.py have no direct unit tests. Medium – Platform dependence – OCCT binaries are large and platform‑specific; the repo does not ship wheels for all OSes, requiring users to build or use Conda. Low – Documentation gaps – API reference (doc/apireference.rst) is present, yet some newer functions (e.g., cadquery.utils) lack explicit examples. Low – CI artifacts – Azure Pipelines and AppVeyor are configured, but badge URLs in README.md point to the old AppVeyor build; the pipeline may be stale. Low – License – LICENSE file exists (BSD‑3‑Clause), so legal exposure is minimal.
Overall, the repository shows a mature structure: setup.cfg, setup.py, CI pipelines, a full test suite, and generated documentation. No secret files or hard‑coded credentials are present.
The Bottom Line
cadquery delivers a well‑engineered, Python‑first parametric CAD API backed by a proven OCCT kernel. It is ready for integration into automated design workflows, especially where headless operation and scriptability are required. Users should verify OCCT binary availability for their target platform and supplement missing tests for any custom extensions. Suitable for engineering teams needing reproducible geometry generation without a GUI.