`experimental-inspect`: no-parameter `pymodule_init` keeps module complete by jonasdedden · Pull Request #6271 · PyO3/pyo3

jonasdedden · 2026-07-31T12:56:31Z

incomplete was set to pymodule_init.is_some(), so any declarative module with an initialiser got def __getattr__(name: str) -> Incomplete: ... in its stubs. This is also relevant for #6242 where it would lead to no emission of __all__ either, breaking stubtest compliance. 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, so it would be silly to have such a strong negative impact on typestubs:

    #[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.

…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.

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.

jonasdedden · 2026-08-14T11:51:05Z

@davidhewitt I ran some additional cleanups over this PR and also introduced one additional change: pymodule_init now also is allowed to return -> (), which simplifies the examples around logging init for example. The latest change is in commit f2b01cd, meaning it also could be easily reverted if you wish so.

Tpt

Thank you! Makes perfect sense to allow () as a return type

jonasdedden · 2026-08-26T10:06:47Z

@Tpt cautious ping

davidhewitt

Thanks, a few small refinements suggested, overall I think this makes sense.

davidhewitt · 2026-08-26T10:45:42Z

 unsafe impl Sync for PyModuleDefSlots {}

+/// Used to accept either `()` or `Result<(), E>` from a `#[pymodule_init]` function.
+pub trait PyModuleInitResult {


I think this will make the UX nicer

Suggested change

pub trait PyModuleInitResult {

#[diagnostic::on_unimplemented(

message = "`{Self}` is not a suitable return value for `#[pymodule_init]` functions

)]

pub trait PyModuleInitResult {

Implemented the suggested change and added an additional note too

davidhewitt · 2026-08-26T10:46:48Z

+                    let call = if pymodule_init_takes_module {
+                        quote! { #ident(module) }
+                    } else {
+                        quote! { #ident() }
+                    };


It might be nice to use split_off_python_arg to optionally allow py: Python<'_> for initialization even if the module is not passed.

py is now also allowed, plus a handful of new tests that show that this feature works

Co-authored-by: David Hewitt <mail@davidhewitt.dev>

…s-module-complete

- `#[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.

jonasdedden · 2026-08-26T13:04:45Z

Raised some issue for the CI failure for completeness here: #6352

jonasdedden mentioned this pull request Jul 31, 2026

experimental-inspect: emit __all__ in the generated stubs #6242

Open

jonasdedden changed the title ~~experimental-inspect no-parameter pymodule init keeps module complete~~ experimental-inspect: no-parameter pymodule init keeps module complete Jul 31, 2026

jonasdedden changed the title ~~experimental-inspect: no-parameter pymodule init keeps module complete~~ experimental-inspect: no-parameter pymodule_init keeps module complete Jul 31, 2026

davidhewitt mentioned this pull request Aug 3, 2026

release: 0.29.2 #6285

Merged

8 tasks

jonasdedden added 5 commits August 14, 2026 13:16

Rename

f921e37

Review

9001564

Allow pymodule_init also to be unfallible

f2b01cd

jonasdedden force-pushed the experimental-inspect-pymodule-init-keeps-module-complete branch from 3da1d09 to f2b01cd Compare August 14, 2026 11:48

Tpt reviewed Aug 14, 2026

View reviewed changes

Comment thread pyo3-macros-backend/src/module.rs Outdated

Comment thread src/impl_/pymodule.rs Outdated

Address review

36ee47d

jonasdedden mentioned this pull request Aug 20, 2026

experimental-inspect: Iterator __next__ not optional #6274

Merged

davidhewitt reviewed Aug 26, 2026

View reviewed changes

jonasdedden and others added 3 commits August 26, 2026 13:01

Update guide/src/module.md

dd18e95

Co-authored-by: David Hewitt <mail@davidhewitt.dev>

Merge branch 'PyO3:main' into experimental-inspect-pymodule-init-keep…

e6f0128

…s-module-complete

Navigation Menu

Uh oh!

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

`experimental-inspect`: no-parameter `pymodule_init` keeps module complete#6271
jonasdedden wants to merge 9 commits into
PyO3:mainfrom
jonasdedden:experimental-inspect-pymodule-init-keeps-module-complete

jonasdedden commented Jul 31, 2026 •

edited

Loading

Uh oh!

jonasdedden commented Aug 14, 2026

Uh oh!

Tpt left a comment

Uh oh!

Uh oh!

Uh oh!

jonasdedden commented Aug 26, 2026

Uh oh!

davidhewitt left a comment

Uh oh!

Uh oh!

davidhewitt Aug 26, 2026

Uh oh!

jonasdedden Aug 26, 2026

Uh oh!

davidhewitt Aug 26, 2026

Uh oh!

jonasdedden Aug 26, 2026

Uh oh!

jonasdedden commented Aug 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

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!

Tpt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jonasdedden commented Aug 26, 2026

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

davidhewitt Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

jonasdedden Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

davidhewitt Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

jonasdedden Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

jonasdedden commented Aug 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jonasdedden commented Jul 31, 2026 •

edited

Loading