Python Type Hints: How to Enhance Code Clarity and Maintainability

We explained in our Python Classes guide already that Python is a dynamically typed language. For those who landed directly to this Python Type Hints explanatory guide, a dynamically typed language means the variables do not require explicit type declarations. While this provides flexibility, it can also lead to bugs, unclear code, and maintainability issues. Python introduced Type Hints in its version 3.5. With this update, you can add optional static typing, making your code more readable and easier to debug.

Today at PythonCentral, we will explain Python Type Hints, how to use them effectively, and their benefits in modern software development. Get. Set. Learn!

What Are Python Type Hints?

Type Hints allow you to annotate variables, function arguments, and return values with explicit types. These hints are not enforced at runtime but can be checked using static type checkers like "mypy".

Let us look at a sample script of a function without type hints first.

def add_numbers(a, b):
return a + b

Now, let us write the same script with type hints:

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

Here, we specify that "a" and "b" are integers, and the function returns an integer. This improves code readability and prevents incorrect usage.

Basic Type Hints in Python

Python provides built-in type hints for common data types. Let us list down a few types and examples as well:

int; Example: x: int = 42
float; Example: y: float = 3.14
str; Example: name: str = "PythonCentral"
bool; Example: flag: bool = True
list; Example: numbers: list[int] = [1, 2, 3]
dict; Example: config: dict[str, int] = {"timeout": 30}
tuple; Example: coords: tuple[int, int] = (10, 20)
None; Example: result: None = None

How to Use Type Hints in Functions

Function Argument and Return Type Hints

Here is a script that uses return type hints in functions.

def greet(name: str) -> str:
return f"Hello, {name}!"

Optional and Default Parameters

Use "Optional" from the "typing" module when a parameter can be None. Here is an example to help you understand better:

from typing import Optional

def get_user_age(name: str, age: Optional[int] = None) -> str:
if age:
return f"{name} is {age} years old."
return f"Age of {name} is unknown."

Advanced Type Hints in Python

Now that we are familiar with the basics, let us look at some advanced type hints.

How to Use "Union" for Multiple Types

If a function accepts multiple types, use "Union". When you use "Union", your script will look similar to:

from typing import Union

def process(value: Union[int, float]) -> float:
return value * 2.5

Type Hinting for Lists and Dictionaries

Here is a sample script for using type hints for lists and dictionaries:

from typing import List, Dict

def get_names(ages: Dict[str, int]) -> List[str]:
return list(ages.keys())

Type Hinting for Classes and Methods

If you are working with classes and methods, you can use this script and adjust it to your requirements:

class User:
def __init__(self, name: str, age: int) -> None:
self.name = name
self.age = age

def greet(self) -> str:
return f"Hello, my name is {self.name} and I am {self.age} years old."

Using "TypedDict" for Structured Data

"TypedDict" helps define dictionaries with specific structures.

from typing import TypedDict

class Person(TypedDict):
name: str
age: int

person: Person = {"name": "Alice", "age": 30}

Static Type Checking with "mypy"

We strongly recommend learning about Python classes as well. We have covered "mypy" in that lesson as well. To enforce type hints, use "mypy":

pip install mypy

Then, you can check the run type by executing this command:

mypy script.py

Type Hints Advantages

Type Hints are both a necessity and a luxury. With Python 3.5's introduction of type hints, you get advantages like:

Improved code readability
Early error detection
Better code documentation
Enhanced IDE Support (autocomplete and suggestions)
Improved maintainability

Wrapping Up

Type hints in Python help you improve code clarity, maintainability, and reliability. While Python remains dynamically typed, adding type hints can reduce bugs, improve collaboration, and optimize developer experience. By leveraging type hinting, you can write more structured, robust, and scalable applications. Start using them today to write better, safer, and more maintainable code.