Annotations are defined in PEP 3107 allow you to add arbitrary metadata to the parameters and return values of functions. The __annotations__
attribute of a function object stores those annotations in a dictionary mapping function parameters or the return value to the specified annotations.
Let’s have a look at a couple of examples next.
Parameter Annotations
The syntax of a parameter annotation works as follows. You add a colon after the parameter name and add an arbitrary object or reference to an object after the colon. The parameter is now annotated with the object.
def f(param_1: annotation_1,
param_2: annotation_2, ...):
pass
The following code snippet shows a minimal example where you add string annotations to the input parameters of a given function. The function calculates the potential savings you’d obtain by investing x
units of money at y
annualized return for n
years.
def save(x: "starting capital", y: "annual return (e.g., 0.1 == 10%)", n: "number of years"): return x * (1+y)**n # Investing $10,000 at 10% for 50 years print(save(10000, 0.1, 50)) # 1173908.5287969578 # = $1.1 million USD
You can print the annotations using the __annotations__
attribute of the function save
:
print(save.__annotations__) # {'x': 'starting capital', 'y': 'annual return (e.g., 0.1 == 10%)', 'n': 'number of years'}
Return Value Annotations
The syntax of a return value annotation works as follows. After the closing parenthesis of the definition of the function parameters, you add the -> arrow symbol, followed by the object or reference to an object associated with the return value of a function or callable.
def f(...) -> annotation:
pass
You can add an annotation to the return value of the function as shown in the following example:
def save(x, y, n) -> "final capital": return x * (1+y)**n print(save.__annotations__) # {'return': 'final capital'}
The __annotations__
attribute stores a dictionary of key,value mappings where
- the keys are the parameter names or the
'return'
string in case of a return value annotation, and - the values are the annotation objects.

While working as a researcher in distributed systems, Dr. Christian Mayer found his love for teaching computer science students.
To help students reach higher levels of Python success, he founded the programming education website Finxter.com that has taught exponential skills to millions of coders worldwide. He’s the author of the best-selling programming books Python One-Liners (NoStarch 2020), The Art of Clean Code (NoStarch 2022), and The Book of Dash (NoStarch 2022). Chris also coauthored the Coffee Break Python series of self-published books. He’s a computer science enthusiast, freelancer, and owner of one of the top 10 largest Python blogs worldwide.
His passions are writing, reading, and coding. But his greatest passion is to serve aspiring coders through Finxter and help them to boost their skills. You can join his free email academy here.