RDRYUSLOG DEV
Back to Blog
Python

Python Type Hints: Syntax, Tools, and Runtime

python type hints: Learn how to use Python type hints effectively: syntax, common patterns, static checking with mypy, and how annotations behave at runtime.

type hintstypingmypystatic analysispython annotations
Illustration of Python code with type annotations and a shield icon representing static type checking.

Python type hints are annotations that describe the expected types of variables, function parameters, and return values. They are not enforced by the interpreter at runtime; instead, they exist for static analysis tools, IDEs, and other developers. Understanding what type hints do—and what they don't—is the first step to using them productively in a codebase.

What Type Hints Actually Do

When you write a function like this:

def greet(name: str) -> str:
    return "Hello, " + name

The : str and -> str are annotations. At runtime, Python stores them in the function's __annotations__ attribute, but it does not check that name is actually a string or that the return value matches. If you call greet(42), the function runs and raises a TypeError only because the + operator fails on an integer and a string—not because of the annotation.

This separation is intentional. Type hints are a developer-facing contract, not a runtime guard. Their real value appears when you run a static type checker like mypy, pyright, or pyre. These tools read the annotations and analyze the flow of types through your code, catching mismatches before the code runs.

Basic Annotation Syntax for Variables and Functions

Variable annotations are straightforward. You can annotate a variable at assignment, though it's rarely necessary because the type checker can often infer it:

count: int = 0
name: str = "Ada"

Function parameters and return types are where annotations matter most. The syntax is parameter: type and -> return_type:

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

For functions that return nothing, use None:

def log(message: str) -> None:
    print(message)

If a parameter can be None, use Optional[T] or T | None (Python 3.10+):

from typing import Optional

def find_user(user_id: int) -> Optional[dict]:
    # returns a dict or None
    ...

Python 3.10 introduced the union operator |, so you can write dict | None instead of Optional[dict]. Both are valid, but the latter is more concise and reads naturally.

Common Built-in Generic Types

The typing module provides generic versions of standard containers. Instead of list, you can use List[T] for a list of a specific type. Similarly, Dict[K, V], Set[T], and Tuple[T, ...] describe their contents.

from typing import List, Dict, Tuple

def process_items(items: List[int]) -> Dict[str, int]:
    result: Dict[str, int] = {}
    for i, item in enumerate(items):
        result[str(i)] = item
    return result

def point() -> Tuple[float, float]:
    return (1.0, 2.0)

In Python 3.9 and later, you can use the built-in generics directly: list[int], dict[str, int], tuple[float, float]. This is cleaner and avoids the extra import. The typing versions remain for backward compatibility.

For a value that can be one of several types, use Union or the | operator:

from typing import Union

def parse_id(value: Union[int, str]) -> int:
    if isinstance(value, str):
        return int(value)
    return value

With Python 3.10+, you can write int | str directly.

Using Type Aliases and NewType for Clarity

Type aliases give a meaningful name to a complex type. This improves readability and reduces repetition:

from typing import List, Tuple

Coordinate = Tuple[float, float]
Polygon = List[Coordinate]

def area(polygon: Polygon) -> float:
    ...

NewType creates a distinct type that is still compatible with the underlying type at runtime, but the type checker treats it as different. This is useful for domain modeling, like user IDs versus order IDs:

from typing import NewType

UserId = NewType('UserId', int)
OrderId = NewType('OrderId', int)

def get_user(user_id: UserId) -> None:
    ...

get_user(UserId(42))  # OK
get_user(42)          # type error: expected UserId

NewType adds no runtime overhead; it's a function that returns its argument unchanged. The type checker enforces the distinction, which helps prevent accidental mixing of IDs from different domains.

Static Type Checking with mypy and Other Tools

The most common way to use type hints is to run a static checker. mypy is the reference implementation. After installing it (pip install mypy), you can run it on a file or directory:

mypy my_module.py

Mypy reads the annotations and reports type errors. For example, given this code:

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

result = add("1", 2)

Mypy will output an error like error: Argument 1 to "add" has incompatible type "str"; expected "int". It does not run the code; it analyzes the abstract syntax tree and type flows.

Other tools include pyright (used by VS Code) and pyre (from Meta). They have slightly different inference rules and configuration options, but the core behavior is the same: they catch type inconsistencies statically.

To get the most out of mypy, you can enable strict mode in pyproject.toml or mypy.ini:

[tool.mypy]
strict = true

Strict mode enables checks like disallowing untyped functions and requiring annotations for all parameters. It's a good starting point for new projects, but it can be noisy for existing codebases. You can gradually enable it by using disallow_untyped_defs and check_untyped_defs separately.

Runtime Behavior: __annotations__ and get_type_hints

Even though type hints aren't enforced at runtime, they are stored and can be inspected. The __annotations__ attribute on functions and classes holds the raw annotations as strings or objects, depending on how they were defined.

def f(x: int) -> str:
    return str(x)

print(f.__annotations__)
# {'x': <class 'int'>, 'return': <class 'str'>}

If you use from __future__ import annotations, all annotations are stored as strings to avoid evaluating them at definition time. This is useful for forward references and to reduce import overhead, but it means you need typing.get_type_hints() to resolve them to actual types:

from __future__ import annotations
from typing import get_type_hints

def f(x: int) -> str:
    return str(x)

print(get_type_hints(f))
# {'x': <class 'int'>, 'return': <class 'str'>}

get_type_hints evaluates the string annotations in the appropriate global and local namespaces. This is how libraries like Pydantic and FastAPI resolve type hints at runtime to generate schemas or perform validation.

Performance and Overhead of Type Hints

Type hints themselves have minimal runtime cost. Annotations are stored as a dictionary, and the overhead of creating that dictionary is negligible for most functions. The real cost can come from two places: evaluating annotations at import time and using runtime type-checking libraries.

Without from __future__ import annotations, Python evaluates each annotation expression when the function is defined. For simple types like int or list[str], this is fast. But if you use a complex expression like list[SomeClass] where SomeClass is defined later, you might get a NameError unless you use forward references (as strings). The from __future__ import annotations directive defers evaluation, which speeds up module import and avoids forward-reference issues.

If you use a library that performs runtime type checking, such as pydantic or typeguard, the overhead is higher because it inspects and validates every value. That's a deliberate tradeoff: you get runtime validation at the cost of performance. For most applications, static checking with mypy is sufficient and has zero runtime overhead.

When Type Hints Add Maintainability Value

Type hints are not always the right choice. For a short script that runs once and is never reused, the extra syntax can feel like noise. The value appears when code is read by others, refactored, or maintained over time. Type hints act as executable documentation that the compiler (or static checker) verifies.

Use type hints when:

  • You are writing a library or module that other developers will import.
  • You are working on a codebase with multiple contributors where interfaces need to be clear.
  • You want to catch bugs early through static analysis.
  • You are using an IDE that benefits from type information for autocompletion and navigation.

Avoid them when the code is exploratory, or when the types are so dynamic that annotations would be misleading. For example, a function that accepts a JSON-like object and returns a transformed version might be better served by a dict annotation and a docstring than by a complex Union of many possible shapes.

The maintainability win comes from the static checker catching mistakes before they reach production. A function signature that says def send_email(recipient: str, subject: str, body: str) -> bool is unambiguous. If someone later passes a list of recipients, mypy flags it immediately. Without type hints, that bug might surface only at runtime, after the email is sent to the wrong address.

Type hints also make refactoring safer. When you change a function's return type, the checker shows every call site that expects the old type. This feedback loop is faster and more reliable than relying on tests alone, especially in large codebases where not every edge case is covered.

python type hints: Practical Usage and Code Examples | RYUSLOG DEV