Sitelet https://github.com/python/cpython/commit/f3e40fac10fa240b98a709191c6648fdd585b55f
Skip to content

Commit f3e40fa

Browse files
author
Yury Selivanov
committed
Issue 24180: Documentation for PEP 492 changes.
1 parent 548de2b commit f3e40fa

11 files changed

Lines changed: 483 additions & 8 deletions

File tree

‎Doc/c-api/typeobj.rst‎

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -220,9 +220,16 @@ type objects) *must* have the :attr:`ob_size` field.
220220
the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*.
221221

222222

223-
.. c:member:: void* PyTypeObject.tp_reserved
223+
.. c:member:: void* PyTypeObject.tp_as_async
224224
225-
Reserved slot, formerly known as tp_compare.
225+
Pointer to an additional structure that contains fields relevant only to
226+
objects which implement :term:`awaitable` and :term:`asynchronous iterator`
227+
protocols at the C-level. See :ref:`async-structs` for details.
228+
229+
.. versionadded:: 3.5
230+
231+
.. note::
232+
Formerly known as tp_compare and tp_reserved.
226233

227234

228235
.. c:member:: reprfunc PyTypeObject.tp_repr
@@ -1332,3 +1339,57 @@ Buffer Object Structures
13321339

13331340
:c:func:`PyBuffer_Release` is the interface for the consumer that
13341341
wraps this function.
1342+
1343+
1344+
.. _async-structs:
1345+
1346+
1347+
Async Object Structures
1348+
=======================
1349+
1350+
.. sectionauthor:: Yury Selivanov <yselivanov@sprymix.com>
1351+
1352+
1353+
.. c:type:: PyAsyncMethods
1354+
1355+
This structure holds pointers to the functions required to implement
1356+
:term:`awaitable` and :term:`asynchronous iterator` objects.
1357+
1358+
Here is the structure definition::
1359+
1360+
typedef struct {
1361+
getawaitablefunc am_await;
1362+
getaiterfunc am_aiter;
1363+
aiternextfunc am_anext;
1364+
} PyAsyncMethods;
1365+
1366+
.. c:member:: getawaitablefunc PyAsyncMethods.am_await
1367+
1368+
The signature of this function is::
1369+
1370+
PyObject *am_await(PyObject *self)
1371+
1372+
The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must
1373+
return ``1`` for it.
1374+
1375+
This slot may be set to *NULL* if an object is not an :term:`awaitable`.
1376+
1377+
.. c:member:: getaiterfunc PyAsyncMethods.am_aiter
1378+
1379+
The signature of this function is::
1380+
1381+
PyObject *am_aiter(PyObject *self)
1382+
1383+
Must return an :term:`awaitable` object. See :meth:`__anext__` for details.
1384+
1385+
This slot may be set to *NULL* if an object does not implement
1386+
asynchronous iteration protocol.
1387+
1388+
.. c:member:: aiternextfunc PyAsyncMethods.am_anext
1389+
1390+
The signature of this function is::
1391+
1392+
PyObject *am_anext(PyObject *self)
1393+
1394+
Must return an :term:`awaitable` object. See :meth:`__anext__` for details.
1395+
This slot may be set to *NULL*.

‎Doc/extending/newtypes.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ Moving on, we come to the crunch --- the type object. ::
8080
0, /* tp_print */
8181
0, /* tp_getattr */
8282
0, /* tp_setattr */
83-
0, /* tp_reserved */
83+
0, /* tp_as_async */
8484
0, /* tp_repr */
8585
0, /* tp_as_number */
8686
0, /* tp_as_sequence */

‎Doc/glossary.rst‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,11 +69,42 @@ Glossary
6969
:ref:`the difference between arguments and parameters
7070
<faq-argument-vs-parameter>`, and :pep:`362`.
7171

72+
asynchronous context manager
73+
An object which controls the environment seen in an
74+
:keyword:`async with` statement by defining :meth:`__aenter__` and
75+
:meth:`__aexit__` methods. Introduced by :pep:`492`.
76+
77+
.. versionadded:: 3.5
78+
79+
asynchronous iterable
80+
An object, that can be used in an :keyword:`async for` statement.
81+
Must return an :term:`awaitable` from its :meth:`__aiter__` method,
82+
which should in turn be resolved in an :term:`asynchronous iterator`
83+
object. Introduced by :pep:`492`.
84+
85+
.. versionadded:: 3.5
86+
87+
asynchronous iterator
88+
An object that implements :meth:`__aiter__` and :meth:`__anext__`
89+
methods, that must return :term:`awaitable` objects.
90+
:keyword:`async for` resolves awaitable returned from asynchronous
91+
iterator's :meth:`__anext__` method until it raises
92+
:exc:`StopAsyncIteration` exception. Introduced by :pep:`492`.
93+
94+
.. versionadded:: 3.5
95+
7296
attribute
7397
A value associated with an object which is referenced by name using
7498
dotted expressions. For example, if an object *o* has an attribute
7599
*a* it would be referenced as *o.a*.
76100

101+
awaitable
102+
An object that can be used in an :keyword:`await` expression. Can be
103+
a :term:`coroutine` or an object with an :meth:`__await__` method.
104+
See also :pep:`492`.
105+
106+
.. versionadded:: 3.5
107+
77108
BDFL
78109
Benevolent Dictator For Life, a.k.a. `Guido van Rossum
79110
<https://www.python.org/~guido/>`_, Python's creator.
@@ -146,6 +177,23 @@ Glossary
146177
statement by defining :meth:`__enter__` and :meth:`__exit__` methods.
147178
See :pep:`343`.
148179

180+
coroutine function
181+
A function which returns a :term:`coroutine` object. It is defined
182+
with an :keyword:`async def` keyword, and may contain :keyword:`await`,
183+
:keyword:`async for`, and :keyword:`async with` keywords. Introduced
184+
by :pep:`492`.
185+
186+
.. versionadded:: 3.5
187+
188+
coroutine
189+
Coroutines is a more generalized form of subroutines. Subroutines are
190+
entered at one point and exited at another point. Coroutines, can be
191+
entered, exited, and resumed at many different points. See
192+
:keyword:`await` expressions, and :keyword:`async for` and
193+
:keyword:`async with` statements. See also :pep:`492`.
194+
195+
.. versionadded:: 3.5
196+
149197
CPython
150198
The canonical implementation of the Python programming language, as
151199
distributed on `python.org <https://www.python.org>`_. The term "CPython"

‎Doc/library/collections.abc.rst‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,9 @@ The collections module offers the following :term:`ABCs <abstract base class>`:
3333

3434
.. tabularcolumns:: |l|L|L|L|
3535

36-
========================= ===================== ====================== ====================================================
36+
========================== ====================== ======================= ====================================================
3737
ABC Inherits from Abstract Methods Mixin Methods
38-
========================= ===================== ====================== ====================================================
38+
========================== ====================== ======================= ====================================================
3939
:class:`Container` ``__contains__``
4040
:class:`Hashable` ``__hash__``
4141
:class:`Iterable` ``__iter__``
@@ -81,7 +81,11 @@ ABC Inherits from Abstract Methods Mixin
8181
:class:`KeysView` :class:`MappingView`, ``__contains__``,
8282
:class:`Set` ``__iter__``
8383
:class:`ValuesView` :class:`MappingView` ``__contains__``, ``__iter__``
84-
========================= ===================== ====================== ====================================================
84+
:class:`Awaitable` ``__await__``
85+
:class:`Coroutine` ``send``, ``throw`` ``close``
86+
:class:`AsyncIterable` ``__aiter__``
87+
:class:`AsyncIterator` :class:`AsyncIterable` ``__anext__`` ``__aiter__``
88+
========================== ====================== ======================= ====================================================
8589

8690

8791
.. class:: Container
@@ -134,6 +138,41 @@ ABC Inherits from Abstract Methods Mixin
134138

135139
ABCs for mapping, items, keys, and values :term:`views <view>`.
136140

141+
.. class:: Awaitable
142+
143+
ABC for classes that provide ``__await__`` method. Instances
144+
of such classes can be used in ``await`` expression.
145+
146+
:term:`coroutine` objects and instances of
147+
:class:`~collections.abc.Coroutine` are too instances of this ABC.
148+
149+
.. versionadded:: 3.5
150+
151+
.. class:: Coroutine
152+
153+
ABC for coroutine compatible classes that implement a subset of
154+
generator methods defined in :pep:`342`, namely:
155+
:meth:`~generator.send`, :meth:`~generator.throw` and
156+
:meth:`~generator.close` methods. All :class:`Coroutine` instances
157+
are also instances of :class:`Awaitable`. See also the definition
158+
of :term:`coroutine`.
159+
160+
.. versionadded:: 3.5
161+
162+
.. class:: AsyncIterable
163+
164+
ABC for classes that provide ``__aiter__`` method. See also the
165+
definition of :term:`asynchronous iterable`.
166+
167+
.. versionadded:: 3.5
168+
169+
.. class:: AsyncIterator
170+
171+
ABC for classes that provide ``__aiter__`` and ``__anext__``
172+
methods. See also the definition of :term:`asynchronous iterator`.
173+
174+
.. versionadded:: 3.5
175+
137176

138177
These ABCs allow us to ask classes or instances if they provide
139178
particular functionality, for example::

‎Doc/library/exceptions.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,14 @@ The following exceptions are the exceptions that are usually raised.
322322
.. versionchanged:: 3.5
323323
Introduced the RuntimeError transformation.
324324

325+
.. exception:: StopAsyncIteration
326+
327+
Must be raised by :meth:`__anext__` method of an
328+
:term:`asynchronous iterator` object to stop the iteration.
329+
330+
.. versionadded:: 3.5
331+
See also :pep:`492`.
332+
325333
.. exception:: SyntaxError
326334

327335
Raised when the parser encounters a syntax error. This may occur in an

‎Doc/library/inspect.rst‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,47 @@ attributes:
266266
Return true if the object is a generator.
267267

268268

269+
.. function:: iscoroutinefunction(object)
270+
271+
Return true if the object is a coroutine function.
272+
273+
Coroutine functions are defined with an ``async def`` syntax,
274+
or are generators decorated with :func:`types.coroutine`
275+
or :func:`asyncio.coroutine`.
276+
277+
The function will return false for plain python generator
278+
functions.
279+
280+
See also :pep:`492`.
281+
282+
.. versionadded:: 3.5
283+
284+
285+
.. function:: iscoroutine(object)
286+
287+
Return true if the object is a coroutine.
288+
289+
Coroutines are results of calls of coroutine functions or
290+
generator functions decorated with :func:`types.coroutine`
291+
or :func:`asyncio.coroutine`.
292+
293+
The function will return false for plain python generators.
294+
295+
See also :class:`collections.abc.Coroutine` and :pep:`492`.
296+
297+
.. versionadded:: 3.5
298+
299+
300+
.. function:: isawaitable(object)
301+
302+
Return true if the object can be used in :keyword:`await`
303+
expression.
304+
305+
See also :class:`collections.abc.Awaitable` and :pep:`492`.
306+
307+
.. versionadded:: 3.5
308+
309+
269310
.. function:: istraceback(object)
270311

271312
Return true if the object is a traceback.

‎Doc/library/types.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,3 +271,17 @@ Additional Utility Classes and Functions
271271
attributes on the class with the same name (see Enum for an example).
272272

273273
.. versionadded:: 3.4
274+
275+
276+
Coroutines Utility Functions
277+
----------------------------
278+
279+
.. function:: coroutine(gen_func)
280+
281+
The function transforms a generator function to a :term:`coroutine function`,
282+
so that it returns a :term:`coroutine` object.
283+
284+
*gen_func* is modified in-place, hence the function can be used as a
285+
decorator.
286+
287+
.. versionadded:: 3.5

0 commit comments

Comments
 (0)