endstone-stubgen

A next-generation stub generator for pybind11 modules, built with Griffe and Jinja2.

Overview

endstone-stubgen generates precise .pyi type stubs for C++/pybind11 codebases. It replaces the legacy pybind11-stubgen workflow with a modern, modular, and more accurate architecture.

Originally built to support Endstone's pybind11 bindings, it works equally well for any pybind11 project.

Features

• Griffe-based introspection — Robust parsing of Python modules, pybind11 extensions, and custom metadata
• Jinja2 templating — Clean, extensible rendering with fully customizable .pyi templates
• High-accuracy type inference — Better handling of overloads, enums, default values, and pybind11-bound C++ types
• Deterministic output — Stable, reproducible stub generation for large codebases
• PEP 561 compliant — Generated stubs work seamlessly with mypy, pyright, and other type checkers

Installation

pip install endstone-stubgen

Or with uv:

uv add endstone-stubgen

Usage

Basic Usage

Generate stubs for a module:

stubgen <module_name>

Specify Output Directory

stubgen <module_name> -o stubs/

Dry Run

Parse the module and report errors without writing files:

stubgen <module_name> --dry-run

CLI Reference

usage: stubgen [-h] [-o OUTPUT_DIR] [--dry-run] MODULE_NAME

positional arguments:
  MODULE_NAME           Module name to generate stubs for

options:
  -h, --help            Show this help message and exit
  -o, --output-dir      The root directory for output stubs (default: current directory)
  --dry-run             Parse module and report errors without writing stubs

Example

Generate stubs for the endstone module:

stubgen endstone -o stubs/

This creates a stubs/ directory with .pyi files mirroring the module structure:

stubs/
└── endstone/
    ├── __init__.pyi
    ├── command.pyi
    ├── event.pyi
    └── ...

License

This project is licensed under the MIT License - see the LICENSE file for details.