Dynamic Typing

Python is a dynamically typed language. This means that the Python interpreter does type checking only as code runs, and that the type of a variable is allowed to change over its lifetime. The following dummy examples demonstrate that Python has dynamic typing:

>>>ifFalse:...1+"two"# This line never runs, so no TypeError is raised...else:...1+2...3>>>1+"two"# Now this is type checked, and a TypeError is raisedTypeError: unsupported operand type(s) for +: 'int' and 'str'

In the first example, the branch1 + "two" never runs so it’s never type checked. The second example shows that when1 + "two" is evaluated it raises aTypeError since you can’t add an integer and a string in Python.

Next, let’s see if variables can change type:

>>>thing="Hello">>>type(thing)<class 'str'>>>>thing=28.1>>>type(thing)<class 'float'>

type() returns the type of an object. These examples confirm that the type ofthing is allowed to change, and Python correctly infers the type as it changes.

Static Typing

The opposite of dynamic typing is static typing. Static type checks are performed without running the program. In most statically typed languages, for instanceC andJava, this is done as your program is compiled.

With static typing, variables generally are not allowed to change types, although mechanisms for casting a variable to a different type may exist.

Let’s look at a quick example from a statically typed language. Consider the following Java snippet:

Stringthing;thing="Hello";

The first line declares that the variable namething is bound to theString type at compile time. The name can never be rebound to another type. In the second line,thing is assigned a value. It can never be assigned a value that is not aString object. For instance, if you were to later saything = 28.1f the compiler would raise an error because of incompatible types.

Python will alwaysremain a dynamically typed language. However,PEP 484 introduced type hints, which make it possible to also do static type checking of Python code.

Unlike how types work in most other statically typed languages, type hints by themselves don’t cause Python to enforce types. As the name says, type hints just suggest types. There are other tools, whichyou’ll see later, that perform static type checking using type hints.

Duck Typing

Another term that is often used when talking about Python isduck typing. This moniker comes from the phrase “if it walks like a duck and it quacks like a duck, then it must be a duck” (orany of its variations).

Duck typing is a concept related to dynamic typing, where the type or the class of an object is less important than the methods it defines. Using duck typing you do not check types at all. Instead you check for the presence of a given method or attribute.

As an example, you can calllen() on any Python object that defines a.__len__() method:

>>>classTheHobbit:...def__len__(self):...return95022...>>>the_hobbit=TheHobbit()>>>len(the_hobbit)95022

Note that the call tolen() gives the return value of the.__len__() method. In fact, the implementation oflen() is essentially equivalent to the following:

deflen(obj):returnobj.__len__()

In order to calllen(obj), the only real constraint onobj is that it must define a.__len__() method. Otherwise, the object can be of types as different asstr,list,dict, orTheHobbit.

Duck typing is somewhat supported when doing static type checking of Python code, usingstructural subtyping. You’ll learnmore about duck typing later.

Function Annotations

For functions, you can annotate arguments and the return value. This is done as follows:

deffunc(arg:arg_type,optarg:arg_type=default)->return_type:...

For arguments the syntax isargument: annotation, while the return type is annotated using-> annotation. Note that the annotation must be a valid Python expression.

The following simple example adds annotations to a function that calculates the circumference of a circle:

importmathdefcircumference(radius:float)->float:return2*math.pi*radius

When running the code, you can also inspect the annotations. They are stored in a special.__annotations__ attribute on the function:

>>>circumference(1.23)7.728317927830891>>>circumference.__annotations__{'radius': <class 'float'>, 'return': <class 'float'>}

Sometimes you might be confused by how mypy is interpreting your type hints. For those cases there are special mypy expressions:reveal_type() andreveal_locals(). You can add these to your code before running mypy, and mypy will dutifully report which types it has inferred. As an example, save the following code toreveal.py:

 1# reveal.py 2 3importmath 4reveal_type(math.pi) 5 6radius=1 7circumference=2*math.pi*radius 8reveal_locals()

Next, run this code through mypy:

$mypyreveal.pyreveal.py:4: error: Revealed type is 'builtins.float'reveal.py:8: error: Revealed local types are:reveal.py:8: error: circumference: builtins.floatreveal.py:8: error: radius: builtins.int

Even without any annotations mypy has correctly inferred the types of the built-inmath.pi, as well as our local variablesradius andcircumference.

If mypy says that “Name ‘reveal_locals’ is not defined” you might need to update your mypy installation. Thereveal_locals() expression is available inmypy version 0.610 and later.

Variable Annotations

In the definition ofcircumference() in the previous section, you only annotated the arguments and the return value. You did not add any annotations inside the function body. More often than not, this is enough.

However, sometimes the type checker needs help in figuring out the types of variables as well. Variable annotations were defined inPEP 526 and introduced in Python 3.6. The syntax is the same as for function argument annotations:

pi:float=3.142defcircumference(radius:float)->float:return2*pi*radius

The variablepi has been annotated with thefloat type hint.

Annotations of variables are stored in the module level__annotations__ dictionary:

>>>circumference(1)6.284>>>__annotations__{'pi': <class 'float'>}

You’re allowed to annotate a variable without giving it a value. This adds the annotation to the__annotations__ dictionary, while the variable remains undefined:

>>>nothing:str>>>nothingNameError: name 'nothing' is not defined>>>__annotations__{'nothing': <class 'str'>}

Since no value was assigned tonothing, the namenothing is not yet defined.

Type Comments

As mentioned, annotations were introduced in Python 3, and they’ve not been backported to Python 2. This means that if you’re writing code that needs to supportlegacy Python, you can’t use annotations.

Instead, you can use type comments. These are specially formatted comments that can be used to add type hints compatible with older code. To add type comments to a function you do something like this:

importmathdefcircumference(radius):# type: (float) -> floatreturn2*math.pi*radius

The type comments are just comments, so they can be used in any version of Python.

Type comments are handled directly by the type checker, so these types are not available in the__annotations__ dictionary:

>>>circumference.__annotations__{}

A type comment must start with thetype: literal, and be on the same or the following line as the function definition. If you want to annotate a function with several arguments, you write each type separated by comma:

defheadline(text,width=80,fill_char="-"):# type: (str, int, str) -> strreturnf"{text.title()} ".center(width,fill_char)print(headline("type comments work",width=40))

You are also allowed to write each argument on a separate line with its own annotation:

 1# headlines.py 2 3defheadline( 4text,# type: str 5width=80,# type: int 6fill_char="-",# type: str 7):# type: (...) -> str 8returnf"{text.title()} ".center(width,fill_char) 910print(headline("type comments work",width=40))

Run the example through Python and mypy:

$pythonheadlines.py---------- Type Comments Work ----------$mypyheadlines.pySuccess: no issues found in 1 source file

If you have errors, for instance if you happened to callheadline() withwidth="full" on line 10, mypy will tell you:

$mypyheadline.pyheadline.py:10: error: Argument "width" to "headline" has incompatible                       type "str"; expected "int"

You can also add type comments to variables. This is done similarly to how you add type comments to arguments:

pi=3.142# type: float

In this example,pi will be type checked as a float variable.

So, Type Annotations or Type Comments?

Should you use annotations or type comments when adding type hints to your own code? In short:Use annotations if you can, use type comments if you must.

Annotations provide a cleaner syntax keeping type information closer to your code. They are also theofficially recommended way of writing type hints, and will be further developed and properly maintained in the future.

Type comments are more verbose and might conflict with other kinds of comments in your code likelinter directives. However, they can be used in code bases that don’t support annotations.

There is also hidden option number three:stub files. You will learn about these later, when we discussadding types to third party libraries.

Stub files will work in any version of Python, at the expense of having to maintain a second set of files. In general, you only want to use stub files if you can’t change the original source code.

Example: A Deck of Cards

The following example shows an implementation of aregular (French) deck of cards:

 1# game.py 2 3importrandom 4 5SUITS="♠ ♡ ♢ ♣".split() 6RANKS="2 3 4 5 6 7 8 9 10 J Q K A".split() 7 8defcreate_deck(shuffle=False): 9"""Create a new deck of 52 cards"""10deck=[(s,r)forrinRANKSforsinSUITS]11ifshuffle:12random.shuffle(deck)13returndeck1415defdeal_hands(deck):16"""Deal the cards in the deck into four hands"""17return(deck[0::4],deck[1::4],deck[2::4],deck[3::4])1819defplay():20"""Play a 4-player card game"""21deck=create_deck(shuffle=True)22names="P1 P2 P3 P4".split()23hands={n:hforn,hinzip(names,deal_hands(deck))}2425forname,cardsinhands.items():26card_str=" ".join(f"{s}{r}"for(s,r)incards)27print(f"{name}:{card_str}")2829if__name__=="__main__":30play()

Each card is represented as a tuple of strings denoting the suit and rank. The deck is represented as a list of cards.create_deck() creates a regular deck of 52 playing cards, and optionally shuffles the cards.deal_hands() deals the deck of cards to four players.

Finally,play() plays the game. As of now, it only prepares for a card game by constructing a shuffled deck and dealing cards to each player. The following is a typical output:

$pythongame.pyP4: ♣9 ♢9 ♡2 ♢7 ♡7 ♣A ♠6 ♡K ♡5 ♢6 ♢3 ♣3 ♣QP1: ♡A ♠2 ♠10 ♢J ♣10 ♣4 ♠5 ♡Q ♢5 ♣6 ♠A ♣5 ♢4P2: ♢2 ♠7 ♡8 ♢K ♠3 ♡3 ♣K ♠J ♢A ♣7 ♡6 ♡10 ♠KP3: ♣2 ♣8 ♠8 ♣J ♢Q ♡9 ♡J ♠4 ♢8 ♢10 ♠9 ♡4 ♠Q

You will see how to extend this example into a more interesting game as we move along.

Sequences and Mappings

Let’s add type hints to our card game. In other words, let’s annotate the functionscreate_deck(),deal_hands(), andplay(). The first challenge is that you need to annotate composite types like the list used to represent the deck of cards and the tuples used to represent the cards themselves.

With simple types likestr,float, andbool, adding type hints is as easy as using the type itself:

>>>name:str="Guido">>>pi:float=3.142>>>centered:bool=False

With composite types, you are allowed to do the same:

>>>names:list=["Guido","Jukka","Ivan"]>>>version:tuple=(3,7,1)>>>options:dict={"centered":False,"capitalize":True}

However, this does not really tell the full story. What will be the types ofnames[2],version[0], andoptions["centered"]? In this concrete case you can see that they arestr,int, andbool, respectively. However, the type hints themselves give no information about this.

Instead, you should use the special types defined in thetyping module. These types add syntax for specifying the types of elements of composite types. You can write the following:

>>>fromtypingimportDict,List,Tuple>>>names:List[str]=["Guido","Jukka","Ivan"]>>>version:Tuple[int,int,int]=(3,7,1)>>>options:Dict[str,bool]={"centered":False,"capitalize":True}

Note that each of these types start with a capital letter and that they all use square brackets to define item types:

• names is a list of strings
• version is a 3-tuple consisting of three integers
• options is a dictionary mapping strings to Boolean values

Thetyping module contains many more composite types, includingCounter,Deque,FrozenSet,NamedTuple, andSet. In addition, the module includes other kinds of types that you’ll see in later sections.

Let’s return to the card game. A card is represented by a tuple of two strings. You can write this asTuple[str, str], so the type of the deck of cards becomesList[Tuple[str, str]]. Therefore you can annotatecreate_deck() as follows:

 8defcreate_deck(shuffle:bool=False)->List[Tuple[str,str]]: 9"""Create a new deck of 52 cards"""10deck=[(s,r)forrinRANKSforsinSUITS]11ifshuffle:12random.shuffle(deck)13returndeck

In addition to the return value, you’ve also added thebool type to the optionalshuffle argument.

In many cases your functions will expect some kind ofsequence, and not really care whether it is a list or a tuple. In these cases you should usetyping.Sequence when annotating the function argument:

fromtypingimportList,Sequencedefsquare(elems:Sequence[float])->List[float]:return[x**2forxinelems]

UsingSequence is an example of using duck typing. ASequence is anything that supportslen() and.__getitem__(), independent of its actual type.

Type Aliases

The type hints might become quite oblique when working with nested types like the deck of cards. You may need to stare atList[Tuple[str, str]] a bit before figuring out that it matches our representation of a deck of cards.

Now consider how you would annotatedeal_hands():

15defdeal_hands(16deck:List[Tuple[str,str]]17)->Tuple[18List[Tuple[str,str]],19List[Tuple[str,str]],20List[Tuple[str,str]],21List[Tuple[str,str]],22]:23"""Deal the cards in the deck into four hands"""24return(deck[0::4],deck[1::4],deck[2::4],deck[3::4])

That’s just terrible!

Recall that type annotations are regular Python expressions. That means that you can define your own type aliases by assigning them to new variables. You can for instance createCard andDeck type aliases:

fromtypingimportList,TupleCard=Tuple[str,str]Deck=List[Card]

Card can now be used in type hints or in the definition of new type aliases, likeDeck in the example above.

Using these aliases, the annotations ofdeal_hands() become much more readable:

15defdeal_hands(deck:Deck)->Tuple[Deck,Deck,Deck,Deck]:16"""Deal the cards in the deck into four hands"""17return(deck[0::4],deck[1::4],deck[2::4],deck[3::4])

Type aliases are great for making your code and its intent clearer. At the same time, these aliases can be inspected to see what they represent:

>>>fromtypingimportList,Tuple>>>Card=Tuple[str,str]>>>Deck=List[Card]>>>Decktyping.List[typing.Tuple[str, str]]

Note that when printingDeck, it shows that it’s an alias for a list of 2-tuples of strings.

Functions Without Return Values

You may know that functions without an explicit return still returnNone:

>>>defplay(player_name):...print(f"{player_name} plays")...>>>ret_val=play("Jacob")Jacob plays>>>print(ret_val)None

While such functions technically return something, that return value is not useful. You should add type hints saying as much by usingNone also as the return type:

 1# play.py 2 3defplay(player_name:str)->None: 4print(f"{player_name} plays") 5 6ret_val=play("Filip")

The annotations help catch the kinds of subtle bugs where you are trying to use a meaningless return value. Mypy will give you a helpful warning:

$mypyplay.pyplay.py:6: error: "play" does not return a value

Note that being explicit about a function not returning anything is different from not adding a type hint about the return value:

# play.pydefplay(player_name:str):print(f"{player_name} plays")ret_val=play("Henrik")

In this latter case, mypy has no information about the return value so it will not generate any warning:

$mypyplay.pySuccess: no issues found in 1 source file

As a more exotic case, note that you can also annotate functions that are never expected to return normally. This is done usingNoReturn:

fromtypingimportNoReturndefblack_hole()->NoReturn:raiseException("There is no going back ...")

Sinceblack_hole() always raises an exception, it will never return properly.

Example: Play Some Cards

Let’s return to ourcard game example. In this second version of the game, we deal a hand of cards to each player as before. Then a start player is chosen and the players take turns playing their cards. There are not really any rules in the game though, so the players will just play random cards:

 1# game.py 2 3importrandom 4fromtypingimportList,Tuple 5 6SUITS="♠ ♡ ♢ ♣".split() 7RANKS="2 3 4 5 6 7 8 9 10 J Q K A".split() 8 9Card=Tuple[str,str]10Deck=List[Card]1112defcreate_deck(shuffle:bool=False)->Deck:13"""Create a new deck of 52 cards"""14deck=[(s,r)forrinRANKSforsinSUITS]15ifshuffle:16random.shuffle(deck)17returndeck1819defdeal_hands(deck:Deck)->Tuple[Deck,Deck,Deck,Deck]:20"""Deal the cards in the deck into four hands"""21return(deck[0::4],deck[1::4],deck[2::4],deck[3::4])2223defchoose(items):24"""Choose and return a random item"""25returnrandom.choice(items)2627defplayer_order(names,start=None):28"""Rotate player order so that start goes first"""29ifstartisNone:30start=choose(names)31start_idx=names.index(start)32returnnames[start_idx:]+names[:start_idx]3334defplay()->None:35"""Play a 4-player card game"""36deck=create_deck(shuffle=True)37names="P1 P2 P3 P4".split()38hands={n:hforn,hinzip(names,deal_hands(deck))}39start_player=choose(names)40turn_order=player_order(names,start=start_player)4142# Randomly play cards from each player's hand until empty43whilehands[start_player]:44fornameinturn_order:45card=choose(hands[name])46hands[name].remove(card)47print(f"{name}:{card[0]+card[1]:<3}  ",end="")48print()4950if__name__=="__main__":51play()

Note that in addition to changingplay(), we have added two new functions that need type hints:choose() andplayer_order(). Before discussing how we’ll add type hints to them, here is an example output from running the game:

$pythongame.pyP3: ♢10  P4: ♣4   P1: ♡8   P2: ♡QP3: ♣8   P4: ♠6   P1: ♠5   P2: ♡KP3: ♢9   P4: ♡J   P1: ♣A   P2: ♡AP3: ♠Q   P4: ♠3   P1: ♠7   P2: ♠AP3: ♡4   P4: ♡6   P1: ♣2   P2: ♠KP3: ♣K   P4: ♣7   P1: ♡7   P2: ♠2P3: ♣10  P4: ♠4   P1: ♢5   P2: ♡3P3: ♣Q   P4: ♢K   P1: ♣J   P2: ♡9P3: ♢2   P4: ♢4   P1: ♠9   P2: ♠10P3: ♢A   P4: ♡5   P1: ♠J   P2: ♢QP3: ♠8   P4: ♢7   P1: ♢3   P2: ♢JP3: ♣3   P4: ♡10  P1: ♣9   P2: ♡2P3: ♢6   P4: ♣6   P1: ♣5   P2: ♢8

In this example, playerP3 was randomly chosen as the starting player. In turn, each player plays a card: firstP3, thenP4, thenP1, and finallyP2. The players keep playing cards as long as they have any left in their hand.

TheAny Type

choose() works for both lists of names and lists of cards (and any other sequence for that matter). One way to add type hints for this would be the following:

importrandomfromtypingimportAny,Sequencedefchoose(items:Sequence[Any])->Any:returnrandom.choice(items)

This means more or less what it says:items is a sequence that can contain items of any type andchoose() will return one such item of any type. Unfortunately, this is not that useful. Consider the following example:

 1# choose.py 2 3importrandom 4fromtypingimportAny,Sequence 5 6defchoose(items:Sequence[Any])->Any: 7returnrandom.choice(items) 8 9names=["Guido","Jukka","Ivan"]10reveal_type(names)1112name=choose(names)13reveal_type(name)

While mypy will correctly infer thatnames is a list of strings, that information is lost after the call tochoose() because of the use of theAny type:

$mypychoose.pychoose.py:10: error: Revealed type is 'builtins.list[builtins.str*]'choose.py:13: error: Revealed type is 'Any'

You’ll see a better way shortly. First though, let’s have a more theoretical look at the Python type system, and the special roleAny plays.

Subtypes

One important concept is that ofsubtypes. Formally, we say that a typeT is a subtype ofU if the following two conditions hold:

• Every value fromT is also in the set of values ofU type.
• Every function fromU type is also in the set of functions ofT type.

These two conditions guarantees that even if typeT is different fromU, variables of typeT can always pretend to beU.

For a concrete example, considerT = bool andU = int. Thebool type takes only two values. Usually these are denotedTrue andFalse, but these names are just aliases for the integer values1 and0, respectively:

>>>int(False)0>>>int(True)1>>>True+True2>>>issubclass(bool,int)True

Since 0 and 1 are both integers, the first condition holds. Above you can see that Booleans can be added together, but they can also do anything else integers can. This is the second condition above. In other words,bool is a subtype ofint.

The importance of subtypes is that a subtype can always pretend to be its supertype. For instance, the following code type checks as correct:

defdouble(number:int)->int:returnnumber*2print(double(True))# Passing in bool instead of int

Subtypes are somewhat related to subclasses. In fact all subclasses corresponds to subtypes, andbool is a subtype ofint becausebool is a subclass ofint. However, there are also subtypes that do not correspond to subclasses. For instanceint is a subtype offloat, butint is not a subclass offloat.

Covariant, Contravariant, and Invariant

What happens when you use subtypes inside composite types? For instance, isTuple[bool] a subtype ofTuple[int]? The answer depends on the composite type, and whether that type iscovariant, contravariant, or invariant. This gets technical fast, so let’s just give a few examples:

• Tuple is covariant. This means that it preserves the type hierarchy of its item types:Tuple[bool] is a subtype ofTuple[int] becausebool is a subtype ofint.

• List is invariant. Invariant types give no guarantee about subtypes. While all values ofList[bool] are values ofList[int], you can append anint toList[int] and not toList[bool]. In other words, the second condition for subtypes does not hold, andList[bool] is not a subtype ofList[int].

• Callable is contravariant in its arguments. This means that it reverses the type hierarchy. You will see howCallable workslater, but for now think ofCallable[[T], ...] as a function with its only argument being of typeT. An example of aCallable[[int], ...] is thedouble() function defined above. Being contravariant means that if a function operating on abool is expected, then a function operating on anint would be acceptable.

In general, you don’t need to keep these expressions straight. However, you should be aware that subtypes and composite types may not be simple and intuitive.

Gradual Typing and Consistent Types

Earlier we mentioned that Python supportsgradual typing, where you can gradually add type hints to your Python code. Gradual typing is essentially made possible by theAny type.

SomehowAny sits both at the top and at the bottom of the type hierarchy of subtypes. Any type behaves as if it is a subtype ofAny, andAny behaves as if it is a subtype of any other type. Looking at the definition of subtypes above this is not really possible. Instead we talk aboutconsistent types.

The typeT is consistent with the typeU ifT is a subtype ofU or eitherT orU isAny.

The type checker only complains about inconsistent types. The takeaway is therefore that you will never see type errors arising from theAny type.

This means that you can useAny to explicitly fall back to dynamic typing, describe types that are too complex to describe in the Python type system, or describe items in composite types. For instance, a dictionary with string keys that can take any type as its values can be annotatedDict[str, Any].

Do remember, though, if you useAny the static type checker will effectively not do any type checking.

Type Variables

A type variable is a special variable that can take on any type, depending on the situation.

Let’s create a type variable that will effectively encapsulate the behavior ofchoose():

 1# choose.py 2 3importrandom 4fromtypingimportSequence,TypeVar 5 6Choosable=TypeVar("Choosable") 7 8defchoose(items:Sequence[Choosable])->Choosable: 9returnrandom.choice(items)1011names=["Guido","Jukka","Ivan"]12reveal_type(names)1314name=choose(names)15reveal_type(name)

A type variable must be defined usingTypeVar from thetyping module. When used, a type variable ranges over all possible types and takes the most specific type possible. In the example,name is now astr:

$mypychoose.pychoose.py:12: error: Revealed type is 'builtins.list[builtins.str*]'choose.py:15: error: Revealed type is 'builtins.str*'

Consider a few other examples:

 1# choose_examples.py 2 3fromchooseimportchoose 4 5reveal_type(choose(["Guido","Jukka","Ivan"])) 6reveal_type(choose([1,2,3])) 7reveal_type(choose([True,42,3.14])) 8reveal_type(choose(["Python",3,7]))

The first two examples should have typestr andint, but what about the last two? The individual list items have different types, and in that case theChoosable type variable does its best to accommodate:

$mypychoose_examples.pychoose_examples.py:5: error: Revealed type is 'builtins.str*'choose_examples.py:6: error: Revealed type is 'builtins.int*'choose_examples.py:7: error: Revealed type is 'builtins.float*'choose_examples.py:8: error: Revealed type is 'builtins.object*'

As you’ve already seenbool is a subtype ofint, which again is a subtype offloat. So in the third example the return value ofchoose() is guaranteed to be something that can be thought of as afloat. In the last example, there is no subtype relationship betweenstr andint, so the best that can be said about the return value is that it is an object.

Note that none of these examples raised a type error. Is there a way to tell the type checker thatchoose() should accept both strings and numbers, but not both at the same time?

You can constrain type variables by listing the acceptable types:

 1# choose.py 2 3importrandom 4fromtypingimportSequence,TypeVar 5 6Choosable=TypeVar("Choosable",str,float) 7 8defchoose(items:Sequence[Choosable])->Choosable: 9returnrandom.choice(items)1011reveal_type(choose(["Guido","Jukka","Ivan"]))12reveal_type(choose([1,2,3]))13reveal_type(choose([True,42,3.14]))14reveal_type(choose(["Python",3,7]))

NowChoosable can only be eitherstr orfloat, and mypy will note that the last example is an error:

$mypychoose.pychoose.py:11: error: Revealed type is 'builtins.str*'choose.py:12: error: Revealed type is 'builtins.float*'choose.py:13: error: Revealed type is 'builtins.float*'choose.py:14: error: Revealed type is 'builtins.object*'choose.py:14: error: Value of type variable "Choosable" of "choose"                     cannot be "object"

Also note that in the second example the type is consideredfloat even though the input list only containsint objects. This is becauseChoosable was restricted to strings and floats andint is a subtype offloat.

In our card game we want to restrictchoose() to be used forstr andCard:

Choosable=TypeVar("Choosable",str,Card)defchoose(items:Sequence[Choosable])->Choosable:...

We briefly mentioned thatSequence represents both lists and tuples. As we noted, aSequence can be thought of as a duck type, since it can be any object with.__len__() and.__getitem__() implemented.

Duck Types and Protocols

Recall the following example fromthe introduction:

deflen(obj):returnobj.__len__()

len() can return the length of any object that has implemented the.__len__() method. How can we add type hints tolen(), and in particular theobj argument?

The answer hides behind the academic sounding termstructural subtyping. One way to categorize type systems is by whether they arenominal orstructural:

• In anominal system, comparisons between types are based on names and declarations. The Python type system is mostly nominal, where anint can be used in place of afloat because of their subtype relationship.

• In astructural system, comparisons between types are based on structure. You could define a structural typeSized that includes all instances that define.__len__(), irrespective of their nominal type.

There is ongoing work to bring a full-fledged structural type system to Python throughPEP 544 which aims at adding a concept called protocols. Most of PEP 544 is alreadyimplemented in mypy though.

A protocol specifies one or more methods that must be implemented. For example, all classes defining.__len__() fulfill thetyping.Sized protocol. We can therefore annotatelen() as follows:

fromtypingimportSizeddeflen(obj:Sized)->int:returnobj.__len__()

Otherexamples of protocols defined in thetyping module includeContainer,Iterable,Awaitable, andContextManager.

You can also define your own protocols. This is done by inheriting fromProtocol and defining the function signatures (with empty function bodies) that the protocol expects. The following example shows howlen() andSized could have been implemented:

fromtyping_extensionsimportProtocolclassSized(Protocol):def__len__(self)->int:...deflen(obj:Sized)->int:returnobj.__len__()

At the time of writing the support for self-defined protocols is still experimental and only available through thetyping_extensions module. This module must be explicitly installed fromPyPI by doingpip install typing-extensions.

TheOptional Type

A common pattern in Python is to useNone as a default value for an argument. This is usually done either to avoid problems withmutable default values or to have a sentinel value flagging special behavior.

In the card example, theplayer_order() function usesNone as a sentinel value forstart saying that if no start player is given it should be chosen randomly:

27defplayer_order(names,start=None):28"""Rotate player order so that start goes first"""29ifstartisNone:30start=choose(names)31start_idx=names.index(start)32returnnames[start_idx:]+names[:start_idx]

The challenge this creates for type hinting is that in generalstart should be a string. However, it may also take the special non-string valueNone.

In order to annotate such arguments you can use theOptional type:

fromtypingimportSequence,Optionaldefplayer_order(names:Sequence[str],start:Optional[str]=None)->Sequence[str]:...

TheOptional type simply says that a variable either has the type specified or isNone. An equivalent way of specifying the same would be using theUnion type:Union[None, str]

Note that when using eitherOptional orUnion you must take care that the variable has the correct type when you operate on it. This is done in the example by testing whetherstart is None. Not doing so would cause both static type errors as well as possible runtime errors:

 1# player_order.py 2 3fromtypingimportSequence,Optional 4 5defplayer_order( 6names:Sequence[str],start:Optional[str]=None 7)->Sequence[str]: 8start_idx=names.index(start) 9returnnames[start_idx:]+names[:start_idx]

Mypy tells you that you have not taken care of the case wherestart isNone:

$mypyplayer_order.pyplayer_order.py:8: error: Argument 1 to "index" of "list" has incompatible                          type "Optional[str]"; expected "str"

defplayer_order(names:Sequence[str],start:str=None)->Sequence[str]:...

Example: The Object(ive) of the Game

Let’s rewrite the card game to be moreobject-oriented. This will allow us to discuss how to properly annotate classes and methods.

A more or less direct translation of our card game into code that uses classes forCard,Deck,Player, andGame looks something like the following:

 1# game.py 2 3importrandom 4importsys 5 6classCard: 7SUITS="♠ ♡ ♢ ♣".split() 8RANKS="2 3 4 5 6 7 8 9 10 J Q K A".split() 910def__init__(self,suit,rank):11self.suit=suit12self.rank=rank1314def__repr__(self):15returnf"{self.suit}{self.rank}"1617classDeck:18def__init__(self,cards):19self.cards=cards2021@classmethod22defcreate(cls,shuffle=False):23"""Create a new deck of 52 cards"""24cards=[Card(s,r)forrinCard.RANKSforsinCard.SUITS]25ifshuffle:26random.shuffle(cards)27returncls(cards)2829defdeal(self,num_hands):30"""Deal the cards in the deck into a number of hands"""31cls=self.__class__32returntuple(cls(self.cards[i::num_hands])foriinrange(num_hands))3334classPlayer:35def__init__(self,name,hand):36self.name=name37self.hand=hand3839defplay_card(self):40"""Play a card from the player's hand"""41card=random.choice(self.hand.cards)42self.hand.cards.remove(card)43print(f"{self.name}:{card!r:<3}  ",end="")44returncard4546classGame:47def__init__(self,*names):48"""Set up the deck and deal cards to 4 players"""49deck=Deck.create(shuffle=True)50self.names=(list(names)+"P1 P2 P3 P4".split())[:4]51self.hands={52n:Player(n,h)forn,hinzip(self.names,deck.deal(4))53}5455defplay(self):56"""Play a card game"""57start_player=random.choice(self.names)58turn_order=self.player_order(start=start_player)5960# Play cards from each player's hand until empty61whileself.hands[start_player].hand.cards:62fornameinturn_order:63self.hands[name].play_card()64print()6566defplayer_order(self,start=None):67"""Rotate player order so that start goes first"""68ifstartisNone:69start=random.choice(self.names)70start_idx=self.names.index(start)71returnself.names[start_idx:]+self.names[:start_idx]7273if__name__=="__main__":74# Read player names from command line75player_names=sys.argv[1:]76game=Game(*player_names)77game.play()

Now let’s add types to this code.

Type Hints for Methods

First of all type hints for methods work much the same as type hints for functions. The only difference is that theself argument need not be annotated, as it always will be a class instance. The types of theCard class are easy to add:

 6classCard: 7SUITS="♠ ♡ ♢ ♣".split() 8RANKS="2 3 4 5 6 7 8 9 10 J Q K A".split() 910def__init__(self,suit:str,rank:str)->None:11self.suit=suit12self.rank=rank1314def__repr__(self)->str:15returnf"{self.suit}{self.rank}"

Note that the.__init__() method always should haveNone as its return type.

Classes as Types

There is a correspondence between classes and types. For example, all instances of theCard class together form theCard type. To use classes as types you simply use the name of the class.

For example, aDeck essentially consists of a list ofCard objects. You can annotate this as follows:

17classDeck:18def__init__(self,cards:List[Card])->None:19self.cards=cards

Mypy is able to connect your use ofCard in the annotation with the definition of theCard class.

This doesn’t work as cleanly though when you need to refer to the class currently being defined. For example, theDeck.create()class method returns an object with typeDeck. However, you can’t simply add-> Deck as theDeck class is not yet fully defined.

Instead, you are allowed to use string literals in annotations. These strings will only be evaluated by the type checker later, and can therefore contain self and forward references. The.create() method should use such string literals for its types:

20classDeck:21@classmethod22defcreate(cls,shuffle:bool=False)->"Deck":23"""Create a new deck of 52 cards"""24cards=[Card(s,r)forrinCard.RANKSforsinCard.SUITS]25ifshuffle:26random.shuffle(cards)27returncls(cards)

Note that thePlayer class also will reference theDeck class. This is however no problem, sinceDeck is defined beforePlayer:

34classPlayer:35def__init__(self,name:str,hand:Deck)->None:36self.name=name37self.hand=hand

Usually annotations are not used at runtime. This has given wings to the idea ofpostponing the evaluation of annotations. Instead of evaluating annotations as Python expressions and storing their value, the proposal is to store the string representation of the annotation and only evaluate it when needed.

Such functionality is planned to become standard in the still mythicalPython 4.0. However, inPython 3.7 and later, forward references are available through a__future__ import:

from__future__importannotationsclassDeck:@classmethoddefcreate(cls,shuffle:bool=False)->Deck:...

With the__future__ import you can useDeck instead of"Deck" even beforeDeck is defined.

Returningself orcls

As noted, you should typically not annotate theself orcls arguments. Partly, this is not necessary asself points to an instance of the class, so it will have the type of the class. In theCard example,self has the implicit typeCard. Also, adding this type explicitly would be cumbersome since the class is not defined yet. You would have to use the string literal syntax,self: "Card".

There is one case where you might want to annotateself orcls, though. Consider what happens if you have a superclass that other classes inherit from, and which has methods that returnself orcls:

 1# dogs.py 2 3fromdatetimeimportdate 4 5classAnimal: 6def__init__(self,name:str,birthday:date)->None: 7self.name=name 8self.birthday=birthday 910@classmethod11defnewborn(cls,name:str)->"Animal":12returncls(name,date.today())1314deftwin(self,name:str)->"Animal":15cls=self.__class__16returncls(name,self.birthday)1718classDog(Animal):19defbark(self)->None:20print(f"{self.name} says woof!")2122fido=Dog.newborn("Fido")23pluto=fido.twin("Pluto")24fido.bark()25pluto.bark()

While the code runs without problems, mypy will flag a problem:

$mypydogs.pydogs.py:24: error: "Animal" has no attribute "bark"dogs.py:25: error: "Animal" has no attribute "bark"

The issue is that even though the inheritedDog.newborn() andDog.twin() methods will return aDog the annotation says that they return anAnimal.

In cases like this you want to be more careful to make sure the annotation is correct. The return type should match the type ofself or the instance type ofcls. This can be done using type variables that keep track of what is actually passed toself andcls:

# dogs.pyfromdatetimeimportdatefromtypingimportType,TypeVarTAnimal=TypeVar("TAnimal",bound="Animal")classAnimal:def__init__(self,name:str,birthday:date)->None:self.name=nameself.birthday=birthday@classmethoddefnewborn(cls:Type[TAnimal],name:str)->TAnimal:returncls(name,date.today())deftwin(self:TAnimal,name:str)->TAnimal:cls=self.__class__returncls(name,self.birthday)classDog(Animal):defbark(self)->None:print(f"{self.name} says woof!")fido=Dog.newborn("Fido")pluto=fido.twin("Pluto")fido.bark()pluto.bark()

There are a few things to note in this example:

• The type variableTAnimal is used to denote that return values might be instances of subclasses ofAnimal.

• We specify thatAnimal is an upper bound forTAnimal. Specifyingbound means thatTAnimal will only beAnimal or one of its subclasses. This is needed to properly restrict the types that are allowed.

• Thetyping.Type[] construct is the typing equivalent oftype(). You need it to note that the class method expects a class and returns an instance of that class.

Annotating*args and**kwargs

In theobject oriented version of the game, we added the option to name the players on the command line. This is done by listing player names after the name of the program:

$pythongame.pyGeirArneDanJoannaDan: ♢A   Joanna: ♡9   P1: ♣A   GeirArne: ♣2Dan: ♡A   Joanna: ♡6   P1: ♠4   GeirArne: ♢8Dan: ♢K   Joanna: ♢Q   P1: ♣K   GeirArne: ♠5Dan: ♡2   Joanna: ♡J   P1: ♠7   GeirArne: ♡KDan: ♢10  Joanna: ♣3   P1: ♢4   GeirArne: ♠8Dan: ♣6   Joanna: ♡Q   P1: ♣Q   GeirArne: ♢JDan: ♢2   Joanna: ♡4   P1: ♣8   GeirArne: ♡7Dan: ♡10  Joanna: ♢3   P1: ♡3   GeirArne: ♠2Dan: ♠K   Joanna: ♣5   P1: ♣7   GeirArne: ♠JDan: ♠6   Joanna: ♢9   P1: ♣J   GeirArne: ♣10Dan: ♠3   Joanna: ♡5   P1: ♣9   GeirArne: ♠QDan: ♠A   Joanna: ♠9   P1: ♠10  GeirArne: ♡8Dan: ♢6   Joanna: ♢5   P1: ♢7   GeirArne: ♣4

This is implemented by unpacking and passing insys.argv toGame() when it’s instantiated. The.__init__() method uses*names to pack the given names into a tuple.

Regarding type annotations: even thoughnames will be a tuple of strings, you should only annotate the type of each name. In other words, you should usestr and notTuple[str]:

46classGame:47def__init__(self,*names:str)->None:48"""Set up the deck and deal cards to 4 players"""49deck=Deck.create(shuffle=True)50self.names=(list(names)+"P1 P2 P3 P4".split())[:4]51self.hands={52n:Player(n,h)forn,hinzip(self.names,deck.deal(4))53}

Similarly, if you have a function or method accepting**kwargs, then you should only annotate the type of each possible keyword argument.

Callables

Functions arefirst-class objects in Python. This means that you can use functions as arguments to other functions. That also means that you need to be able to add type hints representing functions.

Functions, as well as lambdas, methods and classes, arerepresented bytyping.Callable. The types of the arguments and the return value are usually also represented. For instance,Callable[[A1, A2, A3], Rt] represents a function with three arguments with typesA1,A2, andA3, respectively. The return type of the function isRt.

In the following example, the functiondo_twice() calls a given function twice and prints the return values:

 1# do_twice.py 2 3fromtypingimportCallable 4 5defdo_twice(func:Callable[[str],str],argument:str)->None: 6print(func(argument)) 7print(func(argument)) 8 9defcreate_greeting(name:str)->str:10returnf"Hello{name}"1112do_twice(create_greeting,"Jekyll")

Note the annotation of thefunc argument todo_twice() on line 5. It says thatfunc should be a callable with one string argument, that also returns a string. One example of such a callable iscreate_greeting() defined on line 9.

Most callable types can be annotated in a similar manner. However, if you need more flexibility, check outcallback protocols andextended callable types.

Example: Hearts

Let’s end with a full example of the game ofHearts. You might already know this game from other computer simulations. Here is a quick recap of the rules:

• Four players play with a hand of 13 cards each.

• The player holding the ♣2 starts the first round, and must play ♣2.

• Players take turns playing cards, following the leading suit if possible.

• The player playing the highest card in the leading suit wins the trick, and becomes start player in the next turn.

• A player can not lead with a ♡ until a ♡ has already been played in an earlier trick.

• After all cards are played, players get points if they take certain cards:

  • 13 points for the ♠Q
  • 1 point for each ♡

• A game lasts several rounds, until one player has 100 points or more. The player with the least points wins.

More details can befound online.

There are not many new typing concepts in this example that you have not already seen. We’ll therefore not go through this code in detail, but leave it as an example of annotated code.

# hearts.pyfromcollectionsimportCounterimportrandomimportsysfromtypingimportAny,Dict,List,Optional,Sequence,Tuple,UnionfromtypingimportoverloadclassCard:SUITS="♠ ♡ ♢ ♣".split()RANKS="2 3 4 5 6 7 8 9 10 J Q K A".split()def__init__(self,suit:str,rank:str)->None:self.suit=suitself.rank=rank@propertydefvalue(self)->int:"""The value of a card is rank as a number"""returnself.RANKS.index(self.rank)@propertydefpoints(self)->int:"""Points this card is worth"""ifself.suit=="♠"andself.rank=="Q":return13ifself.suit=="♡":return1return0def__eq__(self,other:Any)->Any:returnself.suit==other.suitandself.rank==other.rankdef__lt__(self,other:Any)->Any:returnself.value<other.valuedef__repr__(self)->str:returnf"{self.suit}{self.rank}"classDeck(Sequence[Card]):def__init__(self,cards:List[Card])->None:self.cards=cards@classmethoddefcreate(cls,shuffle:bool=False)->"Deck":"""Create a new deck of 52 cards"""cards=[Card(s,r)forrinCard.RANKSforsinCard.SUITS]ifshuffle:random.shuffle(cards)returncls(cards)defplay(self,card:Card)->None:"""Play one card by removing it from the deck"""self.cards.remove(card)defdeal(self,num_hands:int)->Tuple["Deck",...]:"""Deal the cards in the deck into a number of hands"""returntuple(self[i::num_hands]foriinrange(num_hands))defadd_cards(self,cards:List[Card])->None:"""Add a list of cards to the deck"""self.cards+=cardsdef__len__(self)->int:returnlen(self.cards)@overloaddef__getitem__(self,key:int)->Card:...@overloaddef__getitem__(self,key:slice)->"Deck":...def__getitem__(self,key:Union[int,slice])->Union[Card,"Deck"]:ifisinstance(key,int):returnself.cards[key]elifisinstance(key,slice):cls=self.__class__returncls(self.cards[key])else:raiseTypeError("Indices must be integers or slices")def__repr__(self)->str:return" ".join(repr(c)forcinself.cards)classPlayer:def__init__(self,name:str,hand:Optional[Deck]=None)->None:self.name=nameself.hand=Deck([])ifhandisNoneelsehanddefplayable_cards(self,played:List[Card],hearts_broken:bool)->Deck:"""List which cards in hand are playable this round"""ifCard("♣","2")inself.hand:returnDeck([Card("♣","2")])lead=played[0].suitifplayedelseNoneplayable=Deck([cforcinself.handifc.suit==lead])orself.handifleadisNoneandnothearts_broken:playable=Deck([cforcinplayableifc.suit!="♡"])returnplayableorDeck(self.hand.cards)defnon_winning_cards(self,played:List[Card],playable:Deck)->Deck:"""List playable cards that are guaranteed to not win the trick"""ifnotplayed:returnDeck([])lead=played[0].suitbest_card=max(cforcinplayedifc.suit==lead)returnDeck([cforcinplayableifc<best_cardorc.suit!=lead])defplay_card(self,played:List[Card],hearts_broken:bool)->Card:"""Play a card from a cpu player's hand"""playable=self.playable_cards(played,hearts_broken)non_winning=self.non_winning_cards(played,playable)# Strategyifnon_winning:# Highest card not winning the trick, prefer pointscard=max(non_winning,key=lambdac:(c.points,c.value))eliflen(played)<3:# Lowest card maybe winning, avoid pointscard=min(playable,key=lambdac:(c.points,c.value))else:# Highest card guaranteed winning, avoid pointscard=max(playable,key=lambdac:(-c.points,c.value))self.hand.cards.remove(card)print(f"{self.name} ->{card}")returncarddefhas_card(self,card:Card)->bool:returncardinself.handdef__repr__(self)->str:returnf"{self.__class__.__name__}({self.name!r},{self.hand})"classHumanPlayer(Player):defplay_card(self,played:List[Card],hearts_broken:bool)->Card:"""Play a card from a human player's hand"""playable=sorted(self.playable_cards(played,hearts_broken))p_str="  ".join(f"{n}:{c}"forn,cinenumerate(playable))np_str=" ".join(repr(c)forcinself.handifcnotinplayable)print(f"{p_str}  (Rest:{np_str})")whileTrue:try:card_num=int(input(f"{self.name}, choose card: "))card=playable[card_num]except(ValueError,IndexError):passelse:breakself.hand.play(card)print(f"{self.name} =>{card}")returncardclassHeartsGame:def__init__(self,*names:str)->None:self.names=(list(names)+"P1 P2 P3 P4".split())[:4]self.players=[Player(n)forninself.names[1:]]self.players.append(HumanPlayer(self.names[0]))defplay(self)->None:"""Play a game of Hearts until one player go bust"""score=Counter({n:0forninself.names})whileall(s<100forsinscore.values()):print("\nStarting new round:")round_score=self.play_round()score.update(Counter(round_score))print("Scores:")forname,total_scoreinscore.most_common(4):print(f"{name:<15}{round_score[name]:>3}{total_score:>3}")winners=[nforninself.namesifscore[n]==min(score.values())]print(f"\n{' and '.join(winners)} won the game")defplay_round(self)->Dict[str,int]:"""Play a round of the Hearts card game"""deck=Deck.create(shuffle=True)forplayer,handinzip(self.players,deck.deal(4)):player.hand.add_cards(hand.cards)start_player=next(pforpinself.playersifp.has_card(Card("♣","2")))tricks={p.name:Deck([])forpinself.players}hearts=False# Play cards from each player's hand until emptywhilestart_player.hand:played:List[Card]=[]turn_order=self.player_order(start=start_player)forplayerinturn_order:card=player.play_card(played,hearts_broken=hearts)played.append(card)start_player=self.trick_winner(played,turn_order)tricks[start_player.name].add_cards(played)print(f"{start_player.name} wins the trick\n")hearts=heartsorany(c.suit=="♡"forcinplayed)returnself.count_points(tricks)defplayer_order(self,start:Optional[Player]=None)->List[Player]:"""Rotate player order so that start goes first"""ifstartisNone:start=random.choice(self.players)start_idx=self.players.index(start)returnself.players[start_idx:]+self.players[:start_idx]@staticmethoddeftrick_winner(trick:List[Card],players:List[Player])->Player:lead=trick[0].suitvalid=[(c.value,p)forc,pinzip(trick,players)ifc.suit==lead]returnmax(valid)[1]@staticmethoddefcount_points(tricks:Dict[str,Deck])->Dict[str,int]:return{n:sum(c.pointsforcincards)forn,cardsintricks.items()}if__name__=="__main__":# Read player names from the command lineplayer_names=sys.argv[1:]game=HeartsGame(*player_names)game.play()