Jij-Inc / pyo3-stub-gen

pyo3-stub-gen Python stub file ( ) generator for [PyO3] with [maturin] projects. [PyO3]: https://github.com/PyO3/pyo3 [maturin]: https://github.com/PyO3/maturin | crate name | crates.io | docs.rs | doc (main) | | --- | --- | --- | --- | | [pyo3-stub-gen] | | | | | [pyo3-stub-gen-derive] | | | | [pyo3-stub-gen]: ./pyo3-stub-gen/ [pyo3-stub-gen-derive]: ./pyo3-stub-gen-derive/ > [!NOTE] > Minimum supported Python version is 3.10. Do not enable 3.9 or older in PyO3 setting. > [!NOTE] > Versions 0.15.0–0.17.1 unintentionally included a LGPL dependency. This was removed in 0.17.2, and the affected versions have been yanked. Design Our goal is to create a stub file from Rust code, however, automated complete translation is impossible due to the difference between Rust and Python type systems and the limitation of proc-macro. We take semi-automated approach: • Provide a default translator which will work **most** cases, not **all** cases • Also provide a manual way to specify the translation. If the default translator does not work, users can specify the translation manually, and these manual translations can be integrated with what the default translator generates. So the users can use the default translator as much as possible and only specify the translation for the edge cases. [pyo3-stub-gen] crate provides the manual way to specify the translation, and [pyo3-stub-gen-derive] crate provides the default translator as proc-macro based on the mechanism of [pyo3-stub-gen]. Usage If you are looking for a working example, please see the examples directory. | Example | Description | |:-----------------|:------------| | [examples/pure] | Example for Pure Rust maturin project | | [examples/mixed] | Example for Mixed Rust/Python maturin project with submodule | [examples/pure]: ./examples/pure/ [examples/mixed]: ./examples/mixed/ Here we describe basic usage of [pyo3-stub-gen] crate based on [examples/pure] example. Annotate Rust code with proc-macro This crate provides a procedural macro and others to generate a Python stub file. It is used with PyO3's macro. Let's consider a simple example PyO3 project: To generate a stub file for this project, please modify it as follows: > [!NOTE] > The macro must be placed before macro. For functions or methods that you want to exclude from the generated stub file, use the attribute: For getters, setters, and class attributes, you can specify default values that will appear in the stub file: Generate a stub file And then, create an executable target in to generate a stub file: and add in addition to in section of : This target generates a stub file when executed. The stub file is automatically found by , and it is included in the wheel package. See also the maturin document for more details. Manual Overriding When the automatic Rust-to-Python type translation doesn't produce the desired result, you can manually specify type information using Python stub syntax. There are two main approaches: • **Complete override** - Replace entire function signature with • **Partial override** - Override specific arguments or return types with Method 1: Complete Override Using Parameter Use the parameter to specify the complete function signature in Python stub syntax. This is ideal when you need to define complex types or when the entire signature needs custom definition. This approach: • ✅ Provides complete control over the generated stub • ✅ Supports complex types like • ✅ Allows adding custom docstrings • ✅ Import statements are automatically extracted Method 2: Partial Override Using Attributes For selective overrides, use on specific arguments or on the function. This is useful when most types translate correctly but a few need adjustment. This approach: • ✅ Fine-grained control over individual types • ✅ Preserves automatic generation for other parameters • ✅ Explicit about which types need manual specification Method 3: Separate Definitions Using Macros **How works:** The and macros automatically generate blocks internally to register type information. You can also manually add blocks to supplement or override this automatic registration. When multiple type signatures exist for the same function or method, the stub generator automatically generates decorators in the file. This enables proper type checking for functions that accept multiple type signatures. **Two approaches for overloads:** • ** parameter**: Define overloads inline with the function • ** blocks**: Keep stub definitions separate - useful for proc-macro/code generation **Function overloads:** Use the parameter to define multiple type signatures inline: Generated stub: **Suppress auto-generation** with : **Class method overloads:** Benefits: • ✅ Inline overload definitions with parameter • ✅ Automatic decorator generation • ✅ Deterministic ordering with index-based sorting • ✅ syntax available for proc-macro/code generation use cases **Advanced class method patterns:** For more advanced patterns, see examples/pure/src/manual_submit.rs: • **Fully manual method submission** - Submit all method signatures without • **Mixing proc-macro and manual submission** - Use for methods that need complex type annotations For comprehensive documentation, see Python Stub Syntax Support. Advanced: Using Marker Within Python stub syntax, you can reference Rust types directly using the marker. This leverages the trait implementation of the Rust type. The marker automatically expands to the appropriate Python type: • → (for arguments) • → (for return values) This is particularly useful for: • Generic types like , • Custom types that implement • Ensuring consistency between Rust and Python type mappings When to Use Which Method | Scenario | Recommended Method | |----------|-------------------| | Complex types (e.g., , ) | Method 1: parameter | | Override one or two arguments | Method 2: | | Function overloads ( ) | parameter | | Reference Rust types in Python syntax | Use mark…