Use single-arg form of `#[pymodule]` function in docs and tests (#3899)

* Use single-arg form for `#[pymodule]` functions in docs and tests

* Update guide/src/function.md

Co-authored-by: Icxolu <10486322+Icxolu@users.noreply.github.com>

* Add test of two-argument module function

* Fix new test

---------

Co-authored-by: Icxolu <10486322+Icxolu@users.noreply.github.com>

README.md

@@ -86,7 +86,7 @@ fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
 /// the `lib.name` setting in the `Cargo.toml`, else Python will not be able to
 /// import the module.
 #[pymodule]
-fn string_sum(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn string_sum(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;
     Ok(())
 }

examples/decorator/src/lib.rs

@@ -60,7 +60,7 @@ impl PyCounter {
 }
 
 #[pymodule]
-pub fn decorator(_py: Python<'_>, module: &PyModule) -> PyResult<()> {
+pub fn decorator(module: &Bound<'_, PyModule>) -> PyResult<()> {
     module.add_class::<PyCounter>()?;
     Ok(())
 }

examples/getitem/src/lib.rs

@@ -75,7 +75,7 @@ impl ExampleContainer {
 
 #[pymodule]
 #[pyo3(name = "getitem")]
-fn example(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn example(m: &Bound<'_, PyModule>) -> PyResult<()> {
     // ? -https://github.com/PyO3/maturin/issues/475
     m.add_class::<ExampleContainer>()?;
     Ok(())

examples/maturin-starter/src/submodule.rs

@@ -16,7 +16,7 @@ impl SubmoduleClass {
 }
 
 #[pymodule]
-pub fn submodule(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn submodule(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<SubmoduleClass>()?;
     Ok(())
 }

examples/plugin/plugin_api/src/lib.rs

@@ -26,7 +26,7 @@ impl Gadget {
 
 /// A Python module for plugin interface types
 #[pymodule]
-pub fn plugin_api(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn plugin_api(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Gadget>()?;
     Ok(())
 }

examples/setuptools-rust-starter/src/submodule.rs

@@ -16,7 +16,7 @@ impl SubmoduleClass {
 }
 
 #[pymodule]
-pub fn submodule(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn submodule(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<SubmoduleClass>()?;
     Ok(())
 }

examples/word-count/src/lib.rs

@@ -33,7 +33,7 @@ fn count_line(line: &str, needle: &str) -> usize {
 }
 
 #[pymodule]
-fn word_count(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn word_count(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(search, m)?)?;
     m.add_function(wrap_pyfunction!(search_sequential, m)?)?;
     m.add_function(wrap_pyfunction!(search_sequential_allow_threads, m)?)?;

guide/src/class.md

@@ -181,7 +181,7 @@ The next step is to create the module initializer and add our class to it:
 # struct Number(i32);
 #
 #[pymodule]
-fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Number>()?;
     Ok(())
 }

guide/src/class/numeric.md

@@ -326,7 +326,7 @@ impl Number {
 }
 
 #[pymodule]
-fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Number>()?;
     Ok(())
 }

guide/src/class/object.md

@@ -18,7 +18,7 @@ impl Number {
 }
 
 #[pymodule]
-fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Number>()?;
     Ok(())
 }
@@ -295,7 +295,7 @@ impl Number {
 }
 
 #[pymodule]
-fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Number>()?;
     Ok(())
 }

guide/src/ecosystem/async-await.md

@@ -128,7 +128,7 @@ fn rust_sleep(py: Python<'_>) -> PyResult<&PyAny> {
 }
 
 #[pymodule]
-fn my_async_module(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_async_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(rust_sleep, m)?)?;
 
     Ok(())
@@ -151,7 +151,7 @@ fn rust_sleep(py: Python<'_>) -> PyResult<&PyAny> {
 }
 
 #[pymodule]
-fn my_async_module(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_async_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(rust_sleep, m)?)?;
     Ok(())
 }
@@ -475,7 +475,7 @@ fn rust_sleep(py: Python<'_>) -> PyResult<&PyAny> {
 }
 
 #[pymodule]
-fn my_async_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_async_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(rust_sleep, m)?)?;
 
     Ok(())

guide/src/ecosystem/logging.md

@@ -30,11 +30,11 @@ fn log_something() {
 }
 
 #[pymodule]
-fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     // A good place to install the Rust -> Python logger.
     pyo3_log::init();
 
-    m.add_function(wrap_pyfunction!(log_something))?;
+    m.add_function(wrap_pyfunction!(log_something, m)?)?;
     Ok(())
 }
 ```

guide/src/function.md

@@ -13,7 +13,7 @@ fn double(x: usize) -> usize {
 }
 
 #[pymodule]
-fn my_extension(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_extension(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(double, m)?)?;
     Ok(())
 }
@@ -55,7 +55,7 @@ The `#[pyo3]` attribute can be used to modify properties of the generated Python
     }
 
     #[pymodule]
-    fn module_with_functions(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+    fn module_with_functions(m: &Bound<'_, PyModule>) -> PyResult<()> {
         m.add_function(wrap_pyfunction!(no_args_py, m)?)?;
         Ok(())
     }
@@ -92,7 +92,7 @@ The `#[pyo3]` attribute can be used to modify properties of the generated Python
     }
 
     #[pymodule]
-    fn module_with_fn(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+    fn module_with_fn(m: &Bound<'_, PyModule>) -> PyResult<()> {
         m.add_function(wrap_pyfunction!(pyfunction_with_module, m)?)
     }
     ```
@@ -166,8 +166,8 @@ Python argument passing convention.) It then embeds the call to the Rust functio
 FFI-wrapper function. This wrapper handles extraction of the regular arguments and the keyword
 arguments from the input `PyObject`s.
 
-The `wrap_pyfunction` macro can be used to directly get a `PyCFunction` given a
-`#[pyfunction]` and a `PyModule`: `wrap_pyfunction!(rust_fun, module)`.
+The `wrap_pyfunction` macro can be used to directly get a `Bound<PyCFunction>` given a
+`#[pyfunction]` and a `Bound<PyModule>`: `wrap_pyfunction!(rust_fun, module)`.
 
 ## `#[pyfn]` shorthand
 
@@ -197,7 +197,7 @@ documented in the rest of this chapter. The code above is expanded to the follow
 use pyo3::prelude::*;
 
 #[pymodule]
-fn my_extension(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_extension(m: &Bound<'_, PyModule>) -> PyResult<()> {
     #[pyfunction]
     fn double(x: usize) -> usize {
         x * 2

guide/src/function/signature.md

@@ -21,7 +21,7 @@ fn num_kwds(kwds: Option<&PyDict>) -> usize {
 }
 
 #[pymodule]
-fn module_with_functions(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn module_with_functions(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(num_kwds, m)?).unwrap();
     Ok(())
 }

guide/src/getting_started.md

@@ -163,7 +163,7 @@ fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
 /// the `lib.name` setting in the `Cargo.toml`, else Python will not be able to
 /// import the module.
 #[pymodule]
-fn pyo3_example(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn pyo3_example(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;
     Ok(())
 }

guide/src/module.md

@@ -12,7 +12,7 @@ fn double(x: usize) -> usize {
 
 /// This module is implemented in Rust.
 #[pymodule]
-fn my_extension(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_extension(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(double, m)?)?;
     Ok(())
 }
@@ -34,7 +34,7 @@ fn double(x: usize) -> usize {
 
 #[pymodule]
 #[pyo3(name = "custom_name")]
-fn my_extension(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn my_extension(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(double, m)?)?;
     Ok(())
 }

guide/src/python_from_rust.md

@@ -283,7 +283,7 @@ fn add_one(x: i64) -> i64 {
 }
 
 #[pymodule]
-fn foo(_py: Python<'_>, foo_module: &PyModule) -> PyResult<()> {
+fn foo(foo_module: &Bound<'_, PyModule>) -> PyResult<()> {
     foo_module.add_function(wrap_pyfunction!(add_one, foo_module)?)?;
     Ok(())
 }

guide/src/trait_bounds.md

@@ -132,7 +132,7 @@ struct UserModel {
 }
 
 #[pymodule]
-fn trait_exposure(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn trait_exposure(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<UserModel>()?;
     Ok(())
 }
@@ -489,7 +489,7 @@ pub struct UserModel {
 }
 
 #[pymodule]
-fn trait_exposure(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn trait_exposure(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<UserModel>()?;
     m.add_function(wrap_pyfunction!(solve_wrapper, m)?)?;
     Ok(())

pytests/src/awaitable.rs

@@ -79,7 +79,7 @@ impl FutureAwaitable {
 }
 
 #[pymodule]
-pub fn awaitable(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn awaitable(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<IterAwaitable>()?;
     m.add_class::<FutureAwaitable>()?;
     Ok(())

pytests/src/buf_and_str.rs

@@ -48,7 +48,7 @@ fn return_memoryview(py: Python<'_>) -> PyResult<Bound<'_, PyMemoryView>> {
 }
 
 #[pymodule]
-pub fn buf_and_str(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn buf_and_str(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<BytesExtractor>()?;
     m.add_function(wrap_pyfunction!(return_memoryview, m)?)?;
     Ok(())

pytests/src/comparisons.rs

@@ -101,7 +101,7 @@ impl OrderedDefaultNe {
 }
 
 #[pymodule]
-pub fn comparisons(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn comparisons(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Eq>()?;
     m.add_class::<EqDefaultNe>()?;
     m.add_class::<Ordered>()?;

pytests/src/datetime.rs

@@ -205,7 +205,7 @@ impl TzClass {
 }
 
 #[pymodule]
-pub fn datetime(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn datetime(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(make_date, m)?)?;
     m.add_function(wrap_pyfunction!(get_date_tuple, m)?)?;
     m.add_function(wrap_pyfunction!(date_from_timestamp, m)?)?;

pytests/src/dict_iter.rs

@@ -3,7 +3,7 @@ use pyo3::prelude::*;
 use pyo3::types::PyDict;
 
 #[pymodule]
-pub fn dict_iter(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn dict_iter(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<DictSize>()?;
     Ok(())
 }

pytests/src/enums.rs

@@ -1,7 +1,7 @@
-use pyo3::{pyclass, pyfunction, pymodule, types::PyModule, wrap_pyfunction, PyResult, Python};
+use pyo3::{pyclass, pyfunction, pymodule, types::PyModule, wrap_pyfunction, Bound, PyResult};
 
 #[pymodule]
-pub fn enums(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn enums(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<SimpleEnum>()?;
     m.add_class::<ComplexEnum>()?;
     m.add_wrapped(wrap_pyfunction!(do_simple_stuff))?;

pytests/src/misc.rs

@@ -31,7 +31,7 @@ fn get_item_and_run_callback(dict: Bound<'_, PyDict>, callback: Bound<'_, PyAny>
 }
 
 #[pymodule]
-pub fn misc(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn misc(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(issue_219, m)?)?;
     m.add_function(wrap_pyfunction!(get_type_full_name, m)?)?;
     m.add_function(wrap_pyfunction!(accepts_bool, m)?)?;

pytests/src/objstore.rs

@@ -19,6 +19,6 @@ impl ObjStore {
 }
 
 #[pymodule]
-pub fn objstore(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn objstore(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<ObjStore>()
 }

pytests/src/othermod.rs

@@ -29,7 +29,7 @@ fn double(x: i32) -> i32 {
 }
 
 #[pymodule]
-pub fn othermod(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn othermod(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(double, m)?)?;
 
     m.add_class::<ModClass>()?;

pytests/src/path.rs

@@ -12,7 +12,7 @@ fn take_pathbuf(path: PathBuf) -> PathBuf {
 }
 
 #[pymodule]
-pub fn path(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn path(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(make_path, m)?)?;
     m.add_function(wrap_pyfunction!(take_pathbuf, m)?)?;
 

pytests/src/pyclasses.rs

@@ -80,7 +80,7 @@ impl AssertingBaseClassGilRef {
 struct ClassWithoutConstructor;
 
 #[pymodule]
-pub fn pyclasses(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn pyclasses(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<EmptyClass>()?;
     m.add_class::<PyClassIter>()?;
     m.add_class::<AssertingBaseClass>()?;

pytests/src/pyfunctions.rs

@@ -68,7 +68,7 @@ fn args_kwargs<'py>(
 }
 
 #[pymodule]
-pub fn pyfunctions(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn pyfunctions(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(none, m)?)?;
     m.add_function(wrap_pyfunction!(simple, m)?)?;
     m.add_function(wrap_pyfunction!(simple_args, m)?)?;

pytests/src/sequence.rs

@@ -17,7 +17,7 @@ fn vec_to_vec_pystring(vec: Vec<&PyString>) -> Vec<&PyString> {
 }
 
 #[pymodule]
-pub fn sequence(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn sequence(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(vec_to_vec_i32, m)?)?;
     m.add_function(wrap_pyfunction!(array_to_array_i32, m)?)?;
     m.add_function(wrap_pyfunction!(vec_to_vec_pystring, m)?)?;

pytests/src/subclassing.rs

@@ -18,7 +18,7 @@ impl Subclassable {
 }
 
 #[pymodule]
-pub fn subclassing(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+pub fn subclassing(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Subclassable>()?;
     Ok(())
 }

src/conversions/indexmap.rs

@@ -71,7 +71,7 @@
 //! }
 //!
 //! #[pymodule]
-//! fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+//! fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
 //!     m.add_function(wrap_pyfunction!(calculate_statistics, m)?)?;
 //!     Ok(())
 //! }

src/conversions/num_bigint.rs

@@ -31,7 +31,7 @@
 //! }
 //!
 //! #[pymodule]
-//! fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+//! fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
 //!     m.add_function(wrap_pyfunction!(add_one, m)?)?;
 //!     Ok(())
 //! }

src/conversions/num_complex.rs

@@ -44,7 +44,7 @@
 //! }
 //!
 //! #[pymodule]
-//! fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+//! fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
 //!     m.add_function(wrap_pyfunction!(get_eigenvalues, m)?)?;
 //!     Ok(())
 //! }
@@ -57,7 +57,7 @@
 //! #     Python::with_gil(|py| -> PyResult<()> {
 //! #         let module = PyModule::new_bound(py, "my_module")?;
 //! #
-//! #         module.add_function(&wrap_pyfunction!(get_eigenvalues, module.as_gil_ref())?.as_borrowed())?;
+//! #         module.add_function(&wrap_pyfunction!(get_eigenvalues, module)?)?;
 //! #
 //! #         let m11 = PyComplex::from_doubles_bound(py, 0_f64, -1_f64);
 //! #         let m12 = PyComplex::from_doubles_bound(py, 1_f64, 0_f64);

src/conversions/rust_decimal.rs

@@ -30,7 +30,7 @@
 //! }
 //!
 //! #[pymodule]
-//! fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+//! fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
 //!     m.add_function(wrap_pyfunction!(add_one, m)?)?;
 //!     Ok(())
 //! }

src/exceptions.rs

@@ -164,9 +164,9 @@ macro_rules! import_exception {
 /// }
 ///
 /// #[pymodule]
-/// fn my_module(py: Python<'_>, m: &PyModule) -> PyResult<()> {
-///     m.add("MyError", py.get_type_bound::<MyError>())?;
-///     m.add_function(wrap_pyfunction!(raise_myerror, py)?)?;
+/// fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
+///     m.add("MyError", m.py().get_type_bound::<MyError>())?;
+///     m.add_function(wrap_pyfunction!(raise_myerror, m)?)?;
 ///     Ok(())
 /// }
 /// # fn main() -> PyResult<()> {

src/lib.rs

@@ -168,7 +168,7 @@
 //!
 //! /// A Python module implemented in Rust.
 //! #[pymodule]
-//! fn string_sum(py: Python<'_>, m: &PyModule) -> PyResult<()> {
+//! fn string_sum(m: &Bound<'_, PyModule>) -> PyResult<()> {
 //!     m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;
 //!
 //!     Ok(())

src/types/module.rs

@@ -239,7 +239,7 @@ impl PyModule {
     /// use pyo3::prelude::*;
     ///
     /// #[pymodule]
-    /// fn my_module(_py: Python<'_>, module: &PyModule) -> PyResult<()> {
+    /// fn my_module(module: &Bound<'_, PyModule>) -> PyResult<()> {
     ///     module.add("c", 299_792_458)?;
     ///     Ok(())
     /// }
@@ -280,7 +280,7 @@ impl PyModule {
     /// struct Foo { /* fields omitted */ }
     ///
     /// #[pymodule]
-    /// fn my_module(_py: Python<'_>, module: &PyModule) -> PyResult<()> {
+    /// fn my_module(module: &Bound<'_, PyModule>) -> PyResult<()> {
     ///     module.add_class::<Foo>()?;
     ///     Ok(())
     /// }
@@ -377,7 +377,7 @@ impl PyModule {
     ///     println!("Hello world!")
     /// }
     /// #[pymodule]
-    /// fn my_module(_py: Python<'_>, module: &PyModule) -> PyResult<()> {
+    /// fn my_module(module: &Bound<'_, PyModule>) -> PyResult<()> {
     ///     module.add_function(wrap_pyfunction!(say_hello, module)?)
     /// }
     /// ```
@@ -442,7 +442,7 @@ pub trait PyModuleMethods<'py>: crate::sealed::Sealed {
     /// use pyo3::prelude::*;
     ///
     /// #[pymodule]
-    /// fn my_module(_py: Python<'_>, module: &PyModule) -> PyResult<()> {
+    /// fn my_module(module: &Bound<'_, PyModule>) -> PyResult<()> {
     ///     module.add("c", 299_792_458)?;
     ///     Ok(())
     /// }
@@ -481,7 +481,7 @@ pub trait PyModuleMethods<'py>: crate::sealed::Sealed {
     /// struct Foo { /* fields omitted */ }
     ///
     /// #[pymodule]
-    /// fn my_module(_py: Python<'_>, module: &PyModule) -> PyResult<()> {
+    /// fn my_module(module: &Bound<'_, PyModule>) -> PyResult<()> {
     ///     module.add_class::<Foo>()?;
     ///     Ok(())
     /// }
@@ -570,7 +570,7 @@ pub trait PyModuleMethods<'py>: crate::sealed::Sealed {
     ///     println!("Hello world!")
     /// }
     /// #[pymodule]
-    /// fn my_module(_py: Python<'_>, module: &PyModule) -> PyResult<()> {
+    /// fn my_module(module: &Bound<'_, PyModule>) -> PyResult<()> {
     ///     module.add_function(wrap_pyfunction!(say_hello, module)?)
     /// }
     /// ```

tests/test_append_to_inittab.rs

@@ -8,8 +8,8 @@ fn foo() -> usize {
 }
 
 #[pymodule]
-fn module_fn_with_functions(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
-    m.add_function(wrap_pyfunction!(foo, m)?).unwrap();
+fn module_fn_with_functions(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_function(wrap_pyfunction!(foo, m)?)?;
     Ok(())
 }
 

tests/test_module.rs

@@ -36,7 +36,7 @@ fn double(x: usize) -> usize {
 
 /// This module is implemented in Rust.
 #[pymodule]
-fn module_with_functions(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn module_with_functions(m: &Bound<'_, PyModule>) -> PyResult<()> {
     #[pyfn(m)]
     #[pyo3(name = "no_parameters")]
     fn function_with_name() -> usize {
@@ -54,14 +54,14 @@ fn module_with_functions(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
         v.value * 2
     }
 
-    m.add_class::<AnonClass>().unwrap();
-    m.add_class::<ValueClass>().unwrap();
-    m.add_class::<LocatedClass>().unwrap();
+    m.add_class::<AnonClass>()?;
+    m.add_class::<ValueClass>()?;
+    m.add_class::<LocatedClass>()?;
 
-    m.add("foo", "bar").unwrap();
+    m.add("foo", "bar")?;
 
-    m.add_function(wrap_pyfunction!(double, m)?).unwrap();
-    m.add("also_double", wrap_pyfunction!(double, m)?).unwrap();
+    m.add_function(wrap_pyfunction!(double, m)?)?;
+    m.add("also_double", wrap_pyfunction!(double, m)?)?;
 
     Ok(())
 }
@@ -116,9 +116,31 @@ fn test_module_with_functions() {
     });
 }
 
+/// This module uses a legacy two-argument module function.
+#[pymodule]
+fn module_with_explicit_py_arg(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+    m.add_function(wrap_pyfunction!(double, m)?)?;
+    Ok(())
+}
+
+#[test]
+fn test_module_with_explicit_py_arg() {
+    use pyo3::wrap_pymodule;
+
+    Python::with_gil(|py| {
+        let d = [(
+            "module_with_explicit_py_arg",
+            wrap_pymodule!(module_with_explicit_py_arg)(py),
+        )]
+        .into_py_dict_bound(py);
+
+        py_assert!(py, *d, "module_with_explicit_py_arg.double(3) == 6");
+    });
+}
+
 #[pymodule]
 #[pyo3(name = "other_name")]
-fn some_name(_: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn some_name(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add("other_name", "other_name")?;
     Ok(())
 }
@@ -166,7 +188,7 @@ fn r#move() -> usize {
 }
 
 #[pymodule]
-fn raw_ident_module(_py: Python<'_>, module: &PyModule) -> PyResult<()> {
+fn raw_ident_module(module: &Bound<'_, PyModule>) -> PyResult<()> {
     module.add_function(wrap_pyfunction!(r#move, module)?)
 }
 
@@ -190,7 +212,7 @@ fn custom_named_fn() -> usize {
 #[test]
 fn test_custom_names() {
     #[pymodule]
-    fn custom_names(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+    fn custom_names(m: &Bound<'_, PyModule>) -> PyResult<()> {
         m.add_function(wrap_pyfunction!(custom_named_fn, m)?)?;
         Ok(())
     }
@@ -206,7 +228,7 @@ fn test_custom_names() {
 #[test]
 fn test_module_dict() {
     #[pymodule]
-    fn module_dict(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+    fn module_dict(m: &Bound<'_, PyModule>) -> PyResult<()> {
         m.dict().set_item("yay", "me")?;
         Ok(())
     }
@@ -222,7 +244,7 @@ fn test_module_dict() {
 fn test_module_dunder_all() {
     Python::with_gil(|py| {
         #[pymodule]
-        fn dunder_all(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+        fn dunder_all(m: &Bound<'_, PyModule>) -> PyResult<()> {
             m.dict().set_item("yay", "me")?;
             m.add_function(wrap_pyfunction!(custom_named_fn, m)?)?;
             Ok(())
@@ -245,7 +267,7 @@ fn submodule(module: &Bound<'_, PyModule>) -> PyResult<()> {
 }
 
 #[pymodule]
-fn submodule_with_init_fn(_py: Python<'_>, module: &PyModule) -> PyResult<()> {
+fn submodule_with_init_fn(module: &Bound<'_, PyModule>) -> PyResult<()> {
     module.add_function(wrap_pyfunction!(subfunction, module)?)?;
     Ok(())
 }
@@ -256,14 +278,14 @@ fn superfunction() -> String {
 }
 
 #[pymodule]
-fn supermodule(py: Python<'_>, module: &PyModule) -> PyResult<()> {
+fn supermodule(module: &Bound<'_, PyModule>) -> PyResult<()> {
     module.add_function(wrap_pyfunction!(superfunction, module)?)?;
-    let module_to_add = PyModule::new_bound(py, "submodule")?;
+    let module_to_add = PyModule::new_bound(module.py(), "submodule")?;
     submodule(&module_to_add)?;
-    module.add_submodule(module_to_add.as_gil_ref())?;
-    let module_to_add = PyModule::new_bound(py, "submodule_with_init_fn")?;
-    submodule_with_init_fn(py, module_to_add.as_gil_ref())?;
-    module.add_submodule(module_to_add.as_gil_ref())?;
+    module.add_submodule(&module_to_add)?;
+    let module_to_add = PyModule::new_bound(module.py(), "submodule_with_init_fn")?;
+    submodule_with_init_fn(&module_to_add)?;
+    module.add_submodule(&module_to_add)?;
     Ok(())
 }
 
@@ -300,7 +322,7 @@ fn ext_vararg_fn(py: Python<'_>, a: i32, args: &Bound<'_, PyTuple>) -> PyObject
 }
 
 #[pymodule]
-fn vararg_module(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
+fn vararg_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     #[pyfn(m, signature = (a=5, *args))]
     fn int_vararg_fn(py: Python<'_>, a: i32, args: &Bound<'_, PyTuple>) -> PyObject {
         ext_vararg_fn(py, a, args)
@@ -328,7 +350,7 @@ fn test_module_with_constant() {
     // Regression test for #1102
 
     #[pymodule]
-    fn module_with_constant(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+    fn module_with_constant(m: &Bound<'_, PyModule>) -> PyResult<()> {
         const ANON: AnonClass = AnonClass {};
 
         m.add("ANON", ANON)?;
@@ -410,7 +432,7 @@ fn pyfunction_with_pass_module_in_attribute(module: &PyModule) -> PyResult<&str>
 }
 
 #[pymodule]
-fn module_with_functions_with_module(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
+fn module_with_functions_with_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(pyfunction_with_module, m)?)?;
     m.add_function(wrap_pyfunction!(pyfunction_with_module_gil_ref, m)?)?;
     m.add_function(wrap_pyfunction!(pyfunction_with_module_owned, m)?)?;
@@ -475,7 +497,7 @@ fn test_module_doc_hidden() {
     #[doc(hidden)]
     #[allow(clippy::unnecessary_wraps)]
     #[pymodule]
-    fn my_module(_py: Python<'_>, _m: &PyModule) -> PyResult<()> {
+    fn my_module(_m: &Bound<'_, PyModule>) -> PyResult<()> {
         Ok(())
     }
 

tests/test_text_signature.rs

@@ -335,7 +335,7 @@ fn test_auto_test_signature_opt_out() {
 #[test]
 fn test_pyfn() {
     #[pymodule]
-    fn my_module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+    fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
         #[pyfn(m, signature = (a, b=None, *, c=42))]
         #[pyo3(text_signature = "(a, b=None, *, c=42)")]
         fn my_function(a: i32, b: Option<i32>, c: i32) {

tests/ui/invalid_pymodule_args.rs

@@ -1,7 +1,7 @@
 use pyo3::prelude::*;
 
 #[pymodule(some_arg)]
-fn module(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     Ok(())
 }