Trait FromPyObject

pub trait FromPyObject<'a, 'py>: Sized {
    type Error: Into<PyErr>;

    // Required method
    fn extract(obj: Borrowed<'a, 'py, PyAny>) -> Result<Self, Self::Error>;
}

Available on crate feature tls only.

Expand description

Extract a type from a Python object.

Normal usage is through the extract methods on Bound, Borrowed and Py, which forward to this trait.

§Examples

use pyo3::prelude::*;
use pyo3::types::PyString;

Python::attach(|py| {
    // Calling `.extract()` on a `Bound` smart pointer
    let obj: Bound<'_, PyString> = PyString::new(py, "blah");
    let s: String = obj.extract()?;

    // Calling `.extract(py)` on a `Py` smart pointer
    let obj: Py<PyString> = obj.unbind();
    let s: String = obj.extract(py)?;
})

Note: Depending on the Python version and implementation, some FromPyObject implementations may produce a result that borrows into the Python type. This is described by the input lifetime 'a of obj.

Types that must not borrow from the input can use FromPyObjectOwned as a restriction. This is most often the case for collection types. See its documentation for more details.

§How to implement `FromPyObject`?

§`#[derive(FromPyObject)]`

The simplest way to implement FromPyObject for a custom type is to make use of our derive macro.

use pyo3::prelude::*;

#[derive(FromPyObject)]
struct MyObject {
    msg: String,
    list: Vec<u32>
}

By default this will try to extract each field from the Python object by attribute access, but this can be customized. For more information about the derive macro, its configuration as well as its working principle for other types, take a look at the guide.

In case the derive macro is not sufficient or can not be used for some other reason, FromPyObject can be implemented manually. In the following types without lifetime parameters are handled first, because they are a little bit simpler. Types with lifetime parameters are explained below.

§Manual implementation for types without lifetime

Types that do not contain lifetime parameters are unable to borrow from the Python object, so the lifetimes of FromPyObject can be elided:

use pyo3::prelude::*;

struct MyObject {
    msg: String,
    list: Vec<u32>
}

impl FromPyObject<'_, '_> for MyObject {
    type Error = PyErr;

    fn extract(obj: Borrowed<'_, '_, PyAny>) -> Result<Self, Self::Error> {
        Ok(MyObject {
            msg: obj.getattr("msg")?.extract()?,
            list: obj.getattr("list")?.extract()?,
        })
    }
}

This is basically what the derive macro above expands to.

§Manual implementation for types with lifetime parameters

For types that contain lifetimes, these lifetimes need to be bound to the corresponding FromPyObject lifetime. This is roughly how the extraction of a typed Bound is implemented within PyO3.

use pyo3::prelude::*;
use pyo3::types::PyString;

struct MyObject<'py>(Bound<'py, PyString>);

impl<'py> FromPyObject<'_, 'py> for MyObject<'py> {
    type Error = PyErr;

    fn extract(obj: Borrowed<'_, 'py, PyAny>) -> Result<Self, Self::Error> {
        Ok(MyObject(obj.cast()?.to_owned()))
    }
}

§Details

Cow<'a, str> is an example of an output type that may or may not borrow from the input lifetime 'a. Which variant will be produced depends on the runtime type of the Python object. For a Python byte string, the existing string data can be borrowed for 'a into a Cow::Borrowed. For a Python Unicode string, the data may have to be reencoded to UTF-8, and copied into a Cow::Owned. It does not depend on the Python lifetime 'py.

The output type may also depend on the Python lifetime 'py. This allows the output type to keep interacting with the Python interpreter. See also Bound<'py, T>.

Required Associated Types§

type Error: Into<PyErr>

The type returned in the event of a conversion error.

For most use cases defaulting to PyErr here is perfectly acceptable. Using a custom error type can be used to avoid having to create a Python exception object in the case where that exception never reaches Python. This may lead to slightly better performance under certain conditions.

§Note

Unfortunately Try and thus ? is based on From, not Into, so implementations may need to use .map_err(Into::into) sometimes to convert a generic Error into a PyErr.

Required Methods§

fn extract(obj: Borrowed<'a, 'py, PyAny>) -> Result<Self, Self::Error>

Extracts Self from the bound smart pointer obj.

Users are advised against calling this method directly: instead, use this via Bound<'_, PyAny>::extract or Py::extract.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Trait FromPyObject Copy item path

§Examples

§How to implement FromPyObject?

§#[derive(FromPyObject)]

§Manual implementation for types without lifetime

§Manual implementation for types with lifetime parameters

§Details

Required Associated Types§

type Error: Into<PyErr>

§Note

Required Methods§

fn extract(obj: Borrowed<'a, 'py, PyAny>) -> Result<Self, Self::Error>

Dyn Compatibility§

Implementations on Foreign Types§

impl FromPyObject<'_, '_> for IpAddr

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<IpAddr, <IpAddr as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for bool

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<bool, <bool as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for char

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<char, <char as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for i128

type Error = PyErr

fn extract( ob: Borrowed<'_, '_, PyAny>, ) -> Result<i128, <i128 as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for u64

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<u64, <u64 as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for u128

type Error = PyErr

fn extract( ob: Borrowed<'_, '_, PyAny>, ) -> Result<u128, <u128 as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for usize

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<usize, <usize as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<i8>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<i8>, <NonZero<i8> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<i16>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<i16>, <NonZero<i16> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<i32>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<i32>, <NonZero<i32> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<i64>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<i64>, <NonZero<i64> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<i128>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<i128>, <NonZero<i128> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<isize>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<isize>, <NonZero<isize> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<u8>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<u8>, <NonZero<u8> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<u16>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<u16>, <NonZero<u16> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<u32>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<u32>, <NonZero<u32> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<u64>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<u64>, <NonZero<u64> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<u128>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<u128>, <NonZero<u128> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for NonZero<usize>

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<NonZero<usize>, <NonZero<usize> as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for Duration

type Error = PyErr

fn extract( obj: Borrowed<'_, '_, PyAny>, ) -> Result<Duration, <Duration as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for OsString

type Error = PyErr

fn extract( ob: Borrowed<'_, '_, PyAny>, ) -> Result<OsString, <OsString as FromPyObject<'_, '_>>::Error>

impl FromPyObject<'_, '_> for PathBuf

type Error = PyErr

fn extract( ob: Borrowed<'_, '_, PyAny>, ) -> Result<PathBuf, <PathBuf as FromPyObject<'_, '_>>::Error>

Trait FromPyObject

§How to implement `FromPyObject`?

§`#[derive(FromPyObject)]`

impl<'a, 'py, T0> FromPyObject<'a, 'py> for (T0,)
where T0: FromPyObject<'a, 'py>,

impl<'a, 'py, T0, T1> FromPyObject<'a, 'py> for (T0, T1)
where T0: FromPyObject<'a, 'py>, T1: FromPyObject<'a, 'py>,

impl<'a, 'py, T0, T1, T2> FromPyObject<'a, 'py> for (T0, T1, T2)
where T0: FromPyObject<'a, 'py>, T1: FromPyObject<'a, 'py>, T2: FromPyObject<'a, 'py>,

impl<'a, 'py, T0, T1, T2, T3> FromPyObject<'a, 'py> for (T0, T1, T2, T3)
where T0: FromPyObject<'a, 'py>, T1: FromPyObject<'a, 'py>, T2: FromPyObject<'a, 'py>, T3: FromPyObject<'a, 'py>,

impl<'a, 'py, T0, T1, T2, T3, T4> FromPyObject<'a, 'py> for (T0, T1, T2, T3, T4)
where T0: FromPyObject<'a, 'py>, T1: FromPyObject<'a, 'py>, T2: FromPyObject<'a, 'py>, T3: FromPyObject<'a, 'py>, T4: FromPyObject<'a, 'py>,

impl<'a, 'py, T0, T1, T2, T3, T4, T5> FromPyObject<'a, 'py> for (T0, T1, T2, T3, T4, T5)
where T0: FromPyObject<'a, 'py>, T1: FromPyObject<'a, 'py>, T2: FromPyObject<'a, 'py>, T3: FromPyObject<'a, 'py>, T4: FromPyObject<'a, 'py>, T5: FromPyObject<'a, 'py>,

impl<'a, 'py, T0, T1, T2, T3, T4, T5, T6> FromPyObject<'a, 'py> for (T0, T1, T2, T3, T4, T5, T6)
where T0: FromPyObject<'a, 'py>, T1: FromPyObject<'a, 'py>, T2: FromPyObject<'a, 'py>, T3: FromPyObject<'a, 'py>, T4: FromPyObject<'a, 'py>, T5: FromPyObject<'a, 'py>, T6: FromPyObject<'a, 'py>,

impl<'a, 'py, T> FromPyObject<'a, 'py> for Option<T>
where T: FromPyObject<'a, 'py>,

impl<'a, 'py, T> FromPyObject<'a, 'py> for Cell<T>
where T: FromPyObject<'a, 'py>,