Skip to content

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

Open
sirosen wants to merge 7 commits into
python:mainfrom
sirosen:improve-all-see-pep-585-docstrings
Open

gh-150319: Replace all documentation which says "See PEP 585"#150325
sirosen wants to merge 7 commits into
python:mainfrom
sirosen:improve-all-see-pep-585-docstrings

Conversation

@sirosen
Copy link
Copy Markdown
Contributor

@sirosen sirosen commented May 23, 2026

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:


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
Copy link
Copy Markdown

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

Comment thread Doc/library/string.templatelib.rst Outdated
template.strings: ('Ah! We do have ', '.')
template.values: ( 'Camembert', )

Templates are :ref:`generic <generics>` over the type of the values which
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 []?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread Objects/genobject.c Outdated
Comment thread Objects/genobject.c Outdated
Comment thread Objects/genobject.c Outdated
Comment thread Objects/setobject.c Outdated
Comment thread Objects/sliceobject.c Outdated
Comment thread Objects/tupleobject.c Outdated
Comment thread Objects/unionobject.c Outdated
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
@JelleZijlstra
Copy link
Copy Markdown
Member

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
Copy link
Copy Markdown
Contributor Author

sirosen commented May 24, 2026

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

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

@sirosen
Copy link
Copy Markdown
Contributor Author

sirosen commented May 25, 2026

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
Copy link
Copy Markdown
Contributor Author

sirosen commented May 25, 2026

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.

Comment thread Doc/library/functions.rst Outdated
yield n, elem
n += 1

Enumerations are `generic <generics>` over the type of their values.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit problematic:

  • Nothing else in this section calls enumerate object "enumerations"; the docstring says "Return an enumerate object".
  • We don't even document enumerate as a class, even though it is one. That makes the mention of generics potentially confusing here.

My preference would be to just not mention generics in the enumerate() docs.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I wasn't sure about this in the first place. Striking it in my current changes. 👍

Fix `generic` links which weren't marked as `:ref:`.
Copy link
Copy Markdown
Member

@JelleZijlstra JelleZijlstra left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

Comment thread Doc/library/stdtypes.rst Outdated
built-in.


lists are `generic <generics>` over the types of their contents.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
lists are `generic <generics>` over the types of their contents.
Lists are `generic <generics>` over the types of their contents.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 I just got to that one as I was fixing some typos that prek caught. (Also made me run prek install, which I was missing!)

Comment thread Doc/library/stdtypes.rst Outdated
operations.

Tuples are `generic <generics>` over the types of their contents.
The type arguments to a tuple should match the types and arity of the contents.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this sentence adds much, could we just delete it? (Here and in the corresponding docstring.)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, with the examples maybe it's unnecessary. Removing.

@JelleZijlstra JelleZijlstra requested a review from AlexWaygood May 25, 2026 02:28
Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify what memoryview is generic in Links to PEP 585 in Generic types

2 participants