Debian Codegraph @

Doc/c-api/gen.rst

raw
1 .. highlight:: c
2
3 .. _gen-objects:
4
5 Generator Objects
6 -----------------
7
8 Generator objects are what Python uses to implement generator iterators. They
9 are normally created by iterating over a function that yields values, rather
10 than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
11
12
13 .. c:type:: PyGenObject
14
15 The C structure used for generator objects.
16
17
18 .. c:var:: PyTypeObject PyGen_Type
19
20 The type object corresponding to generator objects.
21
22
23 .. c:function:: int PyGen_Check(PyObject *ob)
24
25 Return true if *ob* is a generator object; *ob* must not be ``NULL``. This
26 function always succeeds.
27
28
29 .. c:function:: int PyGen_CheckExact(PyObject *ob)
30
31 Return true if *ob*'s type is :c:type:`PyGen_Type`; *ob* must not be
32 ``NULL``. This function always succeeds.
33
34
35 .. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
36
37 Create and return a new generator object based on the *frame* object.
38 A reference to *frame* is stolen by this function. The argument must not be
39 ``NULL``.
40
41 .. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
42
43 Create and return a new generator object based on the *frame* object,
44 with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
45 A reference to *frame* is stolen by this function. The *frame* argument
46 must not be ``NULL``.
47
48
49 .. c:function:: PyCodeObject* PyGen_GetCode(PyGenObject *gen)
50
51 Return a new :term:`strong reference` to the code object wrapped by *gen*.
52 This function always succeeds.
53
54
55 Asynchronous Generator Objects
56 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
57
58 .. seealso::
59 :pep:`525`
60
61 .. c:var:: PyTypeObject PyAsyncGen_Type
62
63 The type object corresponding to asynchronous generator objects. This is
64 available as :class:`types.AsyncGeneratorType` in the Python layer.
65
66 .. versionadded:: 3.6
67
68 .. c:function:: PyObject *PyAsyncGen_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
69
70 Create a new asynchronous generator wrapping *frame*, with ``__name__`` and
71 ``__qualname__`` set to *name* and *qualname*. *frame* is stolen by this
72 function and must not be ``NULL``.
73
74 On success, this function returns a :term:`strong reference` to the
75 new asynchronous generator. On failure, this function returns ``NULL``
76 with an exception set.
77
78 .. versionadded:: 3.6
79
80 .. c:function:: int PyAsyncGen_CheckExact(PyObject *op)
81
82 Return true if *op* is an asynchronous generator object, false otherwise.
83 This function always succeeds.
84
85 .. versionadded:: 3.6
86
87
88 Deprecated API
89 ^^^^^^^^^^^^^^
90
91 .. c:macro:: PyAsyncGenASend_CheckExact(op)
92
93 This is a :term:`soft deprecated` API that was included in Python's C API
94 by mistake.
95
96 It is solely here for completeness; do not use this API.