cheat_sheet_py3.rst

.. _cheat-sheet-py3:

Type hints cheat sheet
======================

This document is a quick cheat sheet showing how to use type
annotations for various common types in Python.

Variables
*********

Technically many of the type annotations shown below are redundant,
since mypy can usually infer the type of a variable from its value.
See :ref:`type-inference-and-annotations` for more details.

.. code-block:: python

# This is how you declare the type of a variable
 age: int=1

# You don't need to initialize a variable to annotate it
 a: int# Ok (no value at runtime until assigned)

# Doing so can be useful in conditional branches
 child: bool
if age <18:
 child =True
else:
 child =False


Useful built-in types
*********************

.. code-block:: python

# For most types, just use the name of the type in the annotation
# Note that mypy can usually infer the type of a variable from its value,
# so technically these annotations are redundant
 x: int=1
 x: float=1.0
 x: bool=True
 x: str="test"
 x: bytes=b"test"

# For collections on Python 3.9+, the type of the collection item is in brackets
 x: list[int] = [1]
 x: set[int] = {6, 7}

# For mappings, we need the types of both keys and values
 x: dict[str, float] = {"field": 2.0} # Python 3.9+

# For tuples of fixed size, we specify the types of all the elements
 x: tuple[int, str, float] = (3, "yes", 7.5) # Python 3.9+

# For tuples of variable size, we use one type and ellipsis
 x: tuple[int, ...] = (1, 2, 3) # Python 3.9+

# On Python 3.8 and earlier, the name of the collection type is
# capitalized, and the type is imported from the 'typing' module
from typing import List, Set, Dict, Tuple
 x: List[int] = [1]
 x: Set[int] = {6, 7}
 x: Dict[str, float] = {"field": 2.0}
 x: Tuple[int, str, float] = (3, "yes", 7.5)
 x: Tuple[int, ...] = (1, 2, 3)

from typing import Union, Optional

# On Python 3.10+, use the | operator when something could be one of a few types
 x: list[int|str] = [3, 5, "test", "fun"] # Python 3.10+
# On earlier versions, use Union
 x: list[Union[int, str]] = [3, 5, "test", "fun"]

# Use X | None for a value that could be None on Python 3.10+
# Use Optional[X] on 3.9 and earlier; Optional[X] is the same as 'X | None'
 x: str|None="something"if some_condition() elseNone
if x isnotNone:
# Mypy understands x won't be None here because of the if-statement
print(x.upper())
# If you know a value can never be None due to some logic that mypy doesn't
# understand, use an assert
assert x isnotNone
print(x.upper())

Functions
*********

.. code-block:: python

from collections.abc import Iterator, Callable
from typing import Union, Optional

# This is how you annotate a function definition
defstringify(num: int) -> str:
returnstr(num)

# And here's how you specify multiple arguments
defplus(num1: int, num2: int) -> int:
return num1 + num2

# If a function does not return a value, use None as the return type
# Default value for an argument goes after the type annotation
defshow(value: str, excitement: int=10) -> None:
print(value +"!"* excitement)

# Note that arguments without a type are dynamically typed (treated as Any)
# and that functions without any annotations are not checked
defuntyped(x):
 x.anything() +1+"string"# no errors

# This is how you annotate a callable (function) value
 x: Callable[[int, float], float] = f
defregister(callback: Callable[[str], int]) -> None: ...

# A generator function that yields ints is secretly just a function that
# returns an iterator of ints, so that's how we annotate it
defgen(n: int) -> Iterator[int]:
 i =0
while i < n:
yield i
 i +=1

# You can of course split a function annotation over multiple lines
defsend_email(
address: str| list[str],
sender: str,
cc: list[str] |None,
bcc: list[str] |None,
subject: str='',
body: list[str] |None=None,
 ) -> bool:
...

# Mypy understands positional-only and keyword-only arguments
# Positional-only arguments can also be marked by using a name starting with
# two underscores
defquux(x: int, /, *, y: int) -> None:
pass

 quux(3, y=5) # Ok
 quux(3, 5) # error: Too many positional arguments for "quux"
 quux(x=3, y=5) # error: Unexpected keyword argument "x" for "quux"

# This says each positional arg and each keyword arg is a "str"
defcall(self, *args: str, **kwargs: str) -> str:
 reveal_type(args) # Revealed type is "tuple[str, ...]"
 reveal_type(kwargs) # Revealed type is "dict[str, str]"
 request = make_request(*args, **kwargs)
returnself.do_api_query(request)

Classes
*******

.. code-block:: python

from typing import ClassVar

classBankAccount:
# The "__init__" method doesn't return anything, so it gets return
# type "None" just like any other method that doesn't return anything
def__init__(self, account_name: str, initial_balance: int=0) -> None:
# mypy will infer the correct types for these instance variables
# based on the types of the parameters.
self.account_name = account_name
self.balance = initial_balance

# For instance methods, omit type for "self"
defdeposit(self, amount: int) -> None:
self.balance += amount

defwithdraw(self, amount: int) -> None:
self.balance -= amount

# User-defined classes are valid as types in annotations
 account: BankAccount = BankAccount("Alice", 400)
deftransfer(src: BankAccount, dst: BankAccount, amount: int) -> None:
 src.withdraw(amount)
 dst.deposit(amount)

# Functions that accept BankAccount also accept any subclass of BankAccount!
classAuditedBankAccount(BankAccount):
# You can optionally declare instance variables in the class body
 audit_log: list[str]

def__init__(self, account_name: str, initial_balance: int=0) -> None:
super().__init__(account_name, initial_balance)
self.audit_log: list[str] = []

defdeposit(self, amount: int) -> None:
self.audit_log.append(f"Deposited {amount}")
self.balance += amount

defwithdraw(self, amount: int) -> None:
self.audit_log.append(f"Withdrew {amount}")
self.balance -= amount

 audited = AuditedBankAccount("Bob", 300)
 transfer(audited, account, 100) # type checks!

# You can use the ClassVar annotation to declare a class variable
classCar:
 seats: ClassVar[int] =4
 passengers: ClassVar[list[str]]

# If you want dynamic attributes on your class, have it
# override "__setattr__" or "__getattr__"
classA:
# This will allow assignment to any A.x, if x is the same type as "value"
# (use "value: Any" to allow arbitrary types)
def__setattr__(self, name: str, value: int) -> None: ...

# This will allow access to any A.x, if x is compatible with the return type
def__getattr__(self, name: str) -> int: ...

 a = A()
 a.foo =42# Works
 a.bar ='Ex-parrot'# Fails type checking

When you're puzzled or when things are complicated
**************************************************

.. code-block:: python

from typing import Union, Any, Optional, TYPE_CHECKING, cast

# To find out what type mypy infers for an expression anywhere in
# your program, wrap it in reveal_type(). Mypy will print an error
# message with the type; remove it again before running the code.
 reveal_type(1) # Revealed type is "builtins.int"

# If you initialize a variable with an empty container or "None"
# you may have to help mypy a bit by providing an explicit type annotation
 x: list[str] = []
 x: str|None=None

# Use Any if you don't know the type of something or it's too
# dynamic to write a type for
 x: Any = mystery_function()
# Mypy will let you do anything with x!
 x.whatever() * x["you"] + x("want") -any(x) andall(x) issuper# no errors

# Use a "type: ignore" comment to suppress errors on a given line,
# when your code confuses mypy or runs into an outright bug in mypy.
# Good practice is to add a comment explaining the issue.
 x = confusing_function() # type:ignore# confusing_function won't return None here because ...

# "cast" is a helper function that lets you override the inferred
# type of an expression. It's only for mypy -- there's no runtime check.
 a = [4]
 b = cast(list[int], a) # Passes fine
 c = cast(list[str], a) # Passes fine despite being a lie (no runtime check)
 reveal_type(c) # Revealed type is "builtins.list[builtins.str]"
print(c) # Still prints [4] ... the object is not changed or casted at runtime

# Use "TYPE_CHECKING" if you want to have code that mypy can see but will not
# be executed at runtime (or to have code that mypy can't see)
ifTYPE_CHECKING:
import json
else:
import orjson as json # mypy is unaware of this

In some cases type annotations can cause issues at runtime, see
:ref:`runtime_troubles` for dealing with this.

See :ref:`silencing-type-errors` for details on how to silence errors.

Standard "duck types"
*********************

In typical Python code, many functions that can take a list or a dict
as an argument only need their argument to be somehow "list-like" or
"dict-like". A specific meaning of "list-like" or "dict-like" (or
something-else-like) is called a "duck type", and several duck types
that are common in idiomatic Python are standardized.

.. code-block:: python

from collections.abc import Mapping, MutableMapping, Sequence, Iterable
# or 'from typing import ...' (required in Python 3.8)

# Use Iterable for generic iterables (anything usable in "for"),
# and Sequence where a sequence (supporting "len" and "__getitem__") is
# required
deff(ints: Iterable[int]) -> list[str]:
return [str(x) for x in ints]

 f(range(1, 3))

# Mapping describes a dict-like object (with "__getitem__") that we won't
# mutate, and MutableMapping one (with "__setitem__") that we might
deff(my_mapping: Mapping[int, str]) -> list[int]:
 my_mapping[5] ='maybe'# mypy will complain about this line...
returnlist(my_mapping.keys())

 f({3: 'yes', 4: 'no'})

deff(my_mapping: MutableMapping[int, str]) -> set[str]:
 my_mapping[5] ='maybe'# ...but mypy is OK with this.
returnset(my_mapping.values())

 f({3: 'yes', 4: 'no'})

import sys
from typing importIO

# Use IO[str] or IO[bytes] for functions that should accept or return
# objects that come from an open() call (note that IO does not
# distinguish between reading, writing or other modes)
defget_sys_IO(mode: str='w') -> IO[str]:
if mode =='w':
return sys.stdout
elif mode =='r':
return sys.stdin
else:
return sys.stdout


You can even make your own duck types using :ref:`protocol-types`.

Forward references
******************

.. code-block:: python

# You may want to reference a class before it is defined.
# This is known as a "forward reference".
deff(foo: A) -> int: # This will fail at runtime with 'A' is not defined
...

# However, if you add the following special import:
from__future__import annotations
# It will work at runtime and type checking will succeed as long as there
# is a class of that name later on in the file
deff(foo: A) -> int: # Ok
...

# Another option is to just put the type in quotes
deff(foo: 'A') -> int: # Also ok
...

classA:
# This can also come up if you need to reference a class in a type
# annotation inside the definition of that class
@classmethod
defcreate(cls) -> A:
...

See :ref:`forward-references` for more details.

Decorators
**********

Decorator functions can be expressed via generics. See
:ref:`declaring-decorators` for more details. Example using Python 3.12
syntax:

.. code-block:: python

from collections.abc import Callable
from typing import Any

def bare_decorator[F: Callable[..., Any]](func: F) -> F:
...

def decorator_args[F: Callable[..., Any]](url: str) -> Callable[[F], F]:
...

The same example using pre-3.12 syntax:

.. code-block:: python

from collections.abc import Callable
from typing import Any, TypeVar

 F = TypeVar('F', bound=Callable[..., Any])

defbare_decorator(func: F) -> F:
...

defdecorator_args(url: str) -> Callable[[F], F]:
...

Coroutines and asyncio
**********************

See :ref:`async-and-await` for the full detail on typing coroutines and asynchronous code.

.. code-block:: python

import asyncio

# A coroutine is typed like a normal function
asyncdefcountdown(tag: str, count: int) -> str:
while count >0:
print(f'T-minus {count} ({tag})')
await asyncio.sleep(0.1)
 count -=1
return"Blastoff!"