pub trait IntoPy<T>: Sized {
    fn into_py(self, py: Python<'_>) -> T;

    fn type_output() -> TypeInfo { ... }
}
Expand description

Defines a conversion from a Rust type to a Python object.

It functions similarly to std’s Into trait, but requires a GIL token as an argument. Many functions and traits internal to PyO3 require this trait as a bound, so a lack of this trait can manifest itself in different error messages.

Examples

With #[pyclass]

The easiest way to implement IntoPy is by exposing a struct as a native Python object by annotating it with #[pyclass].

use pyo3::prelude::*;

#[pyclass]
struct Number {
    #[pyo3(get, set)]
    value: i32,
}

Python code will see this as an instance of the Number class with a value attribute.

Conversion to a Python object

However, it may not be desirable to expose the existence of Number to Python code. IntoPy allows us to define a conversion to an appropriate Python object.

use pyo3::prelude::*;

struct Number {
    value: i32,
}

impl IntoPy<PyObject> for Number {
    fn into_py(self, py: Python<'_>) -> PyObject {
        // delegates to i32's IntoPy implementation.
        self.value.into_py(py)
    }
}

Python code will see this as an int object.

Dynamic conversion into Python objects.

It is also possible to return a different Python object depending on some condition. This is useful for types like enums that can carry different types.

use pyo3::prelude::*;

enum Value {
    Integer(i32),
    String(String),
    None,
}

impl IntoPy<PyObject> for Value {
    fn into_py(self, py: Python<'_>) -> PyObject {
        match self {
            Self::Integer(val) => val.into_py(py),
            Self::String(val) => val.into_py(py),
            Self::None => py.None(),
        }
    }
}

Python code will see this as any of the int, string or None objects.

Required Methods

Performs the conversion.

Provided Methods

Extracts the type hint information for this type when it appears as a return value.

For example, Vec<u32> would return List[int]. The default implementation returns Any, which is correct for any type.

For most types, the return value for this method will be identical to that of FromPyObject::type_input. It may be different for some types, such as Dict, to allow duck-typing: functions return Dict but take Mapping as argument.

Implementations on Foreign Types

Converts () to an empty Python tuple.

Implementors