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:

resolvesClarify what memoryview is generic in #149488
resolvesLinks 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 #32959145 | 📁 Comparing cc9a5cf against main (fad0674)

🔍 Preview build

60 files changed · ± 60 modified

±Modified

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 · 2026-05-25T01:51:50Z

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

Missed this question yesterday, sorry!

I thought they would grow scope here too much. I'm treating the question as a nudge and will take a look at adding all of them.

sirosen · 2026-05-25T02:23:56Z

I have still omitted two things because I wasn't quite sure where to document them:

slice
generators (already covered in the typing docs?)

I'm also not 100% confident that a few of these, like list, are documented in the right place, but I took my best initial guess.

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

JelleZijlstra

Thanks!

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

sirosen · 2026-06-02T16:51:38Z

If you thinkg "signifying" is too heavy, you can also use "namely".
Hmm, I much prefer "signifying" here haha. It sounds odd to me to say the type parameters do "name" the key/value types; it makes much more sense to me to say they signify/represent the key types

"signify" or "represent" work, as does "is" or other phrasings of equivalence.

There are some phrasing options which open up if we're willing to name the type vars.

e.g.,

dicts are generic over two types, K and V, where K is the type of the keys and V is the type of the values

Just to show a sample of another style, using "represent", we can write:

dicts are generic over two types, K and V, which represent the types of the keys (K) and values (V)

Personally, I think the current style is nice for a brief one-sentence description. For anything more explicit, I'd like more demonstrative docs like the typing page provides.

picnixz

After relooking at the PR, I think we just need a great cleanup with all those inconsistent wordings (even locally) but this specific PR is in good shape!

AlexWaygood · 2026-06-02T20:13:21Z

Thanks again. This is really great.

miss-islington-app · 2026-06-02T20:13:39Z

Thanks @sirosen for the PR, and @AlexWaygood for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

miss-islington-app · 2026-06-02T20:13:48Z

Sorry, @sirosen and @AlexWaygood, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 50fe49c879af352914da3baa40c7fd1fb170028c 3.14

bedevere-app · 2026-06-02T20:13:53Z

GH-150808 is a backport of this pull request to the 3.15 branch.

miss-islington-app · 2026-06-02T20:13:54Z

Sorry, @sirosen and @AlexWaygood, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 50fe49c879af352914da3baa40c7fd1fb170028c 3.13

…H-150325) (#150808) 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 50fe49c) 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>

…ython#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 Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> * Correct several class getitem docs And expand the text for tuples. Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com> * 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 Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com> * Apply suggestions from code review These are applied at both the originally indicated locations and in the corresponding docstring definitions. Co-authored-by: Alex Waygood <66076021+AlexWaygood@users.noreply.github.com> * Update Doc/library/re.rst Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> * Update Objects/enumobject.c Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> * 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 Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> * 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. Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> * 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 Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> * Fix line endings and wrap more tightly Line endings fixed by pre-commit ; also re-wrapped the MappingProxyType text which was too long. * Use 'ContextVars' style in sphinx doc --------- Co-authored-by: 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>

bedevere-app · 2026-06-02T21:56:34Z

GH-150813 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2026-06-02T22:03:23Z

GH-150814 is a backport of this pull request to the 3.13 branch.

…150325) (#150813) gh-150319: Replace all documentation which says "See PEP 585" (#150325) * Replace all documentation which says "See PEP 585" The following classes in the stdlib get simple updates: - array.array - asyncio.Future - asyncio.Task - collections.defaultdict - collections.deque - contextvars.ContextVar - contextvars.Token - ctypes.Array - os.DirEntry - re.Match - re.Pattern - string.templatelib.Interpolation - string.templatelib.Template - types.MappingProxyType - queue.SimpleQueue - weakref.ref The following classes are documented publicly as functions, and are therefore updated internally (`__class_getitem__.__doc__`) but not in the public docs: - functools.partial - itertools.chain The following builtin types have updates to `__class_getitem__.__doc__` but not to any documentation pages: - BaseExceptionGroup - coroutines (from generators) - dict - enumerate - frozendict - frozenset - generators (and async generators) - list - memoryview - set - slice - tuple Special cases: - union objects are now documented as "supporting class-level []", rather than anything to do with generics. - Templates might be generic over a single type (union, in theory) or over a TypeVarTuple. As this is not currently fully settled, it is marked with a comment and a mild hint that it is a single type is used (namely, "type" is singular rather than "types", plural) * Apply suggestions from code review * Correct several class getitem docs And expand the text for tuples. * Add notes on generic typing of builtins * Fix typo in tuple.__class_getitem__ docstring * Typo fix: malformed refs Fix `generic` links which weren't marked as `:ref:`. * Strike unnecessary docs on generic-ness * Apply suggestions from code review These are applied at both the originally indicated locations and in the corresponding docstring definitions. * Update Doc/library/re.rst * Update Objects/enumobject.c * Remove tuple generic doc in 'stdtypes' page This is covered in more detail in the cross-linked typing documentation. The other copy of this documentation -- in the docstring for `tuple.__class_getitem__` -- is left in place. * Fix whitespace around new doc of generics Per review, do not introduce or remove whitespace such that section breaks are altered by the introduction of doc on various generic types. In most cases, this is a removal of an extra line. In one case (Arrays), it is the reintroduction of a line. Additionally, two other minor fixes are included: - incorrect indent on 'defaultdicts' - make `mappingproxy.__class_getitem__.__doc__` consistent with other mapping type generic docs * Move placement of memoryview generic note Previous placement was at the end of the main docstring, which is consistent with other types but places it after a section on various methods (which makes it read somewhat inconsistently). Moving it up helps resolve. * Ensure sphinxdoc does not start sentences lowercase Lowercase class names at the start of sentences are marked out with the `class` role. In the case of `deque`, documentation already refers to these as `Deques`, so this form is preferred. * Apply suggestions from code review * Fix line endings and wrap more tightly Line endings fixed by pre-commit ; also re-wrapped the MappingProxyType text which was too long. * Use 'ContextVars' style in sphinx doc --------- Co-authored-by: Stephen Rosen <sirosen@globus.org> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

…150325) (#150814) gh-150319: Replace all documentation which says "See PEP 585" (#150325) * Replace all documentation which says "See PEP 585" The following classes in the stdlib get simple updates: - array.array - asyncio.Future - asyncio.Task - collections.defaultdict - collections.deque - contextvars.ContextVar - contextvars.Token - ctypes.Array - os.DirEntry - re.Match - re.Pattern - string.templatelib.Interpolation - string.templatelib.Template - types.MappingProxyType - queue.SimpleQueue - weakref.ref The following classes are documented publicly as functions, and are therefore updated internally (`__class_getitem__.__doc__`) but not in the public docs: - functools.partial - itertools.chain The following builtin types have updates to `__class_getitem__.__doc__` but not to any documentation pages: - BaseExceptionGroup - coroutines (from generators) - dict - enumerate - frozendict - frozenset - generators (and async generators) - list - memoryview - set - slice - tuple Special cases: - union objects are now documented as "supporting class-level []", rather than anything to do with generics. - Templates might be generic over a single type (union, in theory) or over a TypeVarTuple. As this is not currently fully settled, it is marked with a comment and a mild hint that it is a single type is used (namely, "type" is singular rather than "types", plural) * Apply suggestions from code review * Correct several class getitem docs And expand the text for tuples. * Add notes on generic typing of builtins * Fix typo in tuple.__class_getitem__ docstring * Typo fix: malformed refs Fix `generic` links which weren't marked as `:ref:`. * Strike unnecessary docs on generic-ness * Apply suggestions from code review These are applied at both the originally indicated locations and in the corresponding docstring definitions. * Update Doc/library/re.rst * Update Objects/enumobject.c * Remove tuple generic doc in 'stdtypes' page This is covered in more detail in the cross-linked typing documentation. The other copy of this documentation -- in the docstring for `tuple.__class_getitem__` -- is left in place. * Fix whitespace around new doc of generics Per review, do not introduce or remove whitespace such that section breaks are altered by the introduction of doc on various generic types. In most cases, this is a removal of an extra line. In one case (Arrays), it is the reintroduction of a line. Additionally, two other minor fixes are included: - incorrect indent on 'defaultdicts' - make `mappingproxy.__class_getitem__.__doc__` consistent with other mapping type generic docs * Move placement of memoryview generic note Previous placement was at the end of the main docstring, which is consistent with other types but places it after a section on various methods (which makes it read somewhat inconsistently). Moving it up helps resolve. * Ensure sphinxdoc does not start sentences lowercase Lowercase class names at the start of sentences are marked out with the `class` role. In the case of `deque`, documentation already refers to these as `Deques`, so this form is preferred. * Apply suggestions from code review * Fix line endings and wrap more tightly Line endings fixed by pre-commit ; also re-wrapped the MappingProxyType text which was too long. * Use 'ContextVars' style in sphinx doc --------- Co-authored-by: Stephen Rosen <sirosen@globus.org> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

JelleZijlstra · 2026-06-03T02:40:46Z

Thank you for your contribution @sirosen!

sirosen · 2026-06-03T16:07:12Z

And thank all of you for coaching me through this one!

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-appBot mentioned this pull request May 23, 2026
Document generic parameters of generic classes #150319
Closed

bedevere-appBot added the awaiting review label May 23, 2026

JelleZijlstra reviewed May 24, 2026
View reviewed changes

Comment threadDoc/library/string.templatelib.rst Outdated

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>

sirosen added 2 commits May 24, 2026 21:20

Add notes on generic typing of builtins
3f22858

Fix typo in tuple.__class_getitem__ docstring
33770c7

JelleZijlstra reviewed May 25, 2026
View reviewed changes

Comment threadDoc/library/functions.rst Outdated

Typo fix: malformed refs
cf6e6b6
Fix `generic` links which weren't marked as `:ref:`.

JelleZijlstra reviewed May 25, 2026
View reviewed changes

Comment threadDoc/library/stdtypes.rst Outdated
Comment threadDoc/library/stdtypes.rst Outdated

JelleZijlstra requested a review from AlexWaygood May 25, 2026 02:28

Fix line endings and wrap more tightly
5dcee42
Line endings fixed by pre-commit ; also re-wrapped the MappingProxyType text which was too long.

AlexWaygood removed the awaiting changes label Jun 2, 2026

Use 'ContextVars' style in sphinx doc
cc9a5cf

picnixz approved these changes Jun 2, 2026
View reviewed changes

bedevere-appBot added the awaiting merge label Jun 2, 2026

AlexWaygood added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jun 2, 2026

AlexWaygood merged commit 50fe49c into python:mainJun 2, 2026
64 checks passed

bedevere-appBot removed the awaiting merge label Jun 2, 2026

miss-islington-appBot assigned AlexWaygood Jun 2, 2026

bedevere-appBot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jun 2, 2026

bedevere-appBot removed the needs backport to 3.14 bugs and security fixes label Jun 2, 2026

bedevere-appBot removed the needs backport to 3.13 bugs and security fixes label Jun 2, 2026

sirosen deleted the improve-all-see-pep-585-docstrings branch June 3, 2026 02:10

sirosen mentioned this pull request Jun 3, 2026
Feature: Expand the style-guide to cover how type names should be written in prose python/devguide#1821
Closed

Uh oh!

Uh oh!

Conversation

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

Uh oh!

Uh oh!

read-the-docs-communityBot 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JelleZijlstra commented May 24, 2026

Uh oh!

sirosen commented May 24, 2026

Uh oh!

sirosen commented May 25, 2026

Uh oh!

sirosen commented May 25, 2026

Uh oh!

Uh oh!

JelleZijlstra left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sirosen commented Jun 2, 2026

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

AlexWaygood commented Jun 2, 2026

Uh oh!

Uh oh!

miss-islington-appBot commented Jun 2, 2026

Uh oh!

miss-islington-appBot commented Jun 2, 2026

Uh oh!

bedevere-appBot commented Jun 2, 2026

Uh oh!

miss-islington-appBot commented Jun 2, 2026

Uh oh!

bedevere-appBot commented Jun 2, 2026

Uh oh!

bedevere-appBot commented Jun 2, 2026

Uh oh!

JelleZijlstra commented Jun 3, 2026

Uh oh!

sirosen commented Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sirosen commented May 23, 2026•
edited
Loading

read-the-docs-communityBot commented May 23, 2026•
edited
Loading