Merge pull request #154 from konstin/capybara

Relax return types and add functions

guide/src/function.md

@@ -1,3 +1,60 @@
 # Python Function
 
-TODO
+Pyo3 supports two ways to define a function in python. Both require registering
+the function to a [module](./module.md)
+
+One way is defining the function in the module definition.
+
+```rust
+#![feature(proc_macro)]
+
+extern crate pyo3;
+use pyo3::{py, PyResult, Python, PyModule};
+use pyo3::py::modinit as pymodinit;
+
+#[pymodinit(rust2py)]
+fn init_mod(py: Python, m: &PyModule) -> PyResult<()> {
+
+    // Note that the `#[pyfn()]` annotation automatically converts the arguments from
+    // Python objects to Rust values; and the Rust return value back into a Python object.
+    #[pyfn(m, "sum_as_string")]
+    fn sum_as_string_py(_py: Python, a:i64, b:i64) -> PyResult<String> {
+       Ok(format!("{}", a + b).to_string())
+    }
+
+    Ok(())
+}
+
+# fn main() {}
+```
+
+The other is annotating a function with `#[py::function]` and then adding it
+to the module using the `add_function_to_module!` macro, which takes the module
+as first parameter, the function name as second and an instance of `Python`
+as third.
+
+```rust
+#![feature(proc_macro, concat_idents)]
+
+#[macro_use]
+extern crate pyo3;
+use pyo3::{py, PyResult, Python, PyModule};
+
+use pyo3::py::function as pyfunction;
+use pyo3::py::modinit as pymodinit;
+
+#[pyfunction]
+fn double(x: usize) -> usize {
+    x * 2
+}
+
+#[pymodinit(module_with_functions)]
+fn init_mod(py: Python, m: &PyModule) -> PyResult<()> {
+    m.add_function(wrap_function!(double)).unwrap();
+
+    Ok(())
+}
+
+# fn main() {}
+```
+

pyo3-derive-backend/src/args.rs

@@ -1,7 +1,7 @@
 // Copyright (c) 2017-present PyO3 Project and Contributors
 use syn;
 
-#[derive(Debug, PartialEq)]
+#[derive(Debug, Clone, PartialEq)]
 pub enum Argument {
     VarArgsSeparator,
     VarArgs(String),

pyo3-derive-backend/src/method.rs

@@ -1,13 +1,12 @@
 // Copyright (c) 2017-present PyO3 Project and Contributors
 
-use syn;
-use quote::{Tokens, Ident};
-
 use args::{Argument, parse_arguments};
+use quote::{Ident, Tokens};
+use syn;
 use utils::for_err_msg;
 
 
-#[derive(Clone, Debug)]
+#[derive(Clone, PartialEq, Debug)]
 pub struct FnArg<'a> {
     pub name: &'a syn::Ident,
     pub mode: &'a syn::BindingMode,
@@ -29,15 +28,22 @@ pub enum FnType {
     FnStatic,
 }
 
+#[derive(Clone, PartialEq, Debug)]
 pub struct FnSpec<'a> {
     pub tp: FnType,
     pub attrs: Vec<Argument>,
     pub args: Vec<FnArg<'a>>,
     pub output: syn::Ty,
 }
 
-impl<'a> FnSpec<'a> {
+pub fn get_return_info(output: &syn::FunctionRetTy) -> syn::Ty {
+    match output {
+        &syn::FunctionRetTy::Default => syn::Ty::Tup(vec![]),
+        &syn::FunctionRetTy::Ty(ref ty) => ty.clone()
+    }
+}
 
+impl<'a> FnSpec<'a> {
     /// Parser function signature and function attributes
     pub fn parse(name: &'a syn::Ident,
                  sig: &'a syn::MethodSig,
@@ -96,10 +102,7 @@ impl<'a> FnSpec<'a> {
             }
         }
 
-        let ty = match sig.decl.output {
-            syn::FunctionRetTy::Default => syn::Ty::Infer,
-            syn::FunctionRetTy::Ty(ref ty) => ty.clone()
-        };
+        let ty = get_return_info(&sig.decl.output);
 
         FnSpec {
             tp: fn_type,