Python Type Hinting - Part I

If you are using a recent version of Python (which you should because Python 2 will be EOL in less than a year) than you can use type hinting with a sane syntax instead of using docstrings to document the arguments types.

For those of you that are not yet sold on static typing, especially in a dynamic language, I will post a separate post about it in the future. You could come back to this post when you decide to embrace static typing.

Basic Syntax

The type of a variable comes after the name of the variable, separated with a colon. The syntax for variable type hinting and argument type hinting is the same.

To indicate the return type of a function, you need to put an arrow (->) followed by the type and a colon like any other function. Here is an example of a function with type hinting for the argument and return value:

def greeting(name: str) -> str:
    return 'Hello ' + name

Advance Types

You can use all the built in types for type hinting but they are kind of limiting. You can’t specify a more abstract types like iterable or a more specific type like a list of strings.

There are more advance types in the typing package that can let you create more precise function signatures. Instead of using list, you can use typing.List and specify the list type in brackets if you want to. For example if we would want to greet multiple people our function could look like this:

from typing import List

def multiple_greetings(names: List[str]) -> List[str]:
    return list(map(greeting, names))

There are also abstract types that doesn’t map to a specific implementation but instead represent an interface that more than one type implement. A few of those that I find useful are typing.Iterable, typing.Sequence and typing.Mapping. With those types we could redefine our multiple_greetings functions like this:

from typing import Iterable, Iterator

def multiple_greetings(names: Iterable[str]) -> Iterator[str]:
    return map(greeting, names)

Type Checking

Python doesn’t check the types on his own, the interpreter only add it to the __annotations__ property. If you want to validate your program using the type hinting you just added you will need another tool. If you are using an IDE like PyCharm you will have type checking built in without installing anything else. If you are using an editor or want a better type checker than PyCharm I recommend mypy.

You can install mypy through pip with the command

python3 -m pip install -U mypy

After the installation is complete you can simply run mypy from the terminal with your package directory as an argument and you will get a list of complaints about your typing.

What’s Next?

This post should help you start adding type hinting to your code but you might still feel a little bit limited with using only the existing types in the typing package. There are more advance way of defining new types that I will cover in a future post.

If you can’t wait for my second post, you can learn more about typing from the official typing documentation.