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 Type inference and type annotations for more details.

# This is how you declare the type of a variableage:int=1# You don't need to initialize a variable to annotate ita:int# Ok (no value at runtime until assigned)# Doing so can be useful in conditional brancheschild:boolifage<18:child=Trueelse:child=False

Useful built-in types

# 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 redundantx:int=1x:float=1.0x:bool=Truex:str="test"x:bytes=b"test"# For collections on Python 3.9+, the type of the collection item is in bracketsx:list[int]=[1]x:set[int]={6,7}# For mappings, we need the types of both keys and valuesx:dict[str,float]={"field":2.0}# Python 3.9+# For tuples of fixed size, we specify the types of all the elementsx:tuple[int,str,float]=(3,"yes",7.5)# Python 3.9+# For tuples of variable size, we use one type and ellipsisx: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' modulefromtypingimportList,Set,Dict,Tuplex: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)fromtypingimportUnion,Optional# On Python 3.10+, use the | operator when something could be one of a few typesx:list[int|str]=[3,5,"test","fun"]# Python 3.10+# On earlier versions, use Unionx: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"ifsome_condition()elseNoneifxisnotNone:# Mypy understands x won't be None here because of the if-statementprint(x.upper())# If you know a value can never be None due to some logic that mypy doesn't# understand, use an assertassertxisnotNoneprint(x.upper())

Functions

fromcollections.abcimportIterator,CallablefromtypingimportUnion,Optional# This is how you annotate a function definitiondefstringify(num:int)->str:returnstr(num)# And here's how you specify multiple argumentsdefplus(num1:int,num2:int)->int:returnnum1+num2# If a function does not return a value, use None as the return type# Default value for an argument goes after the type annotationdefshow(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 checkeddefuntyped(x):x.anything()+1+"string"# no errors# This is how you annotate a callable (function) valuex:Callable[[int,float],float]=fdefregister(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 itdefgen(n:int)->Iterator[int]:i=0whilei<n:yieldii+=1# You can of course split a function annotation over multiple linesdefsend_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 underscoresdefquux(x:int,/,*,y:int)->None:passquux(3,y=5)# Okquux(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

fromtypingimportClassVarclassBankAccount:# The "__init__" method doesn't return anything, so it gets return# type "None" just like any other method that doesn't return anythingdef__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_nameself.balance=initial_balance# For instance methods, omit type for "self"defdeposit(self,amount:int)->None:self.balance+=amountdefwithdraw(self,amount:int)->None:self.balance-=amount# User-defined classes are valid as types in annotationsaccount: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 bodyaudit_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+=amountdefwithdraw(self,amount:int)->None:self.audit_log.append(f"Withdrew {amount}")self.balance-=amountaudited=AuditedBankAccount("Bob",300)transfer(audited,account,100)# type checks!# You can use the ClassVar annotation to declare a class variableclassCar:seats:ClassVar[int]=4passengers: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 typedef__getattr__(self,name:str)->int:...a=A()a.foo=42# Worksa.bar='Ex-parrot'# Fails type checking

When you’re puzzled or when things are complicated

fromtypingimportUnion,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 annotationx: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 forx: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 finec=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:importjsonelse:importorjsonasjson# mypy is unaware of this

In some cases type annotations can cause issues at runtime, see Annotation issues at runtime for dealing with this.

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

fromcollections.abcimportMapping,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# requireddeff(ints:Iterable[int])->list[str]:return[str(x)forxinints]f(range(1,3))# Mapping describes a dict-like object (with "__getitem__") that we won't# mutate, and MutableMapping one (with "__setitem__") that we mightdeff(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'})importsysfromtypingimportIO# 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]:ifmode=='w':returnsys.stdoutelifmode=='r':returnsys.stdinelse:returnsys.stdout

You can even make your own duck types using Protocols and structural subtyping.

Forward references

# 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__importannotations# It will work at runtime and type checking will succeed as long as there# is a class of that name later on in the filedeff(foo:A)->int:# Ok...# Another option is to just put the type in quotesdeff(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@classmethoddefcreate(cls)->A:...

See Class name forward references for more details.

Decorators

Decorator functions can be expressed via generics. See Declaring decorators for more details. Example using Python 3.12 syntax:

fromcollections.abcimportCallablefromtypingimportAnydefbare_decorator[F:Callable[...,Any]](func:F)->F:...defdecorator_args[F:Callable[...,Any]](url:str)->Callable[[F],F]:...

The same example using pre-3.12 syntax:

fromcollections.abcimportCallablefromtypingimportAny,TypeVarF=TypeVar('F',bound=Callable[...,Any])defbare_decorator(func:F)->F:...defdecorator_args(url:str)->Callable[[F],F]:...

Coroutines and asyncio

See Typing async/await for the full detail on typing coroutines and asynchronous code.

importasyncio# A coroutine is typed like a normal functionasyncdefcountdown(tag:str,count:int)->str:whilecount>0:print(f'T-minus {count} ({tag})')awaitasyncio.sleep(0.1)count-=1return"Blastoff!"