Type Comments

In this lesson, you’ll learn about type comments. As you saw, annotations were introduced in Python 3, and they haven’t been backported to Python 2. This means that, if you’re writing code that needs to support legacy Python, then 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. Type comments will not be available in the __annotations__ dictionary. To add type comments to a function, you do this:

def func(arg):
    # type:(str) -> str
    ...

For variables, add the type comment on the same line:

my_variable = 42 # type: int

The type comments are just comments, so they can be used in any version of Python. Try adding type comments to the function from the previous lesson:

>>> import math

>>> def circumference(radius):
...     # type: (float) -> float
...     return 2 * math.pi * radius
...
...
>>> circumference(4.5)
28.274333882308138
>>> circumference.__annotations__
{}

A type comment must start with the type: literal and be on the same line as the function definition or the following line. If you want to annotate a function with several arguments, you write each type separated by comma. You can also write each argument on a separate line with its own annotation:

# headlines.py

def headline1(text, width=80, fill_char="-"):
    # type: (str, int, str) -> str
    return f" {text.title()} ".center(width, fill_char)

print(headline1("type comments work", width=40))

def headline2(
    text,           # type: str
    width=80,       # type: int
    fill_char='-',  # type: str
):                  # type: (...) -> str
    return f" {text.title()} ".center(width, fill_char)

print(headline2("these type comments also work", width=70))

pi = 3.142  # type: float

Run the example through Python and Mypy:

$ mypy headlines.py
$ python3 headlines.py
---------- Type Comments Work ----------
------------------- These Type Comments Also Work -------------------

If you have errors, for instance if you happened to call headline1() with 67 as the first argument on line 7, and headline2() with width="normal" on line 16, then Mypy will tell you the following:

$ mypy headlines.py
headlines.py:7: error: Argument 1 to "headline1" has incompatible type "int"; expected "str"
headlines.py:16: error: Argument "width" to "headline2" has incompatible type "str"; expected "int"

Should you use annotations or type comments when adding type hints to your own code? 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 the officially 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 like linter directives. However, they can be used in code bases that don’t support annotation