Struct pyo3::Py[][src]

#[repr(transparent)]
pub struct Py<T>(_, _);
Expand description

A Python object of known type T.

Accessing this object is thread-safe, since any access to its API requires a Python<'py> GIL token. There are a few different ways to use the Python object contained:

See the guide for an explanation of the different Python object types.

Implementations

Create a new instance Py<T> of a #[pyclass] on the Python heap.

Borrows a GIL-bound reference to the contained T. By binding to the GIL lifetime, this allows the GIL-bound reference to not require Python for any of its methods.

For native types, this reference is &T. For pyclasses, this is &PyCell<T>.

Examples

Get access to &PyList from Py<PyList>:

let list: Py<PyList> = PyList::empty(py).into();
let list: &PyList = list.as_ref(py);
assert_eq!(list.len(), 0);

Get access to &PyCell<MyClass> from Py<MyClass>:

#[pyclass]
struct MyClass { }
let my_class: Py<MyClass> = Py::new(py, MyClass { }).unwrap();
let my_class_cell: &PyCell<MyClass> = my_class.as_ref(py);
assert!(my_class_cell.try_borrow().is_ok());

Similar to as_ref, and also consumes this Py and registers the Python object reference in PyO3’s object storage. The reference count for the Python object will not be decreased until the GIL lifetime ends.

Examples

Useful when returning GIL-bound references from functions. In the snippet below, note that the 'py lifetime of the input GIL lifetime is also given to the returned reference:

fn new_py_any<'py>(py: Python<'py>, value: impl IntoPy<PyObject>) -> &'py PyAny {
    let obj: PyObject = value.into_py(py);

    // .as_ref(py) would not be suitable here, because a reference to `obj` may not be
    // returned from the function.
    obj.into_ref(py)
}

Immutably borrows the value T. This borrow lasts untill the returned PyRef exists.

Equivalent to self.as_ref(py).borrow() - see PyCell::borrow

Panics

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

Mutably borrows the value T. This borrow lasts untill the returned PyRefMut exists.

Equivalent to self.as_ref(py).borrow_mut() - see PyCell::borrow_mut

Panics

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

Immutably borrows the value T, returning an error if the value is currently mutably borrowed. This borrow lasts untill the returned PyRef exists.

This is the non-panicking variant of borrow.

Equivalent to self.as_ref(py).try_borrow() - see PyCell::try_borrow

Mutably borrows the value T, returning an error if the value is currently borrowed. This borrow lasts untill the returned PyRefMut exists.

This is the non-panicking variant of borrow_mut.

Equivalent to self.as_ref(py).try_borrow_mut() - see [PyCell::try_borrow_mut`](../pycell/struct.PyCell.html#method.try_borrow_mut)

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

Clones self by calling Py_INCREF() on the ptr.

Returns whether the object is considered to be None.

This is equivalent to the Python expression self is None.

Returns whether the object is considered to be true.

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

Extracts some type from the Python object.

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

Retrieves an attribute value.

This is equivalent to the Python expression self.attr_name.

Calls the object.

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

Calls the object with only positional arguments.

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

Calls the object without arguments.

This is equivalent to the Python expression self().

Calls a method on the object.

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

Calls a method on the object with only positional arguments.

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

Calls a method on the object with no arguments.

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

Create a Py<T> instance by taking ownership of the given FFI pointer.

Safety

ptr must be a pointer to a Python object of type T.

Callers must own the object referred to by ptr, as this function implicitly takes ownership of that object.

Panics

Panics if ptr is null.

Create a Py<T> instance by taking ownership of the given FFI pointer.

If ptr is null then the current Python exception is fetched as a PyErr.

Safety

If non-null, ptr must be a pointer to a Python object of type T.

Create a Py<T> instance by taking ownership of the given FFI pointer.

If ptr is null then None is returned.

Safety

If non-null, ptr must be a pointer to a Python object of type T.

Create a Py<T> instance by creating a new reference from the given FFI pointer.

Safety

ptr must be a pointer to a Python object of type T.

Panics

Panics if ptr is null.

Create a Py<T> instance by creating a new reference from the given FFI pointer.

If ptr is null then the current Python exception is fetched as a PyErr.

Safety

ptr must be a pointer to a Python object of type T.

Create a Py<T> instance by creating a new reference from the given FFI pointer.

If ptr is null then None is returned.

Safety

ptr must be a pointer to a Python object of type T.

Casts the PyObject to a concrete Python object type.

This can cast only to native Python types, not types implemented in Rust. For a more flexible alternative, see Py::extract.

Trait Implementations

Gets the underlying FFI pointer, returns a borrowed pointer.

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Deserialize this value from the given Serde deserializer. Read more

Formats the value using the given formatter. Read more

Dropping a Py instance decrements the reference count on the object by 1.

Executes the destructor for this type. Read more

Py can be used as an error when T is an Error.

However for GIL lifetime reasons, cause() cannot be implemented for Py. Use .as_ref() to get the GIL-scoped error if you need to inspect the cause.

The lower-level source of this error, if any. Read more

🔬 This is a nightly-only experimental API. (backtrace)

Returns a stack backtrace, if available, of where this error occurred. Read more

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Extracts Self from the source PyObject.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Converts a Py instance to PyObject. Consumes self without calling Py_DECREF().

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Converts () to an empty Python tuple.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Gets the underlying FFI pointer, returns a owned pointer.

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Serialize this value into the given Serde serializer. Read more

Converts Py instance -> PyObject.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

Converts self into a Python object and calls the specified closure on the native FFI pointer underlying the Python object. Read more

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.