gh-150319: Replace all documentation which says "See PEP 585"

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"}
           ...
       }
 

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
 
 

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.
 

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.
 

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:`!defaultdicts` 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:

Doc/library/contextvars.rst

@@ -42,6 +42,9 @@ Context Variables
    references to context variables which prevents context variables
    from being properly garbage collected.
 
+   Context Variables 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.

Doc/library/ctypes.rst

@@ -3171,6 +3171,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_
 

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

Doc/library/os.rst

@@ -2994,6 +2994,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

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
 
 

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

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:`!memoryviews` 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
 
 

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

Doc/library/types.rst

@@ -386,6 +386,9 @@ Standard names are defined for the following types:
    entries, which means that when the mapping changes, the view reflects these
    changes.
 
+   MappingProxyTypes 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

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

Doc/reference/datamodel.rst

@@ -3854,6 +3854,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.
 

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.

Modules/_asynciomodule.c

@@ -1741,7 +1741,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 */
 };
 
@@ -2926,7 +2927,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 */
 };
 

Modules/_collectionsmodule.c

@@ -1854,7 +1854,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 */
 };
 
@@ -2330,6 +2330,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},
@@ -2340,7 +2346,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}
 };
 

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 }
 };
 

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 */
 };
 

Modules/_queuemodule.c

@@ -548,7 +548,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 */
 };
 

Modules/_sre/sre.c

@@ -3179,7 +3179,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}
 };
 
@@ -3235,7 +3235,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}
 };
 

Modules/arraymodule.c

@@ -2679,7 +2679,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 */
 };
 

Modules/itertoolsmodule.c

@@ -1950,10 +1950,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 */
 };
 

Modules/posixmodule.c

@@ -16538,7 +16538,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}
 };
 

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}

Objects/dictobject.c

@@ -5129,7 +5129,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 */
 };
 
@@ -8197,7 +8198,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 */
 };