[Python-checkins] bpo-31861: Complete the C-API docs for PyObject_GetAiter and PyAiter_Check (GH-25004)

[pablogsal]

https://github.com/python/cpython/commit/d9692027f41ee7600fe401c066617ebfc8bac930
commit: d9692027f41ee7600fe401c066617ebfc8bac930
branch: master
author: Pablo Galindo <Pablogsal at gmail.com>
committer: pablogsal <Pablogsal at gmail.com>
date: 2021-03-23T23:57:03Z
summary:

bpo-31861: Complete the C-API docs for PyObject_GetAiter and PyAiter_Check (GH-25004)

files:
M Doc/c-api/iter.rst
M Doc/c-api/object.rst
M Doc/data/refcounts.dat
M Doc/data/stable_abi.dat
M Doc/library/functions.rst

diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst
index 5706777c41db4..63290e0a7f0bf 100644
--- a/Doc/c-api/iter.rst
+++ b/Doc/c-api/iter.rst
@@ -12,6 +12,12 @@ There are two functions specifically for working with iterators.
    Return non-zero if the object *o* supports the iterator protocol, and ``0``
    otherwise.  This function always succeeds.
 
+.. c:function:: int PyAiter_Check(PyObject *o)
+
+   Returns non-zero if the object 'obj' provides :class:`AsyncIterator`
+   protocols, and ``0`` otherwise.  This function always succeeds.
+
+   .. versionadded:: 3.10
 
 .. c:function:: PyObject* PyIter_Next(PyObject *o)
 
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 1100af1df2928..42e3340acb79a 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -356,3 +356,14 @@ Object Protocol
    iterator for the object argument, or the object  itself if the object is already
    an iterator.  Raises :exc:`TypeError` and returns ``NULL`` if the object cannot be
    iterated.
+
+
+.. c:function:: PyObject* PyObject_GetAiter(PyObject *o)
+
+   This is the equivalent to the Python expression ``aiter(o)``. Takes an
+   :class:`AsyncIterable` object and returns an :class:`AsyncIterator` for it.
+   This is typically a new iterator but if the argument is an
+   :class:`AsyncIterator`, this returns itself. Raises :exc:`TypeError` and
+   returns ``NULL`` if the object cannot be iterated.
+
+   .. versionadded:: 3.10
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 8a6ee718a012d..505f1203dd1bd 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -1073,6 +1073,9 @@ PyInterpreterState_New:PyInterpreterState*:::
 PyIter_Check:int:::
 PyIter_Check:PyObject*:o:0:
 
+PyAiter_Check:int:::
+PyAiter_Check:PyObject*:o:0:
+
 PyIter_Next:PyObject*::+1:
 PyIter_Next:PyObject*:o:0:
 
@@ -1679,6 +1682,9 @@ PyObject_GetItem:PyObject*:key:0:
 PyObject_GetIter:PyObject*::+1:
 PyObject_GetIter:PyObject*:o:0:
 
+PyObject_GetAiter:PyObject*::+1:
+PyObject_GetAiter:PyObject*:o:0:
+
 PyObject_HasAttr:int:::
 PyObject_HasAttr:PyObject*:o:0:
 PyObject_HasAttr:PyObject*:attr_name:0:
diff --git a/Doc/data/stable_abi.dat b/Doc/data/stable_abi.dat
index 67d01da325307..3adee103bce2d 100644
--- a/Doc/data/stable_abi.dat
+++ b/Doc/data/stable_abi.dat
@@ -1,5 +1,6 @@
 # File generated by 'make regen-limited-abi'
 # This is NOT an authoritative list of stable ABI symbols
+PyAiter_Check
 PyArg_Parse
 PyArg_ParseTuple
 PyArg_ParseTupleAndKeywords
@@ -465,6 +466,7 @@ PyObject_GenericGetAttr
 PyObject_GenericGetDict
 PyObject_GenericSetAttr
 PyObject_GenericSetDict
+PyObject_GetAiter
 PyObject_GetAttr
 PyObject_GetAttrString
 PyObject_GetItem
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 4e2e58ee9dd8b..5cb1df93702d6 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -71,6 +71,7 @@ are always available.  They are listed here in alphabetical order.
 
    Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant.
 
+   .. versionadded:: 3.10
 
 .. function:: all(iterable)
 
@@ -97,6 +98,7 @@ are always available.  They are listed here in alphabetical order.
    iterator. If *default* is given, it is returned if the iterator is exhausted,
    otherwise :exc:`StopAsyncIteration` is raised.
 
+   .. versionadded:: 3.10
 
 .. function:: any(iterable)