Guide: focus on the module way of creating python modules

Author: Tpt

README.md

@@ -77,21 +77,18 @@ pyo3 = { version = "0.26.0", features = ["extension-module"] }
 **`src/lib.rs`**
 
 ```rust
-use pyo3::prelude::*;
-
-/// Formats the sum of two numbers as string.
-#[pyfunction]
-fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
-    Ok((a + b).to_string())
-}
-
-/// A Python module implemented in Rust. The name of this function must match
+/// A Python module implemented in Rust. The name of this module must match
 /// the `lib.name` setting in the `Cargo.toml`, else Python will not be able to
 /// import the module.
-#[pymodule]
-fn string_sum(m: &Bound<'_, PyModule>) -> PyResult<()> {
-    m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;
-    Ok(())
+#[pyo3::pymodule]
+mod string_sum {
+  use pyo3::prelude::*;
+
+  /// Formats the sum of two numbers as string.
+  #[pyfunction]
+  fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
+    Ok((a + b).to_string())
+  }
 }
 ```
 

guide/src/module.md

@@ -3,6 +3,7 @@
 You can create a module using `#[pymodule]`:
 
 ```rust,no_run
+# mod declarative_module_basic_test {
 use pyo3::prelude::*;
 
 #[pyfunction]
@@ -12,18 +13,21 @@ fn double(x: usize) -> usize {
 
 /// This module is implemented in Rust.
 #[pymodule]
-fn my_extension(m: &Bound<'_, PyModule>) -> PyResult<()> {
-    m.add_function(wrap_pyfunction!(double, m)?)
+mod my_extension {
+    #[pymodule_export]
+    use super::double; // The double function is made available from Python, works also with classes
 }
+# }
 ```
 
-The `#[pymodule]` procedural macro takes care of exporting the initialization function of your
-module to Python.
+The `#[pymodule]` procedural macro takes care of creating the initialization function of your
+module and expose it to Python.
 
-The module's name defaults to the name of the Rust function. You can override the module name by
+The module's name defaults to the name of the Rust module. You can override the module name by
 using `#[pyo3(name = "custom_name")]`:
 
 ```rust,no_run
+# mod declarative_module_custom_name_test {
 use pyo3::prelude::*;
 
 #[pyfunction]
@@ -32,9 +36,11 @@ fn double(x: usize) -> usize {
 }
 
 #[pymodule(name = "custom_name")]
-fn my_extension(m: &Bound<'_, PyModule>) -> PyResult<()> {
-    m.add_function(wrap_pyfunction!(double, m)?)
+mod my_extension {
+    #[pymodule_export]
+    use super::double;
 }
+# }
 ```
 
 The name of the module must match the name of the `.so` or `.pyd`
@@ -48,8 +54,7 @@ To import the module, either:
 
 ## Documentation
 
-The [Rust doc comments](https://doc.rust-lang.org/stable/book/ch03-04-comments.html) of the module
-initialization function will be applied automatically as the Python docstring of your module.
+The [Rust doc comments](https://doc.rust-lang.org/stable/book/ch03-04-comments.html) of the Rust module will be applied automatically as the Python docstring of your module.
 
 For example, building off of the above code, this will print `This module is implemented in Rust.`:
 
@@ -61,75 +66,54 @@ print(my_extension.__doc__)
 
 ## Python submodules
 
-You can create a module hierarchy within a single extension module by using
-[`Bound<'_, PyModule>::add_submodule()`]({{#PYO3_DOCS_URL}}/pyo3/prelude/trait.PyModuleMethods.html#tymethod.add_submodule).
-For example, you could define the modules `parent_module` and `parent_module.child_module`.
+You can create a module hierarchy within a single extension module by just `use`ing modules like functions or classes.
+For example, you could define the modules `parent_module` and `parent_module.child_module`:
 
 ```rust
+# mod declarative_module_submodule_test {
 use pyo3::prelude::*;
 
 #[pymodule]
-fn parent_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
-    register_child_module(m)?;
-    Ok(())
+mod parent_module {
+    #[pymodule_export]
+    use super::child_module;
 }
 
-fn register_child_module(parent_module: &Bound<'_, PyModule>) -> PyResult<()> {
-    let child_module = PyModule::new(parent_module.py(), "child_module")?;
-    child_module.add_function(wrap_pyfunction!(func, &child_module)?)?;
-    parent_module.add_submodule(&child_module)
+#[pymodule]
+mod child_module {
+    #[pymodule_export]
+    use super::func;
 }
 
 #[pyfunction]
 fn func() -> String {
     "func".to_string()
 }
-
-# Python::attach(|py| {
-#    use pyo3::wrap_pymodule;
-#    use pyo3::types::IntoPyDict;
-#    use pyo3::ffi::c_str;
-#    let parent_module = wrap_pymodule!(parent_module)(py);
-#    let ctx = [("parent_module", parent_module)].into_py_dict(py).unwrap();
-#
-#    py.run(c_str!("assert parent_module.child_module.func() == 'func'"), None, Some(&ctx)).unwrap();
-# })
+# }
 ```
 
 Note that this does not define a package, so this won’t allow Python code to directly import
 submodules by using `from parent_module import child_module`. For more information, see
 [#759](https://github.com/PyO3/pyo3/issues/759) and
 [#1517](https://github.com/PyO3/pyo3/issues/1517#issuecomment-808664021).
 
-It is not necessary to add `#[pymodule]` on nested modules, which is only required on the top-level module.
+## Inline declaration
 
-## Declarative modules
-
-Another syntax based on Rust inline modules is also available to declare modules.
+It is possible to declare functions, classes, sub-modules and constants inline in a module:
 
 For example:
 ```rust,no_run
 # mod declarative_module_test {
-use pyo3::prelude::*;
-
-#[pyfunction]
-fn double(x: usize) -> usize {
-    x * 2
-}
-
-#[pymodule]
+#[pyo3::pymodule]
 mod my_extension {
-    use super::*;
-
-    #[pymodule_export]
-    use super::double; // Exports the double function as part of the module
+    use pyo3::prelude::*;
 
     #[pymodule_export]
     const PI: f64 = std::f64::consts::PI; // Exports PI constant as part of the module
 
     #[pyfunction] // This will be part of the module
-    fn triple(x: usize) -> usize {
-        x * 3
+    fn double(x: usize) -> usize {
+        x * 2
     }
 
     #[pyclass] // This will be part of the module
@@ -138,47 +122,40 @@ mod my_extension {
     #[pymodule]
     mod submodule {
         // This is a submodule
-    }
-
-    #[pymodule_init]
-    fn init(m: &Bound<'_, PyModule>) -> PyResult<()> {
-        // Arbitrary code to run at the module initialization
-        m.add("double2", m.getattr("double")?)
+        use pyo3::prelude::*;
+                
+        #[pyclass]
+        struct Nested;
     }
 }
 # }
 ```
 
-The `#[pymodule]` macro automatically sets the `module` attribute of the `#[pyclass]` macros declared inside of it with its name.
+In this case, `#[pymodule]` macro automatically sets the `module` attribute of the `#[pyclass]` macros declared inside of it with its name.
 For nested modules, the name of the parent module is automatically added.
-In the following example, the `Unit` class will have for `module` `my_extension.submodule` because it is properly nested
-but the `Ext` class will have for `module` the default `builtins` because it not nested.
+In the previous example, the `Nested` class will have for `module` `my_extension.submodule`.
 
-```rust,no_run
-# mod declarative_module_module_attr_test {
-use pyo3::prelude::*;
+You can provide the `submodule` argument to `#[pymodule()]` for modules that are not top-level modules in order for them to properly generate the `#[pyclass]` `module` attribute automatically.
 
-#[pyclass]
-struct Ext;
+## Procedural initialization
 
-#[pymodule]
+If the macros provided by PyO3 are not enough, it is possible to run code at the module initialization:
+```rust,no_run
+# mod procedural_module_test {
+#[pyo3::pymodule]
 mod my_extension {
-    use super::*;
-
-    #[pymodule_export]
-    use super::Ext;
+    use pyo3::prelude::*;
 
-    #[pymodule]
-    mod submodule {
-        use super::*;
-        // This is a submodule
+    #[pyfunction]
+    fn double(x: usize) -> usize {
+        x * 2
+    }
 
-        #[pyclass] // This will be part of the module
-        struct Unit;
+    #[pymodule_init]
+    fn init(m: &Bound<'_, PyModule>) -> PyResult<()> {
+        // Arbitrary code to run at the module initialization
+        m.add("double2", m.getattr("double")?)
     }
 }
 # }
-```
-It is possible to customize the `module` value for a `#[pymodule]` with the `#[pyo3(module = "MY_MODULE")]` option.
-
-You can provide the `submodule` argument to `pymodule()` for modules that are not top-level modules -- it is automatically set for modules nested inside of a `#[pymodule]`.
+```