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

diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst
index 5706777c41db482fb2532ee53250c4ddd810215f..63290e0a7f0bf7e6ab4a1548c2e7cdb64ee1640b 100644 (file)
--- 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 1100af1df2928c58f2e7b295f62f66cd1031cb6b..42e3340acb79a02e1b5752d549ec20dbf2944517 100644 (file)
--- 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 8a6ee718a012dd904a5f5b1f97a2a4673e3b2e65..505f1203dd1bdd67d7af7ad69a6acff81bdd459f 100644 (file)
--- 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 67d01da3253073680622b6f4f9236657e27b5125..3adee103bce2d83eaf1d9ac6a3bb28bbde9072cf 100644 (file)
--- 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 4e2e58ee9dd8b0f3f3b7bdf22a17e4527bf7e845..5cb1df93702d683deca5b02797c4bca78fc14ea4 100644 (file)
--- 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)