Iterator Protocol

There are two functions specifically for working with iterators.

intPyIter_Check(PyObject*o)
Part of theStable ABI since version 3.8.

Return non-zero if the objecto can be safely passed toPyIter_Next(), and0 otherwise. This function always succeeds.

intPyAIter_Check(PyObject*o)
Part of theStable ABI since version 3.10.

Return non-zero if the objecto provides theAsyncIteratorprotocol, and0 otherwise. This function always succeeds.

Added in version 3.10.

PyObject*PyIter_Next(PyObject*o)
Return value: New reference. Part of theStable ABI.

Return the next value from the iteratoro. The object must be an iteratoraccording toPyIter_Check() (it is up to the caller to check this).If there are no remaining values, returnsNULL with no exception set.If an error occurs while retrieving the item, returnsNULL and passesalong the exception.

To write a loop which iterates over an iterator, the C code should looksomething like this:

PyObject*iterator=PyObject_GetIter(obj);PyObject*item;if(iterator==NULL){/* propagate error */}while((item=PyIter_Next(iterator))){/* do something with item */.../* release reference when done */Py_DECREF(item);}Py_DECREF(iterator);if(PyErr_Occurred()){/* propagate error */}else{/* continue doing useful work */}
typePySendResult

The enum value used to represent different results ofPyIter_Send().

Added in version 3.10.

PySendResultPyIter_Send(PyObject*iter,PyObject*arg,PyObject**presult)
Part of theStable ABI since version 3.10.

Sends thearg value into the iteratoriter. Returns:

  • PYGEN_RETURN if iterator returns. Return value is returned viapresult.

  • PYGEN_NEXT if iterator yields. Yielded value is returned viapresult.

  • PYGEN_ERROR if iterator has raised and exception.presult is set toNULL.

Added in version 3.10.