Debian Codegraph @

Doc/c-api/iter.rst

raw
1 .. highlight:: c
2
3 .. _iterator:
4
5 Iterator Protocol
6 =================
7
8 There are two functions specifically for working with iterators.
9
10 .. c:function:: int PyIter_Check(PyObject *o)
11
12 Return non-zero if the object *o* can be safely passed to
13 :c:func:`PyIter_NextItem` and ``0`` otherwise.
14 This function always succeeds.
15
16 .. c:function:: int PyAIter_Check(PyObject *o)
17
18 Return non-zero if the object *o* provides the :class:`AsyncIterator`
19 protocol, and ``0`` otherwise. This function always succeeds.
20
21 .. versionadded:: 3.10
22
23 .. c:function:: int PyIter_NextItem(PyObject *iter, PyObject **item)
24
25 Return ``1`` and set *item* to a :term:`strong reference` of the
26 next value of the iterator *iter* on success.
27 Return ``0`` and set *item* to ``NULL`` if there are no remaining values.
28 Return ``-1``, set *item* to ``NULL`` and set an exception on error.
29
30 .. versionadded:: 3.14
31
32 .. c:function:: PyObject* PyIter_Next(PyObject *o)
33
34 This is an older version of :c:func:`!PyIter_NextItem`,
35 which is retained for backwards compatibility.
36 Prefer :c:func:`PyIter_NextItem`.
37
38 Return the next value from the iterator *o*. The object must be an iterator
39 according to :c:func:`PyIter_Check` (it is up to the caller to check this).
40 If there are no remaining values, returns ``NULL`` with no exception set.
41 If an error occurs while retrieving the item, returns ``NULL`` and passes
42 along the exception.
43
44 .. c:type:: PySendResult
45
46 The enum value used to represent different results of :c:func:`PyIter_Send`.
47
48 .. versionadded:: 3.10
49
50
51 .. c:function:: PySendResult PyIter_Send(PyObject *iter, PyObject *arg, PyObject **presult)
52
53 Sends the *arg* value into the iterator *iter*. Returns:
54
55 - ``PYGEN_RETURN`` if iterator returns. Return value is returned via *presult*.
56 - ``PYGEN_NEXT`` if iterator yields. Yielded value is returned via *presult*.
57 - ``PYGEN_ERROR`` if iterator has raised and exception. *presult* is set to ``NULL``.
58
59 .. versionadded:: 3.10