# 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 .`**