Struct PyObject 

pub struct PyObject(/* private fields */);

Implementations

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

impl PyObject

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>

impl PyObject

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

impl PyObject

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 unsafe fn try_to_owned_from_ptr(ptr: *mut Self) -> Option<PyObjectRef>

Like try_to_owned, but from a raw pointer.

Uses addr_of! to access ref_count without forming &PyObject, minimizing the borrow scope when the pointer may be stale (e.g. cache-hit paths protected by version guards).

Safety

ptr must point to a live (not yet deallocated) PyObject, or to memory whose ref_count field is still atomically readable (same guarantee as _Py_TryIncRefShared).

impl PyObject

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 const 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 const 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_raw(ptr: *mut PyObject) -> Vec<PyObjectRef>

Pop edges from this object for cycle breaking. Returns extracted child references that were removed from this object (tp_clear). This is used during garbage collection to break circular references.

Safety

• ptr must be a valid pointer to a PyObject
• The caller must have exclusive access (no other references exist)
• This is only safe during GC when the object is unreachable

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)

impl PyObject

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.

impl PyObject

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

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

impl PyObject

pub const 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>>

impl PyObject

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

impl PyObject

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

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

Trait Implementations

impl AsRef<PyObject> for ArgCallable

fn as_ref(&self) -> &PyObject

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

impl AsRef<PyObject> for ArgMapping

fn as_ref(&self) -> &PyObject

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

impl<A: AsRef<PyObject>, B: AsRef<PyObject>> AsRef<PyObject> for Either<A, B>

fn as_ref(&self) -> &PyObject

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

impl<T> AsRef<PyObject> for Py<T>

where T: PyPayload,

fn as_ref(&self) -> &PyObject

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

impl<T: PyPayload> AsRef<PyObject> for PyExact<T>

fn as_ref(&self) -> &PyObject

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

impl<O> AsRef<PyObject> for PyIter<O>

where O: Borrow<PyObject>,

fn as_ref(&self) -> &PyObject

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

impl AsRef<PyObject> for PyMapping<'_>

fn as_ref(&self) -> &PyObject

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

impl AsRef<PyObject> for PyObjectRef

fn as_ref(&self) -> &PyObject

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

impl<T> AsRef<PyObject> for PyRef<T>

where T: PyPayload,

fn as_ref(&self) -> &PyObject

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

impl<T: PyPayload> AsRef<PyObject> for PyRefExact<T>

fn as_ref(&self) -> &PyObject

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

impl Borrow<PyObject> for ArgCallable

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl Borrow<PyObject> for ArgMapping

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl<A: Borrow<PyObject>, B: Borrow<PyObject>> Borrow<PyObject> for Either<A, B>

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl<T: PyPayload> Borrow<PyObject> for Py<T>

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl<T: PyPayload> Borrow<PyObject> for PyExact<T>

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl<O> Borrow<PyObject> for PyIter<O>

where O: Borrow<PyObject>,

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl<T: PyPayload> Borrow<PyObject> for PyLease<'_, T>

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl Borrow<PyObject> for PyObjectRef

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl<T> Borrow<PyObject> for PyRef<T>

where T: PyPayload,

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl<T: PyPayload> Borrow<PyObject> for PyRefExact<T>

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl Debug for PyObject

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

Formats the value using the given formatter.

impl<'a, T: PyPayload> From<&'a Py<T>> for &'a PyObject

fn from(py_ref: &'a Py<T>) -> Self

Converts to this type from the input type.

impl ToOwned for PyObject

type Owned = PyObjectRef

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

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

impl ToPyObject for &PyObject

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

impl Traverse for PyObject

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

DO notice that call trace on PyObject means apply tracer_fn on PyObject’s children, not like call trace on PyObjectRef which apply tracer_fn on PyObjectRef itself

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.