gh-150319: Replace all documentation which says "See PEP 585" by sirosen · Pull Request #150325 · python/cpython

sirosen · 2026-05-23T22:37:40Z

This is a documentation update touching many modules, eliminating text which says "See PEP 585".
The general phrasing used is "X is generic over Y", and this is kept consistent as much as possible.
We can use different phrasing; the goal here is to be consistent in whatever we choose.

For types visible in the stdlib, documentation is also lifted up into class-level docs.
For builtins, however, the story for documenting this is in many cases more complex.
Therefore, updates to the doc pages are omitted for now.

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)

Additional issues resolved:

resolves Clarify what memoryview is generic in #149488
resolves Links to PEP 585 in Generic types #140121

Issue: Document generic parameters of generic classes #150319

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)

read-the-docs-community · 2026-05-23T22:41:16Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32826532 | 📁 Comparing 3a51ab5 against main (fad0674)

🔍 Preview build

14 files changed · ± 14 modified

± Modified

JelleZijlstra · 2026-05-24T02:09:37Z

      template.strings:  ('Ah! We do have ',              '.')
      template.values:   (                   'Camembert',    )

+   Templates are :ref:`generic <generics>` over the type of the values which


Template is actually not generic in typeshed at the moment. There has been some low-level discussion about whether and how they should be generic.

Hm. Given that there's debate about how it should work, I can strike this line. But what should I put in the docstring for it? Maybe just Template supports []?

Yes, I'd remove the line from the RST docs and put something noncommittal in the __class_getitem__ docstring.

JelleZijlstra · 2026-05-24T02:11:43Z

    {"__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")},


They are actually generic over three type variables (yield, send, and return type).

Oh, yes! I often see these given as None. I'll fix.

JelleZijlstra · 2026-05-24T02:12:29Z

    {"__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")},


Also three typevars: yield, send, and return. (Though in practice the first two are usually given as Any and I'm not sure they have much practical use.)

JelleZijlstra · 2026-05-24T02:12:45Z

    {"__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")},


Two typevars: yield and send.

JelleZijlstra · 2026-05-24T02:13:35Z

    {"__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"},


In typeshed they are generic over three typevars, for start, end, and step.

Oof! I've made more mistakes than I wanted in this PR. Thanks for all the good catches.

JelleZijlstra · 2026-05-24T02:14:32Z

    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")},


This could use a longer explanation, mentioning the use of tuple[T, ...] for arbitrary-length tuples and tuple[A], tuple[A, B] etc., for fixed-length tuples.

Okay, I think I'll break it out into a PyDoc_STRVAR so that I can make it more legible in that case.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

JelleZijlstra · 2026-05-24T03:10:34Z

Also, any reason you didn't add any wording to the documentation for the builtin generic classes (list etc.)?

And expand the text for tuples. Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>

sirosen · 2026-05-24T03:17:18Z

I pushed the corrections in a co-authored commit, along with

expanded the doc for tuple
made the doc for Template really barebones

sirosen requested review from 1st1, AA-Turner, JelleZijlstra, ZeroIntensity, asvetlov, iritkatriel, kumaraditya303, lysnikolaou, markshannon, methane, rhettinger and willingc as code owners May 23, 2026 22:37

bedevere-app Bot mentioned this pull request May 23, 2026

Document generic parameters of generic classes #150319

Open

bedevere-app Bot added the awaiting review label May 23, 2026

JelleZijlstra reviewed May 24, 2026

View reviewed changes

Apply suggestions from code review

d797621

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

Correct several class getitem docs

3a51ab5

And expand the text for tuples. Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>

Uh oh!

Conversation

sirosen commented May 23, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented May 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JelleZijlstra May 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JelleZijlstra commented May 24, 2026

Uh oh!

sirosen commented May 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sirosen commented May 23, 2026 •

edited by bedevere-app Bot

Loading

read-the-docs-community Bot commented May 23, 2026 •

edited

Loading

JelleZijlstra May 24, 2026 •

edited

Loading