gh-130117: Document why nested Union, Literal, and Annotated types referenced through a type alias are not flattened
#130119
Conversation
|
All commit authors signed the Contributor License Agreement. |
|
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 |
vberlier
changed the title
Annotated types referenced through a type alias are not flattenedUnion, Literal, and Annotated types referenced through a type alias are not flattened
|
This also applies to |
vberlier
force-pushed
the
gh-130117
branch
2 times, most recently
from
929121a to
1aafc37
Compare
Lib/typing.py
Outdated
| @@ -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 | |||
There was a problem hiding this comment.
I think that we should document this in one place, no need to duplicate this info.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Alright I'll only modify typing.rst
Doc/library/typing.rst
Outdated
| @@ -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 | |||
There was a problem hiding this comment.
This sentence is likely to cause confusion for many readers. Literal and Union are very different things in the type system.
There was a problem hiding this comment.
Would it be better as "The Literal annotation supports the same operations as Union"?
There was a problem hiding this comment.
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.
Lib/typing.py
Outdated
| @@ -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 | |||
There was a problem hiding this comment.
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.
typing.Annotateddoes not flatten throughtyping.TypeAliasType#130117📚 Documentation preview 📚: https://cpython-previews--130119.org.readthedocs.build/