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

gh-150319: Replace all documentation which says "See PEP 585" (GH-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

---------
(cherry picked from commit 50fe49c879af352914da3baa40c7fd1fb170028c)

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: Alex Waygood <66076021+AlexWaygood@users.noreply.github.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.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 ca7c055285aa822ba2d30923eff2cf5fe348e409..da9b3fa2fe8a5ded277f938870e9cea11f2d6b7d 100644 (file)
--- a/Doc/library/array.rst
+++ b/Doc/library/array.rst
@@ -134,6 +134,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 43977de273e61f6c9a3a5c26bcc03f24b05f849b..195d99123dbd3675c29db923c4bde2d022651629 100644 (file)
--- a/Doc/library/asyncio-future.rst
+++ b/Doc/library/asyncio-future.rst
@@ -101,6 +101,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 cc833b80d52542be42afb3aceec3d51c62b41339..64f0810777e41b93251db1a05c4f865fdd4f1534 100644 (file)
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -1230,6 +1230,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 e42bdc06be09fff0f2bce31ea4aaf1b71d191c5e..25e4a71b03c6c85151124ab722d10f690f3e719b 100644 (file)
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -484,6 +484,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:
 
@@ -739,6 +741,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 93d0c0d34bf039dad7ca1f80df22a3bdbc6ab831..b0cc0be8e911bf0066461d63678146ab81cefe96 100644 (file)
--- a/Doc/library/contextvars.rst
+++ b/Doc/library/contextvars.rst
@@ -42,6 +42,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.
@@ -130,6 +133,9 @@ Context Variables
    Tokens support the :ref:`context manager protocol <context-managers>`
    to automatically reset context variables. See :meth:`ContextVar.set`.
 
+   Tokens are :ref:`generic <generics>` over the same type as the
+   :class:`ContextVar` which created them.
+
    .. versionadded:: 3.14
 
       Added support for usage as a context manager.

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 618ae89921c3480e3f93b065b7a2de8193e81adb..46b8dd8ef1881497e31c21de02146d0e807cdd13 100644 (file)
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -3178,6 +3178,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 7fc6055aa9a88125e93d5484e986ef22c9652385..3775d5ac81a27369b23172179637e85d6580e115 100644 (file)
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -984,6 +984,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 27a032a8a97c6378368ad5fb67e713a878c5a8fe..f2c9b3914f36e623c9d6d77aa997ae1ee1912d8a 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -2982,6 +2982,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 5ac72ef7604d50c58d32401bfb4d92a6c86b197a..f5326aff7236bd696a7af1169162bd366952c539 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 a46fd42458158cf38b8e3429b0b8553dd00e0171..4745c1b98a4554363814d52b16cb55377d346098 100644 (file)
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -1257,6 +1257,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`.
@@ -1419,6 +1422,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 b0388c4e1f0bd459dca3e7644645839571c365bd..c8f2cca484ab311fb861883974b5807076201341 100644 (file)
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1403,6 +1403,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:
@@ -1494,6 +1496,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.
@@ -4586,6 +4592,9 @@ copying.
    types such as :class:`bytes` and :class:`bytearray`, an element is a single
    byte, but other types such as :class:`array.array` may have bigger elements.
 
+   :class:`!memoryview`\s are :ref:`generic <generics>` over the type of their
+   underlying data.
+
    ``len(view)`` is equal to the length of :meth:`~memoryview.tolist`, which
    is the nested list representation of the view. If ``view.ndim = 1``,
    this is equal to the number of elements in the view.
@@ -5279,6 +5288,8 @@ 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.
+
 .. seealso::
 
    For detailed information on thread-safety guarantees for :class:`set`
@@ -5382,6 +5393,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):
 
@@ -5719,6 +5733,9 @@ Frozen dictionaries
    :class:`!frozendict` is not a :class:`!dict` subclass but inherits directly
    from ``object``.
 
+   Like dictionaries, frozendicts are :ref:`generic <generics>` over two types,
+   signifying (respectively) the types of the frozendict's keys and values.
+
    .. versionadded:: 3.15
 
 

diff --git a/Doc/library/string.templatelib.rst b/Doc/library/string.templatelib.rst
index a5b2d796aaf4b834c83c8eeebcaf67309066cdeb..6e91850fdf59ca4c5419067a3c6ec3881686628a 100644 (file)
--- a/Doc/library/string.templatelib.rst
+++ b/Doc/library/string.templatelib.rst
@@ -245,6 +245,8 @@ Types
    ...
    3.0 | 1. + 2. | None | .2f
 
+   Interpolations are :ref:`generic <generics>` over the types of their values.
+
    .. rubric:: Attributes
 
    .. attribute:: value

diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index 9f7b7579519052abf7b0b8e89d25fd2b2be0add7..38a77119769d72458bb0089d2ae687f47aced92f 100644 (file)
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -386,6 +386,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 318da931fc314cdc2c23a882b35fde8fa26a67e6..fcb9e0199fad69e966045abcb5698a626cdd0f12 100644 (file)
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -120,6 +120,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 e13b2c9db490a14c43f86a6abbc793bc929f87fb..a8614128c85dada8bf5b1ceb9ea361db38245f50 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -3868,6 +3868,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 7fa415a08b1551193452430472782142a1df094a..6620ee26449b1636f66b9d73c635bd5386888528 100644 (file)
--- a/Modules/_asynciomodule.c
+++ b/Modules/_asynciomodule.c
@@ -1742,7 +1742,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 */
 };
 
@@ -2927,7 +2928,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 541ca48633bb56bec25125d3bbb9e435f7b125a4..c5d4879312bc8a8bf824cf4600fbc24576e153ca 100644 (file)
--- a/Modules/_collectionsmodule.c
+++ b/Modules/_collectionsmodule.c
@@ -1855,7 +1855,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 */
 };
 
@@ -2331,6 +2331,12 @@ defdict_reduce(PyObject *op, PyObject *Py_UNUSED(dummy))
     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__", defdict_missing, METH_O,
      defdict_missing_doc},
@@ -2341,7 +2347,7 @@ static PyMethodDef defdict_methods[] = {
     {"__reduce__", 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 09eae97dd21a36654c8795a9f0d565afb4ef9b11..e891249668c20f581910ae2edb6c6f880af7c19a 100644 (file)
--- a/Modules/_ctypes/_ctypes.c
+++ b/Modules/_ctypes/_ctypes.c
@@ -5305,7 +5305,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 393b59883e89f3c38ace7777714b916ba271ca92..b4595c55d519b93d4f949e816eeada1892cccd89 100644 (file)
--- a/Modules/_functoolsmodule.c
+++ b/Modules/_functoolsmodule.c
@@ -860,7 +860,8 @@ static PyMethodDef partial_methods[] = {
     {"__reduce__", partial_reduce, METH_NOARGS},
     {"__setstate__", 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 7205c095cc87b8be45882d6d6936b4c640d297a5..af54e42a6af584c81f377c31bb1ed8c0441cc63b 100644 (file)
--- a/Modules/_queuemodule.c
+++ b/Modules/_queuemodule.c
@@ -550,7 +550,7 @@ static PyMethodDef simplequeue_methods[] = {
     _QUEUE_SIMPLEQUEUE_QSIZE_METHODDEF
     _QUEUE_SIMPLEQUEUE___SIZEOF___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 7a07ed1d7aca20cecae6ba03e706032f6dcf23ee..d372d6a03ab4ee459747e615c5844e22e19fc03e 100644 (file)
--- a/Modules/_sre/sre.c
+++ b/Modules/_sre/sre.c
@@ -3180,7 +3180,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}
 };
 
@@ -3236,7 +3236,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 7f367d639983ae447472adc4ad36f1dd08296b97..aefdfe0edc0e1e40b11e216f34025a00ab44cbe2 100644 (file)
--- a/Modules/arraymodule.c
+++ b/Modules/arraymodule.c
@@ -2676,7 +2676,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 68ac810eaad237f321090431abd6ccb1d8c46902..0dd31dfbc5a3469ae410f384a494df210b264342 100644 (file)
--- a/Modules/itertoolsmodule.c
+++ b/Modules/itertoolsmodule.c
@@ -1952,10 +1952,14 @@ 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
     {"__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 4f745c504a066a352a00cf59be8f4a15a101c2ac..214c4ab8602be72849b55529494e16d306aea800 100644 (file)
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -16528,7 +16528,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 a5926616eeb3cbfb2f0e89c99760df36e8e17366..30444b7d677424755401c39c12639df4a9569073 100644 (file)
--- a/Objects/descrobject.c
+++ b/Objects/descrobject.c
@@ -1178,7 +1178,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 66546b72130dd0ee50229e1979132eeedf5edd2c..e279c8765dd464aa77983c796ddc3a3b64cb4261 100644 (file)
--- a/Objects/dictobject.c
+++ b/Objects/dictobject.c
@@ -5130,7 +5130,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 */
 };
 
@@ -8198,7 +8199,8 @@ static PyMethodDef frozendict_methods[] = {
     DICT_FROMKEYS_METHODDEF
     FROZENDICT_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("frozendicts are generic over two types, signifying (respectively) the types of the frozendict's keys and values")},
     {"__getnewargs__", frozendict_getnewargs, METH_NOARGS},
     {NULL,              NULL}   /* sentinel */
 };

diff --git a/Objects/enumobject.c b/Objects/enumobject.c
index 364d508dd01822cda0334224dd9d0f69ce48c883..fc53f1bfee8dde47b3fa6463b9cad783bac7cadc 100644 (file)
--- a/Objects/enumobject.c
+++ b/Objects/enumobject.c
@@ -290,7 +290,7 @@ PyDoc_STRVAR(reduce_doc, "Return state information for pickling.");
 static PyMethodDef enum_methods[] = {
     {"__reduce__", 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 5e5e87cd6d7559f9dc97016b991d2c598a08b381..10d100384be7aa532a5b4a12a7453cfc5a24039d 100644 (file)
--- a/Objects/exceptions.c
+++ b/Objects/exceptions.c
@@ -1743,7 +1743,8 @@ static PyMemberDef BaseExceptionGroup_members[] = {
 
 static PyMethodDef BaseExceptionGroup_methods[] = {
     {"__class_getitem__", 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")},
     BASEEXCEPTIONGROUP_DERIVE_METHODDEF
     BASEEXCEPTIONGROUP_SPLIT_METHODDEF
     BASEEXCEPTIONGROUP_SUBGROUP_METHODDEF

diff --git a/Objects/genobject.c b/Objects/genobject.c
index 8c5d720c0b9035cedd07bee7380d7bbf34a42ca5..38d493343454fce6303d4a467db14c37424998f3 100644 (file)
--- a/Objects/genobject.c
+++ b/Objects/genobject.c
@@ -1023,7 +1023,8 @@ static PyMethodDef gen_methods[] = {
     {"throw", _PyCFunction_CAST(gen_throw), METH_FASTCALL, throw_doc},
     {"close", gen_close, METH_NOARGS, close_doc},
     {"__sizeof__", 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 */
 };
 
@@ -1374,7 +1375,8 @@ static PyMethodDef coro_methods[] = {
     {"throw",_PyCFunction_CAST(gen_throw), METH_FASTCALL, coro_throw_doc},
     {"close", gen_close, METH_NOARGS, coro_close_doc},
     {"__sizeof__", 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 */
 };
 
@@ -1820,7 +1822,7 @@ static PyMethodDef async_gen_methods[] = {
     {"aclose", async_gen_aclose, METH_NOARGS, async_aclose_doc},
     {"__sizeof__", 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/interpolationobject.c b/Objects/interpolationobject.c
index b58adb693f0cae56828e92350aaf2be0be09cef6..e37724fb7852a278f33eba1b5529d0a26c5befaf 100644 (file)
--- a/Objects/interpolationobject.c
+++ b/Objects/interpolationobject.c
@@ -138,7 +138,7 @@ static PyMethodDef interpolation_methods[] = {
     {"__reduce__", interpolation_reduce, METH_NOARGS,
         PyDoc_STR("__reduce__() -> (cls, state)")},
     {"__class_getitem__", Py_GenericAlias,
-        METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+        METH_O|METH_CLASS, PyDoc_STR("Interpolations are generic over the types of their values")},
     {NULL, NULL},
 };
 

diff --git a/Objects/listobject.c b/Objects/listobject.c
index 38dc38dd277b97a57e43e8dcb4c1fabd76047b81..8a9c9bda68269b84cc4d43cf88c33a288446f909 100644 (file)
--- a/Objects/listobject.c
+++ b/Objects/listobject.c
@@ -3610,7 +3610,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/memoryobject.c b/Objects/memoryobject.c
index 3cfee04d80bb7488dcf0b02dd5f9c3a87ea289fd..a05d3c3b7a7f4695417d071e25f62d3cb410cdea 100644 (file)
--- a/Objects/memoryobject.c
+++ b/Objects/memoryobject.c
@@ -3579,7 +3579,8 @@ static PyMethodDef memory_methods[] = {
     MEMORYVIEW_INDEX_METHODDEF
     {"__enter__",   memory_enter, METH_NOARGS, NULL},
     {"__exit__",    memory_exit, METH_VARARGS, memory_exit_doc},
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+     PyDoc_STR("memoryviews are generic over the type of their underlying data")},
     {NULL,          NULL}
 };
 

diff --git a/Objects/setobject.c b/Objects/setobject.c
index 642baef3544d36a4c4930487d57cbcb94507a2de..7644ea0baf73dd17875943cabc818eb0f2d1009b 100644 (file)
--- a/Objects/setobject.c
+++ b/Objects/setobject.c
@@ -2792,7 +2792,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 */
 };
 
@@ -2896,7 +2897,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/sliceobject.c b/Objects/sliceobject.c
index dbb509b06ecbbae93b4359c678b32fdba02f4cc9..0d05eb7a47bb1d05e7493a10cc6ffbcc75286cbf 100644 (file)
--- a/Objects/sliceobject.c
+++ b/Objects/sliceobject.c
@@ -572,7 +572,8 @@ PyDoc_STRVAR(reduce_doc, "Return state information for pickling.");
 static PyMethodDef slice_methods[] = {
     {"indices", slice_indices, METH_O, slice_indices_doc},
     {"__reduce__", slice_reduce, METH_NOARGS, reduce_doc},
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+     "slices are generic over the types of their start, end, and step values"},
     {NULL, NULL}
 };
 

diff --git a/Objects/templateobject.c b/Objects/templateobject.c
index a05208e4c8fc8e8f4ad0c520c231dd461cd47dd3..1609e82b444516ce334269a9030b0aa2c36145b6 100644 (file)
--- a/Objects/templateobject.c
+++ b/Objects/templateobject.c
@@ -372,7 +372,11 @@ template_reduce(PyObject *op, PyObject *Py_UNUSED(dummy))
 static PyMethodDef template_methods[] = {
     {"__reduce__", template_reduce, METH_NOARGS, NULL},
     {"__class_getitem__", Py_GenericAlias,
-        METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+     METH_O|METH_CLASS,
+     // note that this is not supported in typeshed, and it is not clear if the
+     // type for this is a simple TypeVar or a TypeVarTuple
+     // for details, see: https://github.com/python/typeshed/issues/14878
+     PyDoc_STR("Template supports [] for generic usage")},
     {NULL, NULL},
 };
 

diff --git a/Objects/tupleobject.c b/Objects/tupleobject.c
index 6de9487432a3984544aeb702caba3bcd4b80ddd1..5aa5188905305a49111f89fffd1bd30f24072b00 100644 (file)
--- a/Objects/tupleobject.c
+++ b/Objects/tupleobject.c
@@ -954,11 +954,17 @@ tuple___getnewargs___impl(PyTupleObject *self)
     return Py_BuildValue("(N)", tuple_slice(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/unionobject.c b/Objects/unionobject.c
index 0f6b1e44bc2402c0a60b7ef37a288d20af0c8084..1dc2927b6e6ac70afd4f8f8469223ac58d45cc69 100644 (file)
--- a/Objects/unionobject.c
+++ b/Objects/unionobject.c
@@ -518,7 +518,8 @@ union_mro_entries(PyObject *self, PyObject *args)
 
 static PyMethodDef union_methods[] = {
     {"__mro_entries__", union_mro_entries, METH_O},
-    {"__class_getitem__", union_class_getitem, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", union_class_getitem, METH_O|METH_CLASS,
+     PyDoc_STR("Create a union containing the given types")},
     {0}
 };
 

diff --git a/Objects/weakrefobject.c b/Objects/weakrefobject.c
index 61fa3ddad0bfd83712bde080e1b4845820daf758..8446a2dbcf75593a36ae38513d05789a27f787c5 100644 (file)
--- a/Objects/weakrefobject.c
+++ b/Objects/weakrefobject.c
@@ -491,7 +491,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 3170018da8c1c99066923ef58507d4af9f2b1dfb..593e6ef90037cfa90dd15a236ee4fe6963c3bc7f 100644 (file)
--- a/Python/context.c
+++ b/Python/context.c
@@ -1100,7 +1100,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}
 };
 
@@ -1266,7 +1267,8 @@ token_exit_impl(PyContextToken *self, PyObject *type, PyObject *val,
 
 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.")},
     TOKEN_ENTER_METHODDEF
     TOKEN_EXIT_METHODDEF
     {NULL}