cpython/Doc/c-api/coro.rst

.. highlightlang:: c

.. _coro-objects:

Coroutine Objects
-----------------

.. versionadded:: 3.5

Coroutine objects are what functions declared with an ``async`` keyword
return.


.. c:type:: PyCoroObject

   The C structure used for coroutine objects.


.. c:var:: PyTypeObject PyCoro_Type

   The type object corresponding to coroutine objects.


.. c:function:: int PyCoro_CheckExact(PyObject *ob)

   Return true if *ob*'s type is *PyCoro_Type*; *ob* must not be *NULL*.


.. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)

   Create and return a new coroutine object based on the *frame* object,
   with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
   A reference to *frame* is stolen by this function.  The *frame* argument
   must not be *NULL*.
Issue #24400: Introduce a distinct type for 'async def' coroutines. Summary of changes: 1. Coroutines now have a distinct, separate from generators type at the C level: PyGen_Type, and a new typedef PyCoroObject. PyCoroObject shares the initial segment of struct layout with PyGenObject, making it possible to reuse existing generators machinery. The new type is exposed as 'types.CoroutineType'. As a consequence of having a new type, CO_GENERATOR flag is no longer applied to coroutines. 2. Having a separate type for coroutines made it possible to add an __await__ method to the type. Although it is not used by the interpreter (see details on that below), it makes coroutines naturally (without using __instancecheck__) conform to collections.abc.Coroutine and collections.abc.Awaitable ABCs. [The __instancecheck__ is still used for generator-based coroutines, as we don't want to add __await__ for generators.] 3. Add new opcode: GET_YIELD_FROM_ITER. The opcode is needed to allow passing native coroutines to the YIELD_FROM opcode. Before this change, 'yield from o' expression was compiled to: (o) GET_ITER LOAD_CONST YIELD_FROM Now, we use GET_YIELD_FROM_ITER instead of GET_ITER. The reason for adding a new opcode is that GET_ITER is used in some contexts (such as 'for .. in' loops) where passing a coroutine object is invalid. 4. Add two new introspection functions to the inspec module: getcoroutinestate(c) and getcoroutinelocals(c). 5. inspect.iscoroutine(o) is updated to test if 'o' is a native coroutine object. Before this commit it used abc.Coroutine, and it was requested to update inspect.isgenerator(o) to use abc.Generator; it was decided, however, that inspect functions should really be tailored for checking for native types. 6. sys.set_coroutine_wrapper(w) API is updated to work with only native coroutines. Since types.coroutine decorator supports any type of callables now, it would be confusing that it does not work for all types of coroutines. 7. Exceptions logic in generators C implementation was updated to raise clearer messages for coroutines: Before: TypeError("generator raised StopIteration") After: TypeError("coroutine raised StopIteration") 2015-06-22 13:19:30 -03:00			`.. highlightlang:: c`

			`.. _coro-objects:`

			`Coroutine Objects`
			`-----------------`

			`.. versionadded:: 3.5`

			Coroutine objects are what functions declared with an ``async`` keyword
			`return.`


			`.. c:type:: PyCoroObject`

			`The C structure used for coroutine objects.`


			`.. c:var:: PyTypeObject PyCoro_Type`

			`The type object corresponding to coroutine objects.`


			`.. c:function:: int PyCoro_CheckExact(PyObject *ob)`

			`Return true if ob's type is PyCoro_Type; ob must not be NULL.`


			`.. c:function:: PyObject* PyCoro_New(PyFrameObject frame, PyObject name, PyObject *qualname)`

			`Create and return a new coroutine object based on the frame object,`
			with ``__name__`` and ``__qualname__`` set to name and qualname.
			`A reference to frame is stolen by this function. The frame argument`
			`must not be NULL.`