`experimental-inspect`: emit `__all__` in the generated stubs by jonasdedden · Pull Request #6242 · PyO3/pyo3

jonasdedden · 2026-07-25T16:24:52Z

Problem

PyModuleMethods::add appends every name it adds to the module's __all__ (src/types/module.rs:500), so every #[pymodule] with at least one member has an __all__ at runtime. pyo3-introspection never emitted one, so the stub and the runtime disagreed and mypy.stubtest reported one error per module:

error: pyo3_pytests.misc.__all__ is not present in stub

Beyond stubtest, a stub without __all__ makes type checkers fall back to the implicit re-export rules, which is not what the runtime module actually exports.

Change

module_stubs now emits an __all__ listing the module's submodules, classes, functions and attributes - exactly the names add puts there at runtime. The names are sorted, and the list is serialized through the existing Expr machinery so string escaping is shared with the rest of the generator.

from typing import final

__all__ = ["SubDict"]

@final
class SubDict(dict): ...

The checked-in pytests/stubs/*.pyi are regenerated accordingly.

The open question in the issue: incomplete modules

Modules with a #[pymodule]/#[pymodule_init] function are tagged incomplete and get a def __getattr__(name: str) -> Incomplete: ... marker. This PR emits no __all__ for those.

The alternatives don't hold up:

A partial __all__ = [...] asserts a completeness the introspector cannot verify. It would hide from type checkers names that do exist at runtime, and it does not silence stubtest anyway - it just swaps __all__ is not present in stub for names exported from the stub do not correspond to the names exported at runtime.
A bare __all__: list[str] does not help either: stubtest explicitly handles that case and still compares the exported names (mypy/stubtest.py, _verify_exported_names), so it reports the same mismatch.

Leaving __all__ out keeps the stub accurate. It is easy to revisit if maintainers prefer otherwise - it's the one if module.incomplete guard in dunder_all_stubs.

Effect on `pyo3_pytests`

Measured with stubtest 2.3.0 on CPython 3.13, stubs copied next to the extension:

	before	after
`__all__` errors	15	1
total `stubtest` errors	43	29

The one remaining __all__ error is the root pyo3_pytests module, which is incomplete because its #[pymodule_init] takes the module. Its runtime __all__ is exactly its 17 submodules, and the introspector already knows all of them (Module::modules is populated, that is how the sibling .pyi files are written) so the list would be accurate; it is withheld only by the incomplete guard.

Tests

Three unit tests in pyo3-introspection/src/stubs.rs: the normal case, an incomplete module (no __all__), and an empty module (no __all__, since nothing is ever added and the attribute does not exist at runtime either).
nox -s test-introspection passes against the regenerated pytests/stubs.
Guide (guide/src/type-stub.md) example output and the incomplete-modules note updated.

chirizxc · 2026-07-25T18:43:52Z

https://peps.python.org/pep-0008/#module-level-dunder-names

Maybe we should make sure that __all__ = () is always at the top?

jonasdedden · 2026-07-25T21:32:16Z

https://peps.python.org/pep-0008/#module-level-dunder-names

Maybe we should make sure that all = () is always at the top?

Thanks for linking the PEP8 on this topic! I had a deeper look, since the __all__ even before stdlib or first or third party imports script struck me as weird, I've never seen this in other Python code. I think one also has to differentiate a bit between real Python code and typestubs, as they can have slightly different formatting and other rules.

Let's look at typeshed as the prime example, these are stdlib typestubs. Here, __all__ is typically put after the import block, as shown here for example. I also checked the typeshed package in general, this is the pattern used throughout 229 stub files in it. I think we should adhere to typeshed's formatting here, this also seems to be the __all__ placement used in other libraries.

I also checked ruff linting & formatting rules, and even with all rules enabled (ruff check --select ALL) it seems to be fine with both orderings, on both .py as well as .pyi files. The only placement-adjacent rule is E402 module-import-not-at-top-of-file (https://docs.astral.sh/ruff/rules/module-import-not-at-top-of-file/), and it seems to have an explicit ignore for __all__. The 12 ruff rules that touch __all__/dunders (RUF022, RUF068, F822, PLE0604, PLE0605, PYI056, …) are all about content, not position.

What I implemented already conformed with typeshed's (and other libraries) behavior on positioning of __all__, but nevertheless I applied some improvements in da59625. I noticed that the ordering within the __all__ block is actually checked in ruff and expected in a certain way, specifically in rule RUF022. There also could be some standardization of how many lines have to follow an __all__ block.

jonasdedden · 2026-07-25T22:05:15Z

Regarding the sorting I introduced in da59625. @chirizxc , would you care right now for ruff check --select I (isort) or ruff format compliance?

I'm asking because there are also two other stub files on main (pytests/stubs/exception.pyi and pytests/stubs/pyclasses.pyi) and a test that actually don't conform to ruff's isort-ing.

One could therefore argue that compliance to RUF022 (sorting of the __all__ block) is also not important, at least right now? Maybe we could leave ruff compliance out for now (i.e. remove isort_style_cmp and natural_cmp by reverting da59625), and then tackle ruff isort and RUF022 compliance in a followup?

Tpt

Thank you!

+1 for the approach taken on incomplete modules

Tpt · 2026-07-26T14:12:04Z

+        Other,
+    }
+
+    fn kind_of(name: &str) -> MemberKind {


instead of guessing the kind, what about sorting constants, classes and other separately then concatenate the outputs? This way you can avoid this guess

Going further, is it correct to be sorting here at all? Wouldn't that potentially lead to the type stub having a different value for the constant compared to the runtime behaviour? Can that cause problems?

If the suggestion in https://github.com/PyO3/pyo3/pull/6242/changes#r3652677133 is to make the macros emit __all__ anyway, should we skip adding any code to pyo3-introspection and just add emission in the macros, where we can be confident of the runtime value?

I removed the entire sorting again, mainly because I think that convert_members (introspection.rs:205-229) already sorts each of modules/classes/functions/attributes by name, and there also doesn't seem to be too much focus on strict ruff compliance elsewhere right now.

Regarding emitting __all__ in macros: I believe this would be a larger change and has some kinks here and there (small investigation by the side running). For now I'd propose to do it in the way this PR does it, and maybe we can investigate later?

Tpt · 2026-07-26T14:13:27Z

+    }
+
+    #[test]
+    fn test_dunder_all() {


nit: I would not bother writing unit tests for things that are already well covered by the integration tests. It's more code to maintain and not much added coverage

I deleted test_isort_style_cmp and test_dunder_all_of_incomplete_module (the latter is covered by pytests/stubs/__init__.pyi); I kept one trimmed test_dunder_all for the two cases pytests doesn't cover (submodule in __all__, empty module). Feel free to signal if you want to have this moved into a separate integration-style test.

Tpt · 2026-07-26T14:15:41Z

+///
+/// [`PyModuleMethods::add`]: https://docs.rs/pyo3/latest/pyo3/types/trait.PyModuleMethods.html#tymethod.add
+fn dunder_all_stubs(module: &Module, imports: &Imports) -> Option<String> {
+    if module.incomplete {


pedantic nit: I would also check here that the module does not already include a __all__ constant. This way we can move the __all__ generation into the macros without breaking the old pyo3-introspection versions (the generating code here would just stop to run)

Done, now bailing out if module.attributes already contains an __all__.

jonasdedden · 2026-07-27T17:00:55Z

@davidhewitt I explored generating __all__ directly from macros (which also uncovered edge cases in this PR I'm going to push a bugfix for shortly), and it seems doable. Let me give you a rough Pro & Contra list though why I think this PR's approach is still superior:

Pros of macro-approach:

Not an "inference"-ish approach, but creating __all__ right where modules & classes & co. are declared
Guaranteed exact same ordering in __all__ as the runtime extension exposes

Contras:

Instead of one self-contained function, it is roughly 6x the amount of code and touches 6x as many files, at least in my implementation. I also had to do an API change by introducing a Module::dunder_all field.
For backwards compatibility (i.e. new reader reading old data), I believe the approach chosen in this PR actually also has to be implemented as an additional fallback into the macro approach.
No forward compatibility in the shape I implemented (dedicated chunk field, ignored by older readers). Tpt's original suggestion - emitting it as a plain attribute chunk - would be forward-compatible, but it can't express 'name unknown at compile time', so it breaks for modules exporting native types.

Given that mypy and stubtest to the best of my knowledge consume __all__ purely as sets, there isn't really a user-facing advantage of doing it from macros (i.e. ordering is not important, as long as all runtime-exposed symbols are in __all__), but happy to continue exploring that approach if you think it's better.

jonasdedden · 2026-07-31T12:58:57Z

In #6271 I implement necessary changes to not lose the emission of __all__ on "incomplete" modules, if the only thing you do is something like initializing a pyo3-log logger but no new objects are introduced into the module.

…plete `incomplete` was set to `pymodule_init.is_some()`, so any declarative module with an initialiser got `def __getattr__(name: str) -> Incomplete: ...` in its stubs and (since PyO3#6242) no `__all__` either. That flag is what makes every unknown attribute on the module resolve to `Any`, which is most of the value of having a stub at all. The flag is conservative for a good reason: `#[pymodule_init]` receives `&Bound<'_, PyModule>` and can add arbitrary attributes the macro cannot see. But the common case does not want the module. `pyo3_log::init()` is the motivating example — it installs a global `log` logger and takes nothing: #[pymodule_init] fn init() -> PyResult<()> { pyo3_log::init(); Ok(()) } An initialiser with no parameters cannot reach the module, so it cannot add members to it, so the module is still fully described. This is inferred from the signature rather than asserted by a new attribute: it is checked by the compiler instead of trusted. One-argument initialisers keep today's behaviour exactly. Two or more is now a clear error instead of a confusing one from the generated call site.

jonasdedden · 2026-08-14T12:11:45Z

@davidhewitt & @Tpt : I gave this PR another cleanup; As mentioned in the previous comment, I believe this PR is the easiest way to get functionally correct __all__ emission. Could you give it another look?

codspeed-hq · 2026-08-14T12:28:06Z

Merging this PR will not alter performance

✅ 141 untouched benchmarks
⏩ 6 skipped benchmarks¹

_{Comparing jonasdedden:introspection-dunder-all (18b18f2) with main (7164282)}

6 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

jonasdedden · 2026-08-26T10:07:01Z

@Tpt cautious ping

…plete (PyO3#6271) * feat(inspect): let a no-argument #[pymodule_init] keep the module complete `incomplete` was set to `pymodule_init.is_some()`, so any declarative module with an initialiser got `def __getattr__(name: str) -> Incomplete: ...` in its stubs and (since PyO3#6242) no `__all__` either. That flag is what makes every unknown attribute on the module resolve to `Any`, which is most of the value of having a stub at all. The flag is conservative for a good reason: `#[pymodule_init]` receives `&Bound<'_, PyModule>` and can add arbitrary attributes the macro cannot see. But the common case does not want the module. `pyo3_log::init()` is the motivating example — it installs a global `log` logger and takes nothing: #[pymodule_init] fn init() -> PyResult<()> { pyo3_log::init(); Ok(()) } An initialiser with no parameters cannot reach the module, so it cannot add members to it, so the module is still fully described. This is inferred from the signature rather than asserted by a new attribute: it is checked by the compiler instead of trusted. One-argument initialisers keep today's behaviour exactly. Two or more is now a clear error instead of a confusing one from the generated call site. * Rename * test: cover the no-argument `#[pymodule_init]` paths Codecov flagged three lines in `pymodule_module_impl` as uncovered: the two `ensure_spanned!` error arms and the no-argument codegen branch. - `tests/ui/invalid_pymodule_init_args.rs` covers the new arity check. - `tests/ui/invalid_pymodule_init_pyfunction.rs` covers the pre-existing `#[pyfunction]`-alongside-`#[pymodule_init]` check, which had no test. - `test_pymodule_init_without_module` compiles a module whose `#[pymodule_init]` takes no argument and asserts it still runs, covering the `#ident()?` branch. * Review * Allow `pymodule_init` also to be unfallible * Address review * Update guide/src/module.md Co-authored-by: David Hewitt <mail@davidhewitt.dev> * Address review: optional `Python` argument and better diagnostics - `#[pymodule_init]` may take a `Python<'_>` marker in front of the module argument or instead of it, via `split_off_python_arg`, which moves from `pymethod` to `method` next to `FnArg`. A `Python`-only initialiser is still not handed the module, so the module stays complete for introspection. - `PyModuleInitResult` gets a `#[diagnostic::on_unimplemented]` message naming `#[pymodule_init]` instead of reporting a raw trait bound. * Address review: keep `split_off_python_arg` in `pymethod`, span init on return type --------- Co-authored-by: David Hewitt <mail@davidhewitt.dev>

`PyModuleMethods::add` appends every name it adds to the module `__all__`, so every `#[pymodule]` with at least one member has an `__all__` at runtime. The generated stubs never declared one, so the stub and the runtime disagreed and `mypy.stubtest` reported one error per module. `__all__` is only emitted for complete modules: for a module tagged incomplete we don't know the full list of members, and a partial `__all__` would hide from type checkers names that do exist at runtime. Fixes PyO3#6241 It is also followed by an empty line now, so that it never sticks to the first declaration. Both match what `typeshed` does: of the 231 stdlib stubs declaring `__all__`, 229 have it before any class or function and 204 have an empty line after it. `dunder_all_stubs` now sizes the name vector upfront and returns before allocating it at all when the module has no member, as suggested in review. Review comments

…time one Nothing tied the `__all__` in the checked-in stubs to the value the modules actually build at import time, which is what let the `#[pyfunction(name = "...")]` mismatch go unnoticed. The test compares sets rather than lists: the stubs list the members in the order they are declared in, which is not the order `PyModuleMethods::add` appends them in. `__all__` is only ever consumed as a set of names, so that difference is not observable — writing the assertion this way is also the clearest place to record that decision. It needs no `experimental-inspect` build, only the checked-in stubs and the extension, so it runs as part of the normal `pytest` session. Run the `__all__` stub test where the build matches the stubs `ruff`'s `B009` rejected the `getattr` call, and the test itself only holds for a `pyo3_pytests` built with `experimental-async,experimental-inspect`, which is what the checked-in stubs are generated from. `pytests`' own session builds without them, so `annotations` and `with_async` are missing there; run the test from the `test-introspection` session instead.

…_all__`

jonasdedden · 2026-08-28T08:48:56Z

Now that #6271 was merged 🚀 , I included an additional test in 18b18f2 that shows that a init function doing no modification of the module correctly does not result in Incomplete and thereby emission of __all__ takes place.

jonasdedden · 2026-08-28T09:21:15Z

Btw., the merged PRs of the last weeks show some arguably impressive results:

	before	after
`__all__` errors	15	1
total `stubtest` errors	~~100~~ 43	86 29

The crossed out values reflected the state of PyO3's experimental-inspect feature at creation time of this PR, i.e. Jul 25.

Remaining issues are 17x undeclared submodules, 1x __all__ (root), 6x @disjoint_base, 3x failed-to-import, 1 Number.__pow__ mod default, 1 no .pyi for inner pyo3_pytests.pyo3_pytests.

chirizxc reviewed Jul 25, 2026

View reviewed changes

Comment thread pyo3-introspection/src/stubs.rs Outdated

chirizxc reviewed Jul 25, 2026

View reviewed changes

Comment thread pyo3-introspection/src/stubs.rs

jonasdedden mentioned this pull request Jul 25, 2026

test_super_traverse_early_return_does_not_abort is flaky on free-threaded builds (~30% of runs) #6243

Closed

Tpt reviewed Jul 26, 2026

View reviewed changes

jonasdedden force-pushed the introspection-dunder-all branch from e6e8bbb to cf721d0 Compare July 26, 2026 21:04

jonasdedden force-pushed the introspection-dunder-all branch from 3da1fee to 58691aa Compare July 27, 2026 22:14

jonasdedden mentioned this pull request Jul 31, 2026

experimental-inspect: no-parameter pymodule_init keeps module complete #6271

Merged

jonasdedden force-pushed the introspection-dunder-all branch from 58691aa to 5b32604 Compare August 14, 2026 12:09

jonasdedden mentioned this pull request Aug 20, 2026

experimental-inspect: Iterator __next__ not optional #6274

Merged

jonasdedden added 4 commits August 28, 2026 10:34

review: trim comments and docstrings

ca735c8

experimental-inspect: test that a complete pymodule_init keeps `_…

18b18f2

…_all__`

jonasdedden force-pushed the introspection-dunder-all branch from 5b32604 to 18b18f2 Compare August 28, 2026 08:47

Uh oh!

Conversation

jonasdedden commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Change

The open question in the issue: incomplete modules

Effect on pyo3_pytests

Tests

Uh oh!

chirizxc commented Jul 25, 2026

Uh oh!

Uh oh!

Uh oh!

jonasdedden commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonasdedden commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Tpt left a comment

Choose a reason for hiding this comment

Uh oh!

Tpt Jul 26, 2026

Choose a reason for hiding this comment

Uh oh!

davidhewitt Jul 26, 2026

Choose a reason for hiding this comment

Uh oh!

jonasdedden Jul 26, 2026

Choose a reason for hiding this comment

Uh oh!

Tpt Jul 26, 2026

Choose a reason for hiding this comment

Uh oh!

jonasdedden Jul 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tpt Jul 26, 2026

Choose a reason for hiding this comment

Uh oh!

jonasdedden Jul 26, 2026

Choose a reason for hiding this comment

Uh oh!

jonasdedden commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonasdedden commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonasdedden commented Aug 14, 2026

Uh oh!

codspeed-hq Bot commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

jonasdedden commented Aug 26, 2026

Uh oh!

jonasdedden commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonasdedden commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jonasdedden commented Jul 25, 2026 •

edited

Loading

Effect on `pyo3_pytests`

jonasdedden commented Jul 25, 2026 •

edited

Loading

jonasdedden commented Jul 25, 2026 •

edited

Loading

jonasdedden Jul 26, 2026 •

edited

Loading

jonasdedden commented Jul 27, 2026 •

edited

Loading

jonasdedden commented Jul 31, 2026 •

edited

Loading

codspeed-hq Bot commented Aug 14, 2026 •

edited

Loading

jonasdedden commented Aug 28, 2026 •

edited

Loading

jonasdedden commented Aug 28, 2026 •

edited

Loading