Python Type Annotations: Concepts, Basic Usage, and Advanced Techniques

Python type annotations, introduced in Python 3.5, allow developers to add optional type hints to variables, function parameters, return values, and more, improving code readability and enabling static analysis tools without affecting runtime behavior.

Basic usage

Variable annotations:

name: str = "Alice"  # name is a string type
age: int = 30  # age is an integer type

Function parameter and return annotations:

from typing import List, Tuple

def greet(name: str) -> str:  # name is a string, returns a string
    return f"Hello, {name}"

def add_numbers(a: int, b: int) -> int:  # both integers, returns an integer
    return a + b

def process_data(data: List[int]) -> Tuple[int, str]:  # list of ints, returns a tuple (int, str)
    total = sum(data)
    return total, "Processed"

Type aliases and custom types

Type alias example:

UserId = NewType('UserId', int)  # creates a new type alias for user IDs

def get_user_info(user_id: UserId):
    ...

Using a custom class as a type hint:

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

def print_user_info(user: User):  # user is expected to be a User instance
    print(f"Name: {user.name}, Age: {user.age}")

More complex type annotations

Union (multiple possible types):

from typing import Union

def calculate(a: Union[int, float], b: Union[int, float]) -> float:
    return a + b

Optional (type or None):

from typing import Optional

def find_user(id: int) -> Optional[User]:
    # Returns a User instance or None if not found
    ...

Any (any type, generally discouraged) and container types such as Dict, List, Tuple, Set can also be annotated.

Class method and attribute annotations

from typing import ClassVar, Type

class Book:
    title: ClassVar[str]  # class variable shared by all instances
    author: str           # instance variable
    def __init__(self, title: str, author: str):
        self.title = title
        self.author = author
    def get_summary(self) -> str:
        return f"{self.title} by {self.author}"
    @classmethod
    def from_dict(cls: Type['Book'], data: dict) -> 'Book':
        return cls(title=data['title'], author=data['author'])

Protocols and abstract base classes

from typing import Protocol

class Flyable(Protocol):
    def fly(self) -> None:
        ...

class Bird:
    def fly(self) -> None:
        print("Flying high!")

class Airplane:
    def fly(self) -> None:
        print("Taking off!")

def make_it_fly(obj: Flyable) -> None:
    obj.fly()

bird = Bird()
airplane = Airplane()
make_it_fly(bird)      # works
make_it_fly(airplane)  # works

Type ignoring and specific parameter exclusion

from typing import Any

def legacy_function(data: Any) -> None:  # no type checking on data
    ...

def complex_function(a, *, kwarg: str = "default") -> None:  # kwarg has a default, type hint does not affect signature
    ...

Third‑party tools and static type checking

Mypy is the most popular static type checker that can be installed in the development environment to catch type errors. Pyright is a VS Code extension providing real‑time type checking and code completion. PyCharm, the JetBrains IDE, includes built‑in support for type annotations.

By using these tools and best practices, type annotations can boost individual productivity and improve team code quality, while avoiding over‑annotation that harms readability.