[Stubs] Inner classes extending outer for data-carrying enums

[Aidan-McNay]

Bug Description

Hi all!

I have the following enum in my Rust code:

/// An expectation instead of what was found
#[pyclass(eq, from_py_object, module = "scarf_python")]
#[derive(Clone, PartialEq, Eq)]
pub enum Expectation {
    /// A specific token
    Token { token: Token },
    /// A verbose human-readable label
    Label { label: String },
    /// The end of a file
    EOI(),
}

When I attempt to generate stubs for this, I get the following:

class Expectation:
    """
    An expectation instead of what was found
    """
    def __eq__(self, /, other: object) -> bool: ...
    def __ne__(self, /, other: object) -> bool: ...
    @final
    class EOI(Expectation):
        """
        The end of a file
        """
        __match_args__: Final = ()
        def __getitem__(self, /, key: int) -> Any: ...
        def __len__(self, /) -> int: ...
        def __new__(cls, /) -> Expectation.EOI: ...
    @final
    class Label(Expectation):
        """
        A verbose human-readable label
        """
        __match_args__: Final = ("label",)
        def __new__(cls, /, label: str) -> Expectation.Label: ...
        @property
        def label(self, /) -> str: ...
    @final
    class Token(Expectation):
        """
        A specific token
        """
        __match_args__: Final = ("token",)
        def __new__(cls, /, token: Token) -> Expectation.Token: ...
        @property
        def token(self, /) -> Token: ...

In Python, inner classes cannot extend outer classes, as the outer isn't fully elaborated by the time the inner is encountered. The easiest way to see this is trying to run python on the following:

class Outer:
    class Inner(Outer):
        pass

My proposed fix for the above would just be to avoid nesting the inner classes; since they already extend the parent, they already have access to all methods/attributes/etc. The simplest change that I believe would fix this would be to remove the replace call here. However, I don't know what other changes I'd need to make to the actual generated code, beyond the stubs.

I believe similar issues would be present when generating stubs for any data-carrying enums.

Steps to Reproduce

My particular steps to encounter this involved trying to document the generated stubs (above) with sphinx-autodoc2; can provide issues to reproduce if needed (may be convoluted :), but I believe the issue is already identified

Backtrace

Your operating system and version

MacOS Monterey (12.6.5)

Your Python version (python --version)

Python 3.14.2

Your Rust version (rustc --version)

rustc 1.93.1 (01f6ddf75 2026-02-11)

Your PyO3 version

0.29.0

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

virtualenv

Additional Info

No response

[davidhewitt]

cc @Tpt it sounds like what we discussed in #5708 (comment) is indeed an issue :)

[Aidan-McNay]

Missed that - thanks for the pointer! Would a PR fixing this be welcome? Fixing the stubs is easy enough, just need to figure out the best way for the implementation. Current things I'm thinking about are:

• Import syntax/paths would change/break, but if the overall type stub functionality isn't considered stable yet, might be ok?
• We'd run into namespace collisions quickly just by flattening nested classes (ex. if you have something like)

pub enum First {
    MyVariant()
}

pub enum Second {
    MyVariant()
}

Because of that, I'm wondering whether it would be better to have the outer class act purely as a namespace, and have the inner classes avoid inheriting, and instead re-emit any shared functions? Using my Expectation example above, it would look something like:

class Expectation:
    """
    An expectation instead of what was found
    """
    @final
    class EOI:
        """
        The end of a file
        """
        __match_args__: Final = ()
        def __getitem__(self, /, key: int) -> Any: ...
        def __len__(self, /) -> int: ...
        def __new__(cls, /) -> Expectation.EOI: ...
        def __eq__(self, /, other: object) -> bool: ...
        def __ne__(self, /, other: object) -> bool: ...
    @final
    class Label:
        """
        A verbose human-readable label
        """
        __match_args__: Final = ("label",)
        def __new__(cls, /, label: str) -> Expectation.Label: ...
        @property
        def label(self, /) -> str: ...
        def __eq__(self, /, other: object) -> bool: ...
        def __ne__(self, /, other: object) -> bool: ...
    @final
    class Token:
        """
        A specific token
        """
        __match_args__: Final = ("token",)
        def __new__(cls, /, token: Token) -> Expectation.Token: ...
        @property
        def token(self, /) -> Token: ...
        def __eq__(self, /, other: object) -> bool: ...
        def __ne__(self, /, other: object) -> bool: ...

This would avoid the circular import while keeping variant classes in their own namespaces

(I was surprised too - I had tested with MyPy too and got no type annotation errors, but as soon as I started trying to do other analysis tools (autodoc2, autodoc-typehints, probably others?), I hit infinite recursion on trying to elaborate Outer, depending on Inner, depending on Outer.

[Tpt]

but as soon as I started trying to do other analysis tools (autodoc2, autodoc-typehints, probably others?

Thanks! I tried with Mypy, Ty and Pyrefly and all three were fine with the current structure (indeed invalid in python)

Import syntax/paths would change/break, but if the overall type stub functionality isn't considered stable yet, might be ok?

Note that even if stubs are not stable, the complex enums are. If we apply your inheritance change code like isinstance(value, Expectation) will break.

I would tend to think the best way is to change the stubs.

The solution I see is the one suggested by @davidhewitt in the comment he linked with some provisions to avoid type collision and do not expose the flatten classes as importable.

Something like:

class Expectation:
    """
    An expectation instead of what was found
    """
    def __eq__(self, /, other: object) -> bool: ...
    def __ne__(self, /, other: object) -> bool: ...
    EOI: Final[type[_Expectation_EOI]] = ...
    Label: Final[type[_Expectation_Label]] = ...
    Token: Final[type[_Expectation_Token]] = ...

@final
class _Expectation_EOI(Expectation):
   """
    The end of a file
    """
    __match_args__: Final = ()
    def __getitem__(self, /, key: int) -> Any: ...
    def __len__(self, /) -> int: ...
    def __new__(cls, /) -> Expectation.EOI: ...

@final
class _Expectation_Label(Expectation):
    """
    A verbose human-readable label
    """
    __match_args__: Final = ("label",)
   def __new__(cls, /, label: str) -> Expectation.Label: ...
   @property
   def label(self, /) -> str: ...

@final
class _Expectation_Token(Expectation):
    """
    A specific token
    """
    __match_args__: Final = ("token",)
    def __new__(cls, /, token: Token) -> Expectation.Token: ...
    @property
    def token(self, /) -> Token: ...

but it feels a bit sad.

[Aidan-McNay]

Makes sense - thanks for the feedback! Will try to draft a PR and see how y'all feel about it 🙂 (I'm also open to the answer of "Nah that looks kinda ugly and MyPy already supports our version, go fix the other tools instead" 🤪)

[Tpt]

Makes sense - thanks for the feedback! Will try to draft a PR and see how y'all feel about it 🙂 (

Thanks! I think it can be done by not changing the introspection code but just the pyo3-introspection crate stubs module that emits the stubs. It might make your life much easier.