Initial commit
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -0,0 +1,125 @@
|
||||
# blender-python-stubs
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Type stubs for the Blender Python API. Provides autocomplete, type checking, and inline documentation for `bpy`, `mathutils`, `bmesh`, `gpu`, `freestyle`, and all other Blender Python modules.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install blender-python-stubs==5.1.0
|
||||
```
|
||||
|
||||
The version matches your target Blender version:
|
||||
|
||||
| Blender Version | Install Command |
|
||||
| --------------- | ---------------------------------------------- |
|
||||
| 5.1 | `pip install "blender-python-stubs>=5.1,<5.2"` |
|
||||
| 5.0 | `pip install "blender-python-stubs>=5.0,<5.1"` |
|
||||
| 4.5 | `pip install "blender-python-stubs>=4.5,<4.6"` |
|
||||
| 4.4 | `pip install "blender-python-stubs>=4.4,<4.5"` |
|
||||
| 4.3 | `pip install "blender-python-stubs>=4.3,<4.4"` |
|
||||
| 4.2 | `pip install "blender-python-stubs>=4.2,<4.3"` |
|
||||
| 4.1 | `pip install "blender-python-stubs>=4.1,<4.2"` |
|
||||
| 4.0 | `pip install "blender-python-stubs>=4.0,<4.1"` |
|
||||
|
||||
## Usage
|
||||
|
||||
Install alongside your Blender addon project for type checking with mypy, pyright, basedpyright, ty or your IDE.
|
||||
|
||||
```python
|
||||
import bpy
|
||||
|
||||
# Full autocomplete and type checking
|
||||
obj: bpy.types.Object = bpy.context.active_object
|
||||
obj.location.x = 1.0
|
||||
|
||||
# Collection types with proper methods
|
||||
bpy.data.objects.new("Cube", bpy.data.meshes.new("Mesh"))
|
||||
bpy.data.images.remove(bpy.data.images["old"])
|
||||
|
||||
# GPU module fully typed
|
||||
import gpu
|
||||
shader = gpu.shader.from_builtin('UNIFORM_COLOR')
|
||||
gpu.state.blend_set('ALPHA')
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
- **Full Blender API coverage** — `bpy.types`, `bpy.ops`, `bpy.props`, `bpy.utils`, `bpy.path`, `bpy.app`, `mathutils`, `bmesh`, `gpu`, `gpu_extras`, `bpy_extras`, `freestyle`, `aud`, `blf`, `bl_math`, `imbuf`, `idprop`
|
||||
- **Accurate collection types** — `bpy.data.objects` returns `BlendDataObjects` (not generic `bpy_prop_collection`), exposing `new()`, `remove()`, and other collection-specific methods
|
||||
- **Readonly properties** — uses `@property` decorators for readonly RNA attributes
|
||||
- **Context members** — `bpy.context.active_object`, `selected_objects`, `edit_object`, and ~100 other screen context attributes are properly typed
|
||||
- **Constructor signatures** — GPU types, mathutils types (`Vector`, `Matrix`, `Euler`, etc.) have typed `__init__` methods
|
||||
- **Literal enum types** — string parameters like `gpu.state.blend_set(mode)` use `Literal["NONE", "ALPHA", ...]` instead of plain `str`
|
||||
- **Docstrings** — inline documentation on properties, methods, and functions
|
||||
- **Classmethod detection** — `Matrix.Identity()`, `Vector.Fill()`, etc. correctly typed as `@classmethod`
|
||||
- **Dynamic array types** — `Image.pixels` typed as `bpy_prop_array[float]` (not `list[float]` or `float`)
|
||||
- **Zero `Any` usage** — precise types throughout, no `typing.Any` fallbacks
|
||||
- **basedpyright strict mode** — 0 errors on generated stubs (4.1+)
|
||||
|
||||
## How It Works
|
||||
|
||||
Stubs are generated by running introspection **inside Blender itself**. A script runs in Blender's embedded Python interpreter using `--background` mode and collects:
|
||||
|
||||
1. **RNA type definitions** via `rna_info.BuildRNAInfo()` — all `bpy.types` classes, their properties, methods, inheritance, and readonly status
|
||||
2. **C extension signatures** via `inspect.signature()` and RST docstring parsing — for `mathutils`, `bmesh.types`, `gpu.types`, `aud`, etc.
|
||||
3. **Screen context members** via `dir(bpy.context)` — dynamically injected context attributes with type inference from runtime values, hardcoded overrides, and name-pattern heuristics
|
||||
4. **Collection wrapper classes** via RNA `srna` attributes — maps `bpy.data.objects` to `BlendDataObjects(bpy_prop_collection[Object])` instead of generic `bpy_prop_collection[Object]`
|
||||
|
||||
The introspection data is then passed through a stub generator that handles type cleaning, import resolution, docstring formatting, and `black` formatting.
|
||||
|
||||
## Comparison with Alternatives
|
||||
|
||||
### vs [fake-bpy-module](https://github.com/nutti/fake-bpy-module)
|
||||
|
||||
| Feature | blender-python-stubs | fake-bpy-module |
|
||||
| ------------------------ | -------------------------- | ----------------------------- |
|
||||
| `@property` for readonly | Yes (1700+) | No |
|
||||
| `Any` usage | 0 | 1800+ |
|
||||
| Collection wrapper types | `BlendDataObjects` | `bpy_prop_collection[Object]` |
|
||||
| `bpy_struct` methods | Introspected | Missing |
|
||||
| Constructor `__init__` | Yes (mathutils, gpu, etc.) | No |
|
||||
| Literal enum types | Yes | Yes (via stub_internal) |
|
||||
| Context members | ~100 typed | ~100 typed |
|
||||
| basedpyright strict | 0 errors (4.1+) | Not tested |
|
||||
| Docstrings | Yes | Yes |
|
||||
|
||||
### vs [bpystubgen](https://github.com/mysticfall/bpystubgen)
|
||||
|
||||
bpystubgen generates stubs from Blender's Sphinx documentation, not from runtime introspection. This means it can miss C-level methods, dynamic context members, and runtime-only type information. Our approach introspects the actual running Blender instance, ensuring stubs match the real API.
|
||||
|
||||
## Supported Versions
|
||||
|
||||
Blender 4.0 through 5.1. Each Blender version gets its own stub package version.
|
||||
|
||||
## Contributing
|
||||
|
||||
Pull requests are welcome. The project uses:
|
||||
|
||||
- `uv` for dependency management
|
||||
- `poe` for task running
|
||||
- `basedpyright` for type checking
|
||||
- `black` for formatting
|
||||
- `ruff` for linting
|
||||
|
||||
```bash
|
||||
# Generate stubs for a specific version
|
||||
uv run poe generate 5.1
|
||||
|
||||
# Type-check generated stubs
|
||||
uv run poe typecheck-stubs 5.1
|
||||
|
||||
# Run all checks (format, lint, typecheck, tests)
|
||||
uv run poe check
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
Made with ❤️ at [Autour de Minuit (ADV)](https://blog.autourdeminuit.com/) <img src="https://upload.wikimedia.org/wikipedia/commons/0/0c/Blender_logo_no_text.svg" alt="blender" width="20"/>
|
||||
Reference in New Issue
Block a user