Trait pyo3::conversion::IntoPy
source · pub trait IntoPy<T>: Sized {
// Required method
fn into_py(self, py: Python<'_>) -> T;
// Provided method
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§
Provided Methods§
sourcefn type_output() -> TypeInfo
fn type_output() -> TypeInfo
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.
Object Safety§
This trait is not object safe.