{"id":2816,"date":"2021-11-10T08:46:26","date_gmt":"2021-11-10T08:46:26","guid":{"rendered":"https:\/\/www.pythontutorial.net\/?page_id=2816"},"modified":"2025-04-02T09:50:11","modified_gmt":"2025-04-02T09:50:11","slug":"python-type-hints","status":"publish","type":"page","link":"https:\/\/www.pythontutorial.net\/python-basics\/python-type-hints\/","title":{"rendered":"Python Type Hints"},"content":{"rendered":"\n

Summary<\/strong>: in this tutorial, you’ll learn about the Python type hints and how to use the mypy tool to check types statically.<\/p>\n\n\n\n

Introduction to Python type hints #<\/a><\/h2>\n\n\n\n

Some programming languages have static typing, such as C\/C++. It means you need to declare types of variables, parameters, and return values of a function upfront. The predefined types allow the compilers to check the code before compiling and running the program.<\/p>\n\n\n\n

Python uses dynamic typing, in which a function’s variables, parameters, and return values can be any type. Also, the types of variables can change while the program runs.<\/p>\n\n\n\n

Generally, dynamic typing makes it easy to program and causes unexpected errors that you can only discover until the program runs.<\/p>\n\n\n\n

Python’s type hints provide you with optional static typing to leverage the best of both static and dynamic typing.<\/p>\n\n\n\n

The following example defines a simple function<\/a> that accepts a string and returns another string:<\/p>\n\n\n

def<\/span> say_hi<\/span>(name)<\/span>:<\/span>\n    return<\/span> f'Hi {name}<\/span>'<\/span>\n\n\ngreeting = say_hi('John'<\/span>)\nprint(greeting)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Here’s the syntax for adding type hints to a parameter and return value of a function:<\/p>\n\n\n
parameter: type\n-> type<\/code><\/span><\/pre>\n\n\n
For example, the following shows how to use type hints for the name<\/code> parameter and return value of the say_hi()<\/code> function:<\/p>\n\n\n
def<\/span> say_hi<\/span>(name: str)<\/span> -> str:<\/span>\n    return<\/span> f'Hi {name}<\/span>'<\/span>\n\n\ngreeting = say_hi('John'<\/span>)\nprint(greeting)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Hi John<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
In this new syntax, the name<\/code> parameter has the str<\/code> type:<\/p>\n\n\n
name: str<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
And the return value of the say_hi()<\/code> function also has the type str<\/code>:<\/p>\n\n\n
-> str<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Besides the str<\/code> type, you can use other built-in types such as int<\/code>, float<\/code>, bool<\/code>, and bytes<\/code> for type hintings.<\/p>\n\n\n\n
It’s important to note that the Python interpreter ignores type hints completely. If you pass a number to the say_hi()<\/code> function, the program will run without any warning or error:<\/p>\n\n\n
def<\/span> say_hi<\/span>(name: str)<\/span> -> str:<\/span>\n    return<\/span> f'Hi {name}<\/span>'<\/span>\n\n\ngreeting = say_hi(123<\/span>)\nprint(greeting)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Hi 123<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
To check the syntax for type hints, you need to use a static type checker tool.<\/p>\n\n\n\n
Using a static type checker tool: mypy #<\/a><\/h2>\n\n\n\n
Python doesn’t have an official static type checker tool. At the moment, the most popular third-party tool is Mypy. Since Mypy is a third-party package, you need to install it using the following pip<\/code> command:<\/p>\n\n\n
pip instal mypy<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Once installed mypy<\/code>, you can use it to check the type before running the program by using the following command:<\/p>\n\n\n
mypy app.py<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
It’ll show the following message:<\/p>\n\n\n
app.py:5<\/span>: error: Argument 1<\/span> to \"say_hi\"<\/span> has incompatible type \"int\"<\/span>; expected \"str\"<\/span>\nFound 1<\/span> error in<\/span> 1<\/span> file (checked 1<\/span> source file)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The error indicates that the argument of the say_hi<\/code> is int<\/code> while the expected type is str<\/code>.<\/p>\n\n\n\n
If you change back the argument to a string and run the mypy<\/code> again, it’ll show a success message:<\/p>\n\n\n
Success: no issues found in<\/span> 1<\/span> source file<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Type hinting & type inference #<\/a><\/h2>\n\n\n\n
When defining a variable, you can add a type hint like this:<\/p>\n\n\n
name: str = 'John'<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The type of  name<\/code> variable is str<\/code>. If you assign a value that is not a string to the name<\/code> variable, the static type checker will issue an error. For example:<\/p>\n\n\n
name: str = 'Hello'<\/span>\nname = 100<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
app.py:2<\/span>: error: Incompatible types in<\/span> assignment (expression has type \"int\"<\/span>, variable has type \"str\"<\/span>)\nFound 1<\/span> error in<\/span> 1<\/span> file (checked 1<\/span> source file)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Adding a type to a variable is unnecessary because static type checkers typically can infer the type based on the value assigned to the variable.<\/p>\n\n\n\n
In this example, the value of the name is a literal string so that the static type checker will infer the type of the name variable as str. For example:<\/p>\n\n\n
name = 'Hello'<\/span>\nname = 100<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
It’ll issue the same error:<\/p>\n\n\n
app.py:2<\/span>: error: Incompatible types in<\/span> assignment (expression has type \"int\"<\/span>, variable has type \"str\"<\/span>)\nFound 1<\/span> error in<\/span> 1<\/span> file (checked 1<\/span> source file)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Adding type hints for multiple types #<\/a><\/h2>\n\n\n\n
The following add()<\/code> function returns the sum of two numbers:<\/p>\n\n\n
def<\/span> add<\/span>(x, y)<\/span>:<\/span>\n    return<\/span> x + y<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The numbers can be integers or floats. You can use the module to set type hints for multiple types.<\/p>\n\n\n\n
First, import Union<\/code> from typing<\/code> module:<\/p>\n\n\n
from<\/span> typing import<\/span> Union<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Second, use the Union<\/code> to create a union type that includes int<\/code> and float<\/code>:<\/p>\n\n\n
def<\/span> add<\/span>(x: Union[int, float], y: Union[int, float])<\/span> -> Union[int, float]:<\/span>\n    return<\/span> x + y<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Here is the complete source code:<\/p>\n\n\n
from<\/span> typing import<\/span> Union\n\n\ndef<\/span> add<\/span>(x: Union[int, float], y: Union[int, float])<\/span> -> Union[int, float]:<\/span>\n    return<\/span> x + y<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Starting from Python 3.10, you can use the X | Y  syntax to create a union type, for example:<\/p>\n\n\n
def<\/span> add<\/span>(x: int | float, y: int | float)<\/span> -> int | float:<\/span>\n    return<\/span> x + y<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Type aliases #<\/a><\/h2>\n\n\n\n
Python allows you to assign an alias to a type and use the alias for type hintings. For example:<\/p>\n\n\n
from<\/span> typing import<\/span> Union\n\nnumber = Union[int, float]\n\n\ndef<\/span> add<\/span>(x: number, y: number)<\/span> -> number:<\/span>\n    return<\/span> x + y<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
In this example, we assign the Union[int, float]<\/code> type an alias Number<\/code> and use the Number<\/code> alias in the add() function.<\/p>\n\n\n\n
Adding type hints for lists, dictionaries, and sets #<\/a><\/h2>\n\n\n\n
You can use the following built-in types to set the type hints for a list<\/a>, dictionary<\/a>, and set<\/a>:<\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n