#[repr(C)]pub struct PyObject { /* private fields */ }
Expand description
Represents a reference to a Python object.
Python objects are reference counted.
Calling clone_ref()
on a PyObject
will return a new reference to the same object
(thus incrementing the reference count).
The Drop
implementation will automatically decrement the reference count.
You can also call release_ref()
to explicitly decrement the reference count.
This is slightly faster than relying on automatic drop, because release_ref
does not need to check whether the GIL needs to be acquired.
PyObject
can be used with all Python objects, since all python types
derive from object
. This crate also contains other, more specific types
that serve as references to Python objects (e.g. PyTuple
for Python tuples, etc.).
You can convert from any Python object to PyObject
by calling as_object()
or into_object()
from the PythonObject trait.
In the other direction, you can call cast_as()
or cast_into()
on PyObject
to convert to more specific object types.
Most of the interesting methods are provided by the ObjectProtocol trait.
Implementations
sourceimpl PyObject
impl PyObject
sourcepub unsafe fn from_owned_ptr(_py: Python<'_>, ptr: *mut PyObject) -> PyObject
pub unsafe fn from_owned_ptr(_py: Python<'_>, ptr: *mut PyObject) -> PyObject
Creates a PyObject instance for the given FFI pointer. This moves ownership over the pointer into the PyObject. Undefined behavior if the pointer is NULL or invalid.
sourcepub unsafe fn from_borrowed_ptr(_py: Python<'_>, ptr: *mut PyObject) -> PyObject
pub unsafe fn from_borrowed_ptr(_py: Python<'_>, ptr: *mut PyObject) -> PyObject
Creates a PyObject instance for the given FFI pointer. Calls Py_INCREF() on the ptr. Undefined behavior if the pointer is NULL or invalid.
sourcepub unsafe fn from_owned_ptr_opt(
py: Python<'_>,
ptr: *mut PyObject
) -> Option<PyObject>
pub unsafe fn from_owned_ptr_opt(
py: Python<'_>,
ptr: *mut PyObject
) -> Option<PyObject>
Creates a PyObject instance for the given FFI pointer. This moves ownership over the pointer into the PyObject. Returns None for null pointers; undefined behavior if the pointer is invalid.
sourcepub unsafe fn from_borrowed_ptr_opt(
py: Python<'_>,
ptr: *mut PyObject
) -> Option<PyObject>
pub unsafe fn from_borrowed_ptr_opt(
py: Python<'_>,
ptr: *mut PyObject
) -> Option<PyObject>
Returns None for null pointers; undefined behavior if the pointer is invalid.
sourcepub fn as_ptr(&self) -> *mut PyObject
pub fn as_ptr(&self) -> *mut PyObject
Gets the underlying FFI pointer. Returns a borrowed pointer.
sourcepub fn steal_ptr(self) -> *mut PyObject
pub fn steal_ptr(self) -> *mut PyObject
Gets the underlying FFI pointer.
Consumes self
without calling Py_DECREF()
, thus returning an owned pointer.
sourcepub unsafe fn borrow_from_ptr(ptr: &*mut PyObject) -> &PyObject
pub unsafe fn borrow_from_ptr(ptr: &*mut PyObject) -> &PyObject
Transmutes an FFI pointer to &PyObject
.
Undefined behavior if the pointer is NULL or invalid.
sourcepub unsafe fn borrow_from_owned_ptr_slice(ptr: &[*mut PyObject]) -> &[PyObject]
pub unsafe fn borrow_from_owned_ptr_slice(ptr: &[*mut PyObject]) -> &[PyObject]
Transmutes a slice of owned FFI pointers to &[PyObject]
.
Undefined behavior if any pointer in the slice is NULL or invalid.
sourcepub fn get_refcnt(&self, _py: Python<'_>) -> usize
pub fn get_refcnt(&self, _py: Python<'_>) -> usize
Gets the reference count of this Python object.
sourcepub fn get_type(&self, py: Python<'_>) -> PyType
pub fn get_type(&self, py: Python<'_>) -> PyType
Gets the Python type object for this object’s type.
sourcepub unsafe fn unchecked_cast_into<T>(self) -> Twhere
T: PythonObject,
pub unsafe fn unchecked_cast_into<T>(self) -> Twhere
T: PythonObject,
Casts the PyObject to a concrete Python object type.
Causes undefined behavior if the object is not of the expected type.
This is a wrapper function around PythonObject::unchecked_downcast_from()
.
sourcepub fn cast_into<T>(
self,
py: Python<'_>
) -> Result<T, PythonObjectDowncastError<'_>>where
T: PythonObjectWithCheckedDowncast,
pub fn cast_into<T>(
self,
py: Python<'_>
) -> Result<T, PythonObjectDowncastError<'_>>where
T: PythonObjectWithCheckedDowncast,
Casts the PyObject to a concrete Python object type.
Fails with PythonObjectDowncastError
if the object is not of the expected type.
This is a wrapper function around PythonObjectWithCheckedDowncast::downcast_from()
.
sourcepub unsafe fn unchecked_cast_as<T>(&self) -> &Twhere
T: PythonObject,
pub unsafe fn unchecked_cast_as<T>(&self) -> &Twhere
T: PythonObject,
Casts the PyObject to a concrete Python object type.
Causes undefined behavior if the object is not of the expected type.
This is a wrapper function around PythonObject::unchecked_downcast_borrow_from()
.
sourcepub fn cast_as<'s, 'p, T>(
&'s self,
py: Python<'p>
) -> Result<&'s T, PythonObjectDowncastError<'p>>where
T: PythonObjectWithCheckedDowncast,
pub fn cast_as<'s, 'p, T>(
&'s self,
py: Python<'p>
) -> Result<&'s T, PythonObjectDowncastError<'p>>where
T: PythonObjectWithCheckedDowncast,
Casts the PyObject to a concrete Python object type.
Fails with PythonObjectDowncastError
if the object is not of the expected type.
This is a wrapper function around PythonObjectWithCheckedDowncast::downcast_borrow_from()
.
sourcepub fn extract<'a, T>(&'a self, py: Python<'_>) -> PyResult<T>where
T: FromPyObject<'a>,
pub fn extract<'a, T>(&'a self, py: Python<'_>) -> PyResult<T>where
T: FromPyObject<'a>,
Extracts some type from the Python object.
This is a wrapper function around FromPyObject::from_py_object()
.
Trait Implementations
sourceimpl BaseObject for PyObject
impl BaseObject for PyObject
sourceimpl<'s> FromPyObject<'s> for &'s PyObject
impl<'s> FromPyObject<'s> for &'s PyObject
sourceimpl<'s> FromPyObject<'s> for PyObject
impl<'s> FromPyObject<'s> for PyObject
sourceimpl NumberProtocol for PyObject
impl NumberProtocol for PyObject
sourcefn add(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
fn add(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
sourcefn subtract(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
fn subtract(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
sourcefn multiply(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
fn multiply(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
sourcefn matrix_multiply(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
fn matrix_multiply(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
self @ other
Read moresourcefn power(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
fn power(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
self ** other
,
or the two-argument form of the builtin method pow: pow(self, other)
Read moresourcefn power_modulo(
&self,
py: Python<'_>,
exp: impl ToPyObject,
z: impl ToPyObject
) -> PyResult<PyObject>
fn power_modulo(
&self,
py: Python<'_>,
exp: impl ToPyObject,
z: impl ToPyObject
) -> PyResult<PyObject>
self ** other % mod
but computed much more efficiently. Read moresourcefn true_divide(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
fn true_divide(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
self / other
, Read moresourcefn floor_divide(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
fn floor_divide(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
self // other
, Read moresourcefn modulo(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
fn modulo(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
self
by other
,
equivalent to the Python expression self % other
Read moresourcefn div_mod(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
fn div_mod(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
divmod(self, other)
Read moresourcefn negative(&self, py: Python<'_>) -> PyResult<PyObject>
fn negative(&self, py: Python<'_>) -> PyResult<PyObject>
sourcefn positive(&self, py: Python<'_>) -> PyResult<PyObject>
fn positive(&self, py: Python<'_>) -> PyResult<PyObject>
+self
Read moresourcefn absolute(&self, py: Python<'_>) -> PyResult<PyObject>
fn absolute(&self, py: Python<'_>) -> PyResult<PyObject>
abs
Read moresourcefn bitwise_invert(&self, py: Python<'_>) -> PyResult<PyObject>
fn bitwise_invert(&self, py: Python<'_>) -> PyResult<PyObject>
~self
Read moresourcefn left_shift(&self, py: Python<'_>, bits: impl ToPyObject) -> PyResult<PyObject>
fn left_shift(&self, py: Python<'_>, bits: impl ToPyObject) -> PyResult<PyObject>
self << bits
Read moresourcefn right_shift(&self, py: Python<'_>, bits: impl ToPyObject) -> PyResult<PyObject>
fn right_shift(&self, py: Python<'_>, bits: impl ToPyObject) -> PyResult<PyObject>
self >> bits
Read moresourcefn bitwise_and(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
fn bitwise_and(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
self & other
Read moresourcefn bitwise_xor(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
fn bitwise_xor(
&self,
py: Python<'_>,
other: impl ToPyObject
) -> PyResult<PyObject>
self ^ other
Read moresourcefn bitwise_or(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
fn bitwise_or(&self, py: Python<'_>, other: impl ToPyObject) -> PyResult<PyObject>
self | other
Read moresourcefn to_int(&self, py: Python<'_>) -> PyResult<PyLong>
fn to_int(&self, py: Python<'_>) -> PyResult<PyLong>
int(self)
Read moresourceimpl ObjectProtocol for PyObject
impl ObjectProtocol for PyObject
sourcefn hasattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<bool>where
N: ToPyObject,
fn hasattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<bool>where
N: ToPyObject,
sourcefn getattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<PyObject>where
N: ToPyObject,
fn getattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<PyObject>where
N: ToPyObject,
sourcefn setattr<N, V>(&self, py: Python<'_>, attr_name: N, value: V) -> PyResult<()>where
N: ToPyObject,
V: ToPyObject,
fn setattr<N, V>(&self, py: Python<'_>, attr_name: N, value: V) -> PyResult<()>where
N: ToPyObject,
V: ToPyObject,
sourcefn delattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<()>where
N: ToPyObject,
fn delattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<()>where
N: ToPyObject,
sourcefn compare<O>(&self, py: Python<'_>, other: O) -> PyResult<Ordering>where
O: ToPyObject,
fn compare<O>(&self, py: Python<'_>, other: O) -> PyResult<Ordering>where
O: ToPyObject,
sourcefn rich_compare<O>(
&self,
py: Python<'_>,
other: O,
compare_op: CompareOp
) -> PyResult<PyObject>where
O: ToPyObject,
fn rich_compare<O>(
&self,
py: Python<'_>,
other: O,
compare_op: CompareOp
) -> PyResult<PyObject>where
O: ToPyObject,
sourcefn repr(&self, py: Python<'_>) -> PyResult<PyString>
fn repr(&self, py: Python<'_>) -> PyResult<PyString>
sourcefn str(&self, py: Python<'_>) -> PyResult<PyString>
fn str(&self, py: Python<'_>) -> PyResult<PyString>
sourcefn is_callable(&self, _py: Python<'_>) -> bool
fn is_callable(&self, _py: Python<'_>) -> bool
sourcefn call<A>(
&self,
py: Python<'_>,
args: A,
kwargs: Option<&PyDict>
) -> PyResult<PyObject>where
A: ToPyObject<ObjectType = PyTuple>,
fn call<A>(
&self,
py: Python<'_>,
args: A,
kwargs: Option<&PyDict>
) -> PyResult<PyObject>where
A: ToPyObject<ObjectType = PyTuple>,
sourcefn call_method<A>(
&self,
py: Python<'_>,
name: &str,
args: A,
kwargs: Option<&PyDict>
) -> PyResult<PyObject>where
A: ToPyObject<ObjectType = PyTuple>,
fn call_method<A>(
&self,
py: Python<'_>,
name: &str,
args: A,
kwargs: Option<&PyDict>
) -> PyResult<PyObject>where
A: ToPyObject<ObjectType = PyTuple>,
sourcefn hash(&self, py: Python<'_>) -> PyResult<Py_hash_t>
fn hash(&self, py: Python<'_>) -> PyResult<Py_hash_t>
sourcefn is_true(&self, py: Python<'_>) -> PyResult<bool>
fn is_true(&self, py: Python<'_>) -> PyResult<bool>
sourcefn len(&self, py: Python<'_>) -> PyResult<usize>
fn len(&self, py: Python<'_>) -> PyResult<usize>
sourcefn get_item<K>(&self, py: Python<'_>, key: K) -> PyResult<PyObject>where
K: ToPyObject,
fn get_item<K>(&self, py: Python<'_>, key: K) -> PyResult<PyObject>where
K: ToPyObject,
sourcefn set_item<K, V>(&self, py: Python<'_>, key: K, value: V) -> PyResult<()>where
K: ToPyObject,
V: ToPyObject,
fn set_item<K, V>(&self, py: Python<'_>, key: K, value: V) -> PyResult<()>where
K: ToPyObject,
V: ToPyObject,
sourceimpl PartialEq<PyObject> for PyObject
impl PartialEq<PyObject> for PyObject
PyObject implements the ==
operator using reference equality:
obj1 == obj2
in rust is equivalent to obj1 is obj2
in Python.
sourceimpl PythonObject for PyObject
impl PythonObject for PyObject
sourcefn into_object(self) -> PyObject
fn into_object(self) -> PyObject
sourceunsafe fn unchecked_downcast_from(o: PyObject) -> PyObject
unsafe fn unchecked_downcast_from(o: PyObject) -> PyObject
sourceunsafe fn unchecked_downcast_borrow_from(o: &PyObject) -> &PyObject
unsafe fn unchecked_downcast_borrow_from(o: &PyObject) -> &PyObject
sourceimpl PythonObjectWithCheckedDowncast for PyObject
impl PythonObjectWithCheckedDowncast for PyObject
sourcefn downcast_from(
_py: Python<'_>,
obj: PyObject
) -> Result<PyObject, PythonObjectDowncastError<'_>>
fn downcast_from(
_py: Python<'_>,
obj: PyObject
) -> Result<PyObject, PythonObjectDowncastError<'_>>
sourcefn downcast_borrow_from<'a, 'p>(
_py: Python<'p>,
obj: &'a PyObject
) -> Result<&'a PyObject, PythonObjectDowncastError<'p>>
fn downcast_borrow_from<'a, 'p>(
_py: Python<'p>,
obj: &'a PyObject
) -> Result<&'a PyObject, PythonObjectDowncastError<'p>>
sourceimpl PythonObjectWithTypeObject for PyObject
impl PythonObjectWithTypeObject for PyObject
sourcefn type_object(py: Python<'_>) -> PyType
fn type_object(py: Python<'_>) -> PyType
sourceimpl ToPyObject for PyObject
impl ToPyObject for PyObject
Identity conversion: allows using existing PyObject
instances where
T: ToPyObject
is expected.
type ObjectType = PyObject
sourcefn to_py_object(&self, py: Python<'_>) -> PyObject
fn to_py_object(&self, py: Python<'_>) -> PyObject
sourcefn into_py_object(self, _py: Python<'_>) -> PyObject
fn into_py_object(self, _py: Python<'_>) -> PyObject
impl Eq for PyObject
PyObject implements the ==
operator using reference equality:
obj1 == obj2
in rust is equivalent to obj1 is obj2
in Python.