Function Annotations in Python

Today we’ll be talking about function annotations. These are user-defined data that add some information to functions.

Annotations add information about the function’s arguments and result. They are optional and make no difference for the interpreter. They’re rather for us than the interpreter. Still, they can be pretty helpful.

We often use annotations to add information about the types of the arguments and the type of the value returned from the function. OK, let’s see an example.

We add argument annotations after a colon and result annotations after an arrow (->). We put argument annotations inside the parentheses, directly following the arguments, and result annotations after the closing parenthesis of the argument list.

Here we annotate that the two arguments should be ints and the result also should be an integer:

>>> def func(a: int, b: int) -> int:
...     return a + b
...

Let’s now call the function with two integers:

>>> func(3, 5)
8

But, as I just mentioned, annotations are ignored by the interpreter, so even if we use different data types for our arguments, it still works just like without any annotations at all:

>>> func("good ", "night")
'good night'

Here’s another example. The annotations are just for us:

def func(a: str, b: float, c: list) -> dict:
    pass

This function actually doesn’t do anything, but you can see some other data types used as annotations.

Learn how to make beautiful GUI apps

in Python using the Kivy framework.

Comprehensive, for Kivy beginners, easy to follow.

Get the book here (PDF) or on Amazon:

ebook / paperback (black and white) / paperback (full color)

Function Annotations May Be Anything…

But the annotations don’t have to be data types. Actually, they may be anything. We can use them however it makes sense for us:

>>> def func(a: (0, 4, 8), b: 'not a string', c: 2 * 5) -> 'something funny':
...     return a + b + c
... 

When we call the function, the annotations are just ignored:

>>> func(1, 2, 3)
6

Now, if you want to use optional parameters with annotations, they should follow the parameter names but precede the default values:

def func(a: int, b: int = 1, c: str = " ") -> float:
    pass

Your Panda3D Magazine

Make Awesome Games and Other 3D Apps

with Panda3D and Blender using Python.

Cool stuff, easy to follow articles.

Get the magazine here (PDF).

If you need access to the annotations inside your code, they are stored in a dictionary called __annotations__ . The names of the parameters are the keys and the annotations are the values. You will find the result annotation under the key return.

Here’s an example where we’re using the annotations:

def func(a: str, b: int) -> str:
    return a * b

message = f"""You are supposed to pass a {func.__annotations__['a']}
and a {func.__annotations__['b']} as arguments to the function. 
The function is supposed to return a {func.__annotations__['return']}."""

print(message)

The output is:

You are supposed to pass a <class 'str'>
and a <class 'int'> as arguments to the function.
The function is supposed to return a <class 'str'>.

Python Jumpstart Course

Learn the basics of Python, including OOP.

with lots of exercises, easy to follow

The course is available on Udemy.

Blender Jumpstart Course

Learn the basics of 3D modeling in Blender.

step-by-step, easy to follow, visually rich

The course is available on Udemy and on Skillshare.

Here’s the video version of the article: