3.3. Type Annotation Mapping¶

Before Python 3.9 you need from typing import Dict
Since Python 3.9: PEP 585 -- Type Hinting Generics In Standard Collections
Since Python 3.10: PEP 604 -- Allow writing union types as X | Y

3.3.1. Dict¶

Empty:

>>> data: dict = {}
>>> data: dict = dict()

Generic:

>>> data: dict = {'firstname': 'Mark', 'lastname': 'Watney'}

Strict:

>>> data: dict[str, str] = {'firstname': 'Mark', 'lastname': 'Watney'}
>>> data: dict[str, str|int] = {'firstname': 'Mark', 'lastname': 'Watney', 'age': 40}
>>>
>>> data: dict[int, str] = {
...    0: 'setosa',
...    1: 'virginica',
...    2: 'versicolor'}
>>>
>>> data: dict[float, str] = {
...    5.8: 'Sepal length',
...    2.7: 'Sepal width',
...    5.1: 'Petal length',
...    1.9: 'Petal width'}
>>>
>>> data: dict[str, float] = {
...    'Sepal length': 5.8,
...    'Sepal width': 2.7,
...    'Petal length': 5.1,
...    'Petal width': 1.9}

3.3.2. List of Dicts¶

>>> data: list[dict] = [
...     {'features': [4.7, 3.2, 1.3, 0.2], 'label': 'setosa'},
...     {'features': [7.0, 3.2, 4.7, 1.4], 'label': 'versicolor'},
...     {'features': [7.6, 3.0, 6.6, 2.1], 'label': 'virginica'}]

>>> data: list[dict[str, list[float] | str]] = [
...     {'features': [4.7, 3.2, 1.3, 0.2], 'label': 'setosa'},
...     {'features': [7.0, 3.2, 4.7, 1.4], 'label': 'versicolor'},
...     {'features': [7.6, 3.0, 6.6, 2.1], 'label': 'virginica'}]

3.3.3. Aliases¶

>>> features = list[float]
>>> label = str
>>>
>>> data: list[dict[str, features|label]] = [
...     {'features': [4.7, 3.2, 1.3, 0.2], 'label': 'setosa'},
...     {'features': [7.0, 3.2, 4.7, 1.4], 'label': 'versicolor'},
...     {'features': [7.6, 3.0, 6.6, 2.1], 'label': 'virginica'}]

3.3.4. Typed Dict¶

Since Python 3.8: PEP 589 -- TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys

>>> from typing import TypedDict

>>> class Astronaut(TypedDict):
...     firstname: str
...     lastname: str
...     age: int | float
...
...
>>> def hello_astronaut(astronaut: Astronaut):
...     result = f'Hello {astronaut["firstname"]} {astronaut["lastname"]}'
...
...
>>> mark: Astronaut = {'firstname': 'Mark', 'lastname': 'Watney', 'age': 40}
>>> hello_astronaut(mark)  # ok
>>>
>>> mark: Astronaut = {'firstname': 'Mark', 'lastname': 'Watney'}
>>> hello_astronaut(mark)  # error: missing `age`  
>>>
>>> mark: Astronaut = {'firstname': 'Mark'}
>>> hello_astronaut(mark)  # error: missing `lastname` and `age`  
>>>
>>> mark = Astronaut(firstname='Mark', lastname='Watney', age=40)
>>> hello_astronaut(mark)  # ok
>>>
>>> mark = Astronaut(firstname='Mark', lastname='Watney')
>>> hello_astronaut(mark)  # error: missing `age`  
>>>
>>> mark = Astronaut(firstname='Mark')
>>> hello_astronaut(mark)  # error: missing `lastname`  
>>>
>>> iris = {'genus': 'Iris', 'species': 'Setosa'}
>>> hello_astronaut(iris)  # error: not an astronaut  

3.3.5. Future¶

Since Python 3.11 PEP 655 -- Marking individual TypedDict items as required or potentially-missing

>>> 
... from typing import Required, NotRequired
...
...
... class Astronaut(TypedDict):
...     firstname: Required[str]
...     lastname: Required[str]
...     age: NotRequired[int|float]
...
...
... def hello_astronaut(astronaut: Astronaut):
...     result = f'Hello {astronaut["firstname"]} {astronaut["lastname"]}')
...
...
... mark: Astronaut = {'firstname': 'Mark', 'lastname': 'Watney', 'age': 40}
... hello_astronaut(mark)  # ok
...
... mark: Astronaut = {'firstname': 'Mark', 'lastname': 'Watney'}
... hello_astronaut(mark)  # ok
...
... mark: Astronaut = {'firstname': 'Mark'}
... hello_astronaut(mark)  # error: missing `lastname`
...
... mark = Astronaut(firstname='Mark', lastname='Watney', age=40)
... hello_astronaut(mark)  # ok
...
... mark = Astronaut(firstname='Mark', lastname='Watney')
... hello_astronaut(mark)  # ok
...
... mark = Astronaut(firstname='Mark')
... hello_astronaut(mark)  # error: missing `lastname`
...
... iris = {'genus': 'Iris', 'species': 'Setosa'}
... hello_astronaut(iris)  # error: not an astronaut

3.3.6. Use Case - 0x01¶

>>> calendarium: dict[int, str] = {
...     1961: 'Yuri Gagarin fly to space',
...     1969: 'Neil Armstrong set foot on the Moon',
... }

3.3.7. Use Case - 0x02¶

>>> calendarium: dict[int, list[str]] = {
...     1961: ['Yuri Gagarin fly to space', 'Alan Shepard fly to space'],
...     1969: ['Neil Armstrong set foot on the Moon'],
... }

3.3.8. Further Reading¶

More information in Type Annotations
More information in CI/CD Type Checking