Struct cpython::PyObject

#[repr(C)]
pub struct PyObject { /* fields omitted */ }

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.

Methods

impl 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.

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.

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.

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.

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

Gets the underlying FFI pointer. Returns a borrowed pointer.

#[must_use] pub fn steal_ptr(self) -> *mut PyObject

Gets the underlying FFI pointer. Consumes self without calling Py_DECREF(), thus returning an owned pointer.

pub unsafe fn borrow_from_ptr<'a>(ptr: &'a *mut PyObject) -> &'a PyObject

Transmutes an FFI pointer to &PyObject. Undefined behavior if the pointer is NULL or invalid.

pub unsafe fn borrow_from_owned_ptr_slice<'a>(
    ptr: &'a [*mut PyObject]
) -> &'a [PyObject]

Transmutes a slice of owned FFI pointers to &[PyObject]. Undefined behavior if any pointer in the slice is NULL or invalid.

pub fn get_refcnt(&self, _py: Python) -> usize

Gets the reference count of this Python object.

pub fn get_type(&self, py: Python) -> PyType

Gets the Python type object for this object's type.

pub unsafe fn unchecked_cast_into<T>(self) -> T where
    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().

pub fn cast_into<'p, T>(
    self,
    py: Python<'p>
) -> Result<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_from().

pub unsafe fn unchecked_cast_as<'s, T>(&'s self) -> &'s T where
    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().

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().

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

impl PythonObject for PyObject

fn as_object(&self) -> &PyObject

Casts the Python object to PyObject.

fn into_object(self) -> PyObject

Casts the Python object to PyObject.

unsafe fn unchecked_downcast_from(o: PyObject) -> PyObject

Unchecked downcast from PyObject to Self. Undefined behavior if the input object does not have the expected type.

unsafe fn unchecked_downcast_borrow_from(o: &PyObject) -> &PyObject

Unchecked downcast from PyObject to Self. Undefined behavior if the input object does not have the expected type.

impl PythonObjectWithCheckedDowncast for PyObject

fn downcast_from<'p>(
    _py: Python<'p>,
    obj: PyObject
) -> Result<PyObject, PythonObjectDowncastError<'p>>

Cast from PyObject to a concrete Python object type.

fn downcast_borrow_from<'a, 'p>(
    _py: Python<'p>,
    obj: &'a PyObject
) -> Result<&'a PyObject, PythonObjectDowncastError<'p>>

Cast from PyObject to a concrete Python object type.

impl PythonObjectWithTypeObject for PyObject

fn type_object(py: Python) -> PyType

Retrieves the type object for this Python object type.

impl ToPyObject for PyObject

Identity conversion: allows using existing PyObject instances where T: ToPyObject is expected.

type ObjectType = PyObject

fn to_py_object(&self, py: Python) -> PyObject

Converts self into a Python object.

fn into_py_object(self, _py: Python) -> PyObject

Converts self into a Python object.

fn with_borrowed_ptr<F, R>(&self, _py: Python, f: F) -> R where
    F: FnOnce(*mut PyObject) -> R, 

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

impl<'source> FromPyObject<'source> for PyObject

fn extract(py: Python, obj: &'source PyObject) -> PyResult<PyObject>

Extracts Self from the source PyObject.

impl<'source> FromPyObject<'source> for &'source PyObject

fn extract(py: Python, obj: &'source PyObject) -> PyResult<&'source PyObject>

Extracts Self from the source PyObject.

impl ObjectProtocol for PyObject

fn hasattr<N>(&self, py: Python, attr_name: N) -> PyResult<bool> where
    N: ToPyObject, 

Determines whether this object has the given attribute. This is equivalent to the Python expression 'hasattr(self, attr_name)'.

fn getattr<N>(&self, py: Python, attr_name: N) -> PyResult<PyObject> where
    N: ToPyObject, 

Retrieves an attribute value. This is equivalent to the Python expression 'self.attr_name'.

fn setattr<N, V>(&self, py: Python, attr_name: N, value: V) -> PyResult<()> where
    N: ToPyObject,
    V: ToPyObject, 

Sets an attribute value. This is equivalent to the Python expression 'self.attr_name = value'.

fn delattr<N>(&self, py: Python, attr_name: N) -> PyResult<()> where
    N: ToPyObject, 

Deletes an attribute. This is equivalent to the Python expression 'del self.attr_name'.

fn compare<O>(&self, py: Python, other: O) -> PyResult<Ordering> where
    O: ToPyObject, 

Compares two Python objects.

fn rich_compare<O>(
    &self,
    py: Python,
    other: O,
    compare_op: CompareOp
) -> PyResult<PyObject> where
    O: ToPyObject, 

Compares two Python objects.

fn repr(&self, py: Python) -> PyResult<PyString>

Compute the string representation of self. This is equivalent to the Python expression 'repr(self)'.

fn str(&self, py: Python) -> PyResult<PyString>

Compute the string representation of self. This is equivalent to the Python expression 'str(self)'.

fn is_callable(&self, _py: Python) -> bool

Determines whether this object is callable.

fn call<A>(
    &self,
    py: Python,
    args: A,
    kwargs: Option<&PyDict>
) -> PyResult<PyObject> where
    A: ToPyObject<ObjectType = PyTuple>, 

Calls the object. This is equivalent to the Python expression: 'self(*args, **kwargs)'

fn call_method<A>(
    &self,
    py: Python,
    name: &str,
    args: A,
    kwargs: Option<&PyDict>
) -> PyResult<PyObject> where
    A: ToPyObject<ObjectType = PyTuple>, 

Calls a method on the object. This is equivalent to the Python expression: 'self.name(*args, **kwargs)'

fn hash(&self, py: Python) -> PyResult<Py_hash_t>

Retrieves the hash code of the object. This is equivalent to the Python expression: 'hash(self)'

fn is_true(&self, py: Python) -> PyResult<bool>

Returns whether the object is considered to be true. This is equivalent to the Python expression: 'not not self'

fn len(&self, py: Python) -> PyResult<usize>

Returns the length of the sequence or mapping. This is equivalent to the Python expression: 'len(self)'

fn get_item<K>(&self, py: Python, key: K) -> PyResult<PyObject> where
    K: ToPyObject, 

This is equivalent to the Python expression: 'self[key]'

fn set_item<K, V>(&self, py: Python, key: K, value: V) -> PyResult<()> where
    K: ToPyObject,
    V: ToPyObject, 

Sets an item value. This is equivalent to the Python expression 'self[key] = value'.

fn del_item<K>(&self, py: Python, key: K) -> PyResult<()> where
    K: ToPyObject, 

Deletes an item. This is equivalent to the Python expression 'del self[key]'.

fn iter<'p>(&self, py: Python<'p>) -> PyResult<PyIterator<'p>>

Takes an object and returns an iterator for it. This is typically a new iterator but if the argument is an iterator, this returns itself.

impl BaseObject for PyObject

fn size() -> usize

Gets the size of the object, in bytes.

type InitType = ()

unsafe fn alloc(py: Python, ty: &PyType, _init_val: ()) -> PyResult<PyObject>

Allocates a new object (usually by calling ty->tp_alloc), and initializes it using init_val. ty must be derived from the Self type, and the resulting object must be of type ty.

unsafe fn dealloc(_py: Python, obj: *mut PyObject)

Calls the rust destructor for the object and frees the memory (usually by calling ptr->ob_type->tp_free). This function is used as tp_dealloc implementation.

impl Sync for PyObject

impl Drop for PyObject

Dropping a PyObject decrements the reference count on the object by 1.

fn drop(&mut self)

Executes the destructor for this type.

impl PartialEq<PyObject> for PyObject

PyObject implements the == operator using reference equality: obj1 == obj2 in rust is equivalent to obj1 is obj2 in Python.

fn eq(&self, o: &PyObject) -> bool

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Send for PyObject

impl Eq for PyObject

PyObject implements the == operator using reference equality: obj1 == obj2 in rust is equivalent to obj1 is obj2 in Python.

impl Debug for PyObject

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

Formats the value using the given formatter.

impl Display for PyObject

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

Formats the value using the given formatter.