[3.13] gh-150319: Replace all documentation which says "See PEP 585" (#150325) (...

gh-150319: Replace all documentation which says "See PEP 585" (#150325)

* Replace all documentation which says "See PEP 585"

The following classes in the stdlib get simple updates:

- array.array
- asyncio.Future
- asyncio.Task
- collections.defaultdict
- collections.deque
- contextvars.ContextVar
- contextvars.Token
- ctypes.Array
- os.DirEntry
- re.Match
- re.Pattern
- string.templatelib.Interpolation
- string.templatelib.Template
- types.MappingProxyType
- queue.SimpleQueue
- weakref.ref

The following classes are documented publicly as functions, and are
therefore updated internally (`__class_getitem__.__doc__`) but not in the
public docs:

- functools.partial
- itertools.chain

The following builtin types have updates to `__class_getitem__.__doc__`
but not to any documentation pages:

- BaseExceptionGroup
- coroutines (from generators)
- dict
- enumerate
- frozendict
- frozenset
- generators (and async generators)
- list
- memoryview
- set
- slice
- tuple

Special cases:

- union objects are now documented as "supporting class-level []",
  rather than anything to do with generics.

- Templates might be generic over a single type (union, in theory) or
  over a TypeVarTuple. As this is not currently fully settled, it is
  marked with a comment and a mild hint that it is a single type is used
  (namely, "type" is singular rather than "types", plural)

* Apply suggestions from code review

* Correct several class getitem docs

And expand the text for tuples.

* Add notes on generic typing of builtins

* Fix typo in tuple.__class_getitem__ docstring

* Typo fix: malformed refs

Fix `generic` links which weren't marked as `:ref:`.

* Strike unnecessary docs on generic-ness

* Apply suggestions from code review

These are applied at both the originally indicated locations and in the
corresponding docstring definitions.

* Update Doc/library/re.rst

* Update Objects/enumobject.c

* Remove tuple generic doc in 'stdtypes' page

This is covered in more detail in the cross-linked typing documentation.
The other copy of this documentation -- in the docstring for
`tuple.__class_getitem__` -- is left in place.

* Fix whitespace around new doc of generics

Per review, do not introduce or remove whitespace such that section
breaks are altered by the introduction of doc on various generic types.

In most cases, this is a removal of an extra line.

In one case (Arrays), it is the reintroduction of a line.

Additionally, two other minor fixes are included:
- incorrect indent on 'defaultdicts'
- make `mappingproxy.__class_getitem__.__doc__` consistent with other
  mapping type generic docs

* Move placement of memoryview generic note

Previous placement was at the end of the main docstring, which is
consistent with other types but places it after a section on various
methods (which makes it read somewhat inconsistently). Moving it up
helps resolve.

* Ensure sphinxdoc does not start sentences lowercase

Lowercase class names at the start of sentences are marked out with the
`class` role. In the case of `deque`, documentation already refers to
these as `Deques`, so this form is preferred.

* Apply suggestions from code review

* Fix line endings and wrap more tightly

Line endings fixed by pre-commit ; also re-wrapped the MappingProxyType
text which was too long.

* Use 'ContextVars' style in sphinx doc

---------

Co-authored-by: Stephen Rosen <sirosen@globus.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

diff --git a/Doc/c-api/typehints.rst b/Doc/c-api/typehints.rst
index 98fe68737deb81c31720551c48537c080e058e5a..ec2fba6da8b0438b38d348ccf4f382b2a4af7be5 100644 (file)
--- a/Doc/c-api/typehints.rst
+++ b/Doc/c-api/typehints.rst
@@ -31,7 +31,7 @@ two types exist -- :ref:`GenericAlias <types-genericalias>` and
       static PyMethodDef my_obj_methods[] = {
           // Other methods.
           ...
-          {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"}
+          {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "my_obj is generic over its contained type"}
           ...
       }
 

diff --git a/Doc/library/array.rst b/Doc/library/array.rst
index 95fbf25e3be1dfc17eb4956d56381dd4ebfdbc95..f4e8d8fee714afc3245e81ace6e215c61a0d22ae 100644 (file)
--- a/Doc/library/array.rst
+++ b/Doc/library/array.rst
@@ -99,6 +99,8 @@ The module defines the following type:
    :exc:`TypeError` is raised. Array objects also implement the buffer interface,
    and may be used wherever :term:`bytes-like objects <bytes-like object>` are supported.
 
+   Arrays are :ref:`generic <generics>` over the type of their contents.
+
    .. audit-event:: array.__new__ typecode,initializer array.array
 
 

diff --git a/Doc/library/asyncio-future.rst b/Doc/library/asyncio-future.rst
index 5c32bd3eaad8283cf4e9c7df7762123abbd43d9d..cab9f6513b1d844cab57b748ddad17728fd04b85 100644 (file)
--- a/Doc/library/asyncio-future.rst
+++ b/Doc/library/asyncio-future.rst
@@ -100,6 +100,8 @@ Future Object
    implementations can inject their own optimized implementations
    of a Future object.
 
+   Futures are :ref:`generic <generics>` over the type of their results.
+
    .. versionchanged:: 3.7
       Added support for the :mod:`contextvars` module.
 

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 00423357c62f5fcff7f30e1b14a9b1201fb60904..63bb4bae9bddbb8831e6317883777426e0d306a1 100644 (file)
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -1190,6 +1190,9 @@ Task object
    blocks. If the coroutine returns or raises without blocking, the task
    will be finished eagerly and will skip scheduling to the event loop.
 
+   Tasks are :ref:`generic <generics>` over the return type of their wrapped
+   coroutines.
+
    .. versionchanged:: 3.7
       Added support for the :mod:`contextvars` module.
 

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index d2ba42a3860882c1de6274ee2a23cb5b2b1e1973..c37cb6ba78667272f59025fb0af849bc47c2f8c0 100644 (file)
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -480,6 +480,8 @@ or subtracting from an empty counter.
     Unix. They are also useful for tracking transactions and other pools of data
     where only the most recent activity is of interest.
 
+    Deques are :ref:`generic <generics>` over the type of their contents.
+
 
     Deque objects support the following methods:
 
@@ -735,6 +737,9 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
     as if they were passed to the :class:`dict` constructor, including keyword
     arguments.
 
+    :class:`!defaultdict`\s are :ref:`generic <generics>` over two types,
+    signifying (respectively) the types of the dictionary's keys and values.
+
 
     :class:`defaultdict` objects support the following method in addition to the
     standard :class:`dict` operations:

diff --git a/Doc/library/contextvars.rst b/Doc/library/contextvars.rst
index c34f439282eb7f9654361c04a3f807a8922d1aed..c5d22240e57ccf51d68f449642dd015269f9f119 100644 (file)
--- a/Doc/library/contextvars.rst
+++ b/Doc/library/contextvars.rst
@@ -44,6 +44,9 @@ Context Variables
    references to context variables which prevents context variables
    from being properly garbage collected.
 
+   :class:`!ContextVar`\s are :ref:`generic <generics>` over the type of
+   their contained value.
+
    .. attribute:: ContextVar.name
 
       The name of the variable.  This is a read-only property.
@@ -103,6 +106,9 @@ Context Variables
    the value of the variable to what it was before the corresponding
    *set*. A single token cannot reset a context variable more than once.
 
+   Tokens are :ref:`generic <generics>` over the same type as the
+   :class:`ContextVar` which created them.
+
    .. attribute:: Token.var
 
       A read-only property.  Points to the :class:`ContextVar` object

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 96f6a1e740a17a2f04197681c8c09ff569bc901e..29cf2afd33e7d62d93d617cf70a0251a0f74ef3c 100644 (file)
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -2695,6 +2695,8 @@ Arrays and pointers
    subscript and slice accesses; for slice reads, the resulting object is
    *not* itself an :class:`Array`.
 
+   Arrays are :ref:`generic <generics>` over the type of their elements.
+
 
    .. attribute:: _length_
 

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 1e4cdffd3589d3efa08ba93121d48c0654530a03..df80bfaceca7aac56514bd6c280071b629faf84e 100644 (file)
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -961,6 +961,9 @@ their subgroups based on the types of the contained exceptions.
    raises a :exc:`TypeError` if any contained exception is not an
    :exc:`Exception` subclass.
 
+   Exception groups are :ref:`generic <generics>` over the type of their
+   contained exceptions.
+
    .. impl-detail::
 
       The ``excs`` parameter may be any sequence, but lists and tuples are

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 1ffbae43431f4ed3dab24a8f9f37acf83e5924ad..7b5cc4be5c0b3220bf49d8b780eed6cf338e0b59 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -2864,6 +2864,9 @@ features:
    To be directly usable as a :term:`path-like object`, ``os.DirEntry``
    implements the :class:`PathLike` interface.
 
+   :class:`!DirEntry` objects are :ref:`generic <generics>` over the type of the
+   path (:class:`str` or :class:`bytes`).
+
    Attributes and methods on a ``os.DirEntry`` instance are as follows:
 
    .. attribute:: name

diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst
index 1b75582f0cf45b872ceee8044348fd0679bc4962..c126f31c9453e668c4c60f42f43a8d12e02b2deb 100644 (file)
--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
@@ -76,6 +76,8 @@ The :mod:`queue` module defines the following classes and exceptions:
    Constructor for an unbounded :abbr:`FIFO (first-in, first-out)` queue.
    Simple queues lack advanced functionality such as task tracking.
 
+   Simple queues are :ref:`generic <generics>` over the type of their items.
+
    .. versionadded:: 3.7
 
 

diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index 8f45a4f51c4a57b730f759b86b91d35d4eb3998a..5c7aadb03dad3a2bb6f66adbd14cc86bfef2f58e 100644 (file)
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -1238,6 +1238,9 @@ Regular Expression Objects
 
    Compiled regular expression object returned by :func:`re.compile`.
 
+   Patterns are :ref:`generic <generics>` over the type of string they handle
+   (:class:`str` or :class:`bytes`).
+
    .. versionchanged:: 3.9
       :py:class:`re.Pattern` supports ``[]`` to indicate a Unicode (str) or bytes pattern.
       See :ref:`types-genericalias`.
@@ -1381,6 +1384,9 @@ when there is no match, you can test whether there was a match with a simple
 
    Match object returned by successful ``match``\ es and ``search``\ es.
 
+   Matches are :ref:`generic <generics>` over the type of string which was
+   matched (:class:`str` or :class:`bytes`).
+
    .. versionchanged:: 3.9
       :py:class:`re.Match` supports ``[]`` to indicate a Unicode (str) or bytes match.
       See :ref:`types-genericalias`.

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index ecc11201db7829f754352337c13935d261eaa7d0..d33fba51e5ad56e53b3b45375181e2573aaa59a8 100644 (file)
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1351,6 +1351,8 @@ application).
    Many other operations also produce lists, including the :func:`sorted`
    built-in.
 
+   Lists are :ref:`generic <generics>` over the types of their items.
+
    Lists implement all of the :ref:`common <typesseq-common>` and
    :ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the
    following additional method:
@@ -1437,6 +1439,10 @@ homogeneous data is needed (such as allowing storage in a :class:`set` or
    Tuples implement all of the :ref:`common <typesseq-common>` sequence
    operations.
 
+   Tuples are :ref:`generic <generics>` over the types of their contents.
+   For more information, refer to
+   :ref:`the typing documentation on annotating tuples <annotating-tuples>`.
+
 For heterogeneous collections of data where access by name is clearer than
 access by index, :func:`collections.namedtuple` may be a more appropriate
 choice than a simple tuple object.
@@ -4994,6 +5000,7 @@ Note, the *elem* argument to the :meth:`~object.__contains__`,
 :meth:`~set.discard` methods may be a set.  To support searching for an equivalent
 frozenset, a temporary one is created from *elem*.
 
+Sets and frozensets are :ref:`generic <generics>` over the type of their elements.
 
 .. _typesmapping:
 
@@ -5091,6 +5098,9 @@ can be used interchangeably to index the same dictionary entry.
       Dictionary order is guaranteed to be insertion order.  This behavior was
       an implementation detail of CPython from 3.6.
 
+   Dictionaries are :ref:`generic <generics>` over two types, signifying
+   (respectively) the types of the dictionary's keys and values.
+
    These are the operations that dictionaries support (and therefore, custom
    mapping types should support too):
 

diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index cb3dc2e1848c940e9c825119e320841ac7d4c142..252fbb51679bf5a79392434ebf31989a66f45f83 100644 (file)
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -360,6 +360,10 @@ Standard names are defined for the following types:
    entries, which means that when the mapping changes, the view reflects these
    changes.
 
+   :class:`!MappingProxyType`\s are :ref:`generic <generics>` over two types,
+   signifying (respectively) the types of the underlying mapping's keys and
+   values.
+
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.9

diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 7629d21da072083cecda4cccda6443bf74eee1b7..309ce8f8739ba9f4882ecccc14446c63c9c649c7 100644 (file)
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -125,6 +125,9 @@ See :ref:`__slots__ documentation <slots>` for details.
 
    This is a subclassable type rather than a factory function.
 
+   Weak references are :ref:`generic <generics>` over the type of the object they
+   reference.
+
    .. attribute:: __callback__
 
       This read-only attribute returns the callback currently associated to the

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index bfb06d6e446171f5f6347d581c1ec86363b284fb..01d7666859d2c3e380ca28c372c82ac4653ea6c2 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -3702,6 +3702,9 @@ Coroutines also have the methods listed below, which are analogous to
 those of generators (see :ref:`generator-methods`).  However, unlike
 generators, coroutines do not directly support iteration.
 
+Coroutines are :ref:`generic <generics>` over the types of their yield, send,
+and return values, respectively.
+
 .. versionchanged:: 3.5.2
    It is a :exc:`RuntimeError` to await on a coroutine more than once.
 

diff --git a/Misc/NEWS.d/next/Documentation/2026-05-23-17-27-41.gh-issue-150319.ol9tWK.rst b/Misc/NEWS.d/next/Documentation/2026-05-23-17-27-41.gh-issue-150319.ol9tWK.rst
new file mode 100644 (file)
index 0000000..d56ccbc
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2026-05-23-17-27-41.gh-issue-150319.ol9tWK.rst
@@ -0,0 +1,2 @@
+Generic builtin and standard library types now document the meaning of their
+type parameters.

diff --git a/Modules/_asynciomodule.c b/Modules/_asynciomodule.c
index f8eacc8037fca5de233bb15f1ba553355300ab45..857cb06d013ab3d0fa417e4624753d58829dbe43 100644 (file)
--- a/Modules/_asynciomodule.c
+++ b/Modules/_asynciomodule.c
@@ -1440,7 +1440,8 @@ static PyMethodDef FutureType_methods[] = {
     _ASYNCIO_FUTURE_DONE_METHODDEF
     _ASYNCIO_FUTURE_GET_LOOP_METHODDEF
     _ASYNCIO_FUTURE__MAKE_CANCELLED_ERROR_METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+    PyDoc_STR("Futures are generic over the type of their results")},
     {NULL, NULL}        /* Sentinel */
 };
 
@@ -2612,7 +2613,8 @@ static PyMethodDef TaskType_methods[] = {
     _ASYNCIO_TASK_SET_NAME_METHODDEF
     _ASYNCIO_TASK_GET_CORO_METHODDEF
     _ASYNCIO_TASK_GET_CONTEXT_METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+    PyDoc_STR("Tasks are generic over the return type of their wrapped coroutines")},
     {NULL, NULL}        /* Sentinel */
 };
 

diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c
index b2c3d0e42be4cb24dceed163cdc4a2dec96635c3..daf62c940b3e5b5fddc2105cad561b905788ca1b 100644 (file)
--- a/Modules/_collectionsmodule.c
+++ b/Modules/_collectionsmodule.c
@@ -1824,7 +1824,7 @@ static PyMethodDef deque_methods[] = {
     DEQUE_ROTATE_METHODDEF
     DEQUE___SIZEOF___METHODDEF
     {"__class_getitem__",       Py_GenericAlias,
-        METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,          PyDoc_STR("deques are generic over the type of their contents")},
     {NULL,              NULL}   /* sentinel */
 };
 
@@ -2284,6 +2284,12 @@ defdict_reduce(defdictobject *dd, PyObject *Py_UNUSED(ignored))
     return result;
 }
 
+
+PyDoc_STRVAR(defdict_class_getitem_doc,
+"defaultdicts are generic over two types, signifying (respectively) the types \
+of the dictionary's keys and values");
+
+
 static PyMethodDef defdict_methods[] = {
     {"__missing__", (PyCFunction)defdict_missing, METH_O,
      defdict_missing_doc},
@@ -2294,7 +2300,7 @@ static PyMethodDef defdict_methods[] = {
     {"__reduce__", (PyCFunction)defdict_reduce, METH_NOARGS,
      reduce_doc},
     {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
-     PyDoc_STR("See PEP 585")},
+     defdict_class_getitem_doc},
     {NULL}
 };
 

diff --git a/Modules/_ctypes/_ctypes.c b/Modules/_ctypes/_ctypes.c
index aac812813d95432d874bdef0e71fe6ddd263e62b..c66d157be75e3ae1d66f2680c6d1072a64f30ffb 100644 (file)
--- a/Modules/_ctypes/_ctypes.c
+++ b/Modules/_ctypes/_ctypes.c
@@ -4935,7 +4935,7 @@ Array_length(PyObject *myself)
 
 static PyMethodDef Array_methods[] = {
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,       PyDoc_STR("Arrays are generic over the type of their elements")},
     { NULL, NULL }
 };
 

diff --git a/Modules/_functoolsmodule.c b/Modules/_functoolsmodule.c
index a1682ec4c0ea2204a6ebfd5fac2e99a79bec0e95..08acd2c5ab924b6fa20a1a501a417988a331cbdb 100644 (file)
--- a/Modules/_functoolsmodule.c
+++ b/Modules/_functoolsmodule.c
@@ -522,7 +522,8 @@ static PyMethodDef partial_methods[] = {
     {"__reduce__", (PyCFunction)partial_reduce, METH_NOARGS},
     {"__setstate__", (PyCFunction)partial_setstate, METH_O},
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,
+    PyDoc_STR("partial is generic over the wrapped function's return type")},
     {NULL,              NULL}           /* sentinel */
 };
 

diff --git a/Modules/_queuemodule.c b/Modules/_queuemodule.c
index 7139482c9b7723fc87b999b61a7f0b74da755e59..4ac43748fddfbf97ba19056abffaa7710c85e9a6 100644 (file)
--- a/Modules/_queuemodule.c
+++ b/Modules/_queuemodule.c
@@ -531,7 +531,7 @@ static PyMethodDef simplequeue_methods[] = {
     _QUEUE_SIMPLEQUEUE_PUT_NOWAIT_METHODDEF
     _QUEUE_SIMPLEQUEUE_QSIZE_METHODDEF
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,       PyDoc_STR("SimpleQueues are generic over the type of their contents")},
     {NULL,           NULL}              /* sentinel */
 };
 

diff --git a/Modules/_sre/sre.c b/Modules/_sre/sre.c
index c0cc8268d2de507218e5f9a952473d4e09310c81..2a2a5f8ef9eaa021ce1ceaba990f824a45aca1d2 100644 (file)
--- a/Modules/_sre/sre.c
+++ b/Modules/_sre/sre.c
@@ -3150,7 +3150,7 @@ static PyMethodDef pattern_methods[] = {
     _SRE_SRE_PATTERN___DEEPCOPY___METHODDEF
     _SRE_SRE_PATTERN__FAIL_AFTER_METHODDEF
     {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
-     PyDoc_STR("See PEP 585")},
+     PyDoc_STR("Patterns are generic over the type of string they handle (str or bytes)")},
     {NULL, NULL}
 };
 
@@ -3206,7 +3206,7 @@ static PyMethodDef match_methods[] = {
     _SRE_SRE_MATCH___COPY___METHODDEF
     _SRE_SRE_MATCH___DEEPCOPY___METHODDEF
     {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
-     PyDoc_STR("See PEP 585")},
+     PyDoc_STR("Matches are generic over the type of string which was matched (str or bytes)")},
     {NULL, NULL}
 };
 

diff --git a/Modules/arraymodule.c b/Modules/arraymodule.c
index b3423a01b7b63df4aded0eecf2b099293ebad674..25694e9cf33e557fb5537d572360b30cc8760188 100644 (file)
--- a/Modules/arraymodule.c
+++ b/Modules/arraymodule.c
@@ -2441,7 +2441,8 @@ static PyMethodDef array_methods[] = {
     ARRAY_ARRAY_TOBYTES_METHODDEF
     ARRAY_ARRAY_TOUNICODE_METHODDEF
     ARRAY_ARRAY___SIZEOF___METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+     PyDoc_STR("Arrays are generic over the type of their elements")},
     {NULL, NULL}  /* sentinel */
 };
 

diff --git a/Modules/itertoolsmodule.c b/Modules/itertoolsmodule.c
index 47bac65e041c2f1b3a2aa36200d4178eaa8fae37..96e8542def58fd5f89bba6c241634289153d76fe 100644 (file)
--- a/Modules/itertoolsmodule.c
+++ b/Modules/itertoolsmodule.c
@@ -2229,6 +2229,10 @@ Return a chain object whose .__next__() method returns elements from the\n\
 first iterable until it is exhausted, then elements from the next\n\
 iterable, until all of the iterables are exhausted.");
 
+PyDoc_STRVAR(chain_class_getitem_doc,
+"chain is generic over the type of its contents.\n\
+This is the union of the types of the input iterable contents.");
+
 static PyMethodDef chain_methods[] = {
     ITERTOOLS_CHAIN_FROM_ITERABLE_METHODDEF
     {"__reduce__",      (PyCFunction)chain_reduce,      METH_NOARGS,
@@ -2236,7 +2240,7 @@ static PyMethodDef chain_methods[] = {
     {"__setstate__",    (PyCFunction)chain_setstate,    METH_O,
      setstate_doc},
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,       chain_class_getitem_doc},
     {NULL,              NULL}           /* sentinel */
 };
 

diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
index 78a8776c1cad1da4437409c387e60e8ea37120d0..86187cbeb47a5b5d230e7efbf3515b648826d8cc 100644 (file)
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -15889,7 +15889,7 @@ static PyMethodDef DirEntry_methods[] = {
     OS_DIRENTRY_INODE_METHODDEF
     OS_DIRENTRY___FSPATH___METHODDEF
     {"__class_getitem__",       Py_GenericAlias,
-    METH_O|METH_CLASS,          PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,          PyDoc_STR("DirEntry is generic over the type of the path (str or bytes)")},
     {NULL}
 };
 

diff --git a/Objects/descrobject.c b/Objects/descrobject.c
index 0560d0668513f0a4fcb4bdb5eaec1e84a3f84f5a..7d3f0e4056729910ef51fe661962a75d0f6960a9 100644 (file)
--- a/Objects/descrobject.c
+++ b/Objects/descrobject.c
@@ -1177,7 +1177,7 @@ static PyMethodDef mappingproxy_methods[] = {
     {"copy",      mappingproxy_copy,       METH_NOARGS,
      PyDoc_STR("D.copy() -> a shallow copy of D")},
     {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
-     PyDoc_STR("See PEP 585")},
+     PyDoc_STR("mappingproxy objects are generic over two types, signifying (respectively) the types of their keys and values")},
     {"__reversed__", mappingproxy_reversed, METH_NOARGS,
      PyDoc_STR("D.__reversed__() -> reverse iterator")},
     {0}

diff --git a/Objects/dictobject.c b/Objects/dictobject.c
index 843ece535be63f5af2b8051fd3af252fea7bf6aa..12dd7bbdeeca2a0c23a0b4c6415256547f56de27 100644 (file)
--- a/Objects/dictobject.c
+++ b/Objects/dictobject.c
@@ -4695,7 +4695,8 @@ static PyMethodDef mapp_methods[] = {
     DICT_CLEAR_METHODDEF
     DICT_COPY_METHODDEF
     DICT___REVERSED___METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+     PyDoc_STR("dicts are generic over two types, signifying (respectively) the types of their keys and values")},
     {NULL,              NULL}   /* sentinel */
 };
 

diff --git a/Objects/enumobject.c b/Objects/enumobject.c
index bffe7172a393d786e11fb6ab7d2ba23c76a437be..5f21bfa326f625bed4f6186fa3d39286ae19f2d7 100644 (file)
--- a/Objects/enumobject.c
+++ b/Objects/enumobject.c
@@ -283,7 +283,7 @@ PyDoc_STRVAR(reduce_doc, "Return state information for pickling.");
 static PyMethodDef enum_methods[] = {
     {"__reduce__", (PyCFunction)enum_reduce, METH_NOARGS, reduce_doc},
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,       PyDoc_STR("'enumerate' objects are generic over the type of their values")},
     {NULL,              NULL}           /* sentinel */
 };
 

diff --git a/Objects/exceptions.c b/Objects/exceptions.c
index 1eb2a3bbe24571d32624a69c1db7dd1ffb299971..81242e4405d31b5f55ec45ac5e9b5f5c8d6237f9 100644 (file)
--- a/Objects/exceptions.c
+++ b/Objects/exceptions.c
@@ -1541,7 +1541,8 @@ static PyMemberDef BaseExceptionGroup_members[] = {
 
 static PyMethodDef BaseExceptionGroup_methods[] = {
     {"__class_getitem__", (PyCFunction)Py_GenericAlias,
-      METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+      METH_O|METH_CLASS,
+      PyDoc_STR("Exception groups are generic over the type of their contained exceptions")},
     {"derive", (PyCFunction)BaseExceptionGroup_derive, METH_O},
     {"split", (PyCFunction)BaseExceptionGroup_split, METH_O},
     {"subgroup", (PyCFunction)BaseExceptionGroup_subgroup, METH_O},
@@ -3933,4 +3934,3 @@ _PyException_AddNote(PyObject *exc, PyObject *note)
     Py_XDECREF(r);
     return res;
 }
-

diff --git a/Objects/genobject.c b/Objects/genobject.c
index b19ff252ddb213e4a2a523188a814b04f9bb85d5..2d9f89dbc34cdd75c0d6fa88bd34aa1f84fa532f 100644 (file)
--- a/Objects/genobject.c
+++ b/Objects/genobject.c
@@ -797,7 +797,8 @@ static PyMethodDef gen_methods[] = {
     {"throw",_PyCFunction_CAST(gen_throw), METH_FASTCALL, throw_doc},
     {"close",(PyCFunction)gen_close, METH_NOARGS, close_doc},
     {"__sizeof__", (PyCFunction)gen_sizeof, METH_NOARGS, sizeof__doc__},
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+     PyDoc_STR("generators are generic over the types of their yield, send, and return values")},
     {NULL, NULL}        /* Sentinel */
 };
 
@@ -1150,7 +1151,8 @@ static PyMethodDef coro_methods[] = {
     {"throw",_PyCFunction_CAST(gen_throw), METH_FASTCALL, coro_throw_doc},
     {"close",(PyCFunction)gen_close, METH_NOARGS, coro_close_doc},
     {"__sizeof__", (PyCFunction)gen_sizeof, METH_NOARGS, sizeof__doc__},
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+     PyDoc_STR("coroutines are generic over the types of their yield, send, and return values")},
     {NULL, NULL}        /* Sentinel */
 };
 
@@ -1564,7 +1566,7 @@ static PyMethodDef async_gen_methods[] = {
     {"aclose", (PyCFunction)async_gen_aclose, METH_NOARGS, async_aclose_doc},
     {"__sizeof__", (PyCFunction)gen_sizeof, METH_NOARGS, sizeof__doc__},
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,       PyDoc_STR("async generators are generic over the types of their yield and send values")},
     {NULL, NULL}        /* Sentinel */
 };
 

diff --git a/Objects/listobject.c b/Objects/listobject.c
index 220b26e39f62668888a064670c2ff7dd15d14bb9..591ea3a956ea722380f9c849c8711516eab9d897 100644 (file)
--- a/Objects/listobject.c
+++ b/Objects/listobject.c
@@ -3532,7 +3532,8 @@ static PyMethodDef list_methods[] = {
     LIST_COUNT_METHODDEF
     LIST_REVERSE_METHODDEF
     LIST_SORT_METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+     PyDoc_STR("lists are generic over the type of their contents")},
     {NULL,              NULL}           /* sentinel */
 };
 

diff --git a/Objects/setobject.c b/Objects/setobject.c
index 891987e3519966c20134ae3ed6e5e8dc93ddd376..0743870cec859c428e02c4bba770ed42b81da403 100644 (file)
--- a/Objects/setobject.c
+++ b/Objects/setobject.c
@@ -2416,7 +2416,8 @@ static PyMethodDef set_methods[] = {
     SET_SYMMETRIC_DIFFERENCE_UPDATE_METHODDEF
     SET_UNION_METHODDEF
     SET_UPDATE_METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+     PyDoc_STR("sets are generic over the type of their elements")},
     {NULL,              NULL}   /* sentinel */
 };
 
@@ -2519,7 +2520,8 @@ static PyMethodDef frozenset_methods[] = {
     SET___SIZEOF___METHODDEF
     SET_SYMMETRIC_DIFFERENCE_METHODDEF
     SET_UNION_METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+     PyDoc_STR("frozensets are generic over the type of their elements")},
     {NULL,              NULL}   /* sentinel */
 };
 

diff --git a/Objects/tupleobject.c b/Objects/tupleobject.c
index 818814b663d53451b2931b266c1864494c6b4ce5..42c94c8b1e028420aa78398d303c261fa85a9018 100644 (file)
--- a/Objects/tupleobject.c
+++ b/Objects/tupleobject.c
@@ -827,11 +827,17 @@ tuple___getnewargs___impl(PyTupleObject *self)
     return Py_BuildValue("(N)", tupleslice(self, 0, Py_SIZE(self)));
 }
 
+
+PyDoc_STRVAR(tuple_class_getitem_doc,
+"Tuples are generic over the types of their contents.\n\n\
+For example, use ``tuple[int, str]`` for a pair whose first element is an int and second element is a string.\n\n\
+Tuples also support the form ``tuple[T, ...]`` to indicate an arbitrary length tuple of elements of type T.");
+
 static PyMethodDef tuple_methods[] = {
     TUPLE___GETNEWARGS___METHODDEF
     TUPLE_INDEX_METHODDEF
     TUPLE_COUNT_METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, tuple_class_getitem_doc},
     {NULL,              NULL}           /* sentinel */
 };
 

diff --git a/Objects/weakrefobject.c b/Objects/weakrefobject.c
index 61f05514a480231381175d272382d824fc06da7e..f45522c29a1cb6a8645306d1cb1e5259c55f23f0 100644 (file)
--- a/Objects/weakrefobject.c
+++ b/Objects/weakrefobject.c
@@ -486,7 +486,8 @@ static PyMemberDef weakref_members[] = {
 
 static PyMethodDef weakref_methods[] = {
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,
+    PyDoc_STR("Weakrefs are generic over the type of the referenced object.")},
     {NULL} /* Sentinel */
 };
 

diff --git a/Python/context.c b/Python/context.c
index 32d0443dbd452312cd6845502f3495ab190644ca..bc8b45cf6f1d5b00ef829cd343c8db87b970c46f 100644 (file)
--- a/Python/context.c
+++ b/Python/context.c
@@ -1048,7 +1048,8 @@ static PyMethodDef PyContextVar_methods[] = {
     _CONTEXTVARS_CONTEXTVAR_SET_METHODDEF
     _CONTEXTVARS_CONTEXTVAR_RESET_METHODDEF
     {"__class_getitem__", Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,
+    PyDoc_STR("ContextVars are generic over the type of their contained values")},
     {NULL, NULL}
 };
 
@@ -1187,7 +1188,8 @@ static PyGetSetDef PyContextTokenType_getsetlist[] = {
 
 static PyMethodDef PyContextTokenType_methods[] = {
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,
+    PyDoc_STR("Tokens are generic over the same type as the ContextVar which created them.")},
     {NULL}
 };