Why type hints?
Let me start this article with an example. Consider following function:
def process_records(records, transform, key_field):
results = {}
for record in records:
transformed = transform(record)
results[record[key_field]] = transformed
return resultsAfter a quick look, you might deduce that each record is a dictionary and key_field must be one of its keys, while transform is a function that takes record and returns some result. However, to fully confirm these assumptions, youâd likely have to hunt down every usage of process_records across the codebase, turning into a detective just to figure out the shape of the arguments. Wouldnât it be easier if you knew right away what types to expect?
That where the type hints come to an aid! And aside from providing you the clarity about the type of the arguments and the function itself, thus reducing the guesswork, it could also help your IDE provide you better code suggestions. In other words, fewer bugs, less time wasted, and a smoother development experience overall.
Now that we know what problem we are trying to solve, letâs get to the part of answering the question how exacly we are going to do this.
The ultimate basics
This is goint to be a short introduction into type hints. Itâs not meant to be comprehensive, just to grasp the initial idea. If you are looking to dig deeper, then my next blog posts or this page in python docs are going to be your resources.
Simple types
The type hints in python have rather a simple structure. If we would like to specify what is the type of the variable, we just need to put a colon symbol at the end of a variable name, followed by the type of the variable, like this:
age: int = 20On the other hand, if your variable is a data structure, you could either specify it as a general type of said data structure:
animals: list = ["dog", "cat"]or more specifically:
animals: list[str] = ["dog", "cat"]The return type of the function has a slightly different syntax:
def hello() -> str:
return "Hello world"but typing the parameters is exactly the same as typing the variables:
def add(a: int, b: int = 10) -> int:
return a + bAs you may see, you can still easily provide a default values for the parameters even with a type hint. Type hints for dictionaries on the other hand look like this:
record: dict[str, str] = {}This type hint takes 2 arguments, where the first one it the type of the key in the dictionaty, and the other is the type of the value. So here we say that a record is some dictionary with both keys and the values being a strings.
Inferring types
Itâs also worth noting, that when we create a variable, the type of it is usually obvious to the pythonâs interpreter. This means, that when creating a variable of a simple type, like this:
age: int = 20
name: str = "Matt"
is_happy: bool = Truewe can comfortably ommit the type part, because as we give them the initial values, the type of those variables is inferred by the interpreter and our IDE, so the type hints wouldnât give us any real value here.
age = 20
name = "Matt"
is_happy = TrueWhere to use type hints then?
It is when we define a type for a functions, data structures or any other complex code, that makes the type hints really shine. So letâs say you have a set of numbers:
unique_ids: set[int] = set()Now whoever sees this line would know, that the IDs are integers, not for example strings or UUIDs. Without type hints a programmer would need to put on his detective hat and find wherever this unique_ids are used and what kind of elements are added to this data structure. Similarly with functions:
def get_by_id(user_id: int) -> User:
...Without type hint, digging up what type is user_id would require much more effort.
Callables
There is one last thing we need before we can proceed with typing our function in the example at the beginning. The second argument is a function, that takes a record as an argument. In python typing a function is a Callable. This is the type we have to import either from deprecated typing.Callable or introduced in python 3.9 collections.abc.Callable:
from collections.abc import Callable
def adjust_input(input: list[str], adapter: Callable[[int, str], str]) -> list[str]:
...Here we have typed the adapter as some kind of Callable taking two arguments, one of type int and the orher of type str, and returning a str. The general pattern is:
f = Callable[[arguments_types], return_type]Typing the initial example
Now we have all the tools to enhance our initial example with type hints. Letâs see how it would look like when we add types:
from collections.abc import Callable
def process_records(
records: list[dict[str, str]],
transform: Callable[[dict[str, str]], dict[str, str]],
key_field: str
):
results = {}
for record in records:
transformed = transform(record)
results[record[key_field]] = transformed
return resultsGreat! Now we know what we know a bit better what we are dealing with. Although there is still plenty of room for improvement, we will work on it next blog post. Most of the information we could have guessed ourselves, but now we know that we expect the dictionaryâs keys to be strings, along with the values. We know that the transform takes whatever is a record and returns the dictionary of the similar shape.
Type checking
What do you think will happen, if we were to pass list of strings instead of list of dictionaries as records into this function?
from collections.abc import Callable
def transform_user(record: dict[str, str]) -> dict[str, str]:
# Convert the user's full name to uppercase and age to an integer.
return {"full_name": record["full_name"].upper(), "age": int(record["age"])}
def process_records(
records: list[dict[str, str]],
transform: Callable[[dict[str, str]], dict[str, str]],
key_field: str
):
results = {}
for record in records:
transformed = transform(record)
results[record[key_field]] = transformed
return results
data = ["jsmith", "mdoe"]
processed_users = process_records(data, transform_user, "username")
print(processed_users)Obviously the function would throw and error, but it wouldnât be related to our type hints, rather to python interpreter trying to process the record.
Traceback (most recent call last):
File "/Users/anakin/projects/type-hints/main.py", line 22, in <module>
processed_users = process_records(data, transform_user, "username")
File "/Users/anakin/projects/type-hints/main.py", line 11, in process_records
transformed = transform(record)
File "/Users/anakin/projects/type-hints/main.py", line 18, in transform_user
return {"full_name": record["full_name"].upper(), "age": int(record["age"])}
TypeError: string indices must be integersThis type error is thrown on executing this line: return {"full_name": record["full_name"].upper(), "age": int(record["age"])}, not on passing the wrong type to the function, which happens here: processed_users = process_records(data, transform_user, "username"). This is extremally important to remember, that pythonâs interpreter doesnât care about type hints at all! And there is currently no way to force it to. You could type hint a parameter with any type, and pass a different type and python wouldnât case. You might (correctly) assume that in this case it renders the type hints worthless and they are if you are not using a type checker tool.
Introducing MyPy
MyPy is an example of a tool (but not the only one), that does whatâs called a static type checking before you run your python code. It checks if all the type hints are in place and if you are not accidentally passing a wrong type of value to some function.
In order to introduce MyPy to your project, just install it with:
pip install mypyand then run it:
mypy .The dot at the end is necessary, because we are pointing a directory which we want mypy ti check. If you just want it to check one file or any subdirecotry of your project, you can change the . accordingly:
mypy main.pyIn our case the result would be an error in line 22:
main.py:22: error: Argument 1 to "process_records" has incompatible type "list[str]"; expected "list[dict[str, str]]" [arg-type]
Found 1 error in 1 file (checked 1 source file)Letâs fix it then:
from collections.abc import Callable
def transform_user(record: dict[str, str]) -> dict[str, str]:
# Convert the user's full name to uppercase and age to an integer.
return {"full_name": record["full_name"].upper(), "age": int(record["age"])}
def process_records(
records: list[dict[str, str]],
transform: Callable[[dict[str, str]], dict[str, str]],
key_field: str
):
results = {}
for record in records:
transformed = transform(record)
results[record[key_field]] = transformed
return results
data = [
{"username": "jsmith", "full_name": "John Smith", "age": "25"},
{"username": "mdoe", "full_name": "Mary Doe", "age": "30"},
]
processed_users = process_records(data, transform_user, "username")
print(processed_users)and now we should see MyPy announcing our great success:
Success: no issues found in 1 source fileWe can (and definitely should) automate this process of type checking before commiting our code and Iâll definityly make another blog post on this subject. But it is important to know, that when you use type hints, your IDE will most probably warn you itself if you are trying to pass the wrong type of value in the wrong place. If you use VSCode, you can find Mypy Type Checker extension for this purpose.
Conclusion
Type hints in Python offer a middle ground between flexibility and code clarity. As youâve seen, they can help you spot errors before you run your project, power up your IDEâs auto-completion, and make your code far more understandable. Especially in larger, long-lived projects. Python is never going to force static typing on you, and thatâs part of its charm. But if youâve ever found yourself playing detective just to figure out the shape or purpose of certain variables, give type hints a try. Coupled with a type checker like MyPy, youâll spend less time guessing and more time building features. In future posts, weâll explore more advanced typing features and show how to automate type checks along with introducing other tools to keep your codebase easier to maintain.