The Problem

Blender's Python API (bpy) is only available inside the Blender runtime, so IDEs cannot resolve imports or provide autocomplete for add-on developers. Developers working on Blender add-ons face missing type hints, unresolved symbols, and no IntelliSense, which slows iteration and hides errors until runtime.

What This Does

This repo is a fork of nutti/fake-bpy-module, a toolchain that generates fake, importable Python modules mirroring Blender's API. The generated stubs let IDEs like PyCharm and VS Code resolve bpy, bmesh, mathutils, and related modules. The core pipeline lives in src/fakebpymodule/: an analyzer/ parses Blender's Sphinx-generated .rst documentation, a transformer/ applies patches and cleanup passes, and a generator/ emits the final Python stub files.

The repo ships pre-generated modules for Blender versions 2.78 through 4.2, plus patches for UPBGE. Version-specific .rst patches in src/patches/blender/ and src/patches/upbge/ correct documentation errors before generation. The src/gen.py script orchestrates the full build, and CI workflows in .github/workflows/ automate module generation and linting.

How To Use It

Setup: Install via pip. The README documents version-specific packages:

pip install fake-bpy-module-4.2

For the latest daily build, use fake-bpy-module-latest. The package requires Python >= 3.8.

Configuration: No environment variables or config files are needed for end users. The generated modules are installed directly into your Python environment and picked up by your IDE. For PyCharm, the README recommends raising idea.max.intellisense.filesize in idea.properties to >2600.

Running it: End users do not run anything—installation is the entire workflow. Developers who want to regenerate modules from source run src/gen.py after installing dependencies from src/requirements.txt. The repo does not document a CLI interface for generation beyond the script itself.

Real-World Use

An add-on developer creates a new operator:

import bpy

class MyOperator(bpy.types.Operator): blidname = "object.myoperator" bllabel = "My Operator"

def execute(self, context): # IDE resolves bpy.types.Operator and provides method signatures obj = context.activeobject return {'FINISHED'}

With fake-bpy-module installed, the IDE resolves bpy.types.Operator, context.active_object, and the return annotation, catching typos and signature mismatches before running inside Blender.

Code Health & Issues

Med - No lockfile for dependencies - pyproject.toml and src/requirements.txt declare dependencies without pinned versions, so builds are not reproducible. The CI workflows may mask this by using fixed environments. Low - Large patch surface - Over 100 .rst patch files across 15+ Blender versions. These are manually maintained and prone to bit-rot as Blender's docs change. The CI workflows (fake-bpy-module-ci.yml) test generation, which mitigates this. Low - Single-maintainer risk - The project is largely driven by one maintainer (see FUNDING.yml). Bus factor is a real concern for a project tied to Blender's release cadence. Positive - The repo has a solid test suite (tests/python/ with 22 test files), linting across 5 tools (tests/lint/), and CI for both Blender and UPBGE modules. The architecture is cleanly separated into analyzer/transformer/generator stages.

The Bottom Line

This is a well-engineered, practical tool for anyone writing Blender add-ons. The version-specific pip packages make integration trivial, and the CI-backed generation pipeline keeps stubs current. The lack of dependency pinning and single-maintainer model are the main risks, but for end users this is a reliable way to get proper IDE support for Blender development.