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

intPyIter_NextItem(PyObject*iter,PyObject**item)
Part of theStable ABI since version 3.14.

Return1 and setitem to astrong reference of thenext value of the iteratoriter on success.Return0 and setitem toNULL if there are no remaining values.Return-1, setitem toNULL and set an exception on error.

Added in version 3.14.

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

This is an older version ofPyIter_NextItem(),which is retained for backwards compatibility.PreferPyIter_NextItem().

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.

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.