Skip to content

gh-141004: Document remaining iterator types #141010

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ZeroIntensity merged 9 commits into from
Nov 5, 2025
Merged

gh-141004: Document remaining iterator types #141010

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
cadfc16
Document PyByteArrayIter_Type
ZeroIntensity Nov 4, 2025
e4b2dad
Document PyBytesIter_Type
ZeroIntensity Nov 4, 2025
2902970
Fix missing s.
ZeroIntensity Nov 4, 2025
8d63104
Document PyListIter_Type, PyListRevIter_Type
ZeroIntensity Nov 4, 2025
c8fb023
Document PySetIter_Type
ZeroIntensity Nov 4, 2025
1c2797f
Document PyTupleIter_Type
ZeroIntensity Nov 4, 2025
0d06cce
Don't expose implementation details.
ZeroIntensity Nov 5, 2025
69e4976
Fix newline thingy.
ZeroIntensity Nov 5, 2025
b2bc1d9
Update Doc/c-api/iterator.rst
ZeroIntensity Nov 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions Doc/c-api/bytearray.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@ 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__`.
Copy link
Member

@encukou encukou Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This would imply that all bytearray iterators have a single type, which would mean that no implementation of the C API can do the kind of optimization we did for range.
(Not too relevant for bytearray in particular, but you're adding the same docs for all the iterators.)

Copy link
Member Author

@ZeroIntensity ZeroIntensity Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you prefer that I remove the second sentence?

(I appreciate your feedback on these, by the way!)

Copy link
Member

@encukou encukou Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd rather find some dusty corner of the docs to stash all of these away in, with something like:

.. c:var:: PyTypeObject PyByteArrayIter_Type
           PyTypeObject PyBytesIter_Type
           PyTypeObject PyListIter_Type
           ...

   Type objects for iterators of various built-in objects.
   Do not use these directly; prefer calling `PyObject_GetIter` instead.

   Note that there is no guarantee that a given built-in type uses a given iterator
   type.
   For example, in CPython, iterating over :py: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.

(We might want to add API to get a reverse iterator, just to discourage calling PyReversed_Type->tp_new and such.)

I think I'm sounding grumpy & terse, aren't I. Sorry! Going to sleep now :)

Copy link
Member Author

@ZeroIntensity ZeroIntensity Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still think it'd be better to keep these types close to their friends, but I'm open to convincing. As an alternative, would you be okay with adding a glossary term for "iterator type" or something like that, and then adding the warning there?

I think I'm sounding grumpy & terse, aren't I. Sorry! Going to sleep now :)

You're good :)

Copy link
Member

@encukou encukou Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm open to convincing

Here's my view then.

I think these are implementation details that wouldn't be exposed today. Users are better off not using them (and not exposing their own iterator types).

Their docs should target people that found them in some code and want to understand them. They should show up in a search, and tell you how to replace the API, but they shouldn't be “advertised”.

Copy link
Member Author

@ZeroIntensity ZeroIntensity Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I think I can get behind that. I've updated this PR to use the approach you suggested above. If we merge this, I'll remove the iterator types from the other PRs.



Type check macros
^^^^^^^^^^^^^^^^^

Expand Down
6 changes: 6 additions & 0 deletions Doc/c-api/bytes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,12 @@ 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
Expand Down
15 changes: 15 additions & 0 deletions Doc/c-api/list.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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__`.
6 changes: 6 additions & 0 deletions Doc/c-api/set.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions Doc/c-api/tuple.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading