| 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. |