cffi-stubgen

cffi-stubgen is a tool for automatically generating PEP 561 type stubs (.pyi files) for Python modules built with cffi. This makes it easy to add type hints to your CFFI-based extensions, unlocking the full power of static type checking and IDE features.

Why generate stubs?

• Type checking: Use tools like mypy to catch bugs before runtime.
• IDE support: Get autocompletion, inline documentation, and better navigation in editors like VS Code and PyCharm.
• Documentation: Stubs make your API clearer for users and contributors.

How does it work?

cffi-stubgen inspects the compiled CFFI module (not your Python source!) and generates stubs for all the functions and types exposed via CFFI. You simply point it at the built module, and it does the rest.

Quick Example

Suppose you have a CFFI module built in example_module._example. After installing your package, just run:

cffi-stubgen example_module._example

This will generate .pyi stubs for your module, ready for type checking and IDE use.

For a full walkthrough, see the example/README.md in this repository.

It will show you how cffi-stubgen can make mypy (and your IDE) aware of the arguments of

int add(int a, int b);

Command Line Options

cffi-stubgen provides several options to customize stub generation:

• -o, --output-dir: Set the output directory for stubs (default: same as module).
• -t, --typedefs: Additional C types to define (space-separated).
• --dry-run: Parse the module and report errors, but don’t write stubs.
• --no-cleanup: If stub generation fails, do not remove incomplete stubs.
• --verbose: Print detailed information during stub generation.
• --stub-extension: Choose the file extension for stubs (pyi [default] or py).
• MODULE_NAME: The fully qualified name of your cffi module (e.g., example_module._example).

Learn More

See the example for a hands-on guide!