From cadfc16bdf2a8b9cab1230ece5d51812e42c3ab8 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 4 Nov 2025 12:12:05 -0500 Subject: [PATCH 1/9] Document PyByteArrayIter_Type --- Doc/c-api/bytearray.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst index e2b22ec3c794ae..796faed58383ce 100644 --- a/Doc/c-api/bytearray.rst +++ b/Doc/c-api/bytearray.rst @@ -19,6 +19,11 @@ Byte Array Objects it is the same object as :class:`bytearray` in the Python layer. +.. c:var:: PyTypeObject PyByteArrayIter_Type + + Iterator over a :class:`bytearray` object. + + Type check macros ^^^^^^^^^^^^^^^^^ From e4b2dad4d0b62a6c31ccfab8605c27a02e7b5731 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 4 Nov 2025 12:15:00 -0500 Subject: [PATCH 2/9] Document PyBytesIter_Type --- Doc/c-api/bytearray.rst | 3 ++- Doc/c-api/bytes.rst | 6 ++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst index 796faed58383ce..c902f3335cb9db 100644 --- a/Doc/c-api/bytearray.rst +++ b/Doc/c-api/bytearray.rst @@ -21,7 +21,8 @@ Byte Array Objects .. c:var:: PyTypeObject PyByteArrayIter_Type - Iterator over a :class:`bytearray` object. + Type object for an iterator over a :class:`bytearray` object. Instances + of this object are returned by :meth:`!bytearray.__iter__`. Type check macros diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index 865a9e5d2bf5d5..f4a25f2357da40 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -22,6 +22,12 @@ called with a non-bytes parameter. is the same object as :class:`bytes` in the Python layer. +.. c:var:: PyTypeObject PyByteIter_Type + + Type object for an iterator over a :class:`bytes` object. Instances + of this object are returned by :meth:`!bytes.__iter__`. + + .. c:function:: int PyBytes_Check(PyObject *o) Return true if the object *o* is a bytes object or an instance of a subtype From 2902970455cead85b6c4f9a3d372cc2699bc0e13 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 4 Nov 2025 12:15:19 -0500 Subject: [PATCH 3/9] Fix missing s. --- Doc/c-api/bytes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index f4a25f2357da40..76bb5656bddb32 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -22,7 +22,7 @@ called with a non-bytes parameter. is the same object as :class:`bytes` in the Python layer. -.. c:var:: PyTypeObject PyByteIter_Type +.. c:var:: PyTypeObject PyBytesIter_Type Type object for an iterator over a :class:`bytes` object. Instances of this object are returned by :meth:`!bytes.__iter__`. From 8d6310497d507eea03f3c1c25f7fc7af598a99d0 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 4 Nov 2025 12:17:28 -0500 Subject: [PATCH 4/9] Document PyListIter_Type, PyListRevIter_Type --- Doc/c-api/list.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst index 758415a76e5cb4..e86afe6a6106d5 100644 --- a/Doc/c-api/list.rst +++ b/Doc/c-api/list.rst @@ -181,3 +181,18 @@ List Objects Return a new tuple object containing the contents of *list*; equivalent to ``tuple(list)``. + +List Iterators +^^^^^^^^^^^^^^ + + +.. c:var:: PyTypeObject PyListIter_Type + + Type object for an iterator over a :class:`list` object. Instances + of this object are returned by :meth:`!bytes.__iter__`. + + +.. c:var:: PyTypeObject PyListRevIter_Type + + Type object for a reversed iterator over a :class:`list` object. + Instances of this object are returned by :meth:`!bytes.__reversed__`. From c8fb023bc6836d8e809fe6f2700e5d20563136f3 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 4 Nov 2025 12:45:25 -0500 Subject: [PATCH 5/9] Document PySetIter_Type --- Doc/c-api/set.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index cba823aa027bd6..da6671257d6fac 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -41,6 +41,12 @@ the abstract object protocol (including :c:func:`PyObject_CallMethod`, :class:`set` type. +.. c:var:: PyTypeObject PySetIter_Type + + Type object for an iterator over a :class:`set` object. Instances + of this object are returned by :meth:`!set.__iter__`. + + .. c:var:: PyTypeObject PyFrozenSet_Type This is an instance of :c:type:`PyTypeObject` representing the Python From 1c2797f9eb77ec66dd0e4a4e545984a4757cdcd3 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 4 Nov 2025 12:45:52 -0500 Subject: [PATCH 6/9] Document PyTupleIter_Type --- Doc/c-api/tuple.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index d0add48d7e8457..5d7edb3cebbb12 100644 --- a/Doc/c-api/tuple.rst +++ b/Doc/c-api/tuple.rst @@ -19,6 +19,12 @@ Tuple Objects is the same object as :class:`tuple` in the Python layer. +.. c:var:: PyTypeObject PyTupleIter_Type + + Type object for an iterator over a :class:`tuple` object. Instances + of this object are returned by :meth:`!tuple.__iter__`. + + .. c:function:: int PyTuple_Check(PyObject *p) Return true if *p* is a tuple object or an instance of a subtype of the From 0d06ccee16115e4f1be3750b403ccdefd52bacfa Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 5 Nov 2025 07:07:03 -0500 Subject: [PATCH 7/9] Don't expose implementation details. Co-authored-by: Petr Viktorin --- Doc/c-api/bytearray.rst | 6 ------ Doc/c-api/bytes.rst | 6 ------ Doc/c-api/iterator.rst | 30 ++++++++++++++++++++++++++++++ Doc/c-api/list.rst | 15 --------------- Doc/c-api/set.rst | 6 ------ Doc/c-api/tuple.rst | 6 ------ 6 files changed, 30 insertions(+), 39 deletions(-) diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst index c902f3335cb9db..e2b22ec3c794ae 100644 --- a/Doc/c-api/bytearray.rst +++ b/Doc/c-api/bytearray.rst @@ -19,12 +19,6 @@ Byte Array Objects it is the same object as :class:`bytearray` in the Python layer. -.. c:var:: PyTypeObject PyByteArrayIter_Type - - Type object for an iterator over a :class:`bytearray` object. Instances - of this object are returned by :meth:`!bytearray.__iter__`. - - Type check macros ^^^^^^^^^^^^^^^^^ diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index 76bb5656bddb32..865a9e5d2bf5d5 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -22,12 +22,6 @@ called with a non-bytes parameter. is the same object as :class:`bytes` in the Python layer. -.. c:var:: PyTypeObject PyBytesIter_Type - - Type object for an iterator over a :class:`bytes` object. Instances - of this object are returned by :meth:`!bytes.__iter__`. - - .. c:function:: int PyBytes_Check(PyObject *o) Return true if the object *o* is a bytes object or an instance of a subtype diff --git a/Doc/c-api/iterator.rst b/Doc/c-api/iterator.rst index 6b7ba8c9979163..db2f6b72af0857 100644 --- a/Doc/c-api/iterator.rst +++ b/Doc/c-api/iterator.rst @@ -50,3 +50,33 @@ sentinel value is returned. callable object that can be called with no parameters; each call to it should return the next item in the iteration. When *callable* returns a value equal to *sentinel*, the iteration will be terminated. + + +Other Iterator Objects +^^^^^^^^^^^^^^^^^^^^^^ + +.. c:var:: PyTypeObject PyByteArrayIter_Type +.. c:var:: PyTypeObject PyBytesIter_Type +.. c:var:: PyTypeObject PyListIter_Type +.. c:var:: PyTypeObject PyListRevIter_Type +.. c:var:: PyTypeObject PySetIter_Type +.. c:var:: PyTypeObject PyTupleIter_Type +.. c:var:: PyTypeObject PyRangeIter_Type +.. c:var:: PyTypeObject PyLongRangeIter_Type +.. c:var:: PyTypeObject PyDictIterKey_Type +.. c:var:: PyTypeObject PyDictRevIterKey_Type +.. c:var:: PyTypeObject PyDictIterValue_Type +.. c:var:: PyTypeObject PyDictRevIterValue_Type +.. c:var:: PyTypeObject PyDictIterItem_Type +.. c:var:: PyTypeObject PyDictRevIterItem_Type + + Type objects for iterators of various built-in objects. + + Do not create instances of these directly; prefer calling + :func:`PyObject_GetIter` instead. + + Note that there is no guarantee that a given built-in type uses a given iterator + type. For example, iterating over :class:`range` will use one of two iterator + types depending on the size of the range. Other types may start using a + similar scheme in the future, without warning. + diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst index e86afe6a6106d5..758415a76e5cb4 100644 --- a/Doc/c-api/list.rst +++ b/Doc/c-api/list.rst @@ -181,18 +181,3 @@ List Objects Return a new tuple object containing the contents of *list*; equivalent to ``tuple(list)``. - -List Iterators -^^^^^^^^^^^^^^ - - -.. c:var:: PyTypeObject PyListIter_Type - - Type object for an iterator over a :class:`list` object. Instances - of this object are returned by :meth:`!bytes.__iter__`. - - -.. c:var:: PyTypeObject PyListRevIter_Type - - Type object for a reversed iterator over a :class:`list` object. - Instances of this object are returned by :meth:`!bytes.__reversed__`. diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index da6671257d6fac..cba823aa027bd6 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -41,12 +41,6 @@ the abstract object protocol (including :c:func:`PyObject_CallMethod`, :class:`set` type. -.. c:var:: PyTypeObject PySetIter_Type - - Type object for an iterator over a :class:`set` object. Instances - of this object are returned by :meth:`!set.__iter__`. - - .. c:var:: PyTypeObject PyFrozenSet_Type This is an instance of :c:type:`PyTypeObject` representing the Python diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index 5d7edb3cebbb12..d0add48d7e8457 100644 --- a/Doc/c-api/tuple.rst +++ b/Doc/c-api/tuple.rst @@ -19,12 +19,6 @@ Tuple Objects is the same object as :class:`tuple` in the Python layer. -.. c:var:: PyTypeObject PyTupleIter_Type - - Type object for an iterator over a :class:`tuple` object. Instances - of this object are returned by :meth:`!tuple.__iter__`. - - .. c:function:: int PyTuple_Check(PyObject *p) Return true if *p* is a tuple object or an instance of a subtype of the From 69e49760b078b80908c64e45e847ed8ee0a90966 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 5 Nov 2025 07:10:18 -0500 Subject: [PATCH 8/9] Fix newline thingy. --- Doc/c-api/iterator.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/c-api/iterator.rst b/Doc/c-api/iterator.rst index db2f6b72af0857..e9015ebffacee1 100644 --- a/Doc/c-api/iterator.rst +++ b/Doc/c-api/iterator.rst @@ -79,4 +79,3 @@ Other Iterator Objects type. For example, iterating over :class:`range` will use one of two iterator types depending on the size of the range. Other types may start using a similar scheme in the future, without warning. - From b2bc1d9ea94bc1749e46e2fda6c6134d21b4da25 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 5 Nov 2025 08:53:54 -0500 Subject: [PATCH 9/9] Update Doc/c-api/iterator.rst Co-authored-by: Petr Viktorin --- Doc/c-api/iterator.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/iterator.rst b/Doc/c-api/iterator.rst index e9015ebffacee1..4b94970036f543 100644 --- a/Doc/c-api/iterator.rst +++ b/Doc/c-api/iterator.rst @@ -73,7 +73,7 @@ Other Iterator Objects Type objects for iterators of various built-in objects. Do not create instances of these directly; prefer calling - :func:`PyObject_GetIter` instead. + :c:func:`PyObject_GetIter` instead. Note that there is no guarantee that a given built-in type uses a given iterator type. For example, iterating over :class:`range` will use one of two iterator