Struct PyIter 

pub struct PyIter<O = PyObjectRef>(/* private fields */)
where
    O: Borrow<PyObject>;

Iterator Protocol.

Implementations

impl PyIter<PyObjectRef>

pub fn check(obj: &PyObject) -> bool

impl<O> PyIter<O>

where O: Borrow<PyObject>,

pub const fn new(obj: O) -> Self

pub fn next(&self, vm: &VirtualMachine) -> PyResult<PyIterReturn>

pub fn iter<'a, 'b, U>( &'b self, vm: &'a VirtualMachine, ) -> PyResult<PyIterIter<'a, U, &'b PyObject>>

Walks the iterator without asking it how long it is. Almost nothing asks: a loop over an iterator takes no room up front, so what the object would have answered – slowly, or by raising – never runs.

impl PyIter<PyObjectRef>

pub fn into_iter<U>(self, vm: &VirtualMachine) -> PyIterIter<'_, U, PyObjectRef>

Returns an iterator over this sequence of objects. See Self::iter for why it does not ask how long the iterator is.

pub fn into_iter_sized<U>( self, vm: &VirtualMachine, ) -> PyResult<PyIterIter<'_, U, PyObjectRef>>

Self::into_iter for a caller that fills a sized container from the iterator, the way PySequence_Fast() does. It asks how much room that takes and answers with whatever asking raised.

Methods from Deref<Target = PyObject>

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

Convert Python bool into Rust bool.

Takes &self rather than an owned reference so that the eval loop can call it straight through a borrowed stack entry, without the reference count round trip that owning the operand would cost.

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(&Py<T>) -> PyResult<R>,

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

where F: FnOnce(&[u8]) -> R,

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

where F: FnOnce(&mut [u8]) -> 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 clear_weak_refs(&self)

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 has_inline_values(&self) -> bool

_PyObject_InlineValues(obj)->valid when the type has INLINE_VALUES.

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

pub fn has_instance_dict(&self) -> bool

Whether this object currently has an instance dict, without cloning it.

false both for an object with no dict slot and for one whose slot is still empty, which is what dict().is_none() reports.

pub fn set_dict(&self, dict: Option<PyDictRef>) -> Result<(), Option<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 gc_finalized(&self) -> bool

Check if the object has been finalized (del already called). _PyGC_FINALIZED in Py_GIL_DISABLED mode.

pub fn make_immortal(&self)

Make this object live for the whole process (PEP 683).

Every later reference operation on it becomes a relaxed load and a branch instead of an atomic read-modify-write — and a decref in particular stops paying for a Release store, which is the expensive half of the pair on a weakly ordered target. RefCount’s IMMORTAL documents the full invariant; the parts that bind a caller:

• The object is never deallocated, so its __del__ and its weakref callbacks never run. Only grant this to something an owner already keeps for the whole process — a static_cell, the Context, the string pool.
• Self::strong_count reports a number far past any real total, so the object stays out of every strong_count() == 1 in-place-mutation fast path and the cycle collector reads it as a permanent root.

This is not interning: Self::is_interned answers from a separate bit and keeps meaning “this string is the pool’s copy”.

pub fn is_immortal(&self) -> bool

Whether this object lives for the whole process.

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<Self>>

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_extend_referent_ptrs(&self, out: &mut Vec<NonNull<Self>>)

Append this object’s referents to out, for a caller that holds many objects’ referents in one buffer rather than one buffer each.

Safety

Same as Self::gc_get_referent_ptrs.

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 check_buffer(&self) -> bool

Whether this object’s type exports the buffer protocol. PyObject_CheckBuffer

A consumer that falls back to something else for non-buffer objects asks this instead of attempting an acquisition, so that an error raised by __buffer__ is not mistaken for “not a buffer”.

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>

hasattr() lookup. Missing attributes are false; other errors propagate.

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( &self, other: &Self, op_id: PyComparisonOp, vm: &VirtualMachine, ) -> PyResult

PyObject_RichCompare over two references the caller does not own.

The eval loop reaches this through borrowed stack entries, so taking &self here is what keeps COMPARE_OP free of reference counting.

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, ) -> PyResult<Option<PyObjectRef>>

_PyObject_LookupSpecial: look up a special method in the type MRO without checking the instance dict. A miss is silent; a descr_get error is propagated.

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

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

Trait Implementations

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<O> Borrow<PyObject> for PyIter<O>

where O: Borrow<PyObject>,

fn borrow(&self) -> &PyObject

Immutably borrows from an owned value.

impl<O> Clone for PyIter<O>

where O: Borrow<PyObject> + Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<O> Debug for PyIter<O>

where O: Borrow<PyObject> + Debug,

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

Formats the value using the given formatter.

impl<O> Deref for PyIter<O>

where O: Borrow<PyObject>,

type Target = PyObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl From<PyIter> for PyObjectRef

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

Converts to this type from the input type.

impl ToPyObject for PyIter<PyObjectRef>

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

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

fn traverse(&self, tracer_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 PyIter<PyObjectRef>

fn try_from_object( vm: &VirtualMachine, iter_target: PyObjectRef, ) -> PyResult<Self>

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