Joseph HENRY
f4df542dd1
Remove unused _append_ops_call_method, fix _property_data_from_member call signature, replace sys.version_info guard with hasattr check for __buffer__ protocol, fix implicit string concatenations, add msgbus overrides for 4.0-4.4, add conformance tests, and add publish script. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# 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 .`**
|