python_doc_md/Advanced/c-api/iterator.md

# Iterator Objects

Python provides two general-purpose iterator objects. The first, a sequence iterator, works with an arbitrary sequence supporting the `~object.__getitem__`{.interpreted-text role="meth"} method. The second works with a callable object and a sentinel value, calling the callable for each item in the sequence, and ending the iteration when the sentinel value is returned.

> Type object for iterator objects returned by `PySeqIter_New`{.interpreted-text role="c:func"} and the one-argument form of the `iter`{.interpreted-text role="func"} built-in function for built-in sequence types.

> Return true if the type of *op* is `PySeqIter_Type`{.interpreted-text role="c:data"}. This function always succeeds.

> Return an iterator that works with a general sequence object, *seq*. The iteration ends when the sequence raises `IndexError`{.interpreted-text role="exc"} for the subscripting operation.

> Type object for iterator objects returned by `PyCallIter_New`{.interpreted-text role="c:func"} and the two-argument form of the `iter`{.interpreted-text role="func"} built-in function.

> Return true if the type of *op* is `PyCallIter_Type`{.interpreted-text role="c:data"}. This function always succeeds.

> Return a new iterator. The first parameter, *callable*, can be any Python callable object that can be called with no parameters; each call to it should return the next item in the iteration. When *callable* returns a value equal to *sentinel*, the iteration will be terminated.

## Range Objects

> The type object for `range`{.interpreted-text role="class"} objects.

> Return true if the object *o* is an instance of a `range`{.interpreted-text role="class"} object. This function always succeeds.

## Builtin Iterator Types

These are built-in iteration types that are included in Python\'s C API, but provide no additional functions. They are here for completeness.

  C type   Python type
  -------- ------------------------------------------------
           `enumerate`{.interpreted-text role="py:class"}
           `filter`{.interpreted-text role="py:class"}
           `map`{.interpreted-text role="py:class"}
           `reversed`{.interpreted-text role="py:class"}
           `zip`{.interpreted-text role="py:class"}

## Other Iterator Objects

> Type objects for iterators of various built-in objects.
>
> Do not create instances of these directly; prefer calling `PyObject_GetIter`{.interpreted-text role="c:func"} instead.
>
> Note that there is no guarantee that a given built-in type uses a given iterator type. For example, iterating over `range`{.interpreted-text role="class"} will use one of two iterator types depending on the size of the range. Other types may start using a similar scheme in the future, without warning.