Joseph HENRY f4df542dd1 Clean up dead code, fix type errors, and add publish workflow

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>

2026-04-03 11:07:52 +02:00

2.8 KiB

Raw Blame History

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:

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 .

2.8 KiB Raw Blame History