diff --git a/guide/src/class.md b/guide/src/class.md index d8aab528..ab602535 100644 --- a/guide/src/class.md +++ b/guide/src/class.md @@ -82,7 +82,7 @@ attribute. Only python `__new__` method can be specified, `__init__` is not avai # debug: bool, # token: PyToken, # } - +# #[py::methods] impl MyClass { @@ -123,7 +123,7 @@ with value of custom class struct. Subclass must call parent's `__new__` method. # #![feature(proc_macro, specialization, const_fn)] # extern crate pyo3; # use pyo3::prelude::*; - +# #[py::class] struct BaseClass { val1: usize, @@ -179,10 +179,9 @@ attributes. i.e. # #[py::class] # struct MyClass { # num: i32, -# debug: bool, # token: PyToken, # } - +# #[py::methods] impl MyClass { @@ -207,10 +206,9 @@ rust's special keywords like `type`. # #[py::class] # struct MyClass { # num: i32, -# debug: bool, # token: PyToken, # } - +# #[py::methods] impl MyClass { @@ -239,10 +237,9 @@ If parameter is specified, it is used and property name. i.e. # #[py::class] # struct MyClass { # num: i32, -# debug: bool, # token: PyToken, # } - +# #[py::methods] impl MyClass { @@ -290,10 +287,9 @@ class method static methods, etc. # #[py::class] # struct MyClass { # num: i32, -# debug: bool, # token: PyToken, # } - +# #[py::methods] impl MyClass { @@ -454,7 +450,7 @@ Example: # debug: bool, # token: PyToken, # } - +# #[py::methods] impl MyClass { #[args(arg1=true, args="*", arg2=10, kwargs="**")] diff --git a/guide/src/conversions.md b/guide/src/conversions.md index 9af722ae..068b99f9 100644 --- a/guide/src/conversions.md +++ b/guide/src/conversions.md @@ -4,7 +4,7 @@ ## `ToPyObject` and `IntoPyObject` trait -[`ToPyObject`][ToPyObject] trait is a conversion trait that allows various objects to be converted into [`PyObject`][PyObject]. [`IntoPyObject`][IntoPyObject] serves the same purpose except it consumes `self`. +[`ToPyObject`] trait is a conversion trait that allows various objects to be converted into [`PyObject`][PyObject]. [`IntoPyObject`][IntoPyObject] serves the same purpose except it consumes `self`. ## `IntoPyTuple` trait @@ -14,7 +14,6 @@ For example, [`IntoPyTuple`][IntoPyTuple] trait is implemented for `()` so that ```rust extern crate pyo3; - use pyo3::{Python, IntoPyTuple}; fn main() { @@ -39,66 +38,95 @@ Both methods accept `args` and `kwargs` arguments. `args` argument is generate o [`IntoPyTuple`][IntoPyTuple] trait. So args could be `PyTuple` instance or rust tuple with up to 10 elements. Or `NoArgs` object which represents empty tuple object. -```rust,ignore +```rust extern crate pyo3; - use pyo3::prelude::*; +# struct SomeObject; +# +# impl SomeObject { +# fn new(py: Python) -> PyObject { +# let builtins = py.import("builtins").unwrap(); +# let print = builtins.get("print").unwrap(); +# print.to_object(py) +# } +# } +# fn main() { + # let arg1 = "arg1"; + # let arg2 = "arg2"; + # let arg3 = "arg3"; + let gil = Python::acquire_gil(); let py = gil.python(); - - let obj = SomeObject::new(); - + + let obj = SomeObject::new(py); + // call object without empty arguments - obj.call(NoArgs, NoArg); - + obj.call0(py); + // call object with PyTuple let args = PyTuple::new(py, &[arg1, arg2, arg3]); - obj.call(args, NoArg); + obj.call1(py, args); // pass arguments as rust tuple let args = (arg1, arg2, arg3); - obj.call(args, NoArg); + obj.call1(py, args); } ``` `kwargs` argument is generate over [`IntoPyDictPointer`][IntoPyDictPointer] trait. `HashMap` or `BTreeMap` could be used as keyword arguments. rust tuple with up to 10 elements where each element is tuple with size 2 -could be used as kwargs as well. Or `NoArgs` object can be used to indicate that +could be used as kwargs as well. Or `NoArgs` object can be used to indicate that no keywords arguments are provided. -```rust,ignore +```rust extern crate pyo3; use pyo3::prelude::*; +# use std::collections::HashMap; +# struct SomeObject; +# +# impl SomeObject { +# fn new(py: Python) -> PyObject { +# let builtins = py.import("builtins").unwrap(); +# let print = builtins.get("print").unwrap(); +# print.to_object(py) +# } +# } +# fn main() { + # let key1 = "key1"; + # let val1 = 1; + # let key2 = "key2"; + # let val2 = 2; + let gil = Python::acquire_gil(); let py = gil.python(); - - let obj = SomeObject::new(); - + + let obj = SomeObject::new(py); + // call object with PyDict let kwargs = PyDict::new(py); - kwargs.set_item(key, value); - obj.call(NoArg, kwargs); + kwargs.set_item(key1, val1); + obj.call(py, NoArgs, kwargs); // pass arguments as rust tuple - let kwargs = ((key1, val1), (key2, val2), (key3, val3)); - obj.call(args, kwargs); + let kwargs = ((key1, val1), (key2, val2)); + obj.call(py, NoArgs, kwargs); // pass arguments as HashMap - let mut kwargs = HashMap::::new(); - kwargs.insert(1, 1); - obj.call(args, kwargs); + let mut kwargs = HashMap::<&str, i32>::new(); + kwargs.insert(key1, 1); + obj.call(py, NoArgs, kwargs); } ``` TODO -[ToPyObject]: https://pyo3.github.io/pyo3/pyo3/trait.ToPyObject.html +[`ToPyObject`]: https://pyo3.github.io/pyo3/pyo3/trait.ToPyObject.html [IntoPyObject]: https://pyo3.github.io/pyo3/pyo3/trait.IntoPyObject.html [PyObject]: https://pyo3.github.io/pyo3/pyo3/struct.PyObject.html [IntoPyTuple]: https://pyo3.github.io/pyo3/pyo3/trait.IntoPyTuple.html diff --git a/guide/src/exception.md b/guide/src/exception.md index 0e7c6264..637ddfb5 100644 --- a/guide/src/exception.md +++ b/guide/src/exception.md @@ -66,7 +66,7 @@ have rust type as well. # extern crate pyo3; # use pyo3::prelude::*; # fn check_for_error() -> bool {false} - +# fn my_func(arg: PyObject) -> PyResult<()> { if check_for_error() { Err(exc::ValueError::new("argument is wrong")) @@ -100,8 +100,15 @@ fn main() { To check the type of an exception, you can simply do: -```rust,ignore -let ret = py.is_instance::(&err.instance(py)).expect("Error calling is_instance"); +```rust +# extern crate pyo3; +# use pyo3::prelude::*; +# fn main() { +# let gil = Python::acquire_gil(); +# let py = gil.python(); +# let err = exc::TypeError::new(NoArgs); +err.is_instance::(py); +# } ``` ## Handle Rust Error @@ -124,6 +131,7 @@ trait can be implemented. In that case actual exception arguments creation get d until `Python` object is available. ```rust,ignore +#![feature(proc_macro, specialization)] extern crate pyo3; use std::net::TcpListener;