Struct PyObjectRef 

pub struct PyObjectRef { /* private fields */ }

The PyObjectRef is one of the most used types. It is a reference to a python object. A single python object can have multiple references, and this reference counting is accounted for by this type. Use the .clone() method to create a new reference and increment the amount of references to the python object by 1.

Implementations

impl PyObjectRef

pub fn try_complex( &self, vm: &VirtualMachine, ) -> PyResult<Option<(Complex64, bool)>>

Tries converting a python object into a complex, returns an option of whether the complex and whether the object was a complex originally or coerced into one

impl PyObjectRef

pub fn try_to_bool(self, vm: &VirtualMachine) -> PyResult<bool>

Convert Python bool into Rust bool.

impl PyObjectRef

pub fn try_into_value<T>(self, vm: &VirtualMachine) -> PyResult<T>

where T: TryFromObject,

impl PyObjectRef

pub const fn into_raw(self) -> NonNull<PyObject>

pub const unsafe fn from_raw(ptr: NonNull<PyObject>) -> Self

Safety

The raw pointer must have been previously returned from a call to PyObjectRef::into_raw. The user is responsible for ensuring that the inner data is not dropped more than once due to mishandling the reference count by calling this function too many times.

pub fn downcast<T: PyPayload>(self) -> Result<PyRef<T>, Self>

Attempt to downcast this reference to a subclass.

If the downcast fails, the original ref is returned in as Err so another downcast can be attempted without unnecessary cloning.

pub fn try_downcast<T: PyPayload>( self, vm: &VirtualMachine, ) -> PyResult<PyRef<T>>

pub unsafe fn downcast_unchecked<T>(self) -> PyRef<T>

Force to downcast this reference to a subclass.

Safety

T must be the exact payload type

pub fn downcast_exact<T: PyPayload>( self, vm: &VirtualMachine, ) -> Result<PyRefExact<T>, Self>

Attempt to downcast this reference to the specific class that is associated T.

If the downcast fails, the original ref is returned in as Err so another downcast can be attempted without unnecessary cloning.

impl PyObjectRef

pub fn rich_compare( self, other: Self, op_id: PyComparisonOp, vm: &VirtualMachine, ) -> PyResult

pub fn bytes(self, vm: &VirtualMachine) -> PyResult

pub fn is_true(self, vm: &VirtualMachine) -> PyResult<bool>

pub fn not(self, vm: &VirtualMachine) -> PyResult<bool>

pub fn length_hint( self, defaultvalue: usize, vm: &VirtualMachine, ) -> PyResult<usize>

pub fn dir(self, vm: &VirtualMachine) -> PyResult<PyList>

Methods from Deref<Target = PyObject>

pub fn try_to_value<'a, T>(&'a self, vm: &VirtualMachine) -> PyResult<T>

where T: 'a + TryFromBorrowedObject<'a>,

pub fn try_to_ref<'a, T>(&'a self, vm: &VirtualMachine) -> PyResult<&'a Py<T>>

where T: 'a + PyPayload,

pub fn try_value_with<T, F, R>(&self, f: F, vm: &VirtualMachine) -> PyResult<R>

where T: PyPayload, F: Fn(&T) -> PyResult<R>,

pub fn try_bytes_like<R>( &self, vm: &VirtualMachine, f: impl FnOnce(&[u8]) -> R, ) -> PyResult<R>

pub fn try_rw_bytes_like<R>( &self, vm: &VirtualMachine, f: impl FnOnce(&mut [u8]) -> R, ) -> PyResult<R>

pub fn as_interned_str( &self, vm: &VirtualMachine, ) -> Option<&'static PyStrInterned>

pub fn try_to_owned(&self) -> Option<PyObjectRef>

Atomically try to create a strong reference. Returns None if the strong count is already 0 (object being destroyed). Uses CAS to prevent the TOCTOU race between checking strong_count and incrementing it.

pub fn downgrade( &self, callback: Option<PyObjectRef>, vm: &VirtualMachine, ) -> PyResult<PyRef<PyWeak>>

pub fn get_weak_references(&self) -> Option<Vec<PyRef<PyWeak>>>

pub fn payload_is<T: PyPayload>(&self) -> bool

👎Deprecated:

use downcastable instead

pub unsafe fn payload_unchecked<T: PyPayload>(&self) -> &T

👎Deprecated:

use downcast_unchecked_ref instead

Force to return payload as T.

Safety

The actual payload type must be T.

pub fn payload<T: PyPayload>(&self) -> Option<&T>

👎Deprecated:

use downcast_ref instead

pub fn class(&self) -> &Py<PyType>

pub fn set_class(&self, typ: PyTypeRef, vm: &VirtualMachine)

pub fn payload_if_exact<T: PyPayload>(&self, vm: &VirtualMachine) -> Option<&T>

👎Deprecated:

use downcast_ref_if_exact instead

pub fn dict(&self) -> Option<PyDictRef>

pub fn set_dict(&self, dict: PyDictRef) -> Result<(), PyDictRef>

Set the dict field. Returns Err(dict) if this object does not have a dict field in the first place.

pub fn payload_if_subclass<T: PyPayload>( &self, vm: &VirtualMachine, ) -> Option<&T>

👎Deprecated:

use downcast_ref instead

pub fn downcastable<T: PyPayload>(&self) -> bool

Check if this object can be downcast to T.

pub fn try_downcast_ref<'a, T: PyPayload>( &'a self, vm: &VirtualMachine, ) -> PyResult<&'a Py<T>>

Attempt to downcast this reference to a subclass.

pub fn downcast_ref<T: PyPayload>(&self) -> Option<&Py<T>>

Attempt to downcast this reference to a subclass.

pub fn downcast_ref_if_exact<T: PyPayload>( &self, vm: &VirtualMachine, ) -> Option<&Py<T>>

pub unsafe fn downcast_unchecked_ref<T: PyPayload>(&self) -> &Py<T>

Safety

T must be the exact payload type

pub fn strong_count(&self) -> usize

pub fn weak_count(&self) -> Option<usize>

pub fn as_raw(&self) -> *const Self

pub fn is_gc_tracked(&self) -> bool

_PyObject_GC_IS_TRACKED

pub fn gc_get_referents(&self) -> Vec<PyObjectRef>

Get the referents (objects directly referenced) of this object. Uses the full traverse including dict and slots.

pub fn try_call_finalizer(&self)

Call del if present, without triggering object deallocation. Used by GC to call finalizers before breaking cycles. This allows proper resurrection detection. PyObject_CallFinalizerFromDealloc

pub fn gc_clear_weakrefs_collect_callbacks( &self, ) -> Vec<(PyRef<PyWeak>, PyObjectRef)>

Clear weakrefs but collect callbacks instead of calling them. This is used by GC to ensure ALL weakrefs are cleared BEFORE any callbacks run. Returns collected callbacks as (PyRef, callback) pairs.

pub unsafe fn gc_get_referent_ptrs(&self) -> Vec<NonNull<PyObject>>

Get raw pointers to referents without incrementing reference counts. This is used during GC to avoid reference count manipulation. tp_traverse visits objects without incref

Safety

The returned pointers are only valid as long as the object is alive and its contents haven’t been modified.

pub unsafe fn gc_clear(&self) -> Vec<PyObjectRef>

Clear this object for cycle breaking (tp_clear). This version takes &self but should only be called during GC when exclusive access is guaranteed.

Safety

• The caller must guarantee exclusive access (no other references exist)
• This is only safe during GC when the object is unreachable

pub fn gc_has_clear(&self) -> bool

Check if this object has clear capability (tp_clear)

pub fn to_callable(&self) -> Option<PyCallable<'_>>

pub fn is_callable(&self) -> bool

pub fn call(&self, args: impl IntoFuncArgs, vm: &VirtualMachine) -> PyResult

PyObject_CallArg series

pub fn call_with_args(&self, args: FuncArgs, vm: &VirtualMachine) -> PyResult

PyObject_Call

pub fn vectorcall( &self, args: Vec<PyObjectRef>, nargs: usize, kwnames: Option<&[PyObjectRef]>, vm: &VirtualMachine, ) -> PyResult

Vectorcall: call with owned positional args + optional kwnames. Falls back to FuncArgs-based call if no vectorcall slot.

pub fn mapping_unchecked(&self) -> PyMapping<'_>

pub fn try_mapping(&self, vm: &VirtualMachine) -> PyResult<PyMapping<'_>>

pub fn number(&self) -> PyNumber<'_>

pub fn try_index_opt(&self, vm: &VirtualMachine) -> Option<PyResult<PyIntRef>>

pub fn try_index(&self, vm: &VirtualMachine) -> PyResult<PyIntRef>

pub fn try_int(&self, vm: &VirtualMachine) -> PyResult<PyIntRef>

pub fn try_float_opt( &self, vm: &VirtualMachine, ) -> Option<PyResult<PyRef<PyFloat>>>

pub fn try_float(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyFloat>>

pub fn get_iter(&self, vm: &VirtualMachine) -> PyResult<PyIter>

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.

pub fn get_aiter(&self, vm: &VirtualMachine) -> PyResult

pub fn has_attr<'a>( &self, attr_name: impl AsPyStr<'a>, vm: &VirtualMachine, ) -> PyResult<bool>

pub fn get_attr<'a>( &self, attr_name: impl AsPyStr<'a>, vm: &VirtualMachine, ) -> PyResult

Get an attribute by name. attr_name can be a &str, String, or PyStrRef.

pub fn call_set_attr( &self, vm: &VirtualMachine, attr_name: &Py<PyStr>, attr_value: PySetterValue, ) -> PyResult<()>

pub fn set_attr<'a>( &self, attr_name: impl AsPyStr<'a>, attr_value: impl Into<PyObjectRef>, vm: &VirtualMachine, ) -> PyResult<()>

pub fn generic_setattr( &self, attr_name: &Py<PyStr>, value: PySetterValue, vm: &VirtualMachine, ) -> PyResult<()>

pub fn generic_getattr(&self, name: &Py<PyStr>, vm: &VirtualMachine) -> PyResult

pub fn generic_getattr_opt( &self, name_str: &Py<PyStr>, dict: Option<PyDictRef>, vm: &VirtualMachine, ) -> PyResult<Option<PyObjectRef>>

CPython _PyObject_GenericGetAttrWithDict

pub fn del_attr<'a>( &self, attr_name: impl AsPyStr<'a>, vm: &VirtualMachine, ) -> PyResult<()>

pub fn rich_compare_bool( &self, other: &Self, op_id: PyComparisonOp, vm: &VirtualMachine, ) -> PyResult<bool>

pub fn repr_utf8(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyUtf8Str>>

pub fn repr(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyStr>>

pub fn ascii(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyStr>>

pub fn str_utf8(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyUtf8Str>>

pub fn str(&self, vm: &VirtualMachine) -> PyResult<PyRef<PyStr>>

pub fn real_is_subclass( &self, cls: &Self, vm: &VirtualMachine, ) -> PyResult<bool>

Real issubclass check without going through subclasscheck This is equivalent to CPython’s _PyObject_RealIsSubclass which just calls recursive_issubclass

pub fn is_subclass(&self, cls: &Self, vm: &VirtualMachine) -> PyResult<bool>

Determines if self is a subclass of cls, either directly, indirectly or virtually via the subclasscheck magic method. PyObject_IsSubclass/object_issubclass

pub fn is_instance(&self, cls: &Self, vm: &VirtualMachine) -> PyResult<bool>

Determines if self is an instance of cls, either directly, indirectly or virtually via the instancecheck magic method.

pub fn hash(&self, vm: &VirtualMachine) -> PyResult<PyHash>

pub fn obj_type(&self) -> PyObjectRef

pub fn type_check(&self, typ: &Py<PyType>) -> bool

pub fn length_opt(&self, vm: &VirtualMachine) -> Option<PyResult<usize>>

pub fn length(&self, vm: &VirtualMachine) -> PyResult<usize>

pub fn get_item<K: DictKey + ?Sized>( &self, needle: &K, vm: &VirtualMachine, ) -> PyResult

pub fn set_item<K: DictKey + ?Sized>( &self, needle: &K, value: PyObjectRef, vm: &VirtualMachine, ) -> PyResult<()>

pub fn del_item<K: DictKey + ?Sized>( &self, needle: &K, vm: &VirtualMachine, ) -> PyResult<()>

pub fn lookup_special( &self, attr: &Py<PyStr>, vm: &VirtualMachine, ) -> Option<PyObjectRef>

Equivalent to CPython’s _PyObject_LookupSpecial Looks up a special method in the type’s MRO without checking instance dict. Returns None if not found (masking AttributeError like CPython).

pub fn sequence_unchecked(&self) -> PySequence<'_>

pub fn try_sequence(&self, vm: &VirtualMachine) -> PyResult<PySequence<'_>>

Trait Implementations

impl AsRef<PyObject> for PyObjectRef

fn as_ref(&self) -> &PyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<PyObject> for PyObjectRef

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl Clone for PyObjectRef

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 PyObjectRef

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

Formats the value using the given formatter.

impl Deref for PyObjectRef

type Target = PyObject

The resulting type after dereferencing.

fn deref(&self) -> &PyObject

Dereferences the value.

impl Drop for PyObjectRef

fn drop(&mut self)

Executes the destructor for this type.

impl Dumpable for PyObjectRef

type Error = DumpError

type Constant = Literal

fn with_dump<R>( &self, f: impl FnOnce(DumpableValue<'_, Self>) -> R, ) -> Result<R, Self::Error>

impl From<ArgBytesLike> for PyObjectRef

fn from(buffer: ArgBytesLike) -> Self

Converts to this type from the input type.

impl From<ArgCallable> for PyObjectRef

fn from(value: ArgCallable) -> Self

Converts to this type from the input type.

impl From<ArgMapping> for PyObjectRef

fn from(value: ArgMapping) -> Self

Converts to this type from the input type.

impl<A: Into<Self>, B: Into<Self>> From<Either<A, B>> for PyObjectRef

fn from(value: Either<A, B>) -> Self

Converts to this type from the input type.

impl From<PyIter> for PyObjectRef

fn from(value: PyIter<Self>) -> Self

Converts to this type from the input type.

impl From<PyObjectRef> for PyAtomicRef<PyObject>

fn from(obj: PyObjectRef) -> Self

Converts to this type from the input type.

impl From<PyObjectRef> for PyClassMethod

fn from(callable: PyObjectRef) -> Self

Converts to this type from the input type.

impl From<PyObjectRef> for PyStaticMethod

fn from(callable: PyObjectRef) -> Self

Converts to this type from the input type.

impl<T> From<PyRef<T>> for PyObjectRef

fn from(value: PyRef<T>) -> Self

Converts to this type from the input type.

impl FromIterator<PyObjectRef> for PyList

fn from_iter<T: IntoIterator<Item = PyObjectRef>>(iter: T) -> Self

Creates a value from an iterator.

impl ToPyObject for PyObjectRef

fn to_pyobject(self, _vm: &VirtualMachine) -> PyObjectRef

impl Traverse for PyObjectRef

fn traverse(&self, traverse_fn: &mut TraverseFn<'_>)

impl traverse() with caution! Following those guideline so traverse doesn’t cause memory error!:

fn clear(&mut self, _out: &mut Vec<PyObjectRef>)

Extract all owned child PyObjectRefs for circular reference resolution (tp_clear). Called just before object deallocation to break circular references. Default implementation does nothing.

impl TryFromObject for PyObjectRef

fn try_from_object(_vm: &VirtualMachine, obj: PyObjectRef) -> PyResult<Self>

Attempt to convert a Python object to a value of this type.