tests and agents.md

AGENTS.md

@@ -0,0 +1,45 @@
+# 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 .`**