The World of Python Programming

Python Type Hints: Boost Readability & Maintainability

Functions & Classes
目次

1. The Need for Type Hints and Their Benefits

Python is a dynamically typed language, and it works without explicitly specifying the types of variables or functions. While this feature enables flexible coding, it can become a drawback as codebases grow larger or when working in a team, making it harder for other developers to read the code. That’s where type hints come in handy.

Challenges of Dynamic Typing and the Benefits of Type Hints

In Python, it can be unclear what type a variable should have. This issue might not be noticeable in small scripts, but as the codebase grows, it becomes harder to understand and can become a breeding ground for bugs. Using type hints provides the following advantages.
  • Improved Readability: With type hints, the types of variables and functions are explicit, making it easier for other developers to understand the code.
  • Early Bug Detection: By using tools such as mypy, you can detect type mismatches before the code runs.
  • Increased Development Efficiency: Integrated with editor autocomplete features, it helps you code more smoothly.

2. How to Write Basic Type Hints

Type hints are a feature officially introduced in Python 3.5 that allow you to explicitly specify types in your code. This enables developers to understand code behavior more clearly.

How to Add Type Hints to Variables

Adding a type hint to a variable is simple. You write the type after the variable name as shown below.
x: int = 10
y: float = 3.14
name: str = "John"

Type Hints for Function Arguments and Return Values

In functions, you can also add type hints to arguments and return values. For example, the function below indicates that argument a is of type int and the return value is of type str.
def greet(age: int) -> str:
    return f"Your age is {age}"
Type hints have no effect at runtime, but they make code more readable and improve development efficiency by working with editor autocomplete features.

3. Utilizing the typing module

Python’s typing module is used to represent more complex types. Here we introduce several commonly used types.

Example of List type usage

When specifying a type for a list, use List. The following example shows a list of int type.
from typing import List

numbers: List[int] = [1, 2, 3, 4, 5]
From Python 3.9 onward, you can use list instead of List.
numbers: list[int] = [1, 2, 3, 4, 5]

Using the Dict type

You can also add type hints to dictionary types. The following example is a dictionary with keys of str and values of int.
from typing import Dict

inventory: Dict[str, int] = {"apple": 10, "banana": 5}

Using Union

When a value may have multiple possible types, use Union. The following example shows that an argument may be either str or int type.
from typing import Union

def process(value: Union[int, str]) -> None:
    if isinstance(value, int):
        print(f"Integer: {value}")
    else:
        print(f"String: {value}")
By using the typing module in this way, you can add more flexible and intuitive type hints.

4. Advanced Type Hint Usage Examples

Type hints also support more complex data structures and functions. Here we introduce how to handle functions with multiple return values and how to create custom types.

Specifying Types for Multiple Return Values

When a function returns multiple values, use tuple to specify the return type.
def get_coordinates() -> tuple[float, float]:
    return 35.6895, 139.6917
Doing so makes the return types explicit and improves code readability.

Defining Custom Types

By using NewType, you can create custom types. For example, the following example defines a new type called UserId.
from typing import NewType

UserId = NewType('UserId', int)

def get_user(user_id: UserId) -> str:
    return f"User ID is {user_id}"
Defining custom types clarifies the meaning of the code and makes its intent easier to understand.
年収訴求

5. How to Use Type-Checking Tools

Beyond just using type hints, leveraging static type-checking tools lets you write more robust code. Common tools include mypy and Pylance.

Installation and Usage of mypy

mypy is a type-checking tool that performs error checks based on the type hints in your Python code. First, install it.
pip install mypy
Next, run the type check.
mypy script.py
This will notify you of any type mismatches or issues.

Real-Time Type Checking with Pylance

The VSCode extension Pylance supports real-time type checking. For example, error messages appear in the editor based on type hints, allowing you to fix issues immediately.
def add_numbers(a: int, b: int) -> str:
    return a + b  # An error will appear here, prompting a fix
Because real-time error checking is possible, development speed improves and bugs are

6. Using Type Hints in Real Projects

Type hints are also extremely useful in real projects. Here we’ll present practical usage examples for projects.

The Importance of Type Hints in Team Development

Type hints are especially powerful in team development and open-source projects. The code example below shows a function that fetches data from an API and processes it.
from typing import Dict, Any

def fetch_data() -> Dict[str, Any]:
    return {"status": 200, "data": {"user": "Alice", "age": 30}}
By using type hints to clarify data structures, other developers can more easily understand the code.

Validation Using Type Hints

Type hints also help with data validation. The following function checks that all elements in a list are strings.
from typing import List

def validate_strings(values: List[str]) -> bool:
    return all(isinstance(v, str) for v in values)
Using type hints improves code accuracy and helps prevent bugs.

Convenience of Refactoring with Type Hints

Using type hints is also extremely helpful when refactoring code. Refactoring is the process of improving code without changing its functionality, and when dealing with functions that have many arguments or return values, or complex data structures, type hints serve as a guide to prevent errors. For example, let’s look at the following code.
def process_data(data: dict) -> None:
    # Processing
    pass
This function simply receives a basic dictionary, but if the data structure becomes more complex or the incoming data might be of different types, there’s a risk of making incorrect changes during refactoring. By using type hints to specify clear types as shown below, you can safely refactor even when the code changes.
from typing import Dict, Union

def process_data(data: Dict[str, Union[str, int]]) -> None:
    # Processing
    pass
In this case, because the type Dict[str, Union[str, int]] is specified, even if you refactor, the type checker (e.g., mypy) will detect errors in advance, preventing unexpected bugs.

7. Summary

Python’s type hints are a very powerful tool for improving readability and maintainability, especially in large projects and team development. By leveraging type hints, you can prevent bugs before they occur and raise code quality. Also, by using static type checking tools such as mypy and Pylance, you can detect type errors early in the development process and fix them efficiently. In particular, type hints are useful for the following points.
  • Improved code readability, allowing other developers to understand it quickly.
  • Refactoring can be done safely, so as the project progresses, you can maintain code quality.
  • By leveraging static type checking tools, early detection and fixing of errors is possible.
Going forward, actively incorporating type hints into Python projects will enable you to create more robust and understandable code.
年収訴求