Struct PythonObject 

pub struct PythonObject(pub Py<PyAny>);

Available on crate feature python only.

Wrapper around PyObject from pyo3 with additional trait impls.

Tuple Fields

0: Py<PyAny>

Implementations

impl PythonObject

pub fn serialize_with_pyversion<T, S>( value: &T, serializer: S, ) -> Result<S::Ok, S::Error>

where T: AsRef<PythonObject>, S: Serializer,

Available on crate feature serde only.

pub fn deserialize_with_pyversion<'de, T, D>(d: D) -> Result<T, D::Error>

where T: From<PythonObject>, D: Deserializer<'de>,

Available on crate feature serde only.

Methods from Deref<Target = Py<PyAny>>

pub fn as_ptr(&self) -> *mut PyObject

Returns the raw FFI pointer represented by self.

Safety

Callers are responsible for ensuring that the pointer does not outlive self.

The reference is borrowed; callers should not decrease the reference count when they are finished with the pointer.

pub fn as_any(&self) -> &Py<PyAny>

Helper to cast to Py<PyAny>.

pub fn borrow<'py>(&'py self, py: Python<'py>) -> PyRef<'py, T>

Immutably borrows the value T.

This borrow lasts while the returned [PyRef] exists. Multiple immutable borrows can be taken out at the same time.

For frozen classes, the simpler [get][Self::get] is available.

Equivalent to self.bind(py).borrow() - see [Bound::borrow].

Examples

#[pyclass]
struct Foo {
    inner: u8,
}

Python::attach(|py| -> PyResult<()> {
    let foo: Py<Foo> = Py::new(py, Foo { inner: 73 })?;
    let inner: &u8 = &foo.borrow(py).inner;

    assert_eq!(*inner, 73);
    Ok(())
})?;

Panics

Panics if the value is currently mutably borrowed. For a non-panicking variant, use try_borrow.

pub fn borrow_mut<'py>(&'py self, py: Python<'py>) -> PyRefMut<'py, T>

where T: PyClass<Frozen = False>,

Mutably borrows the value T.

This borrow lasts while the returned [PyRefMut] exists.

Equivalent to self.bind(py).borrow_mut() - see [Bound::borrow_mut].

Examples

#[pyclass]
struct Foo {
    inner: u8,
}

Python::attach(|py| -> PyResult<()> {
    let foo: Py<Foo> = Py::new(py, Foo { inner: 73 })?;
    foo.borrow_mut(py).inner = 35;

    assert_eq!(foo.borrow(py).inner, 35);
    Ok(())
})?;

Panics

Panics if the value is currently borrowed. For a non-panicking variant, use try_borrow_mut.

pub fn try_borrow<'py>( &'py self, py: Python<'py>, ) -> Result<PyRef<'py, T>, PyBorrowError>

Attempts to immutably borrow the value T, returning an error if the value is currently mutably borrowed.

The borrow lasts while the returned [PyRef] exists.

This is the non-panicking variant of borrow.

For frozen classes, the simpler [get][Self::get] is available.

Equivalent to self.bind(py).try_borrow() - see [Bound::try_borrow].

pub fn try_borrow_mut<'py>( &'py self, py: Python<'py>, ) -> Result<PyRefMut<'py, T>, PyBorrowMutError>

where T: PyClass<Frozen = False>,

Attempts to mutably borrow the value T, returning an error if the value is currently borrowed.

The borrow lasts while the returned [PyRefMut] exists.

This is the non-panicking variant of borrow_mut.

Equivalent to self.bind(py).try_borrow_mut() - see [Bound::try_borrow_mut].

pub fn get(&self) -> &T

where T: PyClass<Frozen = True> + Sync,

Provide an immutable borrow of the value T without acquiring the GIL.

This is available if the class is [frozen][macro@crate::pyclass] and Sync.

Examples

use std::sync::atomic::{AtomicUsize, Ordering};

#[pyclass(frozen)]
struct FrozenCounter {
    value: AtomicUsize,
}

let cell  = Python::attach(|py| {
    let counter = FrozenCounter { value: AtomicUsize::new(0) };

    Py::new(py, counter).unwrap()
});

cell.get().value.fetch_add(1, Ordering::Relaxed);

pub fn bind<'py>(&self, _py: Python<'py>) -> &Bound<'py, T>

Attaches this Py to the given Python context, allowing access to further Python APIs.

pub fn bind_borrowed<'a, 'py>(&'a self, py: Python<'py>) -> Borrowed<'a, 'py, T>

Same as bind but produces a Borrowed<T> instead of a Bound<T>.

pub fn is<U>(&self, o: U) -> bool

where U: AsRef<Py<PyAny>>,

Returns whether self and other point to the same object. To compare the equality of two objects (the == operator), use eq.

This is equivalent to the Python expression self is other.

pub fn get_refcnt(&self, _py: Python<'_>) -> isize

Gets the reference count of the ffi::PyObject pointer.

pub fn clone_ref(&self, _py: Python<'_>) -> Py<T>

Makes a clone of self.

This creates another pointer to the same object, increasing its reference count.

You should prefer using this method over Clone if you happen to be holding the GIL already.

Examples

use pyo3::prelude::*;
use pyo3::types::PyDict;

Python::attach(|py| {
    let first: Py<PyDict> = PyDict::new(py).unbind();
    let second = Py::clone_ref(&first, py);

    // Both point to the same object
    assert!(first.is(&second));
});

pub fn is_none(&self, _py: Python<'_>) -> bool

Returns whether the object is considered to be None.

This is equivalent to the Python expression self is None.

pub fn is_truthy(&self, py: Python<'_>) -> Result<bool, PyErr>

Returns whether the object is considered to be true.

This applies truth value testing equivalent to the Python expression bool(self).

pub fn extract<'a, 'py, D>(&'a self, py: Python<'py>) -> Result<D, PyErr>

where 'py: 'a, D: FromPyObjectBound<'a, 'py>,

Extracts some type from the Python object.

This is a wrapper function around FromPyObject::extract().

pub fn getattr<'py, N>( &self, py: Python<'py>, attr_name: N, ) -> Result<Py<PyAny>, PyErr>

where N: IntoPyObject<'py, Target = PyString>,

Retrieves an attribute value.

This is equivalent to the Python expression self.attr_name.

If calling this method becomes performance-critical, the intern! macro can be used to intern attr_name, thereby avoiding repeated temporary allocations of Python strings.

Example: intern!ing the attribute name

#[pyfunction]
fn version(sys: Py<PyModule>, py: Python<'_>) -> PyResult<Py<PyAny>> {
    sys.getattr(py, intern!(py, "version"))
}

pub fn setattr<'py, N, V>( &self, py: Python<'py>, attr_name: N, value: V, ) -> Result<(), PyErr>

where N: IntoPyObject<'py, Target = PyString>, V: IntoPyObject<'py>,

Sets an attribute value.

This is equivalent to the Python expression self.attr_name = value.

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern attr_name.

Example: intern!ing the attribute name

#[pyfunction]
fn set_answer(ob: Py<PyAny>, py: Python<'_>) -> PyResult<()> {
    ob.setattr(py, intern!(py, "answer"), 42)
}

pub fn call<'py, A>( &self, py: Python<'py>, args: A, kwargs: Option<&Bound<'py, PyDict>>, ) -> Result<Py<PyAny>, PyErr>

where A: PyCallArgs<'py>,

Calls the object.

This is equivalent to the Python expression self(*args, **kwargs).

pub fn call1<'py, A>( &self, py: Python<'py>, args: A, ) -> Result<Py<PyAny>, PyErr>

where A: PyCallArgs<'py>,

Calls the object with only positional arguments.

This is equivalent to the Python expression self(*args).

pub fn call0(&self, py: Python<'_>) -> Result<Py<PyAny>, PyErr>

Calls the object without arguments.

This is equivalent to the Python expression self().

pub fn call_method<'py, N, A>( &self, py: Python<'py>, name: N, args: A, kwargs: Option<&Bound<'py, PyDict>>, ) -> Result<Py<PyAny>, PyErr>

where N: IntoPyObject<'py, Target = PyString>, A: PyCallArgs<'py>,

Calls a method on the object.

This is equivalent to the Python expression self.name(*args, **kwargs).

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern name.

pub fn call_method1<'py, N, A>( &self, py: Python<'py>, name: N, args: A, ) -> Result<Py<PyAny>, PyErr>

where N: IntoPyObject<'py, Target = PyString>, A: PyCallArgs<'py>,

Calls a method on the object with only positional arguments.

This is equivalent to the Python expression self.name(*args).

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern name.

pub fn call_method0<'py, N>( &self, py: Python<'py>, name: N, ) -> Result<Py<PyAny>, PyErr>

where N: IntoPyObject<'py, Target = PyString>,

Calls a method on the object with no arguments.

This is equivalent to the Python expression self.name().

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern name.

pub fn downcast_bound<'py, T>( &self, py: Python<'py>, ) -> Result<&Bound<'py, T>, DowncastError<'_, 'py>>

where T: PyTypeCheck,

Downcast this Py<PyAny> to a concrete Python type or pyclass.

Note that you can often avoid casting yourself by just specifying the desired type in function or method signatures. However, manual casting is sometimes necessary.

For extracting a Rust-only type, see [Py::extract].

Example: Downcasting to a specific Python object

use pyo3::prelude::*;
use pyo3::types::{PyDict, PyList};

Python::attach(|py| {
    let any = PyDict::new(py).into_any().unbind();

    assert!(any.downcast_bound::<PyDict>(py).is_ok());
    assert!(any.downcast_bound::<PyList>(py).is_err());
});

Example: Getting a reference to a pyclass

This is useful if you want to mutate a Py<PyAny> that might actually be a pyclass.

use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Py::new(py, Class { i: 0 })?.into_any();

    let class_bound = class.downcast_bound::<Class>(py)?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})

pub unsafe fn downcast_bound_unchecked<'py, T>( &self, py: Python<'py>, ) -> &Bound<'py, T>

Casts the Py<PyAny> to a concrete Python object type without checking validity.

Safety

Callers must ensure that the type is valid or risk type confusion.

pub fn cast_bound<'py, U>( &self, py: Python<'py>, ) -> Result<&Bound<'py, U>, DowncastError<'_, 'py>>

where U: PyTypeCheck,

Cast this Py<T> to a concrete Python type or pyclass.

Note that you can often avoid casting yourself by just specifying the desired type in function or method signatures. However, manual casting is sometimes necessary.

For extracting a Rust-only type, see [Py::extract].

Example: Casting to a specific Python object

use pyo3::prelude::*;
use pyo3::types::{PyDict, PyList};

Python::attach(|py| {
    let any = PyDict::new(py).into_any().unbind();

    assert!(any.cast_bound::<PyDict>(py).is_ok());
    assert!(any.cast_bound::<PyList>(py).is_err());
});

Example: Getting a reference to a pyclass

This is useful if you want to mutate a Py<PyAny> that might actually be a pyclass.

use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Py::new(py, Class { i: 0 })?.into_any();

    let class_bound = class.cast_bound::<Class>(py)?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})

pub unsafe fn cast_bound_unchecked<'py, U>( &self, py: Python<'py>, ) -> &Bound<'py, U>

Casts the Py<T> to a concrete Python object type without checking validity.

Safety

Callers must ensure that the type is valid or risk type confusion.

Trait Implementations

impl Clone for PythonObject

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PythonObject

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for PythonObject

type Target = Py<PyAny>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for PythonObject

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'a> Deserialize<'a> for PythonObject

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'a>,

Deserialize this value from the given Serde deserializer.

impl From<Py<PyAny>> for PythonObject

fn from(value: Py<PyAny>) -> Self

Converts to this type from the input type.

impl<'py> IntoPyObject<'py> for &PythonObject

type Target = PyAny

The Python output type

type Output = Bound<'py, <&PythonObject as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error>

Performs the conversion.

impl<'py> IntoPyObject<'py> for PythonObject

type Target = PyAny

The Python output type

type Output = Bound<'py, <PythonObject as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error>

Performs the conversion.

impl JsonSchema for PythonObject

Available on crate feature dsl-schema only.

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl PartialEq for PythonObject

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for PythonObject

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TrySerializeToBytes for PythonObject

Available on crate feature serde only.

fn try_serialize_to_bytes(&self) -> PolarsResult<Vec<u8>>

fn try_deserialize_bytes(bytes: &[u8]) -> PolarsResult<Self>

impl Eq for PythonObject