Python Type Hints Practical Guide: From Basics to mypy

# double.py
def double(x: int) -> int:
    return x * 2

# The hint says "x: int", but Python does not check that str violates it
result = double("ab")
print(repr(result))
print(type(result))

$ python3 double.py
'abab'
<class 'str'>

$ mypy double.py
double.py:6: error: Argument 1 to "double" has incompatible type "str"; expected "int"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

name: str = "hello"
age: int = 30
height: float = 175.5
is_active: bool = True

name: str = 123  # mypy: Incompatible types in assignment

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

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

def log_message(message: str) -> None:
    print(f"[LOG] {message}")

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

# Python 3.9+
names: list[str] = ["Alice", "Bob"]
scores: dict[str, int] = {"Alice": 95, "Bob": 87}
coordinates: tuple[float, float] = (35.68, 139.76)
unique_tags: set[str] = {"python", "typing"}

# A tuple of arbitrary length containing ints
numbers: tuple[int, ...] = (1, 2, 3, 4, 5)

from typing import List, Dict, Tuple, Set

names: List[str] = ["Alice", "Bob"]
scores: Dict[str, int] = {"Alice": 95}
coordinates: Tuple[float, float] = (35.68, 139.76)
unique_tags: Set[str] = {"python", "typing"}

# Dict with string keys and list of strings as values
user_tags: dict[str, list[str]] = {
    "alice": ["python", "ml"],
    "bob": ["go", "docker"],
}

# List of tuples
points: list[tuple[int, int]] = [(0, 0), (1, 2), (3, 4)]

from typing import Optional

# Python 3.9 and earlier
def find_user(user_id: int) -> Optional[str]:
    if user_id == 1:
        return "Alice"
    return None

# Python 3.10+
def find_user(user_id: int) -> str | None:
    if user_id == 1:
        return "Alice"
    return None

from typing import Union

# Python 3.9 and earlier
def process(value: Union[int, str]) -> str:
    return str(value)

# Python 3.10+
def process(value: int | str) -> str:
    return str(value)

# All of these are equivalent
from typing import Optional, Union

x: Optional[str]
x: Union[str, None]
x: str | None  # Python 3.10+

from typing import TypedDict

class UserProfile(TypedDict):
    name: str
    age: int
    email: str
    is_active: bool

def get_user() -> UserProfile:
    return {
        "name": "Alice",
        "age": 30,
        "email": "alice@example.com",
        "is_active": True,
    }

user = get_user()
print(user["name"])  # "Alice" — IDE provides auto-completion

from typing import TypedDict, NotRequired  # Python 3.11+

class UserProfile(TypedDict):
    name: str
    age: int
    nickname: NotRequired[str]  # Optional key

from dataclasses import dataclass

@dataclass
class User:
    name: str
    age: int
    email: str
    is_active: bool = True

user = User(name="Alice", age=30, email="alice@example.com")
print(user.name)  # "Alice"
print(user)       # User(name='Alice', age=30, email='alice@example.com', is_active=True)

@dataclass(frozen=True)
class Point:
    x: float
    y: float

p = Point(1.0, 2.0)
p.x = 3.0  # FrozenInstanceError

from typing import TypeVar

T = TypeVar("T")

def first(items: list[T]) -> T:
    return items[0]

# Type inference works
name = first(["Alice", "Bob"])   # str
number = first([1, 2, 3])        # int

from typing import TypeVar

Number = TypeVar("Number", int, float)

def double(x: Number) -> Number:
    return x * 2

double(5)      # OK: int
double(3.14)   # OK: float
double("hi")   # mypy error

# Python 3.12+
def first[T](items: list[T]) -> T:
    return items[0]

from typing import TypeVar, Generic

T = TypeVar("T")

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        if not self._items:
            raise IndexError("Stack is empty")
        return self._items.pop()

    def is_empty(self) -> bool:
        return len(self._items) == 0

# Type is determined at usage
int_stack = Stack[int]()
int_stack.push(1)
int_stack.push(2)
value: int = int_stack.pop()  # 2

str_stack = Stack[str]()
str_stack.push("hello")

# Python 3.12+
class Stack[T]:
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

# variance_demo.py
from typing import Sequence


def sum_as_float(values: list[float]) -> float:
    return sum(values)


def sum_seq_as_float(values: Sequence[float]) -> float:
    return sum(values)


ints: list[int] = [1, 2, 3]

# list[int] is not a list[float] (list is invariant)
sum_as_float(ints)  # mypy error

# Sequence[int] is compatible with Sequence[float] (Sequence is covariant)
sum_seq_as_float(ints)  # OK

$ mypy variance_demo.py
variance_demo.py:16: error: Argument 1 to "sum_as_float" has incompatible type "list[int]"; expected "list[float]"  [arg-type]
variance_demo.py:16: note: "list" is invariant -- see https://mypy.readthedocs.io/en/stable/common_issues.html#variance
variance_demo.py:16: note: Consider using "Sequence" instead, which is covariant
Found 1 error in 1 file (checked 1 source file)

from typing import Protocol

class Drawable(Protocol):
    def draw(self) -> str:
        ...

class Circle:
    def draw(self) -> str:
        return "Drawing a circle"

class Square:
    def draw(self) -> str:
        return "Drawing a square"

def render(shape: Drawable) -> None:
    print(shape.draw())

# Circle and Square don't explicitly inherit Drawable,
# but they pass type checking because they have a draw() method
render(Circle())  # OK
render(Square())  # OK

from abc import ABC, abstractmethod
from typing import Protocol

# ABC: Explicit inheritance required (nominal subtyping)
class DrawableABC(ABC):
    @abstractmethod
    def draw(self) -> str:
        ...

class CircleABC(DrawableABC):  # Must inherit
    def draw(self) -> str:
        return "circle"

# Protocol: No inheritance needed (structural subtyping)
class DrawableProtocol(Protocol):
    def draw(self) -> str:
        ...

class CircleProtocol:  # No inheritance. Just having draw() is enough
    def draw(self) -> str:
        return "circle"

from typing import Protocol

class Logger(Protocol):
    def log(self, message: str) -> None:
        ...

class ConsoleLogger:
    def log(self, message: str) -> None:
        print(f"[CONSOLE] {message}")

class FileLogger:
    def __init__(self, path: str) -> None:
        self.path = path

    def log(self, message: str) -> None:
        with open(self.path, "a") as f:
            f.write(f"{message}\n")

def process_data(data: list[int], logger: Logger) -> int:
    logger.log(f"Processing {len(data)} items")
    result = sum(data)
    logger.log(f"Result: {result}")
    return result

# Both satisfy the Logger Protocol
process_data([1, 2, 3], ConsoleLogger())
process_data([1, 2, 3], FileLogger("/tmp/app.log"))

pip install mypy

# Check a single file
mypy script.py

# Check an entire directory
mypy src/

# Check a package
mypy -p mypackage

# example.py
def greet(name: str) -> str:
    return f"Hello, {name}"

result: int = greet("Alice")  # error: Incompatible types in assignment
greet(123)                     # error: Argument 1 has incompatible type "int"

$ mypy example.py
example.py:4: error: Incompatible types in assignment
    (expression has type "str", variable has type "int")
example.py:5: error: Argument 1 to "greet" has incompatible type "int";
    expected "str"
Found 2 errors in 1 file (checked 1 source file)

# pyproject.toml
[tool.mypy]
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
no_implicit_optional = true
strict_equality = true

# For third-party libraries without type stubs
[[tool.mypy.overrides]]
module = ["some_untyped_library.*"]
ignore_missing_imports = true

mypy --strict src/

# strict_demo.py
from typing import Optional


# 1. Missing return type annotation
def get_display_name(user_id: int):
    if user_id == 1:
        return "Alice"
    return "Guest"


# 2. Incompatible assignment
count: int = "42"


# 3. Optional used without a None check
def to_upper(name: Optional[str]) -> str:
    return name.upper()

$ mypy --strict strict_demo.py
strict_demo.py:6: error: Function is missing a return type annotation  [no-untyped-def]
strict_demo.py:13: error: Incompatible types in assignment (expression has type "str", variable has type "int")  [assignment]
strict_demo.py:18: error: Item "None" of "str | None" has no attribute "upper"  [union-attr]
Found 3 errors in 1 file (checked 1 source file)

# any_vs_object.py
from typing import Any


def use_any(value: Any) -> int:
    # value is Any, so calling a nonexistent method is never flagged by mypy
    return value.nonexistent_method()


def use_object(value: object) -> int:
    # value is object, so calling a nonexistent method IS flagged by mypy
    return value.nonexistent_method()

$ mypy any_vs_object.py
any_vs_object.py:12: error: "object" has no attribute "nonexistent_method"  [attr-defined]
Found 1 error in 1 file (checked 1 source file)

# 1. Missing return statement
def get_name(user_id: int) -> str:
    if user_id == 1:
        return "Alice"
    # error: Missing return statement
    # Fix: return "" or raise ValueError()

# 2. Incompatible types in assignment
data: list[int] = []
data.append("hello")  # error
# Fix: data: list[int | str] = [] or data.append(123)

# 3. Item "None" of "Optional[str]" has no attribute "upper"
def process(name: str | None) -> str:
    return name.upper()  # error: name could be None
    # Fix: Add a None check
    # if name is None:
    #     return ""
    # return name.upper()

# 4. type: ignore for specific lines (last resort)
result = some_untyped_function()  # type: ignore[no-untyped-call]

# Python 3.12+ (PEP 695): type alias statement
type StringList = list[str]
type Coordinate = tuple[float, float]

def normalize(values: StringList) -> StringList:
    return [v.strip() for v in values]

print(normalize([" a ", "b "]))  # ['a', 'b']

# Python 3.13+ (PEP 742): narrowing with TypeIs
from typing import TypeIs, Sequence

def is_str_seq(val: Sequence[object]) -> TypeIs[Sequence[str]]:
    return all(isinstance(x, str) for x in val)

items: Sequence[object] = ["a", "b"]
if is_str_seq(items):
    print("narrowed to Sequence[str]:", items)

$ mypy pep_features_final.py
Success: no issues found in 1 source file

# Python 3.13+ (PEP 705): read-only TypedDict key
from typing import TypedDict, ReadOnly

class Config(TypedDict):
    name: str
    version: ReadOnly[str]

def bump(c: Config) -> None:
    c["version"] = "2.0"  # writing to a ReadOnly key

$ mypy readonly_check.py
readonly_check.py:8: error: ReadOnly TypedDict key "version" TypedDict is mutated  [typeddict-readonly-mutated]
Found 1 error in 1 file (checked 1 source file)