3.4.5. Type annotations#
In addition to docstrings, type annotations (also called type hints) are increasingly popular to document the types of a function’s parameters and return value.
Good practice: Docstring vs type annotations
Always write a good docstring in the first place. Type annotation are much more optional, and at this point, knowing about type annotations is important mainly to read Python packages documentation.
Type annotation allows documenting the types directly in the function signature instead of the docstring. They use :
to document parameter types, and ->
to document return value types (see the ->
as a right-arrow):
def format_info(
i_participant: int,
first_name: str,
last_name: str,
age: float,
height: float,
weight: float
) -> str:
"""
Format the provided information into a human-readable string.
Parameters
----------
i_participant
Identifier for the participant
first_name
First name (given name) of the participant
last_name
Last name (surname) of the participant
age
Age of the participant, in years
height
Height of the participant, in meters
weight
Weight of the participant, in kg
Returns
-------
str
A human-readable string based on the provided information.
"""