Contributing

Setup

uv sync --all-extras --dev
git config core.hooksPath .githooks

The second command activates the shared pre-commit hook, which runs format, lint, and type-check before every commit.

Running tests

Tests run using bpy installed from pip (no need for Blender on PATH)

uv run pytest -n 4

Regenerating node classes

Most node classes under src/nodebpy/nodes/ are auto-generated from Blender's live node registry by the gen/ package (kept outside src/ so it never ships in the wheel). After a Blender / bpy version change, regenerate with:

make generate

which runs, in order:

1. uv run python -m nodebpy.assets — regenerates the typed classes for Blender's bundled essentials asset libraries
2. uv run python -m gen — regenerates the node classes for every tree type
3. make format — ruff format, ruff check --fix, and ty check --fix src

For faster iteration you can regenerate a single tree type:

uv run python -m gen --only geometry

(Geometry is always processed first because the shader and compositor trees re-export shared nodes from it.)

Inside gen/: config.py holds the per-tree-type configuration and the skip / hand-written / generate disposition for each node, customizations.py is the register_customization registry that layers generation-time mixins onto specific nodes, introspect.py inspects the live node registry, and model.py / emit.py / writers.py turn the results into module files.

Nodes that need special handling are hand-written in src/nodebpy/nodes/*/manual.py (and the zone nodes in nodes/geometry/zone.py / nodes/shader/zone.py); the generator skips these and re-exports them alongside the generated classes.

Building the docs

The documentation is a Quarto site under docs/, with the API reference generated by quartodoc:

make docs

CI

Two GitHub Actions workflows run on every push and pull request:

• lint.yml — ruff format check, ruff check, ty check (Ubuntu only, platform-independent)
• tests.yml — pytest on macOS, Windows, and Ubuntu