Describe Values with Type Hints

The previous lesson used a docstring to describe a function’s promise in complete sentences. Sometimes a reader also needs a quick summary of the kinds of values that go into and come out of a function.

Python lets you add those clues directly to the function definition. They are called type hints.

Hint at a parameter’s type

Start with an ordinary function:

def repeat(text, times):
    return text * times

To say that text should be a string, write a colon and the type name after the parameter:

def repeat(text: str, times):
    return text * times

The : str is a type hint. It says that the function expects a string for text.

You can give each parameter its own hint:

def repeat(text: str, times: int):
    return text * times

Read this definition as: “repeat expects a string named text and an integer named times.”

The hint uses a type name such as str, int, float, or bool. It does not use an example value, so write text: str, not text: "hello".

Hint at the return type

A hint after an arrow describes the value the function returns:

def repeat(text: str, times: int) -> str:
    return text * times

The -> str says that repeat promises to return a string. The arrow belongs after the closing parenthesis and before the colon that ends the def line.

Here is an average function with all three hints:

def average(total: int, count: int) -> float:
    return total / count

You can read it from left to right:

• total: int says total should be an integer;

• count: int says count should be an integer;

• -> float says the function should return a floating-point number.

Calling the function does not change:

result = average(21, 3)

The hints belong to the definition, not to each call.

See type hints with help()

In the previous lesson, you used help() to read a function’s docstring. The same output also shows its type hints.

Run this example:

help() summarizes the function like this:

average(total: int, count: int) -> float

The parameter and return hints come from the function definition. The sentence underneath comes from the docstring. Together, they show both kinds of documentation without requiring someone to read the function body.

Hints describe; they do not enforce

Python does not automatically reject a value just because it disagrees with a type hint:

The second call passes a string even though the hint says int. Python still runs the function body, and multiplying the string produces "haha".

The function body still determines what happens while the program runs.

This is different from many other programming languages. In statically typed languages such as Java, C#, and Rust, declared types are part of the language’s rules. Supplying the wrong type is normally rejected before the program runs. Python’s type hints provide useful information, but Python does not enforce them automatically.

Help automated checkers

Type hints are especially useful to tools that examine code for likely mistakes. A linter is a general automated code checker. A type checker focuses on whether values agree with type hints.

For example, a type checker can compare this call with the definition above:

double("ha")

It can warn that double expects an int, but the call supplies a str. The checker can find that mismatch without running the program. Code editors may display the same kind of warning while you type.

The warning does not change Python’s runtime behavior: as the runnable example showed, Python itself still executes the call. Type hints give people and automated checkers more information with which to spot a likely mistake earlier.

That makes honest hints important. A wrong hint can mislead the next person who uses the function.

Add hints to an existing function

The percentage function already calculates the correct result. Add only the type hints that describe its two parameters and returned value. The next lesson will use that returned value to compare pure functions with side effects.