Warning

Type hints are a way of annotating the expected types of variables, function parameters, and function return types in Python. In other words, they are a way that a programmer can indicate the type that is expected in a certain part of a Python program. Most Python programs are written without type hints. In fact, before reading this book, even if you are an intermediate Python programmer, it is very possible that you have never seen a Python program with type hints.

Now that Python has type hints, we call it a gradually typed language—meaning that you can use type annotations when you want to, but they are not required. In this short introduction I hope to convince you (despite perhaps your resistance to how they fundamentally change the look of the language) that having type hints available is a good thing—a good thing that you should take advantage of in your code.

Type hints are added to the line of code where a variable or a function is declared. A colon (:) is used to indicate the start of a type hint for a variable or a function parameter, and an arrow (->) is used to indicate the start of a type hint for a function return type. For example, take the following line of Python code:

def repeat(item, times):

Without reading the function definition, can you tell what this function is supposed to do? Is it supposed to print out a string a certain number of times? Is it supposed to do something else? Of course, one could read the function definition to figure out what it’s supposed to do, but that would take more time. The author of this function has also, unfortunately, not provided any documentation. Let’s try it again with type hints:

def repeat(item: Any, times: int) -> List[Any]:

That’s a lot clearer. Just looking at the type hints, it would appear that this function takes an item of Any type and returns a List filled with times number of that item. Of course, documentation would still help make this function more understandable, but at least the user of this library now knows what kind of values to supply it and what kind of value it can be expected to return.

Suppose the library that this function is supposed to be used with only works with floating-point numbers, and this function was meant to be used as a setup for lists to be used in other functions. We can easily change the type hints to indicate the floating-point constraint:

def repeat(item: float, times: int) -> List[float]:

Now it’s clear that item must be a float, and the returned list will be filled with floats. Well, the word must is rather strong. Type hints, as of Python 3.7, have no bearing on the execution of a Python program. They truly are just hints rather than musts. At runtime, a Python program can completely ignore its type hints and break any of its supposed constraints. However, type-checker tooling can evaluate the type hints in a program during development and tell the programmer if there are any illegitimate calls to a function. A call of repeat("hello", 30) can be caught before it enters production (because "hello" is not a float).

Let’s look at one more example. This time, we will examine a type hint for a variable declaration:

myStrs: List[str] = repeat(4.2, 2)

Now that you know what type hints are, you may be wondering why all of this trouble is worth it. After all, you have also learned that type hints are ignored by Python at runtime. Why would one spend all this time adding type annotations to the code when the Python interpreter couldn’t care less? As has already been touched upon, type hints are a good idea for two primary reasons: They self-document the code, and they allow a type checker to verify the correctness of a program prior to execution.

In most programming languages with static typing (like Java or Haskell), required type declarations make it very clear what parameters a function (or method) expects and what type it will return. This alleviates some of the documentation burden on the programmer. For instance, it is completely unnecessary to specify what the following Java method expects as parameters or return type:

/* Eats the world, returning the amount of money generated as refuse. */
public float eatWorld(World w, Software s) { ... }

Contrast this with the required documentation for the equivalent method written in traditional Python, without type hints:

# Eat the world
# Parameters:
# w – the World to eat
# s – the Software to eat the World with
# Returns:
# The amount of money generated by eating the world as a float
def eat_world(w, s):

By allowing us to self-document our code, type hints make Python documentation as succinct as statically typed languages:

# Eat the world, returning the amount of money generated as refuse.
def eat_world(w: World, s: Software) -> float:

Take it to an extreme. Imagine you inherit a codebase that has no comments whatsoever. Will a commentless codebase be easier to make sense of with type hints or without type hints? The type hints will save you from having to dig into the actual code of a commentless function to understand what types to pass it as parameters and what type to expect it to return.

Remember, a type hint is essentially a way of stating what type is expected at some point in a program. Yet Python does nothing to verify this expectation. That’s where a type checker comes in. A type checker can take a file of Python source code filled with type hints and verify if they actually will hold when the program is run.

The leading Python type checker, as I write this book, is mypy. The mypy project is led by Guido van Rossum, the same person who originally created Python itself. Does that leave any doubt in your mind that type hints could potentially have a very prominent role in the future of Python? After you install mypy, using it is as simple as running mypy example.py, where example.py is the name of the file you want to type check. mypy will spit out to the console all of the type errors in your program or nothing if there are no errors.

There may be other ways type hints will be useful in the future. Right now, type hints have no impact on the performance of a running Python program. (To reiterate one last time, they are ignored at runtime.) But it is possible that future versions of Python will use the type information from type hints to perform optimizations. In such a world, perhaps you will be able to speed up the execution of your Python program by simply adding type hints. This is pure speculation, of course. I know of no plans to implement type hint-based optimizations in Python.

There are three potential downsides of using type hints:

• Code with type hints takes longer to write than code without type hints.
• Type hints can arguably lead to a decrease of readability in some cases.
• Type hints are still not fully baked, and implementing some typing constraints with Python’s current implementations can be confusing.

Code with type hints takes longer to write for two reasons: It’s simply more typing (literally more keys hit on the keyboard), and you have to reason more about your code. Reasoning about your code is almost always a good thing, but doing extra reasoning will slow you down. However, you will hopefully make up for that lost time by catching errors with a type checker before your program even runs. The time spent debugging errors that could be caught by a type checker is probably greater than the time spent reasoning about types at composition time for any complex codebase.