Update docs for Literal types#8152
Merged
Michael0x2a merged 3 commits intopython:masterfrom Jan 8, 2020
Merged
Conversation
This pull request is a long-overdue update of the Literal type docs. It: 1. Removes the "this is alpha" warning we have at the top. 2. Mentions Literal enums are a thing (and works in a brief example of one). 3. Adds a section about "intelligent indexing". 4. Adds a section about the "tagged union" pattern (see python#8151). I made the example focus on the TypedDict/JSON use case -- IMO that's really the only realistically useful use case for the pattern. 5. Cross-references the "tagged union" docs with the TypedDicts docs -- IMO, tagged unions are mostly useful when you're working with JSON I also thought about making the "Unions of TypedDict" section I added to the TypedDicts doc mention using [pydantic][0] as an alternative to the "tagged union" pattern. I personally prefer using libraries like this which handle validation and let me use regular classes (and `isinstance`) instead of dicts, but I wasn't sure whether we want to be recommending 3rd party libraries so held off for now. [0]: https://pydantic-docs.helpmanual.io
ilevkivskyi
approved these changes
Dec 20, 2019
Member
ilevkivskyi
left a comment
ilevkivskyi
left a comment
There was a problem hiding this comment.
Great! Thanks for updates, I have some optional comments here.
docs/source/literal_types.rst
Outdated
| from typing import overload, Union | ||
| from typing_extensions import Literal | ||
| # Note: if you are using Python 3.7 or earlier, you will need to import | ||
| # Literal from the typing_extensions module. |
Member
There was a problem hiding this comment.
I would make it a proper .. note:: (for example above at the start), we do this for Protocol for example.
docs/source/literal_types.rst
Outdated
|
|
||
| from typing_extensions import Final, Literal | ||
| # Note: if you are using Python 3.7 or earlier, you will need to import | ||
| # Literal and Final from the typing_extensions module. |
Member
There was a problem hiding this comment.
If you add the above one, this one would be unnecessary.
| lit_index: Literal[1] = 1 | ||
| fin_index: Final = 1 | ||
| reveal_type(tup[lit_index]) # Revealed type is 'str' | ||
| reveal_type(tup[fin_index]) # Revealed type is 'str' |
Member
There was a problem hiding this comment.
Maybe add an example with TypedDict? Maybe also an example with union of literals, something along these lines:
i: Literal[1, 2]
t: Tuple[str, int, int]
reveal_type(t[i]) # This is "int"
docs/source/literal_types.rst
Outdated
| .. code-block:: python | ||
|
|
||
| # Note: if you are using Python 3.7 or earlier, you will need to import | ||
| # Literal and TypedDict from the typing_extensions module. |
Member
There was a problem hiding this comment.
Again, it is not necessary to repeat everywhere if there is a dedicated note at the top.
| print(event["job_id"]) | ||
|
|
||
| While this feature is mostly useful when working with TypedDicts, you can also | ||
| use the same technique wih regular objects, tuples, or namedtuples. |
Member
There was a problem hiding this comment.
Mention that tags can also be proper enum values (using is) and classes (using isinstance()), not just strings.
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request is a long-overdue update of the Literal type docs. It:
Removes the "this is alpha" warning we have at the top.
Mentions Literal enums are a thing (and works in a brief example of one).
Adds a section about "intelligent indexing".
Adds a section about the "tagged union" pattern (see Add support for narrowing Literals using equality #8151). I made the example focus on the TypedDict/JSON use case -- IMO that's really the only realistically useful use case for the pattern.
Cross-references the "tagged union" docs with the TypedDicts docs.
I also thought about making the "Unions of TypedDict" section I added to the TypedDicts doc mention using pydantic as an alternative to the "tagged union" pattern.
I personally prefer using libraries like this which handle validation and let me use regular classes (and
isinstance) instead of dicts, but I wasn't sure whether we want to be recommending 3rd party libraries so held off for now. LMK if you think it's worth including it, and I can update the PR.