Add docs for Literal types #6150
Conversation
This pull request adds some documentation on using Literal types. It focuses mostly on how they can be parameterized, and different ways of declaring variables to be Literal. These docs deliberately do not mention the "intelligent indexing" feature: we don't yet support intelligently indexing using variables that are declared to be Final, so I think we should leave this feature undocumented for now.
|
Also, we should probably delay merging this PR until we've released a new version of |
|
@bluetech -- Thanks! I made all of the changes you suggested. |
docs/source/more_types.rst
Outdated
|
|
||
| Literal is an officially supported feature, but is highly experimental | ||
| and should be considered to be in alpha stage. It is very likely that future | ||
| releases of mypy will modify the behavior of Literal types, either by adding |
There was a problem hiding this comment.
| releases of mypy will modify the behavior of Literal types, either by adding | |
| releases of mypy will modify the behavior of literal types, either by adding |
There was a problem hiding this comment.
Just to double-check, did you want me to lowercase every instance where I use "Literal" as a proper noun?
I capitalized this (and every other time I used the phrase "Literal types") because I wanted to refer specifically to the Literal[...] type itself. I can lowercase this if there's a good reason for it, but then we should probably lowercase that phrase every other time I use it.
There was a problem hiding this comment.
Ideally I would prefer to always use one of two: literal or ``Literal`` (i.e. if it is capitalized, then it is ``code``).
docs/source/more_types.rst
Outdated
| reveal_type(b) # Revealed type is 'int' | ||
|
|
||
| If you find repeating the value of the variable in the type hint to be tedious, | ||
| you can instead declare the variable to be :ref:`Final <final_attrs>`: |
There was a problem hiding this comment.
"Final variable" is an kind of oxymoron. I would rather say "final name", or reformulate this otherwise.
There was a problem hiding this comment.
I decided to rephrase this to say "you can instead change the variable to be Final" (and did a similar thing below).
|
Can you create a new top-level file for literal types? |
|
@JukkaL and @ilevkivskyi -- FYI: I made the last few changes you suggested! (I moved the doc to the top level and changed the capitalization). |
This pull request adds some documentation on using Literal types.
It focuses mostly on how they can be parameterized, and different ways of declaring variables to be Literal.
These docs deliberately do not mention the "intelligent indexing" feature: we don't yet support intelligently indexing using variables that are declared to be Final, so I think we should leave this feature undocumented for now.
(I'll add in that feature + update the docs once #6081 lands.)