create_interface macro example from documentation does not produce usable classes when used inside pymodule

[jamespickering5-nhs]

Bug Description

The documentation includes an example macro showing how to work around restrictions on generic using macros. However, when building modules using this macro, the classes defined inside the macro are not available to be imported.

Steps to Reproduce

1. Create a new project with maturin init macro-reproducer
2. Make lib.rs look like this:

use pyo3::prelude::*;

#[pymodule]
mod macro_reproducer {
    use pyo3::prelude::*;

    struct GenericClass<T> {
        data: T,
    }

    macro_rules! create_interface {
        ($name: ident, $type: ident) => {
            #[pyclass]
            pub struct $name {
                inner: GenericClass<$type>,
            }
            #[pymethods]
            impl $name {
                #[new]
                pub fn new(data: $type) -> Self {
                    Self {
                        inner: GenericClass { data: data },
                    }
                }
            }
        };
    }

    create_interface!(IntClass, i64);
    create_interface!(FloatClass, f64);

    #[pyclass]
    pub struct StringClass {
        inner: GenericClass<String>,
    }

    #[pymethods]
    impl StringClass {
        #[new]
        pub fn new(data: String) -> Self {
            Self {
                inner: GenericClass { data: data },
            }
        }
    }
}

3. Create a test:

def test_string_class():
    from macro_reproducer import StringClass
    s = StringClass("Hello, World!")

def test_int_class():
    from macro_reproducer import IntClass
    i = IntClass(42)

def test_float_class():
    from macro_reproducer import FloatClass
    f = FloatClass(3.14)

4. Run test with pytest test.py
5. IntClass and FloatClass tests fail with ImportError: cannot import name 'IntClass' from 'macro_reproducer'. Test for non-macro-coded StringClass passes

Backtrace

Your operating system and version

Ubuntu Linux 24.04

Your Python version (python --version)

Python 3.14.4

Your Rust version (rustc --version)

rustc 1.94.1 (e408947bf 2026-03-25)

Your PyO3 version

0.28.2

How did you install python? Did you use a virtualenv?

apt installed from deadsnakes, but issue is reproducible with uv installed Python too

Additional Info

No response

[jamespickering5-nhs]

It seems to be sufficient to add a #[pymodule_init] that adds the macro-generated classes to the module:

#[pymodule_init]
fn init(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<IntClass>()?;
    m.add_class::<FloatClass>()?;
    Ok(())
}

I guess this is a limitation of the macro system, but it seems like enough of a pitfall that perhaps it's worth documenting.

[davidhewitt]

Thanks for the report, agreed we can improve the documentation here.

Cc @Tpt as this workaround will also defeat our introspection machinery, I wonder if there's anything we can do about this in the long run (e.g. allow a way to programatically add classes as const fn)?

[Tpt]

Cc @Tpt as this workaround will also defeat our introspection machinery

Indeed. It's sad that there is no easy way to expand macros in the module content before processing it. It would cleanly solve our problem.

e.g. allow a way to programatically add classes as const fn

Does not sound possible because const fn are a subset of general functions so can't declare statics based on their arguments. So, we need macros for that (a add_class_to_module!(module, class) macro-by-example might just work).