# CLAUDE.md - Project Guidelines

## Project Overview

Type stubs generator for the Blender Python API (`bpy`, `mathutils`, `bmesh`, `gpu`, etc.). Stubs are generated by running introspection inside Blender's embedded Python interpreter in `--background` mode. Supported Blender versions: **4.0 through 5.1** (8 versions total).

## Commands

- `uv run poe generate <version>` — Generate stubs for a Blender version (e.g., 5.0)
- `uv run poe typecheck-stubs <version>` — Type-check generated stubs
- `uv run poe conformance <version>` — Run conformance tests against stubs
- `uv run poe check` — Run all checks (format, lint, typecheck, test)
- `uv run poe test` — Run unit tests
- `uv run poe format` — Format with black
- `uv run poe lint` — Lint with ruff

## Code Style

- Format all Python files with **black** after modifying them
- Use **basedpyright strict** mode — 0 errors is the target
- Never use `typing.Any` — use concrete types, TypedDicts, Protocols, or unions instead
- Use raw dict literals for TypedDicts, not explicit constructors (e.g., `{"name": ..., "type": ...}` not `ParamData(name=..., type=...)`)

## Type Checking Rules

- **Never use `# type: ignore`** — fix the actual typing issue instead
- **Never suppress typecheck rules** with excludes or pyright config overrides — fix the root cause
- **Never bypass issues with workarounds** — always investigate and fix root causes properly (no empty placeholder stubs, no shims)

## Testing

- **Add tests for every behavior/regex change** — at least two examples per change
- Test files live in `tests/` and run via `python -m unittest discover -s tests -v`

## Conformance Tests

- **Never modify conformance test files** — they are copied verbatim from Blender documentation
- When a conformance test fails, fix the stub generation or overrides, not the test
- Conformance tests live in `conformance/<version>/`

## Architecture

- Stubs are versioned per Blender version: `dist/<version>/` (e.g., `dist/5.0/`)
- Type overrides are organized per version: `overrides/<version>/<module>.json`
- Always prefer **introspection** over hardcoding — if something can be discovered at runtime, don't hardcode it
- Key files: `introspect.py` (data collection), `generate_stubs.py` (stub output), `main.py` (CLI)
- `introspect.py` runs inside Blender's embedded Python interpreter, which varies by version (e.g., Blender 4.0 uses Python 3.10). Code in this file must be compatible with all supported Blender Python versions.

## Blender Binaries

Cached Blender executables are in `downloads/` (e.g., `downloads/blender-5.1.0-linux-x64/blender`). You can run scripts inside Blender with:

```bash
downloads/blender-5.1.0-linux-x64/blender --background --python script.py
```

## Git

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