gh-141004: Document remaining iterator types

[ZeroIntensity]

• Issue: Document the entire C API #141004

---

📚 Documentation preview 📚: https://cpython-previews--141010.org.readthedocs.build/en/141010/c-api/iterator.html#other-iterator-objects

[encukou]

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.)

[ZeroIntensity]

Would you prefer that I remove the second sentence?

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

[encukou]

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 :)

[ZeroIntensity]

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 :)

[encukou]

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”.

[ZeroIntensity]

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.

[miss-islington-app]

Thanks @ZeroIntensity for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-141046 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-141047 is a backport of this pull request to the 3.13 branch.

[bedevere-bot]

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot ARM64 MacOS M1 Refleaks NoGIL 3.13 (tier-2) has failed when building commit a3756c6.

What do you need to do:

1. Don't panic.
2. Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
3. Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/1396/builds/1732) and take a look at the build logs.
4. Check if the failure is related to this commit (a3756c6) or if it is a false positive.
5. If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/1396/builds/1732

Failed tests:

• test.test_multiprocessing_forkserver.test_processes

Failed subtests:

• test_repr_rlock - test.test_multiprocessing_forkserver.test_processes.WithProcessesTestLock.test_repr_rlock
• test_sock_client_racing - test.test_asyncio.test_sock_lowlevel.SelectEventLoopTests.test_sock_client_racing

Test leaking resources:

• test_sock_lowlevel: memory blocks

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last):
  File "/Users/buildbot/buildarea/3.13.itamaro-macos-arm64-aws.macos-with-brew.refleak.nogil/build/Lib/test/test_asyncio/test_sock_lowlevel.py", line 273, in test_sock_client_racing
    self.loop.run_until_complete(asyncio.wait_for(
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
        self._basetest_sock_send_racing(listener, sock), 10))
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/buildbot/buildarea/3.13.itamaro-macos-arm64-aws.macos-with-brew.refleak.nogil/build/Lib/asyncio/base_events.py", line 725, in run_until_complete
    return future.result()
           ~~~~~~~~~~~~~^^
  File "/Users/buildbot/buildarea/3.13.itamaro-macos-arm64-aws.macos-with-brew.refleak.nogil/build/Lib/asyncio/tasks.py", line 507, in wait_for
    return await fut
           ^^^^^^^^^
  File "/Users/buildbot/buildarea/3.13.itamaro-macos-arm64-aws.macos-with-brew.refleak.nogil/build/Lib/test/test_asyncio/test_sock_lowlevel.py", line 196, in _basetest_sock_send_racing
    sock.send(b' ' * size)
    ~~~~~~~~~^^^^^^^^^^^^^
ConnectionResetError: [Errno 54] Connection reset by peer


Traceback (most recent call last):
  File "/Users/buildbot/buildarea/3.13.itamaro-macos-arm64-aws.macos-with-brew.refleak.nogil/build/Lib/test/_test_multiprocessing.py", line 1492, in test_repr_rlock
    self.assertEqual('<RLock(SomeOtherThread, nonzero)>', repr(lock))
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: '<RLock(SomeOtherThread, nonzero)>' != '<RLock(None, 0)>'
- <RLock(SomeOtherThread, nonzero)>
+ <RLock(None, 0)>