Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for Literal types #8152

Merged

Conversation

@Michael0x2a
Copy link
Collaborator

Michael0x2a commented Dec 16, 2019

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 #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.

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.

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
   #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
Copy link
Collaborator

ilevkivskyi left a comment

Great! Thanks for updates, I have some optional comments here.

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.

This comment has been minimized.

Copy link
@ilevkivskyi

ilevkivskyi Dec 20, 2019

Collaborator

I would make it a proper .. note:: (for example above at the start), we do this for Protocol for example.

@@ -115,7 +106,9 @@ you can instead change the variable to be ``Final`` (see :ref:`final_attrs`):

.. code-block:: python
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.

This comment has been minimized.

Copy link
@ilevkivskyi

ilevkivskyi Dec 20, 2019

Collaborator

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'

This comment has been minimized.

Copy link
@ilevkivskyi

ilevkivskyi Dec 20, 2019

Collaborator

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"
.. 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.

This comment has been minimized.

Copy link
@ilevkivskyi

ilevkivskyi Dec 20, 2019

Collaborator

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.

This comment has been minimized.

Copy link
@ilevkivskyi

ilevkivskyi Dec 20, 2019

Collaborator

Mention that tags can also be proper enum values (using is) and classes (using isinstance()), not just strings.

Michael0x2a added 2 commits Dec 23, 2019
@Michael0x2a Michael0x2a merged commit 7055725 into python:master Jan 8, 2020
1 check passed
1 check passed
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@Michael0x2a Michael0x2a deleted the Michael0x2a:adjust-docs-for-literal-types branch Jan 8, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants
You can’t perform that action at this time.