`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: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

davidhewitt

Thanks, some smaller suggestions and then I think will be ready to merge.

Nightly rust failure should hopefully not block CI.

davidhewitt · 2026-08-26T21:55:15Z

+/// Split an argument of pyo3::Python from the front of the arg list, if present
+pub fn split_off_python_arg<'a, 'b>(
+    args: &'a [FnArg<'b>],
+) -> (Option<&'a PyArg<'b>>, &'a [FnArg<'b>]) {
+    match args {
+        [FnArg::Py(py), args @ ..] => (Some(py), args),
+        args => (None, args),
+    }
+}


Why did this move? Seemed fine where it was.

davidhewitt · 2026-08-26T21:59:27Z

+                    pymodule_init = Some(quote! {
+                        #pyo3_path::impl_::pymodule::PyModuleInitResult::into_result(#ident(#(#call_args),*))?;
+                    });


As a closing thought, I think if this is produced with the return type span the errors will be easier to locate.

Suggested change

pymodule_init = Some(quote! {

#pyo3_path::impl_::pymodule::PyModuleInitResult::into_result(#ident(#(#call_args),*))?;

});

let return_span = item_fn.sig.output.span();

let pyo3_path = pyo3_path.to_tokens_spanned(return_span);

pymodule_init = Some(quote_spanned! { return_span =>

#pyo3_path::impl_::pymodule::PyModuleInitResult::into_result(#ident(#(#call_args),*))?;

});

…on return type

jonasdedden · 2026-08-27T11:25:10Z

@davidhewitt applied your suggestions, thanks!

davidhewitt

Thanks!

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

davidhewitt reviewed Aug 26, 2026

View reviewed changes

Address review: keep split_off_python_arg in pymethod, span init …

39f99f5

…on return type

davidhewitt approved these changes Aug 27, 2026

View reviewed changes

davidhewitt added this pull request to the merge queue Aug 27, 2026

Merged via the queue into PyO3:main with commit 2e4212d Aug 27, 2026
52 of 53 checks passed

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!

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!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

davidhewitt 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 commented Aug 27, 2026

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jonasdedden commented Jul 31, 2026 •

edited

Loading