`typing`

Python’s typing module provides tools for adding type hints to your code. Type hints make your programs more readable, safer to refactor, and help static type checkers catch errors before runtime.

This module is a cornerstone of Python’s gradual typing system, allowing for enhanced code clarity and static analysis.

Here’s a quick example:

Python
      
        
      
    
>>> from typing import TypedDict

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

>>> def print_people(people: list[Person]) -> None:
...     for person in people:
...         print(f"{person['name']} is {person['age']} years old")
...

>>> print_people(
...     [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]
... )
Alice is 30 years old
Bob is 25 years old

Key Features

Supports type hinting for variables, functions, and classes
Allows for custom type creation using TypeVar and NewType
Supports defining reusable type aliases for better code readability
Enables complex type definitions
Supports defining structural subtyping interfaces with protocols

Frequently Used Classes and Functions

Object	Type	Description
`typing.NamedTuple`	Class	Creates tuple-like classes with named fields
`typing.TypedDict`	Class	Creates dictionary-like classes with a fixed set of keys
`typing.Callable`	Class	Represents a callable with a specified signature
`typing.Any`	Class	Represents a type that can be any value
`typing.TypeVar()`	Function	Creates a generic type variable
`typing.NewType()`	Function	Creates a distinct type based on an existing one
`typing.Protocol`	Class	Defines a structural subtyping interface that classes can implement

Examples

Define a class using NamedTuple and a function that takes it as an argument:

Python
      
        
      
    
>>> from typing import NamedTuple

>>> class User(NamedTuple):
...     name: str
...     age: int
...

>>> def greet(user: User) -> str:
...     return f"Hello {user.name}, age {user.age}"
...

>>> greet(User("Alice", 30))
'Hello Alice, age 30'

Define a type alias to simplify complex type annotations:

Python
      
>>> from typing import Dict, Union

>>> UserData = Dict[str, Union[str, int]]

>>> def format_user(user: UserData) -> str:
...     return f"{user['name']} is {user['age']} years old"
...

>>> format_user({"name": "Charlie", "age": 40})
'Charlie is 40 years old'

Create a protocol and implement it in a class:

Python
      
        
      
    
>>> from typing import Protocol

>>> class Greeter(Protocol):
...     def greet(self) -> str:
...         ...
...

>>> class FriendlyGreeter:
...     def greet(self) -> str:
...         return "Hello, friend!"
...

>>> def welcome(greeter: Greeter) -> None:
...     print(greeter.greet())
...

>>> welcome(FriendlyGreeter())
Hello, friend!

Common Use Cases

Specifying expected types for function parameters and return values
Defining complex data structures with precise type information
Enhancing code readability and maintainability
Assisting static type checkers like mypy in identifying potential errors

Real-World Example

Imagine you’re building an order processing system where you want to apply discounts to products. Using the typing module, you can create distinct type aliases, type variables, and callables to make your code safer and more expressive:

Python
      
        
      
    
>>> from typing import NewType, Callable

>>> OrderId = NewType("OrderId", int)

>>> def apply_discount(
...     price: float, discount_fn: Callable[[float], float]
... ) -> float:
...     return discount_fn(price)
...

>>> def process_order(
...     order_id: OrderId,
...     price: float,
...     discount_fn: Callable[[float], float]
... ) -> str:
...     final_price = apply_discount(price, discount_fn)
...     return f"Order No. {order_id}: final price ${final_price:.2f}"
...

>>> ten_percent_off = lambda p: p * 0.9
>>> print(process_order(OrderId(101), 50.0, ten_percent_off))
Order No. 101: final price $45.00

This example shows how to use NewType to create a type for order IDs and Callable to define a flexible function signature for discounts. These type hints make the order processing code more robust and maintainable.

The Ultimate Guide to Python Type Checking

Tutorial

Python Type Checking (Guide)

In this guide, you'll look at Python type checking. Traditionally, types have been handled by the Python interpreter in a flexible but implicit way. Recent versions of Python allow you to specify explicit type hints that can be used by different tools to help you develop your code more efficiently.

intermediate best-practices

For additional information on related topics, take a look at the following resources: