blender-python-stubs — AI agent instructions

These instructions apply to any AI coding agent working in this repository.

Type stubs generator for the Blender Python API (bpy, mathutils, bmesh, gpu, etc.). Introspects Blender's embedded Python in --background mode. Supported: Blender 4.0–5.1.

Commands

uv run poe generate <version> — generate stubs (e.g., 5.0)
uv run poe typecheck-stubs <version> — type-check generated stubs
uv run poe conformance <version> — run conformance tests
uv run poe check — format, lint, typecheck, test
uv run poe test / format / lint — individual steps
Run a script inside Blender: downloads/blender-<version>-linux-x64/blender --background --python script.py

Code style

Format with black and lint with ruff after editing
basedpyright strict, 0 errors is the target
Never use typing.Any — use concrete types, TypedDicts, Protocols, or unions
Use raw dict literals for TypedDicts ({"name": ..., "type": ...}, not ParamData(name=..., type=...))

Never bypass typing issues

Fix root causes — no # type: ignore, no pyright excludes/overrides, no placeholder stubs, no shims.

Testing

Add tests for every behavior/regex change — at least two examples per change
Tests live in tests/, run via python -m unittest discover -s tests -v

Conformance tests

Never modify files in conformance/<version>/ — copied verbatim from Blender docs
On failure, fix stub generation or overrides/<version>/<module>.json, not the test

Architecture

Prefer introspection over hardcoding — if runtime can discover it, don't hardcode
Key files: introspect.py (collects data inside Blender), generate_stubs.py (emits stubs), main.py (CLI)
introspect.py must work on every Blender Python (4.0 ships Python 3.10) — no newer-version syntax

Git

Always add specific files by name — never git add -A or git add .

1.9 KiB Raw Blame History Unescape Escape