luxolus/pyo3
2
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Make tons of small fixes in the guide

Browse source 
- spelling/grammar
- update docs.rs links and Cargo.toml examples to 0.6.0
- fix a few factual mistakes I found in the process
This commit is contained in:
Georg Brandl 2019-04-17 11:35:29 +02:00
parent 74600f5f05
commit b289a75c16
11 changed files with 207 additions and 200 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
guide/src/advanced.md
View file

@ -2,13 +2,13 @@
## ffi
PyO3 exposes much of python's C api through the `ffi`.
PyO3 exposes much of Python's C API through the `ffi` module.
The C api is naturally unsafe and requires you to manage reference counts, errors and specific invariants yourself. Please refer to the [C API Reference Manual](https://docs.python.org/3/c-api/) and [The Rustonomicon](https://doc.rust-lang.org/nightly/nomicon/ffi.html) before using any function from that api.
The C API is naturally unsafe and requires you to manage reference counts, errors and specific invariants yourself. Please refer to the [C API Reference Manual](https://docs.python.org/3/c-api/) and [The Rustonomicon](https://doc.rust-lang.org/nightly/nomicon/ffi.html) before using any function from that API.
## Testing
Currently, [#341](https://github.com/PyO3/pyo3/issues/341) causes `cargo test` to fail with weird linking errors when the `extension-module` feature is activated. For nnow you can work around this by making the `extension-module` feature optional and running the tests with `cargo test --no-default-features`:
Currently, [#341](https://github.com/PyO3/pyo3/issues/341) causes `cargo test` to fail with weird linking errors when the `extension-module` feature is activated. For now you can work around this by making the `extension-module` feature optional and running the tests with `cargo test --no-default-features`:
```toml
[dependencies.pyo3]

10
guide/src/building_and_distribution.md
View file

@ -2,7 +2,7 @@
## Python version
PyO3 uses a build script to determine the python version and set the correct linker arguments. By default it uses the `python3` executable. You can override the python interpreter by setting `PYTHON_SYS_EXECUTABLE`, e.g., `PYTHON_SYS_EXECUTABLE=python3.6`.
PyO3 uses a build script to determine the Python version and set the correct linker arguments. By default it uses the `python3` executable. You can override the Python interpreter by setting `PYTHON_SYS_EXECUTABLE`, e.g., `PYTHON_SYS_EXECUTABLE=python3.6`.
## Linking
@ -32,11 +32,11 @@ my_main_crate = { path = "..", default-features = false }
pyo3 = "0.6"
```
On linux/mac you might have to change `LD_LIBRARY_PATH` to include libpython, while on windows you might need to set `LIB` to include `pythonxy.lib` (where x and y are major and minor version), which is normally either in the `libs` or `Lib` folder of a python installation.
On Linux/macOS you might have to change `LD_LIBRARY_PATH` to include libpython, while on windows you might need to set `LIB` to include `pythonxy.lib` (where x and y are major and minor version), which is normally either in the `libs` or `Lib` folder of a Python installation.
## Distribution
There are two ways to distribute your module as python package: The old [setuptools-rust](https://github.com/PyO3/setuptools-rust) and the new [pyo3-pack](https://github.com/pyo3/pyo3-pack). setuptools-rust needs some configuration files (`setup.py`, `MANIFEST.in`, `build-wheels.sh`, etc.) and external tools (docker, twine). pyo3-pack doesn't need any configuration files. It can not yet build sdist though ([pyo3/pyo3-pack#2](https://github.com/PyO3/pyo3-pack/issues/2)).
There are two ways to distribute your module as a Python package: the old, [setuptools-rust](https://github.com/PyO3/setuptools-rust), and the new, [pyo3-pack](https://github.com/pyo3/pyo3-pack). setuptools-rust needs some configuration files (`setup.py`, `MANIFEST.in`, `build-wheels.sh`, etc.) and external tools (docker, twine). pyo3-pack doesn't need any configuration files. It can not yet build sdist though ([pyo3/pyo3-pack#2](https://github.com/PyO3/pyo3-pack/issues/2)).
## Cross Compiling
@ -49,9 +49,9 @@ Cross compiling PyO3 modules is relatively straightforward and requires a few pi
See https://github.com/japaric/rust-cross for a primer on cross compiling Rust in general.
After you've obtained the above, you can build a cross compiled Pyo3 module by setting a few extra environment variables:
After you've obtained the above, you can build a cross compiled PyO3 module by setting a few extra environment variables:
* `PYO3_CROSS_INCLUDE_DIR`: This variable must be set to the directory containing the headers for the target's python interpreter.
* `PYO3_CROSS_INCLUDE_DIR`: This variable must be set to the directory containing the headers for the target's Python interpreter.
* `PYO3_CROSS_LIB_DIR`: This variable must be set to the directory containing the target's libpython DSO.
An example might look like the following (assuming your target's sysroot is at `/home/pyo3/cross/sysroot` and that your target is `armv7`):

184
guide/src/class.md
View file

@ -1,8 +1,8 @@
# Python Class
# Python Classes
## Define new class
To define a custom python class, a rust struct needs to be annotated with the
To define a custom Python class, a Rust struct needs to be annotated with the
`#[pyclass]` attribute.
```rust
@ -18,6 +18,7 @@ struct MyClass {
The above example generates implementations for `PyTypeInfo` and `PyTypeObject` for `MyClass`.
## Get Python objects from `pyclass`
You can use `pyclass`es like normal rust structs.
However, if instantiated normally, you can't treat `pyclass`es as Python objects.
@ -25,13 +26,14 @@ However, if instantiated normally, you can't treat `pyclass`es as Python objects
To get a Python object which includes `pyclass`, we have to use some special methods.
### `PyRef`
`PyRef` is a special reference, which ensures that the referred struct is a part of
a Python object, and you are also holding the GIL.
You can get an instance of `PyRef` by `PyRef::new`, which does 3 things:
1. Allocate a Python object in the Python heap
2. Copies the rust struct into the Python object
3. Returns a reference of it
1. Allocates a Python object in the Python heap
2. Copies the Rust struct into the Python object
3. Returns a reference to it
You can use `PyRef` just like `&T`, because it implements `Deref<Target=T>`.
```rust
@ -52,6 +54,7 @@ dict.set_item("obj", obj).unwrap();
```
### `PyRefMut`
`PyRefMut` is a mutable version of `PyRef`.
```rust
# use pyo3::prelude::*;
@ -67,7 +70,8 @@ obj.num = 5;
```
### `Py`
`Py` is a object wrapper which stores an object longer than the GIL lifetime.
`Py` is an object wrapper which stores an object longer than the GIL lifetime.
You can use it to avoid lifetime problems.
```rust
@ -88,25 +92,24 @@ assert_eq!(obj.as_ref(gil.python()).num, 1);
## Customizing the class
The `#[pyclass]` macro accepts following parameters:
The `#[pyclass]` macro accepts the following parameters:
* `name=XXX` - Set the class name shown in python code. By default struct name is used as a class name.
* `freelist=XXX` - `freelist` parameter add support of free allocation list to custom class.
* `name=XXX` - Set the class name shown in Python code. By default, the struct name is used as the class name.
* `freelist=XXX` - The `freelist` parameter adds support of free allocation list to custom class.
The performance improvement applies to types that are often created and deleted in a row,
so that they can benefit from a freelist. `XXX` is a number of items for free list.
* `gc` - Classes with the `gc` parameter
participate in python garbage collector. If a custom class contains references to other
python object that can be collected, the `PyGCProtocol` trait has to be implemented.
* `weakref` - adds support for python weak references
* `extends=BaseType` - use a custom base class. The base BaseType must implement `PyTypeInfo`.
* `subclass` - Allows Python classes to inherit from this class
* `dict` - adds `__dict__` support, the instances of this type have a dictionary containing instance variables.
so that they can benefit from a freelist. `XXX` is a number of items for the free list.
* `gc` - Classes with the `gc` parameter participate in Python garbage collection.
If a custom class contains references to other Python objects that can be collected, the `PyGCProtocol` trait has to be implemented.
* `weakref` - Adds support for Python weak references.
* `extends=BaseType` - Use a custom base class. The base `BaseType` must implement `PyTypeInfo`.
* `subclass` - Allows Python classes to inherit from this class.
* `dict` - Adds `__dict__` support, so that the instances of this type have a dictionary containing arbitrary instance variables.
## Constructor
By default it is not possible to create an instance of a custom class from python code.
To declare a constructor, you need to define a class method and annotate it with `#[new]`
attribute. Only the python `__new__` method can be specified, `__init__` is not available.
By default it is not possible to create an instance of a custom class from Python code.
To declare a constructor, you need to define a method and annotate it with the `#[new]`
attribute. Only Python's `__new__` method can be specified, `__init__` is not available.
```rust
# use pyo3::prelude::*;
@ -135,19 +138,19 @@ Rules for the `new` method:
* If no method marked with `#[new]` is declared, object instances can only be created
from Rust, but not from Python.
* The first parameter is the raw object and the custom `new` method must initialize the object
with an instance of the struct using `init` method. The type of the object may be the type object of
with an instance of the struct using the `init` method. The type of the object may be the type object of
a derived class declared in Python.
* The first parameter implicitly has type `&PyRawObject`.
* For details on `parameter-list`, see the documentation of `Method arguments` section.
* The return type must be `PyResult<T>` for some `T` that implements `IntoPyObject`. Usually, `T` will be `MyType`.
* The first parameter must have type `&PyRawObject`.
* For details on the parameter list, see the `Method arguments` section below.
* The return value must be `T` or `PyResult<T>` where `T` is ignored, so it can
be just `()` as in the example above.
## Inheritance
By default `PyObject` is used as default base class. To override default base class
`base` parameter for `class` needs to be used. Value is full path to base class.
`new` method accepts `PyRawObject` object. `obj` instance must be initialized
with value of custom class struct. Subclass must call parent's `new` method.
By default, `PyObject` is used as the base class. To override this default,
use the `extends` parameter for `pyclass` with the full path to the base class.
The `new` method of subclasses must call their parent's `new` method.
```rust,ignore
# use pyo3::prelude::*;
@ -161,7 +164,7 @@ struct BaseClass {
impl BaseClass {
#[new]
fn new(obj: &PyRawObject) {
obj.init(BaseClass{ val1: 10 });
obj.init(BaseClass { val1: 10 });
}
pub fn method(&self) -> PyResult<()> {
@ -178,7 +181,7 @@ struct SubClass {
impl SubClass {
#[new]
fn new(obj: &PyRawObject) {
obj.init(SubClass{ val2: 10 });
obj.init(SubClass { val2: 10 });
BaseClass::new(obj);
}
@ -188,15 +191,14 @@ impl SubClass {
}
```
`ObjectProtocol` trait provides `get_base()` method. It returns reference to instance of
base class.
The `ObjectProtocol` trait provides a `get_base()` method, which returns a reference
to the instance of the base struct.
## Object properties
Descriptor methods can be defined in
`#[pymethods]` `impl` block only and has to be annotated with `#[getter]` or `[setter]`
attributes. i.e.
Property descriptor methods can be defined in a `#[pymethods]` `impl` block only and have to be
annotated with `#[getter]` and `#[setter]` attributes. For example:
```rust
# use pyo3::prelude::*;
@ -215,12 +217,14 @@ impl MyClass {
}
```
Getter or setter function's name is used as property name by default. There are several
ways how to override name.
A getter or setter's function name is used as the property name by default. There are several
ways how to override the name.
If function name starts with `get_` or `set_` for getter or setter respectively.
Descriptor name becomes function name with prefix removed. This is useful in case of
rust's special keywords like `type`.
If a function name starts with `get_` or `set_` for getter or setter respectively,
the descriptor name becomes the function name with this prefix removed. This is also useful in case of
Rust keywords like `type`
([raw identifiers](https://doc.rust-lang.org/edition-guide/rust-2018/module-system/raw-identifiers.html)
can be used since Rust 2018).
```rust
# use pyo3::prelude::*;
@ -245,10 +249,10 @@ impl MyClass {
}
```
In this case property `num` is defined. And it is available from python code as `self.num`.
In this case, a property `num` is defined and available from Python code as `self.num`.
Also both `#[getter]` and `#[setter]` attributes accepts one parameter.
If this parameter is specified, it is used as a property name. i.e.
Both the `#[getter]` and `#[setter]` attributes accept one parameter.
If this parameter is specified, it is used as the property name, i.e.
```rust
# use pyo3::prelude::*;
@ -273,9 +277,10 @@ impl MyClass {
}
```
In this case the property `number` is defined and is available from python code as `self.number`.
In this case, the property `number` is defined and available from Python code as `self.number`.
For simple cases you can also define getters and setters in your Rust struct field definition, for example:
For simple cases where a member variable is just read and written with no side effects, you
can also declare getters and setters in your Rust struct field definition, for example:
```rust
# use pyo3::prelude::*;
@ -290,8 +295,8 @@ Then it is available from Python code as `self.num`.
## Instance methods
To define a python compatible method, `impl` block for struct has to be annotated with the
`#[pymethods]` attribute. PyO3 generates python compatible wrappers for all functions in this
To define a Python compatible method, an `impl` block for your struct has to be annotated with the
`#[pymethods]` attribute. PyO3 generates Python compatible wrappers for all functions in this
block with some variations, like descriptors, class method static methods, etc.
```rust
@ -315,11 +320,12 @@ impl MyClass {
}
```
Calls to this methods protected by `GIL`, `&self` or `&mut self` can be used.
The return type must be `PyResult<T>` for some `T` that implements `IntoPyObject`.
Calls to these methods are protected by the GIL, so both `&self` and `&mut self` can be used.
The return type must be `PyResult<T>` or `T` for some `T` that implements `IntoPyObject`;
the latter is allowed if the method cannot raise Python exceptions.
`Python` parameter can be specified as part of method signature, in this case `py` argument
get injected by method wrapper. i.e
A `Python` parameter can be specified as part of method signature, in this case the `py` argument
gets injected by the method wrapper, e.g.
```rust
# use pyo3::prelude::*;
@ -337,11 +343,11 @@ impl MyClass {
}
```
From python perspective `method2`, in above example, does not accept any arguments.
From the Python perspective, the `method2` in this example does not accept any arguments.
## Class methods
To specify a class method for a custom class, the method needs to be annotated
To create a class method for a custom class, the method needs to be annotated
with the `#[classmethod]` attribute.
```rust
@ -368,12 +374,12 @@ Declares a class method callable from Python.
This may be the type object of a derived class.
* The first parameter implicitly has type `&PyType`.
* For details on `parameter-list`, see the documentation of `Method arguments` section.
* The return type must be `PyResult<T>` for some `T` that implements `IntoPyObject`.
* The return type must be `PyResult<T>` or `T` for some `T` that implements `IntoPyObject`.
## Static methods
To specify a static method for a custom class, method needs to be annotated with
`#[staticmethod]` attribute. The return type must be `PyResult<T>` for some `T` that implements
To create a static method for a custom class, the method needs to be annotated with the
`#[staticmethod]` attribute. The return type must be `T` or `PyResult<T>` for some `T` that implements
`IntoPyObject`.
```rust
@ -393,10 +399,10 @@ impl MyClass {
}
```
## Callable object
## Callable objects
To specify a custom `__call__` method for a custom class, call methods need to be annotated with
the `#[call]` attribute. Arguments of the method are specified same as for instance method.
To specify a custom `__call__` method for a custom class, the method needs to be annotated with
the `#[call]` attribute. Arguments of the method are specified as for instance methods.
```rust
# use pyo3::prelude::*;
@ -420,23 +426,23 @@ impl MyClass {
## Method arguments
By default PyO3 uses function signatures to determine which arguments are required. Then it scans
incoming `args` parameter and then incoming `kwargs` parameter. If it can not find all required
By default, PyO3 uses function signatures to determine which arguments are required. Then it scans
the incoming `args` and `kwargs` parameters. If it can not find all required
parameters, it raises a `TypeError` exception. It is possible to override the default behavior
with `#[args(...)]` attribute. `args` attribute accepts a comma separated list of parameters in
form of `attr_name="default value"`. Each parameter has to match the method parameter by name.
with the `#[args(...)]` attribute. This attribute accepts a comma separated list of parameters in
the form of `attr_name="default value"`. Each parameter has to match the method parameter by name.
Each parameter could be one of following type:
Each parameter can be one of the following types:
* "\*": var arguments separator, each parameter defined after "*" is keyword only parameters.
corresponds to python's `def meth(*, arg1.., arg2=..)`
* args="\*": "args" is var args, corresponds to python's `def meth(*args)`. Type of `args`
* `"*"`: var arguments separator, each parameter defined after `"*"` is a keyword-only parameter.
Corresponds to python's `def meth(*, arg1.., arg2=..)`.
* `args="*"`: "args" is var args, corresponds to Python's `def meth(*args)`. Type of the `args`
parameter has to be `&PyTuple`.
* kwargs="\*\*": "kwargs" is keyword arguments, corresponds to python's `def meth(**kwargs)`.
Type of `kwargs` parameter has to be `Option<&PyDict>`.
* arg="Value": arguments with default value. corresponds to python's `def meth(arg=Value)`.
if `arg` argument is defined after var arguments it is treated as keyword argument.
Note that `Value` has to be valid rust code, PyO3 just inserts it into generated
* `kwargs="**"`: "kwargs" receives keyword arguments, corresponds to Python's `def meth(**kwargs)`.
The type of the `kwargs` parameter has to be `Option<&PyDict>`.
* `arg="Value"`: arguments with default value. Corresponds to Python's `def meth(arg=Value)`.
If the `arg` argument is defined after var arguments, it is treated as a keyword-only argument.
Note that `Value` has to be valid rust code, PyO3 just inserts it into the generated
code unmodified.
Example:
@ -464,22 +470,22 @@ impl MyClass {
Python's object model defines several protocols for different object behavior, like sequence,
mapping or number protocols. PyO3 defines separate traits for each of them. To provide specific
python object behavior you need to implement the specific trait for your struct. Important note,
each protocol implementation block has to be annotated with `#[pyproto]` attribute.
Python object behavior, you need to implement the specific trait for your struct. Important note,
each protocol implementation block has to be annotated with the `#[pyproto]` attribute.
### Basic object customization
[`PyObjectProtocol`](https://docs.rs/pyo3/0.7.0-alpha.1/class/basic/trait.PyObjectProtocol.html) trait provide several basic customizations.
The [`PyObjectProtocol`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/class/basic/trait.PyObjectProtocol.html) trait provides several basic customizations.
#### Attribute access
To customize object attribute access define following methods:
To customize object attribute access, define the following methods:
* `fn __getattr__(&self, name: FromPyObject) -> PyResult<impl IntoPyObject>`
* `fn __setattr__(&mut self, name: FromPyObject, value: FromPyObject) -> PyResult<()>`
* `fn __delattr__(&mut self, name: FromPyObject) -> PyResult<()>`
Each methods corresponds to python's `self.attr`, `self.attr = value` and `del self.attr` code.
Each method corresponds to Python's `self.attr`, `self.attr = value` and `del self.attr` code.
#### String Conversions
@ -520,14 +526,14 @@ Each methods corresponds to python's `self.attr`, `self.attr = value` and `del s
### Garbage Collector Integration
If your type owns references to other python objects, you will need to
If your type owns references to other Python objects, you will need to
integrate with Python's garbage collector so that the GC is aware of
those references.
To do this, implement [`PyGCProtocol`](https://docs.rs/pyo3/0.7.0-alpha.1/class/gc/trait.PyGCProtocol.html) trait for your struct.
To do this, implement the [`PyGCProtocol`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/class/gc/trait.PyGCProtocol.html) trait for your struct.
It includes two methods `__traverse__` and `__clear__`.
These correspond to the slots `tp_traverse` and `tp_clear` in the Python C API.
`__traverse__` must call `visit.call()` for each reference to another python object.
`__clear__` must clear out any mutable references to other python objects
`__traverse__` must call `visit.call()` for each reference to another Python object.
`__clear__` must clear out any mutable references to other Python objects
(thus breaking reference cycles). Immutable references do not have to be cleared,
as every cycle must contain at least one mutable reference.
Example:
@ -554,10 +560,10 @@ impl PyGCProtocol for ClassWithGCSupport {
fn __clear__(&mut self) {
if let Some(obj) = self.obj.take() {
// Release reference, this decrements ref counter.
let gil = GILGuard::acquire();
let py = gil.python();
py.release(obj);
// Release reference, this decrements ref counter.
let gil = GILGuard::acquire();
let py = gil.python();
py.release(obj);
}
}
}
@ -565,14 +571,14 @@ impl PyGCProtocol for ClassWithGCSupport {
Special protocol trait implementations have to be annotated with the `#[pyproto]` attribute.
It is also possible to enable GC for custom class using `gc` parameter for `class` annotation.
i.e. `#[pyclass(gc)]`. In that case instances of custom class participate in python garbage
collector, and it is possible to track them with `gc` module methods.
It is also possible to enable GC for custom class using the `gc` parameter of the `pyclass` attribute.
i.e. `#[pyclass(gc)]`. In that case instances of custom class participate in Python garbage
collection, and it is possible to track them with `gc` module methods.
### Iterator Types
Iterators can be defined using the
[`PyIterProtocol`](https://docs.rs/pyo3/0.7.0-alpha.1/class/iter/trait.PyIterProtocol.html) trait.
[`PyIterProtocol`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/class/iter/trait.PyIterProtocol.html) trait.
It includes two methods `__iter__` and `__next__`:
* `fn __iter__(slf: PyRefMut<Self>) -> PyResult<impl IntoPyObject>`
* `fn __next__(slf: PyRefMut<Self>) -> PyResult<Option<impl IntoPyObject>>`

35
guide/src/conversions.md
View file

@ -4,22 +4,23 @@ PyO3 provides some handy traits to convert between Python types and Rust types.
## `.extract()`
The easiest way to convert a python object to a rust value is using `.extract()?`.
The easiest way to convert a Python object to a Rust value is using `.extract()?`.
## `ToPyObject` and `IntoPyObject` trait
[`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 that it consumes `self`.
## `FromPyObject` and `RefFromPyObject` trait
## `*args` and `**kwargs` for python object call
There are several way how to pass positional and keyword arguments to python object call.
[`ObjectProtocol`][ObjectProtocol] trait
provides two methods:
There are several ways how to pass positional and keyword arguments to a Python object call.
The [`ObjectProtocol`][ObjectProtocol] trait provides two methods:
* `call` - call callable python object.
* `call_method` - call specific method on the object.
* `call` - call any callable Python object.
* `call_method` - call a specific method on the object, shorthand for `get_attr` then `call`.
Both methods accept `args` and `kwargs` arguments.
@ -57,8 +58,8 @@ fn main() {
}
```
`kwargs` can by `None` or `Some(&PyDict)`. You can use the
[`IntoPyDict`][IntoPyDict] trait to convert other dict-like containers, e.g. `HashMap`, `BTreeMap` as well as tuples with up to 10 elements and `Vec`s where each element is a two element tuple.
`kwargs` can be `None` or `Some(&PyDict)`. You can use the
[`IntoPyDict`][IntoPyDict] trait to convert other dict-like containers, e.g. `HashMap`, `BTreeMap` as well as tuples with up to 10 elements and `Vec`s where each element is a two-element tuple.
```rust
use pyo3::prelude::*;
@ -101,13 +102,13 @@ fn main() {
## `IntoPy<T>`
Many conversions in PyO3 can't use `std::convert::Into` because they need a gil token. That's why the `IntoPy<T>` trait offers an `into_py` methods that works just like `into` except for taking a `Python<'_>` as argument.
Many conversions in PyO3 can't use `std::convert::Into` because they need a GIL token. That's why the `IntoPy<T>` trait offers an `into_py` method that works just like `into`, except for taking a `Python<'_>` argument.
Eventually, traits such as `IntoPyObject` will be replaces by this trait and a `FromPy` trait will be added that will implement `IntoPy`, just like with `From` and `Into`.
Eventually, traits such as `IntoPyObject` will be replaced by this trait and a `FromPy` trait will be added that will implement `IntoPy`, just like with `From` and `Into`.
[`ToPyObject`]: https://docs.rs/pyo3/0.7.0-alpha.1/trait.ToPyObject.html
[IntoPyObject]: https://docs.rs/pyo3/0.7.0-alpha.1/trait.IntoPyObject.html
[PyObject]: https://docs.rs/pyo3/0.7.0-alpha.1/struct.PyObject.html
[PyTuple]: https://docs.rs/pyo3/0.7.0-alpha.1/struct.PyTuple.html
[ObjectProtocol]: https://docs.rs/pyo3/0.7.0-alpha.1/trait.ObjectProtocol.html
[IntoPyDict]: https://docs.rs/pyo3/0.7.0-alpha.1/trait.IntoPyDict.html
[`ToPyObject`]: https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/trait.ToPyObject.html
[IntoPyObject]: https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/trait.IntoPyObject.html
[PyObject]: https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/struct.PyObject.html
[PyTuple]: https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/types/struct.PyTuple.html
[ObjectProtocol]: https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/trait.ObjectProtocol.html
[IntoPyDict]: https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/types/trait.IntoPyDict.html

12
guide/src/debugging.md
View file

@ -2,7 +2,7 @@
## Macros
PyO3's attributes, `#[pyclass]`, `#[pymodule]`, etc. are [procedural macros](https://doc.rust-lang.org/unstable-book/language-features/proc-macro.html), which means that rewrite the source of the annotated item. You can view the generated source with the following command, which also expands a few other things:
PyO3's attributes (`#[pyclass]`, `#[pymodule]`, etc.) are [procedural macros](https://doc.rust-lang.org/reference/procedural-macros.html), which means that they rewrite the source of the annotated item. You can view the generated source with the following command, which also expands a few other things:
```bash
cargo rustc --profile=check -- -Z unstable-options --pretty=expanded > expanded.rs; rustfmt expanded.rs
@ -10,7 +10,7 @@ cargo rustc --profile=check -- -Z unstable-options --pretty=expanded > expanded.
(You might need to install [rustfmt](https://github.com/rust-lang-nursery/rustfmt) if you don't already have it.)
You can also debug classic `!`-macros by adding -Z trace-macros`:
You can also debug classic `!`-macros by adding `-Z trace-macros`:
```bash
cargo rustc --profile=check -- -Z unstable-options --pretty=expanded -Z trace-macros > expanded.rs; rustfmt expanded.rs
@ -22,13 +22,13 @@ See [cargo expand](https://github.com/dtolnay/cargo-expand) for a more elaborate
Valgrind is a tool to detect memory management bugs such as memory leaks.
You first need to install a debug build of python, otherwise valgrind won't produce usable results. In ubuntu there's e.g. a `python3-dbg` package.
You first need to install a debug build of Python, otherwise Valgrind won't produce usable results. In Ubuntu there's e.g. a `python3-dbg` package.
Activate an environment with the debug interpreter and recompile. If you're on linux, use `ldd` with the name of you're binary and check that you're linking e.g. `libpython3.6dm.so.1.0` instead of `libpython3.6m.so.1.0`.
Activate an environment with the debug interpreter and recompile. If you're on Linux, use `ldd` with the name of your binary and check that you're linking e.g. `libpython3.6dm.so.1.0` instead of `libpython3.6m.so.1.0`.
[Download the suppressions file for cpython](https://raw.githubusercontent.com/python/cpython/master/Misc/valgrind-python.supp).
Run valgrind with `valgrind --suppressions=valgrind-python.supp ./my-command --with-options`
Run Valgrind with `valgrind --suppressions=valgrind-python.supp ./my-command --with-options`
## Getting a stacktrace
@ -37,4 +37,4 @@ The best start to investigate a crash such as an segmentation fault is a backtra
* Link against a debug build of python as described in the previous chapter
* Run `gdb <my-binary>`
* Enter `r` to run
* After the crash occurred, enter `bt` or `bt full` to print the stacktrace
* After the crash occurred, enter `bt` or `bt full` to print the stacktrace

63
guide/src/exception.md
View file

@ -1,4 +1,4 @@
# Python Exception
# Python Exceptions
## Define a new exception
@ -35,7 +35,7 @@ fn main() {
## Raise an exception
To raise an exception, first you need to obtain an exception type and construct a new [`PyErr`](https://docs.rs/pyo3/0.7.0-alpha.1/struct.PyErr.html), then call [`PyErr::restore()`](https://docs.rs/pyo3/0.7.0-alpha.1/struct.PyErr.html#method.restore) method to write the exception back to the Python interpreter's global state.
To raise an exception, first you need to obtain an exception type and construct a new [`PyErr`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/struct.PyErr.html), then call the [`PyErr::restore()`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/struct.PyErr.html#method.restore) method to write the exception back to the Python interpreter's global state.
```rust
use pyo3::{Python, PyErr};
@ -50,16 +50,16 @@ fn main() {
}
```
If you already have a Python exception instance, you can simply call [`PyErr::from_instance()`](https://docs.rs/pyo3/0.7.0-alpha.1/struct.PyErr.html#method.from_instance).
If you already have a Python exception instance, you can simply call [`PyErr::from_instance()`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/struct.PyErr.html#method.from_instance).
```rust,ignore
PyErr::from_instance(py, err).restore(py);
```
If rust type exists for exception, then it is possible to use `new` method.
For example each standard exception defined in `exc` module
has corresponding rust type, exceptions defined by `create_exception!` and `import_exception!` macro
have rust type as well.
If a Rust type exists for the exception, then it is possible to use the `new` method.
For example, each standard exception defined in the `pyo3::exceptions` module
has a corresponding Rust type, exceptions defined by `create_exception!` and `import_exception!` macro
have Rust types as well.
```rust
# use pyo3::exceptions;
@ -76,8 +76,8 @@ fn my_func(arg: PyObject) -> PyResult<()> {
## Check exception type
Python has an [`isinstance`](https://docs.python.org/3/library/functions.html#isinstance) method to check object type,
in `PyO3` there is a [`Python::is_instance()`](https://docs.rs/pyo3/0.7.0-alpha.1/struct.Python.html#method.is_instance) method which does the same thing.
Python has an [`isinstance`](https://docs.python.org/3/library/functions.html#isinstance) method to check an object's type,
in PyO3 there is a [`Python::is_instance()`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/struct.Python.html#method.is_instance) method which does the same thing.
```rust
use pyo3::Python;
@ -93,7 +93,7 @@ fn main() {
}
```
[`Python::is_instance()`](https://docs.rs/pyo3/0.7.0-alpha.1/struct.Python.html#method.is_instance) calls the underlying [`PyType::is_instance`](https://docs.rs/pyo3/0.7.0-alpha.1/struct.PyType.html#method.is_instance) method to do the actual work.
[`Python::is_instance()`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/struct.Python.html#method.is_instance) calls the underlying [`PyType::is_instance`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/types/struct.PyType.html#method.is_instance) method to do the actual work.
To check the type of an exception, you can simply do:
@ -108,24 +108,25 @@ err.is_instance::<exceptions::TypeError>(py);
# }
```
## Handle Rust Error
## Handle Rust Errors
The vast majority of operations in this library will return [`PyResult<T>`](https://docs.rs/pyo3/0.7.0-alpha.1/type.PyResult.html).
The vast majority of operations in this library will return [`PyResult<T>`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/prelude/type.PyResult.html).
This is an alias for the type `Result<T, PyErr>`.
A [`PyErr`](https://docs.rs/pyo3/0.7.0-alpha.1/struct.PyErr.html) represents a Python exception.
A [`PyErr`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/struct.PyErr.html) represents a Python exception.
Errors within the PyO3 library are also exposed as Python exceptions.
PyO3 library handles python exception in two stages. During first stage `PyErr` instance get
created. At this stage python GIL is not required. During second stage, actual python
exception instance get crated and set to python interpreter.
The PyO3 library handles Python exceptions in two stages. During the first stage, a `PyErr` instance is
created. At this stage, holding Python's GIL is not required. During the second stage, an actual Python
exception instance is created and set active in the Python interpreter.
In simple case, for custom errors support implementation of `std::convert::From<T>` trait
for this custom error is enough. `PyErr::new` accepts arguments in form
of `ToPyObject + 'static`. In case if `'static` constraint can not be satisfied or
more complex arguments are required [`PyErrArgument`](https://docs.rs/pyo3/0.7.0-alpha.1/trait.PyErrArguments.html)
trait can be implemented. In that case actual exception arguments creation get delayed
until `Python` object is available.
In simple cases, for custom errors adding an implementation of `std::convert::From<T>` trait
for this custom error is enough. `PyErr::new` accepts an argument in the form
of `ToPyObject + 'static`. If the `'static` constraint can not be satisfied or
more complex arguments are required, the
[`PyErrArguments`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/trait.PyErrArguments.html)
trait can be implemented. In that case, actual exception argument creation is delayed
until a `Python` object is available.
```rust,ignore
use std::net::TcpListener;
@ -143,10 +144,10 @@ fn connect(s: String) -> PyResult<bool> {
}
```
The code snippet above will raise `OSError` in Python if `TcpListener::bind()` return an error.
The code snippet above will raise an `OSError` in Python if `TcpListener::bind()` returns an error.
`std::convert::From<T>` trait is implemented for most of the standard library's error
types so `try!` macro or `?` operator can be used.
The `std::convert::From<T>` trait is implemented for most of the Rust standard library's error
types so the `try!` macro or the `?` operator can be used.
```rust
use pyo3::prelude::*;
@ -156,13 +157,13 @@ fn parse_int(s: String) -> PyResult<usize> {
}
```
The code snippet above will raise `ValueError` in Python if `String::parse()` return an error.
The code snippet above will raise a `ValueError` in Python if `String::parse()` returns an error.
## Using exceptions defined in python code
It is possible to use exception defined in python code as native rust types.
`import_exception!` macro allows to import specific exception class and defined zst type
It is possible to use an exception defined in Python code as a native Rust type.
The `import_exception!` macro allows importing a specific exception class and defines a zero-sized Rust type
for that exception.
```rust
@ -180,10 +181,10 @@ fn tell(file: PyObject) -> PyResult<u64> {
match file.call_method0(py, "tell") {
Err(_) => Err(UnsupportedOperation::py_err("not supported: tell")),
Ok(x) => x.extract::<u64>(py),
}
}
}
```
[`exc`](https://docs.rs/pyo3/0.7.0-alpha.1/exc/index.html) defines exceptions for
several standard library modules.
[`pyo3::exceptions`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/exceptions/index.html)
defines exceptions for several standard library modules.

33
guide/src/function.md
View file

@ -1,7 +1,7 @@
# Python Function
# Python Functions
PyO3 supports two ways to define a function in python. Both require registering
the function to a [module](./module.md)
PyO3 supports two ways to define a free function in Python. Both require registering
the function to a [module](./module.md).
One way is defining the function in the module definition.
@ -15,7 +15,7 @@ fn rust2py(py: Python, m: &PyModule) -> PyResult<()> {
// 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(format!("{}", a + b))
}
Ok(())
@ -25,9 +25,7 @@ fn rust2py(py: Python, m: &PyModule) -> PyResult<()> {
```
The other is annotating a function with `#[pyfunction]` and then adding it
to the module using the `add_wrapped_to_module!` macro, which takes the module
as first parameter, the function name as second and an instance of `Python`
as third.
to the module using the `wrap_pyfunction!` macro.
```rust
use pyo3::prelude::*;
@ -51,13 +49,13 @@ fn module_with_functions(py: Python, m: &PyModule) -> PyResult<()> {
### Making the function signature available to Python
In order to make the function signature available to Python to be retrieved via
`inspect.signature`, simply make sure the first line of your doc-string is
formatted like in the example below. Please note that the new-line after the
`--` is mandatory. The `/` signifies the end of positional only arguments. This
`inspect.signature`, simply make sure the first line of your docstring is
formatted like in the example below. Please note that the newline after the
`--` is mandatory. The `/` signifies the end of positional-only arguments. This
is not a feature of this library in particular, but the general format used by
CPython for annotating signatures of built-in functions. Function signatures for
built-ins are new in Python 3 — in Python 2, it is simply considered to be part
of the doc-string.
built-ins are new in Python 3 — in Python 2, they are simply considered to be a
part of the docstring.
```rust
use pyo3::prelude::*;
@ -82,13 +80,12 @@ 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 a python function in rust
### Calling a Python function in Rust
You can use `ObjectProtocol::is_callable` to check if you got a callable, which is true for functions (including lambdas), methods and objects with a `__call__` method. You can call the object with `ObjectProtocol::call` with the args as first parameter and the kwargs (or `None`) as second parameter. There are also `ObjectProtocol::call0` with no args and `ObjectProtocol::call1` with only the args.
You can use `ObjectProtocol::is_callable` to check if you got a callable, which is true for functions (including lambdas), methods and objects with a `__call__` method. You can call the object with `ObjectProtocol::call` with the args as first parameter and the kwargs (or `None`) as second parameter. There are also `ObjectProtocol::call0` with no args and `ObjectProtocol::call1` with only the positional args.
### Calling rust `Fn`s 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. lambda and functions that were passed as arguments, you must put them in some kind of owned container, e.g. a box. (Long-Term a special container similar to wasm-bindgen's `Closure` should take care of that). You can than use a `#[pyclass]` struct with that container as 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.
### Calling Rust `Fn`s 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. lambda 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.

25
guide/src/get_started.md
View file

@ -1,6 +1,6 @@
# PyO3
[Rust](http://www.rust-lang.org/) bindings for [Python](https://www.python.org/). This includes running and interacting with python code from a rust binaries as well as writing native python modules.
[Rust](http://www.rust-lang.org/) bindings for [Python](https://www.python.org/). This includes running and interacting with Python code from a Rust binary, as well as writing native Python modules.
* User Guide: [stable](https://pyo3.rs) | [master](https://pyo3.rs/master)
@ -10,13 +10,13 @@ A comparison with rust-cpython can be found [in the guide](https://pyo3.rs/maste
## Usage
PyO3 supports python 3.5 and up. The minimum required rust version is 1.34.0-nightly 2019-02-06.
PyO3 supports Python 3.5 and up. The minimum required Rust version is 1.34.0-nightly 2019-02-06.
You can either write a native python module in rust or use python from a rust binary.
You can either write a native Python module in Rust, or use Python from a Rust binary.
On some OSs, you need some additional packages.
E.g. if you are on Ubuntu18.04, please run
E.g. if you are on Ubuntu 18.04, please run
```bash
sudo apt install python3-dev python-dev
@ -24,7 +24,7 @@ sudo apt install python3-dev python-dev
## Using rust from python
PyO3 can be used to generate a native python module.
PyO3 can be used to generate a native Python module.
**`Cargo.toml`:**
@ -63,7 +63,7 @@ fn string_sum(py: Python, m: &PyModule) -> PyResult<()> {
}
```
On windows and linux, you can build normally with `cargo build --release`. On macOS, you need to set additional linker arguments. One option is to compile with `cargo rustc --release -- -C link-arg=-undefined -C link-arg=dynamic_lookup`, the other is to create a `.cargo/config` with the following content:
On Windows and Linux, you can build normally with `cargo build --release`. On macOS, you need to set additional linker arguments. One option is to compile with `cargo rustc --release -- -C link-arg=-undefined -C link-arg=dynamic_lookup`, the other is to create a `.cargo/config` with the following content:
```toml
[target.x86_64-apple-darwin]
@ -73,20 +73,20 @@ rustflags = [
]
```
For developing, you can copy and rename the shared library from the target folder: On macOS, rename `libstring_sum.dylib` to `string_sum.so`, on windows `libstring_sum.dll` to `string_sum.pyd` and on linux `libstring_sum.so` to `string_sum.so`. Then open a python shell in the same folder and you'll be able to `import string_sum`.
For developing, you can copy and rename the shared library from the target folder: On macOS, rename `libstring_sum.dylib` to `string_sum.so`, on windows `libstring_sum.dll` to `string_sum.pyd` and on linux `libstring_sum.so` to `string_sum.so`. Then open a Python shell in the same folder and you'll be able to `import string_sum`.
To build, test and publish your crate as python module, you can use [pyo3-pack](https://github.com/PyO3/pyo3-pack) or [setuptools-rust](https://github.com/PyO3/setuptools-rust). You can find an example for setuptools-rust in [examples/word-count](examples/word-count), while pyo3-pack should work on your crate without any configuration.
To build, test and publish your crate as a Python module, you can use [pyo3-pack](https://github.com/PyO3/pyo3-pack) or [setuptools-rust](https://github.com/PyO3/setuptools-rust). You can find an example for setuptools-rust in [examples/word-count](examples/word-count), while pyo3-pack should work on your crate without any configuration.
## Using python from rust
## Using Python from Rust
Add `pyo3` this to your `Cargo.toml`:
Add `pyo3` to your `Cargo.toml` like this:
```toml
[dependencies]
pyo3 = "0.6"
```
Example program displaying the value of `sys.version`:
Example program displaying the value of `sys.version` and the current user name:
```rust
use pyo3::prelude::*;
@ -99,7 +99,8 @@ fn main() -> PyResult<()> {
let version: String = sys.get("version")?.extract()?;
let locals = [("os", py.import("os")?)].into_py_dict(py);
let user: String = py.eval("os.getenv('USER') or os.getenv('USERNAME')", None, Some(&locals))?.extract()?;
let user: String = py.eval("os.getenv('USER') or os.getenv('USERNAME')",
None, Some(&locals))?.extract()?;
println!("Hello {}, I'm Python {}", user, version);
Ok(())

10
guide/src/module.md
View file

@ -1,4 +1,4 @@
# Python Module
# Python Modules
As shown in the Getting Started chapter, you can create a module as follows:
@ -11,7 +11,7 @@ use pyo3::prelude::*;
#[pymodule]
fn rust2py(py: Python, m: &PyModule) -> PyResult<()> {
// PyO3 aware function. All of our python interface could be declared in a separate module.
// PyO3 aware function. All of our python interfaces could be declared in a separate module.
// 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")]
@ -31,7 +31,7 @@ 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 takes one argument as the name of your module, which must be the name of the `.so` or `.pyd` file.
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.
To import the module, either copy the shared library as described in [Get Started](./overview.md) or use a tool, e.g. `pyo3-pack develop` with [pyo3-pack](https://github.com/PyO3/pyo3-pack) or `python setup.py develop` with [setuptools-rust](https://github.com/PyO3/setuptools-rust).
@ -49,7 +49,7 @@ 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 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::*;
@ -82,3 +82,5 @@ fn nested_call() {
py.run("assert supermodule.submodule.subfunction() == 'Subfunction'", None, Some(&ctx)).unwrap();
}
```
This way, you can create a module hierarchy within a single extension module.

15
guide/src/parallelism.md
View file

@ -1,10 +1,10 @@
# Parallelism
CPython has an infamous GIL(Global Interpreter Lock) prevents developers
getting true parallelism. With PyO3 you can release GIL when executing
Rust code to achieve true parallelism.
CPython has the infamous GIL (Global Interpreter Lock), which prevents developers
from getting true parallelism when running pure Python code. With PyO3, you can
release the GIL when executing Rust code to achieve true parallelism.
The [`Python::allow_threads`](https://docs.rs/pyo3/0.7.0-alpha.1/struct.Python.html#method.allow_threads)
The [`Python::allow_threads`](https://docs.rs/pyo3/0.7.0-alpha.1/pyo3/struct.Python.html#method.allow_threads)
method temporarily releases the GIL, thus allowing other Python threads to run.
```rust,ignore
@ -14,7 +14,7 @@ impl Python {
```
Let's take a look at our [word-count](https://github.com/PyO3/pyo3/blob/master/examples/word-count/src/lib.rs) example,
we have a `wc_parallel` function utilize the [rayon](https://github.com/nikomatsakis/rayon) crate to count words in parallel.
where we have a `wc_parallel` function that utilizes the [rayon](https://github.com/nikomatsakis/rayon) crate to count words in parallel.
```rust,ignore
fn wc_parallel(lines: &str, search: &str) -> i32 {
@ -24,8 +24,7 @@ fn wc_parallel(lines: &str, search: &str) -> i32 {
}
```
Then in the Python bridge, we have a function `search` exposed to Python runtime which calls `wc_parallel` inside
`Python::allow_threads` method to enable true parallelism:
Then in the Python bridge, we have a function `search` exposed to the Python runtime which calls `wc_parallel` inside a closure passed to `Python::allow_threads` to enable true parallelism:
```rust,ignore
#[pymodule]
@ -54,7 +53,7 @@ We are using `pytest-benchmark` to benchmark three word count functions:
2. [Rust sequential version](https://github.com/PyO3/pyo3/blob/master/examples/word-count/src/lib.rs#L64)
3. [Rust parallel version](https://github.com/PyO3/pyo3/blob/master/examples/word-count/src/lib.rs#L54)
Benchmark script can be found [here](https://github.com/PyO3/pyo3/blob/master/examples/word-count/tests/test_word_count.py),
The benchmark script can be found [here](https://github.com/PyO3/pyo3/blob/master/examples/word-count/tests/test_word_count.py),
then we can run `pytest tests` to benchmark them.
On MacBook Pro (Retina, 15-inch, Mid 2015) the benchmark gives:

14
guide/src/rust_cpython.md
View file

@ -1,12 +1,12 @@
# Appendix: PyO3 and rust-cpython
PyO3 began as fork of [rust-cpython](https://github.com/dgrunwald/rust-cpython) when rust-cpython wasn't maintained. Over the time pyo3 has become fundamentally different from rust-cpython.
PyO3 began as fork of [rust-cpython](https://github.com/dgrunwald/rust-cpython) when rust-cpython wasn't maintained. Over the time PyO3 has become fundamentally different from rust-cpython.
This chapter is based on the discussion in [PyO3/pyo3#55](https://github.com/PyO3/pyo3/issues/55).
## Macros
While rust-cpython has a macro based dsl for declaring modules and classes, PyO3 use proc macros and specialization. PyO3 also doesn't change your struct and functions so you can still use them as normal rust functions. The disadvantage is that proc macros and specialization currently only work on nightly.
While rust-cpython has a macro based dsl for declaring modules and classes, PyO3 uses proc macros and specialization. PyO3 also doesn't change your struct and functions so you can still use them as normal Rust functions. The disadvantage is that specialization currently only works on nightly.
**rust-cpython**
@ -52,9 +52,9 @@ impl MyClass {
## Ownership and lifetimes
All objects are owned by PyO3 library and all apis available with references, while in rust-cpython, you own python objects.
All objects are owned by the PyO3 library and all APIs available with references, while in rust-cpython, you own python objects.
Here is example of PyList api:
Here is an example of the PyList API:
**rust-cpython**
@ -78,10 +78,10 @@ impl PyList {
}
```
Because PyO3 allows only references to python object, all reference have the Gil lifetime. So the python object is not required, and it is safe to have functions like `fn py<'p>(&'p self) -> Python<'p> {}`.
Because PyO3 allows only references to Python objects, all references have the GIL lifetime. So the owned Python object is not required, and it is safe to have functions like `fn py<'p>(&'p self) -> Python<'p> {}`.
## Error handling
rust-cpython requires a `Python` parameter for `PyErr`, so error handling ergonomics is pretty bad. It is not possible to use `?` with rust errors.
rust-cpython requires a `Python` parameter for constructing a `PyErr`, so error handling ergonomics is pretty bad. It is not possible to use `?` with Rust errors.
PyO3 on other hand does not require `Python` for `PyErr`, it is only required if you want to raise an exception in python with the `PyErr::restore()` method. Due to the `std::convert::From<Err> for PyErr` trait `?` is supported automatically.
PyO3 on other hand does not require `Python` for constructing a `PyErr`, it is only required if you want to raise an exception in Python with the `PyErr::restore()` method. Due to various `std::convert::From<E> for PyErr` implementations for Rust standard error types `E`, propagating `?` is supported automatically.