Merge master into the abi3 branch to resolve conflicts

guide/src/function.md

@@ -173,15 +173,31 @@ Type:      builtin_function_or_method
 
 ## Closures
 
-Currently, there are no conversions between `Fn`s in Rust and callables in Python. This would definitely be possible and very useful, so contributions are welcome. In the meantime, you can do the following:
+Currently, there are no conversions between `Fn`s in Rust and callables in Python. This would
+definitely be possible and very useful, so contributions are welcome. In the meantime, you can do
+the following:
 
 ### Calling Python functions in Rust
 
-You can use [`PyAny::is_callable`] to check if you have a callable object. `is_callable` will return `true` for functions (including lambdas), methods and objects with a `__call__` method. You can call the object with [`PyAny::call`] with the args as first parameter and the kwargs (or `None`) as second parameter. There are also [`PyAny::call0`] with no args and [`PyAny::call1`] with only positional args.
+You can pass Python `def`'d functions and built-in functions to Rust functions `[PyFunction]`
+corresponds to regular Python functions while `[PyCFunction]` describes built-ins such as
+`repr()`.
+
+You can also use [`PyAny::is_callable`] to check if you have a callable object. `is_callable` will 
+return `true` for functions (including lambdas), methods and objects with a `__call__` method. 
+You can call the object with [`PyAny::call`] with the args as first parameter and the kwargs 
+(or `None`) as second parameter. There are also [`PyAny::call0`] with no args and [`PyAny::call1`]
+with only positional args.
 
 ### Calling Rust functions in Python
 
-If you have a static function, you can expose it with `#[pyfunction]` and use [`wrap_pyfunction!`] to get the corresponding [`PyObject`]. For dynamic functions, e.g. lambdas and functions that were passed as arguments, you must put them in some kind of owned container, e.g. a `Box`. (A long-term solution will be a special container similar to wasm-bindgen's `Closure`). You can then use a `#[pyclass]` struct with that container as a field as a way to pass the function over the FFI barrier. You can even make that class callable with `__call__` so it looks like a function in Python code.
+If you have a static function, you can expose it with `#[pyfunction]` and use [`wrap_pyfunction!`]
+to get the corresponding [`PyCFunction`]. For dynamic functions, e.g. lambdas and functions that
+were passed as arguments, you must put them in some kind of owned container, e.g. a `Box`.
+(A long-term solution will be a special container similar to wasm-bindgen's `Closure`). You can
+then use a `#[pyclass]` struct with that container as a field as a way to pass the function over
+the FFI barrier. You can even make that class callable with `__call__` so it looks like a function
+in Python code.
 
 [`PyAny::is_callable`]: https://docs.rs/pyo3/latest/pyo3/struct.PyAny.html#tymethod.is_callable
 [`PyAny::call`]: https://docs.rs/pyo3/latest/pyo3/struct.PyAny.html#tymethod.call
@@ -233,3 +249,15 @@ fn module_with_fn(py: Python, m: &PyModule) -> PyResult<()> {
 
 # fn main() {}
 ```
+
+## Accessing the FFI functions
+
+In order to make Rust functions callable from Python, PyO3 generates a 
+`extern "C" Fn(slf: *mut PyObject, args: *mut PyObject, kwargs: *mut PyObject) -> *mut Pyobject`
+function and embeds the call to the Rust function inside this FFI-wrapper function. This
+wrapper handles extraction of the regular arguments and the keyword arguments from the input
+`PyObjects`. Since this function is not user-defined but required to build a `PyCFunction`, PyO3
+offers the `raw_pycfunction!()` macro to get the identifier of this generated wrapper.
+
+The `wrap_pyfunction` macro can be used to directly get a `PyCFunction` given a
+`#[pyfunction]` and a `PyModule`: `wrap_pyfunction!(rust_fun, module)`.

src/lib.rs

@@ -221,6 +221,25 @@ macro_rules! wrap_pyfunction {
 /// Returns the function that is called in the C-FFI.
 ///
 /// Use this together with `#[pyfunction]` and [types::PyCFunction].
+/// ```
+/// use pyo3::prelude::*;
+/// use pyo3::types::PyCFunction;
+/// use pyo3::raw_pycfunction;
+///
+/// #[pyfunction]
+/// fn some_fun() -> PyResult<()> {
+///     Ok(())
+/// }
+///
+/// #[pymodule]
+/// fn module(_py: Python, module: &PyModule) -> PyResult<()> {
+///     let ffi_wrapper_fun = raw_pycfunction!(some_fun);
+///     let docs = "Some documentation string with null-termination\0";
+///     let py_cfunction =
+///         PyCFunction::new_with_keywords(ffi_wrapper_fun, "function_name", docs, module.into())?;
+///     module.add_function(py_cfunction)
+/// }
+/// ```
 #[macro_export]
 macro_rules! raw_pycfunction {
     ($function_name: ident) => {{

src/types/function.rs

@@ -13,6 +13,8 @@ pyobject_native_var_type!(PyCFunction, ffi::PyCFunction_Type, ffi::PyCFunction_C
 
 impl PyCFunction {
     /// Create a new built-in function with keywords.
+    ///
+    /// See [raw_pycfunction] for documentation on how to get the `fun` argument.
     pub fn new_with_keywords<'a>(
         fun: ffi::PyCFunctionWithKeywords,
         name: &str,