Merge pull request #1143 from sebpuetz/pyfunction-modules

PyModule in #[pyfunction]

Author: davidhewitt

CHANGELOG.md

@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Add optional implementations of `ToPyObject`, `IntoPy`, and `FromPyObject` for [hashbrown](https://crates.io/crates/hashbrown)'s `HashMap` and `HashSet` types. The `hashbrown` feature must be enabled for these implementations to be built. [#1114](https://github.com/PyO3/pyo3/pull/1114/)
 - Allow other `Result` types when using `#[pyfunction]`. [#1106](https://github.com/PyO3/pyo3/issues/1106).
 - Add `#[derive(FromPyObject)]` macro for enums and structs. [#1065](https://github.com/PyO3/pyo3/pull/1065)
+- Add macro attribute to `#[pyfn]` and `#[pyfunction]` to pass the module of a Python function to the function
+  body. [#1143](https://github.com/PyO3/pyo3/pull/1143)
+- Add `add_function()` and `add_submodule()` functions to `PyModule` [#1143](https://github.com/PyO3/pyo3/pull/1143)
 
 ### Changed
 - Exception types have been renamed from e.g. `RuntimeError` to `PyRuntimeError`, and are now only accessible by `&T` or `Py<T>` similar to other Python-native types. The old names continue to exist but are deprecated. [#1024](https://github.com/PyO3/pyo3/pull/1024)
@@ -30,6 +33,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Implement `Send + Sync` for `PyErr`. `PyErr::new`, `PyErr::from_type`, `PyException::py_err` and `PyException::into` have had these bounds added to their arguments. [#1067](https://github.com/PyO3/pyo3/pull/1067)
 - Change `#[pyproto]` to return NotImplemented for operators for which Python can try a reversed operation. #[1072](https://github.com/PyO3/pyo3/pull/1072)
 - `PyModule::add` now uses `IntoPy<PyObject>` instead of `ToPyObject`. #[1124](https://github.com/PyO3/pyo3/pull/1124)
+- Add nested modules as `&PyModule` instead of using the wrapper generated by `#[pymodule]`. [#1143](https://github.com/PyO3/pyo3/pull/1143)
 
 ### Removed
 - Remove `PyString::as_bytes`. [#1023](https://github.com/PyO3/pyo3/pull/1023)
@@ -50,6 +54,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Link against libpython on android with `extension-module` set. [#1095](https://github.com/PyO3/pyo3/pull/1095)
 - Fix support for both `__add__` and `__radd__`  in the `+` operator when both are defined in `PyNumberProtocol`
   (and similar for all other reversible operators). [#1107](https://github.com/PyO3/pyo3/pull/1107)
+- Associate Python functions with their module by passing the Module and Module name [#1143](https://github.com/PyO3/pyo3/pull/1143)
 
 ## [0.11.1] - 2020-06-30
 ### Added

README.md

@@ -67,7 +67,7 @@ fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
 /// A Python module implemented in Rust.
 #[pymodule]
 fn string_sum(py: Python, m: &PyModule) -> PyResult<()> {
-    m.add_wrapped(wrap_pyfunction!(sum_as_string))?;
+    m.add_function(wrap_pyfunction!(sum_as_string))?;
 
     Ok(())
 }

examples/rustapi_module/src/datetime.rs

@@ -215,29 +215,29 @@ impl TzClass {
 
 #[pymodule]
 fn datetime(_py: Python<'_>, m: &PyModule) -> PyResult<()> {
-    m.add_wrapped(wrap_pyfunction!(make_date))?;
-    m.add_wrapped(wrap_pyfunction!(get_date_tuple))?;
-    m.add_wrapped(wrap_pyfunction!(date_from_timestamp))?;
-    m.add_wrapped(wrap_pyfunction!(make_time))?;
-    m.add_wrapped(wrap_pyfunction!(get_time_tuple))?;
-    m.add_wrapped(wrap_pyfunction!(make_delta))?;
-    m.add_wrapped(wrap_pyfunction!(get_delta_tuple))?;
-    m.add_wrapped(wrap_pyfunction!(make_datetime))?;
-    m.add_wrapped(wrap_pyfunction!(get_datetime_tuple))?;
-    m.add_wrapped(wrap_pyfunction!(datetime_from_timestamp))?;
+    m.add_function(wrap_pyfunction!(make_date))?;
+    m.add_function(wrap_pyfunction!(get_date_tuple))?;
+    m.add_function(wrap_pyfunction!(date_from_timestamp))?;
+    m.add_function(wrap_pyfunction!(make_time))?;
+    m.add_function(wrap_pyfunction!(get_time_tuple))?;
+    m.add_function(wrap_pyfunction!(make_delta))?;
+    m.add_function(wrap_pyfunction!(get_delta_tuple))?;
+    m.add_function(wrap_pyfunction!(make_datetime))?;
+    m.add_function(wrap_pyfunction!(get_datetime_tuple))?;
+    m.add_function(wrap_pyfunction!(datetime_from_timestamp))?;
 
     // Python 3.6+ functions
     #[cfg(Py_3_6)]
     {
-        m.add_wrapped(wrap_pyfunction!(time_with_fold))?;
+        m.add_function(wrap_pyfunction!(time_with_fold))?;
         #[cfg(not(PyPy))]
         {
-            m.add_wrapped(wrap_pyfunction!(get_time_tuple_fold))?;
-            m.add_wrapped(wrap_pyfunction!(get_datetime_tuple_fold))?;
+            m.add_function(wrap_pyfunction!(get_time_tuple_fold))?;
+            m.add_function(wrap_pyfunction!(get_datetime_tuple_fold))?;
         }
     }
 
-    m.add_wrapped(wrap_pyfunction!(issue_219))?;
+    m.add_function(wrap_pyfunction!(issue_219))?;
     m.add_class::<TzClass>()?;
 
     Ok(())

examples/rustapi_module/src/othermod.rs

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

examples/word-count/src/lib.rs

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

guide/src/function.md

@@ -36,7 +36,7 @@ fn double(x: usize) -> usize {
 
 #[pymodule]
 fn module_with_functions(py: Python, m: &PyModule) -> PyResult<()> {
-    m.add_wrapped(wrap_pyfunction!(double)).unwrap();
+    m.add_function(wrap_pyfunction!(double)).unwrap();
 
     Ok(())
 }
@@ -65,7 +65,7 @@ fn num_kwds(kwds: Option<&PyDict>) -> usize {
 
 #[pymodule]
 fn module_with_functions(py: Python, m: &PyModule) -> PyResult<()> {
-    m.add_wrapped(wrap_pyfunction!(num_kwds)).unwrap();
+    m.add_function(wrap_pyfunction!(num_kwds)).unwrap();
     Ok(())
 }
 
@@ -189,3 +189,47 @@ If you have a static function, you can expose it with `#[pyfunction]` and use [`
 [`PyAny::call1`]: https://docs.rs/pyo3/latest/pyo3/struct.PyAny.html#tymethod.call1
 [`PyObject`]: https://docs.rs/pyo3/latest/pyo3/type.PyObject.html
 [`wrap_pyfunction!`]: https://docs.rs/pyo3/latest/pyo3/macro.wrap_pyfunction.html
+
+### Accessing the module of a function
+
+It is possible to access the module of a `#[pyfunction]` and `#[pyfn]` in the
+function body by passing the `pass_module` argument to the attribute:
+
+```rust
+use pyo3::wrap_pyfunction;
+use pyo3::prelude::*;
+
+#[pyfunction(pass_module)]
+fn pyfunction_with_module(module: &PyModule) -> PyResult<&str> {
+    module.name()
+}
+
+#[pymodule]
+fn module_with_fn(py: Python, m: &PyModule) -> PyResult<()> {
+    m.add_function(wrap_pyfunction!(pyfunction_with_module))
+}
+
+# fn main() {}
+```
+
+If `pass_module` is set, the first argument **must** be the `&PyModule`. It is then possible to use the module
+in the function body.
+
+The same works for `#[pyfn]`:
+
+```rust
+use pyo3::wrap_pyfunction;
+use pyo3::prelude::*;
+
+#[pymodule]
+fn module_with_fn(py: Python, m: &PyModule) -> PyResult<()> {
+
+    #[pyfn(m, "module_name", pass_module)]
+    fn module_name(module: &PyModule) -> PyResult<&str> {
+        module.name()
+    }
+    Ok(())
+}
+
+# fn main() {}
+```

guide/src/logging.md

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

guide/src/module.md

@@ -32,16 +32,22 @@ fn sum_as_string(a: i64, b: i64) -> String {
 # fn main() {}
 ```
 
-The `#[pymodule]` procedural macro attribute takes care of exporting the initialization function of your module to Python. It can take as an argument the name of your module, which must be the name of the `.so` or `.pyd` file; the default is the Rust function's name.
+The `#[pymodule]` procedural macro attribute takes care of exporting the initialization function of your 
+module to Python. It can take as an argument the name of your module, which must be the name of the `.so`
+or `.pyd` file; the default is the Rust function's name.
 
-If the name of the module (the default being the function name) does not match the name of the `.so` or `.pyd` file, you will get an import error in Python with the following message:
+If the name of the module (the default being the function name) does not match the name of the `.so` or
+`.pyd` file, you will get an import error in Python with the following message:
 `ImportError: dynamic module does not define module export function (PyInit_name_of_your_module)`
 
-To import the module, either copy the shared library as described in [the README](https://github.com/PyO3/pyo3) or use a tool, e.g. `maturin develop` with [maturin](https://github.com/PyO3/maturin) or `python setup.py develop` with [setuptools-rust](https://github.com/PyO3/setuptools-rust).
+To import the module, either copy the shared library as described in [the README](https://github.com/PyO3/pyo3)
+or use a tool, e.g. `maturin develop` with [maturin](https://github.com/PyO3/maturin) or 
+`python setup.py develop` with [setuptools-rust](https://github.com/PyO3/setuptools-rust).
 
 ## Documentation
 
-The [Rust doc comments](https://doc.rust-lang.org/stable/book/first-edition/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/first-edition/comments.html) of the module
+initialization function will be applied automatically as the Python docstring of your module.
 
 ```python
 import rust2py
@@ -53,7 +59,8 @@ Which means that the above Python code will print `This module is implemented in
 
 ## Modules as objects
 
-In Python, modules are first class objects. This means that you can store them as values or add them to dicts or other modules:
+In Python, modules are first class objects. This means that you can store them as values or add them to
+dicts or other modules:
 
 ```rust
 use pyo3::prelude::*;
@@ -65,15 +72,16 @@ fn subfunction() -> String {
     "Subfunction".to_string()
 }
 
-#[pymodule]
-fn submodule(_py: Python, module: &PyModule) -> PyResult<()> {
-    module.add_wrapped(wrap_pyfunction!(subfunction))?;
+fn init_submodule(module: &PyModule) -> PyResult<()> {
+    module.add_function(wrap_pyfunction!(subfunction))?;
     Ok(())
 }
 
 #[pymodule]
-fn supermodule(_py: Python, module: &PyModule) -> PyResult<()> {
-    module.add_wrapped(wrap_pymodule!(submodule))?;
+fn supermodule(py: Python, module: &PyModule) -> PyResult<()> {
+    let submod = PyModule::new(py, "submodule")?;
+    init_submodule(submod)?;
+    module.add_submodule(submod)?;
     Ok(())
 }
 
@@ -86,3 +94,5 @@ fn supermodule(_py: Python, module: &PyModule) -> PyResult<()> {
 ```
 
 This way, you can create a module hierarchy within a single extension module.
+
+It is not necessary to add `#[pymodule]` on nested modules, this is only required on the top-level module.

guide/src/trait_bounds.md

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