gh-130117: Document why nested `Union`, `Literal`, and `Annotated` types referenced through a type alias are not flattened #130119

vberlier · 2025-02-14T17:05:58Z

Issue: typing.Annotated does not flatten through typing.TypeAliasType #130117

📚 Documentation preview 📚: https://cpython-previews--130119.org.readthedocs.build/

ghost · 2025-02-14T17:06:03Z

All commit authors signed the Contributor License Agreement.

bedevere-app · 2025-02-14T17:06:04Z

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

Lib/typing.py

vberlier · 2025-02-14T20:00:45Z

This also applies to Union and Literal, so I updated them as well. I also noticed the documentation for Literal was missing some of the helpful details that we have in the documentation for Union and Annotated.

sobolevn · 2025-02-20T06:10:49Z

Lib/typing.py

@@ -765,6 +765,13 @@ def Union(self, parameters):

        assert Union[Union[int, str], float] == Union[int, str, float]

+      However, this does not apply to unions referenced through a type


I think that we should document this in one place, no need to duplicate this info.

Do you mean the existing duplication between typing.rst and typing.py? I assume it's intended so I don't want to make the two diverge by only updating one of them.

Or is it that you'd prefer a separate section for mentioning that Union/Literal/Annotated flattening doesn't work with TypeAliasType, instead of it being inlined within each type's respective documentation?

I'd rather document a specific caveat about a feature as close as possible to where the feature itself is documented, otherwise it could easily be missed by readers. And since the flattening behavior is explained in each type's respective documentation, it makes sense to follow suit. I'm guessing that this is the intent of the original authors as the overall redundancy in the properties listed for Union/Literal/Annotated probably reduces the need to jump up and down the page to a hypothetical common section about "union-like" types when reading.

In general, the docstrings are meant to be more concise. I think the new information in this PR is specialized enough that we can document it only in typing.rst and not the docstrings.

Alright I'll only modify typing.rst

JelleZijlstra · 2025-03-03T23:05:33Z

Doc/library/typing.rst

@@ -1222,6 +1228,33 @@ These can be used as types in annotations. They all support subscription using
   is allowed as type argument to ``Literal[...]``, but type checkers may
   impose restrictions. See :pep:`586` for more details about literal types.

+   ``Literal`` is very similar to :class:`Union`, the main difference is that its


This sentence is likely to cause confusion for many readers. Literal and Union are very different things in the type system.

Would it be better as "The Literal annotation supports the same operations as Union"?

I think it's better not to draw comparisons. Literal and Union have similar runtime behavior but they mean different things, and I don't think it will help most readers to compare them.

Fair enough

JelleZijlstra · 2025-03-03T23:06:39Z

Lib/typing.py

@@ -765,6 +765,13 @@ def Union(self, parameters):

        assert Union[Union[int, str], float] == Union[int, str, float]

+      However, this does not apply to unions referenced through a type


In general, the docstrings are meant to be more concise. I think the new information in this PR is specialized enough that we can document it only in typing.rst and not the docstrings.

…s are not flattened

Doc/library/typing.rst

Co-authored-by: Jelle Zijlstra <[email protected]>

JelleZijlstra · 2025-05-05T13:55:08Z

This has a merge conflict now.

miss-islington-app · 2025-05-06T02:05:20Z

Thanks @vberlier for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

…ed` types referenced through a type alias are not flattened (pythonGH-130119) (cherry picked from commit b936ccd) Co-authored-by: Valentin Berlier <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>

bedevere-app · 2025-05-06T02:05:30Z

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

…ted` types referenced through a type alias are not flattened (GH-130119) (#133488) gh-130117: Document why nested `Union`, `Literal`, and `Annotated` types referenced through a type alias are not flattened (GH-130119) (cherry picked from commit b936ccd) Co-authored-by: Valentin Berlier <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>

vberlier · 2025-05-06T21:38:15Z

Thanks for taking the time to merge this! Is there an automated workflow that's supposed to close the associated issue or should we close it manually?

…ed` types referenced through a type alias are not flattened (python#130119) Co-authored-by: Jelle Zijlstra <[email protected]>

vberlier requested review from JelleZijlstra and AlexWaygood as code owners February 14, 2025 17:05

bedevere-app bot added the awaiting review label Feb 14, 2025

bedevere-app bot mentioned this pull request Feb 14, 2025

typing.Annotated does not flatten through typing.TypeAliasType #130117

Closed

sobolevn added the skip news label Feb 14, 2025

sobolevn reviewed Feb 14, 2025

View reviewed changes

Lib/typing.py Outdated Show resolved Hide resolved

vberlier changed the title ~~gh-130117: Document that nested Annotated types referenced through a type alias are not flattened~~ gh-130117: Document why nested Union, Literal, and Annotated types referenced through a type alias are not flattened Feb 14, 2025

vberlier force-pushed the gh-130117 branch 2 times, most recently from 929121a to 1aafc37 Compare February 19, 2025 23:33

vberlier requested a review from sobolevn February 19, 2025 23:35

sobolevn reviewed Feb 20, 2025

View reviewed changes

vberlier requested a review from sobolevn March 1, 2025 00:23

JelleZijlstra reviewed Mar 3, 2025

View reviewed changes

vberlier added 3 commits March 4, 2025 00:26

Document that nested Annotated types referenced through a type alia…

7dc0ee8

…s are not flattened

Explain why alias is not flattened

88fb637

Same improvement to the documentation of Union and Literal

0885a93

vberlier force-pushed the gh-130117 branch from 1aafc37 to 0885a93 Compare March 3, 2025 23:26

vberlier added 2 commits March 4, 2025 00:33

Revert all docstring changes

57b32a4

Do not draw comparisons between Literal and Union

fd75adf

vberlier requested a review from JelleZijlstra March 6, 2025 21:59

JelleZijlstra reviewed May 4, 2025

View reviewed changes

Doc/library/typing.rst Outdated Show resolved Hide resolved

Fix typo Union -> Literal

511797c

Co-authored-by: Jelle Zijlstra <[email protected]>

Merge branch 'main' into pythongh-130117

593c7ac

JelleZijlstra approved these changes May 6, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting review labels May 6, 2025

JelleZijlstra added the needs backport to 3.13 bugs and security fixes label May 6, 2025

JelleZijlstra merged commit b936ccd into python:main May 6, 2025
30 checks passed

bedevere-app bot removed the awaiting merge label May 6, 2025

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label May 6, 2025

		@@ -765,6 +765,13 @@ def Union(self, parameters):

		assert Union[Union[int, str], float] == Union[int, str, float]

		However, this does not apply to unions referenced through a type

Uh oh!

gh-130117: Document why nested Union, Literal, and Annotated types referenced through a type alias are not flattened #130119

gh-130117: Document why nested Union, Literal, and Annotated types referenced through a type alias are not flattened #130119

Uh oh!

Conversation

vberlier commented Feb 14, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghost commented Feb 14, 2025 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bedevere-app bot commented Feb 14, 2025

Uh oh!

Uh oh!

vberlier commented Feb 14, 2025

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JelleZijlstra commented May 5, 2025

Uh oh!

Uh oh!

miss-islington-app bot commented May 6, 2025

Uh oh!

bedevere-app bot commented May 6, 2025

Uh oh!

vberlier commented May 6, 2025

Uh oh!

Uh oh!

gh-130117: Document why nested `Union`, `Literal`, and `Annotated` types referenced through a type alias are not flattened #130119

gh-130117: Document why nested `Union`, `Literal`, and `Annotated` types referenced through a type alias are not flattened #130119

vberlier commented Feb 14, 2025 •

edited by github-actions bot

Loading

ghost commented Feb 14, 2025 •

edited by ghost

Loading