46 lines
1.9 KiB
Markdown
46 lines
1.9 KiB
Markdown
# 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 .`**
|