From 12ca4d923be8c0525d7f508ee1db127bb5544930 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Sat, 23 May 2026 13:09:43 -0500 Subject: [PATCH 1/3] 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) --- Doc/c-api/typehints.rst | 2 +- Doc/library/array.rst | 2 ++ Doc/library/asyncio-future.rst | 2 ++ Doc/library/asyncio-task.rst | 3 +++ Doc/library/collections.rst | 7 +++++++ Doc/library/contextvars.rst | 5 +++++ Doc/library/ctypes.rst | 1 + Doc/library/os.rst | 3 +++ Doc/library/queue.rst | 2 ++ Doc/library/re.rst | 5 +++++ Doc/library/string.templatelib.rst | 5 +++++ Doc/library/types.rst | 3 +++ Doc/library/weakref.rst | 3 +++ .../2026-05-23-17-27-41.gh-issue-150319.ol9tWK.rst | 2 ++ Modules/_asynciomodule.c | 6 ++++-- Modules/_collectionsmodule.c | 4 ++-- Modules/_ctypes/_ctypes.c | 2 +- Modules/_functoolsmodule.c | 3 ++- Modules/_queuemodule.c | 2 +- Modules/_sre/sre.c | 4 ++-- Modules/arraymodule.c | 3 ++- Modules/itertoolsmodule.c | 6 +++++- Modules/posixmodule.c | 2 +- Objects/descrobject.c | 2 +- Objects/dictobject.c | 6 ++++-- Objects/enumobject.c | 2 +- Objects/exceptions.c | 3 ++- Objects/genobject.c | 8 +++++--- Objects/interpolationobject.c | 2 +- Objects/listobject.c | 3 ++- Objects/memoryobject.c | 3 ++- Objects/setobject.c | 6 ++++-- Objects/sliceobject.c | 3 ++- Objects/templateobject.c | 6 +++++- Objects/tupleobject.c | 3 ++- Objects/unionobject.c | 3 ++- Objects/weakrefobject.c | 3 ++- Python/context.c | 6 ++++-- 38 files changed, 103 insertions(+), 33 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2026-05-23-17-27-41.gh-issue-150319.ol9tWK.rst diff --git a/Doc/c-api/typehints.rst b/Doc/c-api/typehints.rst index 98fe68737deb81c..ec2fba6da8b0438 100644 --- a/Doc/c-api/typehints.rst +++ b/Doc/c-api/typehints.rst @@ -31,7 +31,7 @@ two types exist -- :ref:`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 4b3ffbbfe804065..aa22cea5f76af3e 100644 --- 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 ` are supported. + Arrays are :ref:`generic ` 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 43977de273e61f6..e92bfc7c9efa159 100644 --- 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 ` over the type of their return value. + .. 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 cc833b80d52542b..969ecbfa12350c1 100644 --- 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 ` over the return type of their contained + coroutine. + .. versionchanged:: 3.7 Added support for the :mod:`contextvars` module. diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index e42bdc06be09fff..a97157bd273b584 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -485,6 +485,9 @@ or subtracting from an empty counter. where only the most recent activity is of interest. + deques are :ref:`generic ` over the type of their contents. + + Deque objects support the following methods: .. method:: append(item, /) @@ -740,6 +743,10 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``, arguments. + defaultdicts are :ref:`generic ` over two types, for the types of + keys and values, respectively. + + :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 93d0c0d34bf039d..c000696967330fa 100644 --- a/Doc/library/contextvars.rst +++ b/Doc/library/contextvars.rst @@ -42,6 +42,8 @@ Context Variables references to context variables which prevents context variables from being properly garbage collected. + Context Variables are :ref:`generic ` over the type of their value. + .. attribute:: ContextVar.name The name of the variable. This is a read-only property. @@ -130,6 +132,9 @@ Context Variables Tokens support the :ref:`context manager protocol ` to automatically reset context variables. See :meth:`ContextVar.set`. + Tokens are :ref:`generic ` 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 4330be922013f30..ef8ffd10a041fc7 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -3171,6 +3171,7 @@ Arrays and pointers subscript and slice accesses; for slice reads, the resulting object is *not* itself an :class:`Array`. + Arrays are :ref:`generic ` over the type of their values. .. attribute:: _length_ diff --git a/Doc/library/os.rst b/Doc/library/os.rst index d406d43cdf7f4fb..9c2a0e749c08fe9 100644 --- a/Doc/library/os.rst +++ b/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. + DirEntry objects are :ref:`generic ` over the type of the path (str + or 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 5ac72ef7604d50c..69fa794b8e3fc60 100644 --- 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 ` over the type of their contents. + .. versionadded:: 3.7 diff --git a/Doc/library/re.rst b/Doc/library/re.rst index a46fd42458158cf..12263bd612fceef 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -1257,6 +1257,8 @@ Regular expression objects Compiled regular expression object returned by :func:`re.compile`. + Patterns are :ref:`generic ` over the type of string they handle (str or bytes). + .. versionchanged:: 3.9 :py:class:`re.Pattern` supports ``[]`` to indicate a Unicode (str) or bytes pattern. See :ref:`types-genericalias`. @@ -1419,6 +1421,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 ` over the type of string which was + matched (str or 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/string.templatelib.rst b/Doc/library/string.templatelib.rst index a5b2d796aaf4b83..130217935a4279b 100644 --- a/Doc/library/string.templatelib.rst +++ b/Doc/library/string.templatelib.rst @@ -78,6 +78,9 @@ Types template.strings: ('Ah! We do have ', '.') template.values: ( 'Camembert', ) + Templates are :ref:`generic ` over the type of the values which + are interpolated. + .. rubric:: Attributes .. attribute:: strings @@ -245,6 +248,8 @@ Types ... 3.0 | 1. + 2. | None | .2f + Interpolations are :ref:`generic ` over the types of their values. + .. rubric:: Attributes .. attribute:: value diff --git a/Doc/library/types.rst b/Doc/library/types.rst index 74898baa521bd69..7ed85f8266c44cd 100644 --- a/Doc/library/types.rst +++ b/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 ` over two types, for the keys + and values, respectively. + .. versionadded:: 3.3 .. versionchanged:: 3.9 diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 87dd860da4dcc46..2e21b5616e9979e 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -120,6 +120,9 @@ See :ref:`__slots__ documentation ` for details. This is a subclassable type rather than a factory function. + Weak references are :ref:`generic ` over the type of the object they + reference. + .. attribute:: __callback__ This read-only attribute returns the callback currently associated to the 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 index 000000000000000..d56ccbce2fa325c --- /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 9679a7dde31b0d0..dab6c8d94e9ba15 100644 --- a/Modules/_asynciomodule.c +++ b/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 their return type")}, {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 contained coroutine")}, {NULL, NULL} /* Sentinel */ }; diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c index 4ff05727ebc8ce3..ed78885f6882571 100644 --- a/Modules/_collectionsmodule.c +++ b/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 */ }; @@ -2340,7 +2340,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")}, + PyDoc_STR("defaultdicts are generic over two types, for the types of keys and values, respectively")}, {NULL} }; diff --git a/Modules/_ctypes/_ctypes.c b/Modules/_ctypes/_ctypes.c index 09eae97dd21a366..1dbf6db97a00a78 100644 --- 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 contents")}, { NULL, NULL } }; diff --git a/Modules/_functoolsmodule.c b/Modules/_functoolsmodule.c index c702eecc700ac80..12de9aac112fb0f 100644 --- 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 d5ba36273c82626..38de6b53c5d1601 100644 --- a/Modules/_queuemodule.c +++ b/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 */ }; diff --git a/Modules/_sre/sre.c b/Modules/_sre/sre.c index 044eb6e5f1fb662..b2e83c54bf14771 100644 --- a/Modules/_sre/sre.c +++ b/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} }; diff --git a/Modules/arraymodule.c b/Modules/arraymodule.c index 7f4427b114aafdd..bafe3cb589c8e9a 100644 --- a/Modules/arraymodule.c +++ b/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 contents")}, {NULL, NULL} /* sentinel */ }; diff --git a/Modules/itertoolsmodule.c b/Modules/itertoolsmodule.c index a6bfa78a461bb05..64bd309bb3575bb 100644 --- a/Modules/itertoolsmodule.c +++ b/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 */ }; diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index db29c6e5f08d6f8..ff864208755e043 100644 --- a/Modules/posixmodule.c +++ b/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} }; diff --git a/Objects/descrobject.c b/Objects/descrobject.c index a5926616eeb3cbf..0a66e83afffcf2c 100644 --- 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, for their keys and values, respectively")}, {"__reversed__", mappingproxy_reversed, METH_NOARGS, PyDoc_STR("D.__reversed__() -> reverse iterator")}, {0} diff --git a/Objects/dictobject.c b/Objects/dictobject.c index 3830fedd42bd273..56242b2581451af 100644 --- a/Objects/dictobject.c +++ b/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, for their keys and values, respectively")}, {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, for their keys and values, respectively")}, {"__getnewargs__", frozendict_getnewargs, METH_NOARGS}, {NULL, NULL} /* sentinel */ }; diff --git a/Objects/enumobject.c b/Objects/enumobject.c index 364d508dd01822c..f654df7eee03a0c 100644 --- 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("enumerations are generic over the type of their values")}, {NULL, NULL} /* sentinel */ }; diff --git a/Objects/exceptions.c b/Objects/exceptions.c index 5e5e87cd6d7559f..48ee57257904571 100644 --- 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 inner exceptions")}, BASEEXCEPTIONGROUP_DERIVE_METHODDEF BASEEXCEPTIONGROUP_SPLIT_METHODDEF BASEEXCEPTIONGROUP_SUBGROUP_METHODDEF diff --git a/Objects/genobject.c b/Objects/genobject.c index 8c5d720c0b9035c..82be36f9d8b87fa 100644 --- 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 type of their 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 type of their return value")}, {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 type of their values")}, {NULL, NULL} /* Sentinel */ }; diff --git a/Objects/interpolationobject.c b/Objects/interpolationobject.c index b58adb693f0cae5..e37724fb7852a27 100644 --- 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 c76721c5d2ac9ea..2dae089d7b0480e 100644 --- a/Objects/listobject.c +++ b/Objects/listobject.c @@ -3611,7 +3611,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 ebb3ed7360de682..41232621b67b9f7 100644 --- 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 contents, as retrieved by indexing")}, {NULL, NULL} }; diff --git a/Objects/setobject.c b/Objects/setobject.c index a1f654f0715bf39..9ae0ed1a8f3ebb5 100644 --- a/Objects/setobject.c +++ b/Objects/setobject.c @@ -2800,7 +2800,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 contents")}, {NULL, NULL} /* sentinel */ }; @@ -2904,7 +2905,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("frozenets are generic over the type of their contents")}, {NULL, NULL} /* sentinel */ }; diff --git a/Objects/sliceobject.c b/Objects/sliceobject.c index 96ff3118dc4405d..81aabe3df92fe99 100644 --- a/Objects/sliceobject.c +++ b/Objects/sliceobject.c @@ -562,7 +562,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 type of their values"}, {NULL, NULL} }; diff --git a/Objects/templateobject.c b/Objects/templateobject.c index a05208e4c8fc8e8..1f6f11acacbd1c8 100644 --- 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("Templates are generic over the type of the values which are interpolated")}, {NULL, NULL}, }; diff --git a/Objects/tupleobject.c b/Objects/tupleobject.c index 6120e70f3eeea43..4f475254d3633d7 100644 --- a/Objects/tupleobject.c +++ b/Objects/tupleobject.c @@ -958,7 +958,8 @@ 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, + PyDoc_STR("tuples are generic over the types of their contents, with type arguments which match the types and arity of their contents")}, {NULL, NULL} /* sentinel */ }; diff --git a/Objects/unionobject.c b/Objects/unionobject.c index 0f6b1e44bc2402c..7975741721f578f 100644 --- 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("unions types support [] as part of the typing specification")}, {0} }; diff --git a/Objects/weakrefobject.c b/Objects/weakrefobject.c index 61fa3ddad0bfd83..8446a2dbcf75593 100644 --- 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 62b582f271ffe57..e3e40d0585695c0 100644 --- a/Python/context.c +++ b/Python/context.c @@ -1098,7 +1098,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 value.")}, {NULL, NULL} }; @@ -1264,7 +1265,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} From d7976215809fa2654cdb185177b3b216b0b7b79d Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Sat, 23 May 2026 21:38:39 -0500 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Jelle Zijlstra --- Objects/setobject.c | 2 +- Objects/unionobject.c | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Objects/setobject.c b/Objects/setobject.c index 9ae0ed1a8f3ebb5..0a69ff8dc88d574 100644 --- a/Objects/setobject.c +++ b/Objects/setobject.c @@ -2906,7 +2906,7 @@ static PyMethodDef frozenset_methods[] = { SET_SYMMETRIC_DIFFERENCE_METHODDEF SET_UNION_METHODDEF {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, - PyDoc_STR("frozenets are generic over the type of their contents")}, + PyDoc_STR("frozensets are generic over the type of their contents")}, {NULL, NULL} /* sentinel */ }; diff --git a/Objects/unionobject.c b/Objects/unionobject.c index 7975741721f578f..1dc2927b6e6ac70 100644 --- a/Objects/unionobject.c +++ b/Objects/unionobject.c @@ -519,7 +519,7 @@ 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("unions types support [] as part of the typing specification")}, + PyDoc_STR("Create a union containing the given types")}, {0} }; From 3a51ab58975156d39872bb914106efbb7cad435d Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Sat, 23 May 2026 22:15:18 -0500 Subject: [PATCH 3/3] Correct several class getitem docs And expand the text for tuples. Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com> --- Doc/library/string.templatelib.rst | 3 --- Objects/genobject.c | 6 +++--- Objects/sliceobject.c | 2 +- Objects/templateobject.c | 2 +- Objects/tupleobject.c | 10 ++++++++-- 5 files changed, 13 insertions(+), 10 deletions(-) diff --git a/Doc/library/string.templatelib.rst b/Doc/library/string.templatelib.rst index 130217935a4279b..6e91850fdf59ca4 100644 --- a/Doc/library/string.templatelib.rst +++ b/Doc/library/string.templatelib.rst @@ -78,9 +78,6 @@ Types template.strings: ('Ah! We do have ', '.') template.values: ( 'Camembert', ) - Templates are :ref:`generic ` over the type of the values which - are interpolated. - .. rubric:: Attributes .. attribute:: strings diff --git a/Objects/genobject.c b/Objects/genobject.c index 82be36f9d8b87fa..38d493343454fce 100644 --- a/Objects/genobject.c +++ b/Objects/genobject.c @@ -1024,7 +1024,7 @@ static PyMethodDef gen_methods[] = { {"close", gen_close, METH_NOARGS, close_doc}, {"__sizeof__", gen_sizeof, METH_NOARGS, sizeof__doc__}, {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, - PyDoc_STR("generators are generic over the type of their values")}, + PyDoc_STR("generators are generic over the types of their yield, send, and return values")}, {NULL, NULL} /* Sentinel */ }; @@ -1376,7 +1376,7 @@ static PyMethodDef coro_methods[] = { {"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("coroutines are generic over the type of their return value")}, + PyDoc_STR("coroutines are generic over the types of their yield, send, and return values")}, {NULL, NULL} /* Sentinel */ }; @@ -1822,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("async generators are generic over the type of their values")}, + 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/sliceobject.c b/Objects/sliceobject.c index 81aabe3df92fe99..2456f28c7a08f20 100644 --- a/Objects/sliceobject.c +++ b/Objects/sliceobject.c @@ -563,7 +563,7 @@ 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, - "slices are generic over the type of their values"}, + "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 1f6f11acacbd1c8..1609e82b444516c 100644 --- a/Objects/templateobject.c +++ b/Objects/templateobject.c @@ -376,7 +376,7 @@ static PyMethodDef template_methods[] = { // 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("Templates are generic over the type of the values which are interpolated")}, + PyDoc_STR("Template supports [] for generic usage")}, {NULL, NULL}, }; diff --git a/Objects/tupleobject.c b/Objects/tupleobject.c index 4f475254d3633d7..60f08913db2adc4 100644 --- a/Objects/tupleobject.c +++ b/Objects/tupleobject.c @@ -954,12 +954,18 @@ 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\ +The type arguments to a tuple should match the types and arity of the 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 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("tuples are generic over the types of their contents, with type arguments which match the types and arity of their contents")}, + {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, tuple_class_getitem_doc}, {NULL, NULL} /* sentinel */ };