pyo3-stub-gen

Class methods can be overloaded using the submit! macro combined with gen_methods_from_python!. This allows you to manually define method signatures (including @overload variants) for a #[gen_stub_pyclass].

Rules for class method overloads:

• Multiple methods with the same name must use the @overload decorator in the Python string.
• At most one method can have is_overload = false (this represents the actual implementation).
• The @overload decorator is automatically detected from the provided Python stub syntax.

use pyo3::prelude::*;
use pyo3_stub_gen::{derive::*, inventory::submit};

#[gen_stub_pyclass]
#[pyclass]
pub struct ManualSubmit {}

submit! {
    gen_methods_from_python! {
        r"#
        class ManualSubmit:
            @overload
            def echo(self, obj: int) -> int: ...

            @overload
            def echo(self, obj: float) -> float: ...
        "#
    }
}

#[pymethods]
impl ManualSubmit {
    fn echo<'arg>(&self, obj: Bound<'arg, PyAny>) -> Bound<'arg, PyAny> {
        obj
    }
}

The pyo3-stub-gen tool handles default values differently based on how the member is defined in Rust:

1. Class Attributes (#[classattr])

For constants defined within a #[pymethods] block using #[classattr], the default value is automatically extracted from the constant value. The #[gen_stub(default = ...)] attribute is optional here.

Rust:

#[gen_stub_pymethods]
#[pymethods]
impl MyClass {
    #[classattr]
    const VERSION: &'static str = "1.0.0";
}

Stub:

class MyClass:
    VERSION: str = '1.0.0'

2. Getters (#[pyo3(get)] or custom methods)

For properties, the default value is embedded into the docstring of the @property method using a markdown-style Python block.

Rust:

#[gen_stub_pyclass]
#[pyclass]
struct MyClass {
    #[pyo3(get, set)]
    #[gen_stub(default = MyClass::default().value)]
    value: i32,
}

Stub:

class MyClass:
    @property
    def value(self) -> int:
        r"""
        ```python
        default = 42
        ```
        """

3. Setters (#[pyo3(set)])

When a member has both a getter and a setter, the default value is included in the docstrings of both the @property and the @value.setter methods.

For classes where most methods can be automatically generated but a few require complex type annotations (like Callable) or overloads, you can combine #[gen_stub_pymethods] with manual submit! blocks.

Important Rules:

1. Use #[gen_stub(skip)] on Rust methods that you want to handle manually.
2. Place submit! blocks before the #[gen_stub_pymethods] implementation block. This ensures that pyo3-stub-gen orders @overload definitions correctly based on their source position in the Python snippet.

#[gen_stub_pyclass]
#[pyclass]
pub struct PartialManualSubmit {}

// 1. Submit manual entries (overloads/complex types) FIRST
submit! {
    gen_methods_from_python! {
        r#"
        class PartialManualSubmit:
            @overload
            def echo_overloaded(self, obj: int) -> int: ...
        "#
    }
}

// 2. Then use the proc-macro for the rest
#[gen_stub_pymethods]
#[pymethods]
impl PartialManualSubmit {
    #[gen_stub(skip)]
    pub fn echo_overloaded<'arg>(&self, obj: Bound<'arg, PyAny>) -> PyResult<Bound<'arg, PyAny>> {
        // ...
    }
}

The way pyo3-stub-gen generates stub files depends on your project layout. Choosing the correct layout is critical for ensuring that submodules are correctly represented and packaged by maturin.

Pure Rust Layout

Use this when your project is a single module with no submodules and no existing Python source files.

• Configuration: Omit python-source from [tool.maturin] in pyproject.toml.
• Stub Generation: Generates a single {package_name}.pyi file at the project root.
• Limitation: maturin will only package this single file. Directory-based stubs are ignored in this layout.

Mixed Python/Rust Layout (Recommended)

Use this if you have Python source files OR if you use PyO3's add_submodule to create a module hierarchy.

• Configuration: Add python-source = "<path>" (e.g., python-source = "python") to [tool.maturin] in pyproject.toml.
• Stub Generation: Generates __init__.pyi files within the directory structure corresponding to your modules (e.g., {python_root}/{module_path}/__init__.pyi).
• Benefit: This is the only way to ensure submodules are properly packaged and recognized by type checkers.

# Example Mixed Layout Configuration
[tool.maturin]
python-source = "python"
module-name = "mypackage.main_mod"

The library supports two distinct ways to specify default values for function arguments, which are then converted into the final Python stub syntax (param_name: Type = default_value).

1. Rust-based Approach (PyO3 Signature)

In this approach, default values are extracted from the PyO3 #[pyo3(signature = ...)] attribute in your Rust code.

How it works:

• Signature Parsing: The generator parses the PyO3 signature, identifying positional-only (/), keyword-only (*), and standard parameters. When it encounters an assignment (e.g., param = value), it captures the Rust expression.
• Type-safe Conversion (RustType): If the parameter has a known Rust type, the generator uses compile-time type checking (let v: #r#type = #expr) and a runtime utility fmt_py_obj to convert the Rust value into its proper Python string representation.
• Direct String Conversion (OverrideType): If a type override is used, the generator performs direct string conversion, including translating Rust boolean literals (true/false) to Python literals (True/False).

2. Python-based Approach (Direct Stub Syntax)

In this approach, default values are extracted directly from a Python stub string provided to the generator.

How it works:

• AST Parsing: The generator uses rustpython-parser to parse the Python stub string into an Abstract Syntax Tree (AST).
• AST to String Conversion: The generator traverses the AST to convert Python expressions back into valid Python syntax strings. This includes handling:
  • Literals: None, True, False, integers, floats, and strings.
  • Attribute access: e.g., MyEnum.VARIANT.
  • Unary operations: e.g., -42.
  • Collections: Recursive conversion of list, tuple, and dict.
• Direct Usage: Because the input is already Python syntax, the generated code simply returns the extracted string directly without further conversion.

Comparison of Conversion Logic