← Python

Type Hints & Static Typing

← Type Hints & Static Typing

Select a question from the sidebar

15 questions in this topic

Question 1 / 15

What are type hints in Python and why should you use them?

Type hints (PEP 484, Python 3.5+) are optional annotations that indicate the expected types of variables, function parameters, and return values. They do not enforce types at runtime -- Python remains dynamically typed. Instead, they serve as documentation and enable static analysis tools like mypy to catch type errors before running the code.

Benefits:

Catch bugs early: Static analyzers find type mismatches before runtime.
Better IDE support: Autocomplete, refactoring, and inline documentation.
Living documentation: Types communicate intent more precisely than comments.
Easier refactoring: Changing a type signature immediately reveals all affected call sites.

Basic syntax:

Parameters: def func(name: str, age: int) -> bool:
Variables: count: int = 0
No effect at runtime: def add(x: int, y: int) -> int: happily accepts strings.

Pseudo Code

1. Annotate function parameters with : type
2. Annotate return type with -> type
3. Annotate variables with : type = value
4. Run mypy to check types statically
5. Types are ignored at runtime (no performance cost)

Code

# Basic type hints
def greet(name: str) -> str:
    return f"Hello, {name}!"

def add(x: int, y: int) -> int:
    return x + y

# Variable annotations
count: int = 0
name: str = "Alice"
prices: list[float] = [9.99, 19.99, 29.99]

# Python 3.9+ built-in generics
def process_items(items: list[str]) -> dict[str, int]:
    return {item: len(item) for item in items}

# Python 3.10+ union with |
def parse_id(value: int | str) -> int:
    return int(value)

# Type hints are NOT enforced at runtime
result = add("hello", "world")  # No runtime error!
print(result)  # "helloworld"
# But mypy would flag: error: Argument 1 has incompatible type "str"; expected "int"

# Checking annotations at runtime (metadata only)
print(greet.__annotations__)
# {'name': <class 'str'>, 'return': <class 'str'>}

# None return type
def log_message(msg: str) -> None:
    print(msg)

# Complex types
def find_user(users: list[dict[str, str]], name: str) -> dict[str, str] | None:
    for user in users:
        if user.get('name') == name:
            return user
    return None

helloworld
{'name': <class 'str'>, 'return': <class 'str'>}

Key Points

•Type hints are optional annotations; they do NOT enforce types at runtime
•Use : for parameter/variable types and -> for return types
•Python 3.9+ supports list[int], dict[str, int] directly (no import needed)
•Python 3.10+ supports X | Y syntax instead of Union[X, Y]
•mypy is the primary static type checker for Python

Gotchas

•Type hints have zero runtime enforcement; passing wrong types still works
•list[int] syntax requires Python 3.9+; use typing.List[int] for older versions
•Annotations are stored in __annotations__ and can slightly increase import time

Type hints annotate expected types for parameters (: type), returns (-> type), and variables. They are not enforced at runtime but enable static analysis (mypy) and better IDE support. Python 3.9+ supports list[int] directly; 3.10+ supports X | Y for unions.

•Annotations only; no runtime enforcement
•Python 3.9+ for list[int]; 3.10+ for int | str

def greet(name: str, times: int = 1) -> str:
    return f"Hello, {name}!" * times

count: int = 0
items: list[str] = ["a", "b"]
result: dict[str, int] = {"a": 1}

# Run: mypy myfile.py

Type hints do not prevent passing wrong types at runtime

Question 2 / 15

How do you use Optional, Union, and the | syntax for type hints?

Union[X, Y] means a value can be of type X or type Y. Optional[X] is shorthand for Union[X, None] -- it means the value can be X or None.

Python 3.10+ introduced the | operator as a cleaner syntax for unions:

Union[int, str] becomes int | str
Optional[int] becomes int | None

When to use each:

Optional[X]: When a value might be None (function return, optional parameter)
Union[X, Y]: When a value can be one of multiple types
X | Y (3.10+): The modern, preferred syntax for both cases

Pseudo Code

Union[X, Y] = value is X or Y
Optional[X] = Union[X, None] = value is X or None
X | Y = Union[X, Y] (Python 3.10+)
X | None = Optional[X] (Python 3.10+)

Code

from typing import Optional, Union

# Optional: value or None
def find_user(user_id: int) -> Optional[dict]:
    """Returns a user dict or None if not found."""
    users = {1: {'name': 'Alice'}}
    return users.get(user_id)

# Union: multiple possible types
def format_id(value: Union[int, str]) -> str:
    """Accepts int or str, returns formatted string."""
    return f"ID-{value}"

# Python 3.10+ syntax (preferred)
def find_user_modern(user_id: int) -> dict | None:
    users = {1: {'name': 'Alice'}}
    return users.get(user_id)

def format_id_modern(value: int | str) -> str:
    return f"ID-{value}"

# Optional parameter with default None
def connect(
    host: str,
    port: int = 5432,
    password: str | None = None,   # Optional parameter
    timeout: int | None = None,
) -> None:
    pass

# Nested Optional
def get_config(key: str) -> dict[str, str | int | None] | None:
    """Returns config dict or None. Values can be str, int, or None."""
    configs = {'db': {'host': 'localhost', 'port': 5432, 'password': None}}
    return configs.get(key)

# Type narrowing with Optional
def process_user(user_id: int) -> str:
    user = find_user(user_id)  # Optional[dict]

    # mypy knows user might be None here
    if user is None:
        return "User not found"

    # After the check, mypy knows user is dict (type narrowed)
    return user['name']

# Common mistake: Optional does NOT mean "optional parameter"
def bad_example(name: Optional[str]) -> None:  # Still required!
    pass

bad_example(None)   # Valid
bad_example()       # TypeError! Parameter is required, not optional

Key Points

•Optional[X] = Union[X, None] = X | None (Python 3.10+)
•Union[X, Y] = X | Y means the value can be either type
•Optional describes the type, not whether the parameter has a default
•After an `if x is None` check, mypy narrows the type automatically
•Prefer X | None over Optional[X] in Python 3.10+ for clarity

Gotchas

•Optional[str] does NOT make a parameter optional (no default value); it means str | None
•Union[int, float] is redundant because int is a subtype of float in the type system
•Using Optional without checking for None before accessing attributes causes mypy errors

Optional[X] = X | None (value or None). Union[X, Y] = X | Y (multiple types). Python 3.10+ supports | syntax directly. Optional describes the type, not whether a parameter has a default value.

•Optional[X] means X or None, not 'optional parameter'
•Python 3.10+ X | Y replaces Union and Optional

from typing import Optional, Union

# Pre-3.10
def find(key: str) -> Optional[int]:    # int or None
    ...
def parse(val: Union[int, str]) -> str:  # int or str
    ...

# Python 3.10+
def find(key: str) -> int | None: ...
def parse(val: int | str) -> str: ...

Optional[str] parameter without default is still required to pass

Question 3 / 15

How do you use TypeVar and generics in Python type hints?

TypeVar creates a type variable that represents "some type" without specifying which one. It enables you to write generic functions and classes that work with any type while preserving type relationships.

For example, a function that returns the first element of a list should return the same type as the list's elements. Without TypeVar, you would lose this relationship.

Generics let you parameterize classes and functions with type variables, similar to Java/C# generics.

Bound TypeVar: T = TypeVar('T', bound=SomeBase) means T must be a subtype of SomeBase. Constrained TypeVar: T = TypeVar('T', int, str) means T must be exactly int or str.

Python 3.12 introduced a new syntax: def first[T](items: list[T]) -> T:

Pseudo Code

1. T = TypeVar('T') creates a generic type variable
2. Use T in function signatures to link input/output types
3. Bound TypeVar restricts to subtypes of a base class
4. Constrained TypeVar restricts to specific types
5. Generic classes inherit from Generic[T]

Code

from typing import TypeVar, Generic, Sequence

# Basic TypeVar: preserves type relationship
T = TypeVar('T')

def first(items: list[T]) -> T:
    """Return first item, preserving the type."""
    return items[0]

result1 = first([1, 2, 3])       # mypy infers: int
result2 = first(['a', 'b', 'c']) # mypy infers: str

# Without TypeVar, you'd lose the type:
def first_bad(items: list) -> object:
    return items[0]  # Returns 'object', not the actual type

# Constrained TypeVar: must be one of the listed types
Number = TypeVar('Number', int, float)

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

double(5)     # OK, returns int
double(3.14)  # OK, returns float
# double('hi')  # mypy error: "str" is not valid

# Bound TypeVar: must be subtype of a base
from typing import Comparable

class Animal:
    def speak(self) -> str:
        return "..."

class Dog(Animal):
    def speak(self) -> str:
        return "Woof"

A = TypeVar('A', bound=Animal)

def make_speak(animal: A) -> A:
    """Accepts any Animal subtype, returns the same subtype."""
    print(animal.speak())
    return animal

dog: Dog = make_speak(Dog())  # Returns Dog, not Animal

# Generic class
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:
        return self._items.pop()

    def peek(self) -> T:
        return self._items[-1]

int_stack: Stack[int] = Stack()
int_stack.push(42)
int_stack.push(99)
value: int = int_stack.pop()  # mypy knows it's int

str_stack: Stack[str] = Stack()
str_stack.push('hello')

# Python 3.12 syntax (no explicit TypeVar needed)
# def first[T](items: list[T]) -> T:
#     return items[0]
#
# class Stack[T]:
#     def __init__(self) -> None:
#         self._items: list[T] = []

Key Points

•TypeVar('T') creates a placeholder type that preserves relationships between input and output
•Bound TypeVar (bound=Base) restricts to subtypes; constrained TypeVar (int, str) restricts to specific types
•Generic[T] makes a class parameterizable: Stack[int], Stack[str]
•Python 3.12 introduces def func[T]() syntax, eliminating explicit TypeVar definitions
•TypeVar name string must match the variable name: T = TypeVar('T')

Gotchas

•TypeVar name string must match the variable name: T = TypeVar('T'), not TypeVar('Type')
•Constrained TypeVar (int, str) means exactly one of those types, not a union
•Without TypeVar, generic functions lose type specificity and return broader types

TypeVar('T') creates a generic type variable that preserves type relationships. Use it in functions to say 'input and output are the same type.' Use Generic[T] for generic classes. bound=Base restricts to subtypes. Python 3.12 adds def func[T]() syntax.

•TypeVar preserves type relationships across parameters and returns
•Generic[T] for parameterizable classes; 3.12+ uses def f[T]() syntax

from typing import TypeVar, Generic

T = TypeVar('T')

def first(items: list[T]) -> T:
    return items[0]  # Returns same type as list elements

class Box(Generic[T]):
    def __init__(self, value: T) -> None:
        self.value = value

box = Box(42)    # Box[int]
box = Box('hi')  # Box[str]

TypeVar('T') name string must match the variable name

Question 4 / 15

What is the Protocol class and how does it enable structural typing?

Protocol (PEP 544, Python 3.8+) enables structural typing (static duck typing) in Python. Instead of requiring classes to inherit from an interface, Protocol checks that a class has the required methods and attributes -- regardless of its inheritance hierarchy.

This aligns with Python's duck typing philosophy: 'If it walks like a duck and quacks like a duck, it is a duck.'

Protocol vs ABC:

ABC (Abstract Base Class): Nominal typing - classes must explicitly inherit.
Protocol: Structural typing - classes just need to have the right methods.

Use Protocol when you want to accept any object that has certain methods, without forcing inheritance.

Pseudo Code

1. Define a Protocol class with required methods/attributes
2. Any class that has those methods/attributes satisfies the Protocol
3. No inheritance required (structural, not nominal)
4. mypy checks conformance statically
5. Use runtime_checkable for isinstance() checks

Code

from typing import Protocol, runtime_checkable

# Define a Protocol
class Drawable(Protocol):
    def draw(self) -> str:
        ...  # Protocol methods use ... (Ellipsis) as body

class HasArea(Protocol):
    def area(self) -> float:
        ...

# These classes satisfy Drawable WITHOUT inheriting from it
class Circle:
    def draw(self) -> str:
        return "Drawing a circle"

    def area(self) -> float:
        return 3.14 * self.radius ** 2

    def __init__(self, radius: float) -> None:
        self.radius = radius

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

    def __init__(self, side: float) -> None:
        self.side = side

# Function accepts anything that matches Drawable Protocol
def render(shape: Drawable) -> None:
    print(shape.draw())

render(Circle(5))   # OK - Circle has draw() method
render(Square(4))   # OK - Square has draw() method
# render(42)         # mypy error: int doesn't have draw()

# Protocol with attributes
class Named(Protocol):
    name: str

class User:
    def __init__(self, name: str) -> None:
        self.name = name

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

greet(User("Alice"))  # OK - User has name attribute

# runtime_checkable enables isinstance() checks
@runtime_checkable
class Closable(Protocol):
    def close(self) -> None:
        ...

import io
f = io.StringIO()
print(isinstance(f, Closable))  # True - StringIO has close()
print(isinstance(42, Closable))  # False - int doesn't have close()

# Combining Protocol with Generic
from typing import TypeVar, Generic

T = TypeVar('T')

class Repository(Protocol[T]):
    def get(self, id: int) -> T | None:
        ...
    def save(self, entity: T) -> None:
        ...
    def delete(self, id: int) -> None:
        ...

class UserRepo:  # Satisfies Repository[User] without inheriting
    def get(self, id: int) -> User | None:
        return None
    def save(self, entity: User) -> None:
        pass
    def delete(self, id: int) -> None:
        pass

def process_repo(repo: Repository[User]) -> None:
    user = repo.get(1)
    if user:
        repo.save(user)

Drawing a circle
Drawing a square
True
False

Key Points

•Protocol enables structural typing: any class with the right methods satisfies it
•No inheritance required; classes are checked by structure, not hierarchy
•Use ... (Ellipsis) for Protocol method bodies
•@runtime_checkable allows isinstance() checks (but only checks method existence, not signatures)
•Protocol[T] supports generic protocols for type-parameterized interfaces

Gotchas

•runtime_checkable isinstance() only checks method names, not parameter types or return types
•Protocol attributes must be annotated: 'name: str', not just 'self.name = name'
•A Protocol cannot be instantiated directly; it's an interface definition only

Protocol enables structural (duck) typing for static analysis. Any class with the required methods satisfies the Protocol without inheriting from it. Use @runtime_checkable for isinstance() checks.

•Structural typing: matching methods, no inheritance required
•@runtime_checkable for isinstance(); only checks method names

from typing import Protocol, runtime_checkable

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

class Circle:  # No inheritance needed
    def draw(self) -> str:
        return "circle"

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

render(Circle())  # OK - has draw() method
print(isinstance(Circle(), Drawable))  # True

circle
True

runtime_checkable only checks method existence, not signatures

Question 5 / 15

How do you use Callable, Literal, and TypedDict type hints?

Callable[[ArgTypes], ReturnType] - Type hint for functions and callable objects. The first argument is a list of parameter types, and the second is the return type.

Literal[values...] (PEP 586, Python 3.8+) - Restricts a value to specific literal values. Useful for function parameters that accept only certain strings or numbers.

TypedDict (PEP 589, Python 3.8+) - A dictionary with specific keys and typed values. Unlike a regular dict, mypy knows exactly which keys exist and what their types are.

Pseudo Code

Callable[[param_types], return_type] - type for functions
Literal['a', 'b'] - only these exact values allowed
TypedDict('Name', key1=type1, key2=type2) - typed dictionary keys

Code

from typing import Callable, Literal, TypedDict

# Callable: type hint for functions
def apply(func: Callable[[int, int], int], a: int, b: int) -> int:
    return func(a, b)

def add(x: int, y: int) -> int:
    return x + y

result = apply(add, 3, 4)  # 7

# Callable with no args
def run_later(callback: Callable[[], None]) -> None:
    callback()

# Callable as variable
handler: Callable[[str], bool] = lambda s: len(s) > 0

# Callable with *args/**kwargs (use ... for untyped)
def decorator(func: Callable[..., str]) -> Callable[..., str]:
    def wrapper(*args, **kwargs) -> str:
        return func(*args, **kwargs).upper()
    return wrapper

# Literal: restrict to specific values
def set_color(color: Literal['red', 'green', 'blue']) -> None:
    print(f"Color set to {color}")

set_color('red')    # OK
# set_color('pink')  # mypy error: "pink" not in Literal

def open_file(mode: Literal['r', 'w', 'a', 'rb', 'wb']) -> None:
    pass

# Literal with overloads for different return types
from typing import overload

@overload
def fetch(raw: Literal[True]) -> bytes: ...
@overload
def fetch(raw: Literal[False]) -> str: ...

def fetch(raw: bool = False) -> bytes | str:
    if raw:
        return b"raw bytes"
    return "decoded string"

# TypedDict: dictionary with known keys and typed values
class UserDict(TypedDict):
    name: str
    age: int
    email: str

def create_user(data: UserDict) -> None:
    print(data['name'])   # mypy knows this is str
    print(data['age'])    # mypy knows this is int
    # print(data['phone'])  # mypy error: key not in TypedDict

user: UserDict = {'name': 'Alice', 'age': 30, 'email': 'alice@example.com'}
create_user(user)

# TypedDict with optional keys
class Config(TypedDict, total=False):  # All keys optional
    host: str
    port: int
    debug: bool

config: Config = {'host': 'localhost'}  # OK, other keys are optional

# Mixing required and optional (Python 3.11+)
class UserProfile(TypedDict):
    name: str          # Required
    email: str         # Required

class UserProfileFull(UserProfile, total=False):
    bio: str           # Optional
    age: int           # Optional

profile: UserProfileFull = {'name': 'Alice', 'email': 'a@b.com', 'bio': 'Hi'}

Color set to red
Alice
30

Key Points

•Callable[[ParamTypes], ReturnType] types functions; use ... for unknown params
•Literal restricts values to specific constants; great for string enums
•TypedDict gives dictionaries specific key names and typed values
•TypedDict(total=False) makes all keys optional
•Combine Literal with @overload for type-dependent return types

Gotchas

•Callable[..., RetType] loses parameter type info; use Protocol for complex signatures
•TypedDict is still a regular dict at runtime; mypy checks are static only
•Literal values must be literal (strings, ints, bools, None, enums), not variables

Callable[[args], return] types functions. Literal['a', 'b'] restricts to specific values. TypedDict types dictionary keys. All are static-only; no runtime enforcement.

•Callable for function types; Literal for exact values; TypedDict for typed dicts
•All are static analysis only, no runtime effect

from typing import Callable, Literal, TypedDict

def apply(func: Callable[[int], str], x: int) -> str:
    return func(x)

def set_mode(mode: Literal['fast', 'slow']) -> None: ...

class User(TypedDict):
    name: str
    age: int

user: User = {'name': 'Alice', 'age': 30}

Literal values must be actual literals, not variables

Question 6 / 15

What is the difference between runtime and static type checking in Python?

Static type checking happens before running the code, using tools like mypy, pyright, or pytype. These tools analyze your source code and type annotations to find type errors without executing anything.

Runtime type checking happens during program execution. Python itself does minimal runtime type checking (e.g., TypeError: unsupported operand type(s)), but libraries like typeguard, pydantic, and beartype can enforce type hints at runtime.

Aspect	Static (mypy)	Runtime
When	Before running	During execution
Performance	No runtime cost	Small overhead
Coverage	All code paths	Only executed paths
Enforcement	Advisory (errors)	Raises exceptions
Dynamic types	Limited support	Full support

Pseudo Code

Static: mypy checks code without running it
Runtime: isinstance(), typeguard, pydantic enforce during execution
Best practice: Use both - mypy for development, pydantic for API boundaries

Code

# Static type checking with mypy
# Run: mypy myfile.py
def add(x: int, y: int) -> int:
    return x + y

add("hello", "world")  # No runtime error!
# But mypy says: error: Argument 1 has incompatible type "str"; expected "int"

# Runtime type checking with isinstance()
def safe_add(x: int, y: int) -> int:
    if not isinstance(x, int) or not isinstance(y, int):
        raise TypeError(f"Expected int, got {type(x)} and {type(y)}")
    return x + y

# Runtime enforcement with typeguard
# pip install typeguard
from typeguard import typechecked

@typechecked
def multiply(x: int, y: int) -> int:
    return x * y

multiply(3, 4)       # OK
# multiply("3", 4)   # TypeError at runtime!

# Runtime validation with pydantic (great for API data)
from pydantic import BaseModel, ValidationError

class User(BaseModel):
    name: str
    age: int
    email: str

# Valid
user = User(name="Alice", age=30, email="alice@example.com")

# Invalid - raises ValidationError at runtime
try:
    user = User(name="Alice", age="not a number", email="alice@example.com")
except ValidationError as e:
    print(e)  # age: value is not a valid integer

# Checking types at runtime using __annotations__
def validate_types(func, *args):
    hints = func.__annotations__
    params = list(hints.keys())
    for i, arg in enumerate(args):
        if i < len(params) and params[i] != 'return':
            expected = hints[params[i]]
            if not isinstance(arg, expected):
                raise TypeError(
                    f"Arg '{params[i]}' expected {expected.__name__}, got {type(arg).__name__}"
                )

# Best practice: use both
# 1. mypy for static checking during development
# 2. pydantic/typeguard at API boundaries (user input)
# 3. No runtime checking for internal functions (trust mypy)

Key Points

•Static checking (mypy) catches errors before running; no runtime cost
•Runtime checking (typeguard, pydantic) enforces types during execution
•Python itself does not enforce type hints at runtime
•Use pydantic for API/user input validation; mypy for internal code
•mypy checks all code paths; runtime only checks executed paths

Gotchas

•Runtime type checking has performance overhead; use it at boundaries, not everywhere
•isinstance() does not work with generic types (list[int]) without runtime_checkable Protocol
•Dynamic features like monkey patching and metaprogramming confuse static type checkers

Static (mypy): Checks types before running, no runtime cost, covers all code paths. Runtime (typeguard, pydantic): Enforces types during execution with small overhead. Best practice: mypy for development, pydantic at API boundaries.

•mypy for static checking; pydantic/typeguard for runtime enforcement
•Use runtime checking at boundaries (API input), static everywhere else

# Static: mypy myfile.py catches this
def add(x: int, y: int) -> int:
    return x + y
add("a", "b")  # mypy error, but runs fine

# Runtime: pydantic enforces at runtime
from pydantic import BaseModel
class User(BaseModel):
    name: str
    age: int
User(name="A", age="bad")  # ValidationError at runtime

Python itself never enforces type hints at runtime

Question 7 / 15

How do you use mypy for static type checking?

mypy is the reference static type checker for Python. It reads your code and type annotations, then reports type errors without running the program.

Setup: pip install mypy, then run mypy your_file.py or mypy your_package/.

Configuration via mypy.ini, setup.cfg, or pyproject.toml:

strict = true enables all strict checks
ignore_missing_imports = true for untyped third-party libraries
disallow_untyped_defs = true requires all functions to have type hints

Common mypy flags:

--strict - Enable all optional checks
--ignore-missing-imports - Skip errors from untyped libraries
--show-error-codes - Show error codes like [arg-type]
--no-implicit-optional - Do not treat None defaults as Optional

Pseudo Code

1. pip install mypy
2. Add type hints to your code
3. Run mypy your_file.py
4. Fix reported errors
5. Add mypy to CI/CD pipeline
6. Configure strictness in pyproject.toml

Code

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

def add(x: int, y: int) -> int:
    return x + y

# These will produce mypy errors:
result: str = add(1, 2)     # error: Incompatible types in assignment
add("hello", "world")      # error: Argument 1 has incompatible type "str"

# Run: mypy example.py
# Output:
# example.py:7: error: Incompatible types in assignment
#     (expression has type "int", variable has type "str")  [assignment]
# example.py:8: error: Argument 1 to "add" has incompatible type "str";
#     expected "int"  [arg-type]

# --- pyproject.toml configuration ---
# [tool.mypy]
# python_version = "3.11"
# strict = true
# warn_return_any = true
# warn_unused_configs = true
# disallow_untyped_defs = true
# 
# [[tool.mypy.overrides]]
# module = "third_party_lib.*"
# ignore_missing_imports = true

# Type: ignore comments for specific lines
import untyped_library  # type: ignore[import]

result = some_dynamic_thing()  # type: ignore[assignment]

# reveal_type for debugging
from typing import reveal_type  # Python 3.11+

x = [1, 2, 3]
reveal_type(x)  # mypy output: builtins.list[builtins.int]

# cast for when you know better than mypy
from typing import cast

value: object = get_something()
name = cast(str, value)  # Tell mypy: trust me, this is a str
print(name.upper())      # mypy is happy now

# Gradual typing: add types incrementally
# Start with key functions, expand over time
# Use --disallow-untyped-defs to find unannotated functions

Key Points

•Run mypy file.py to check types; --strict for maximum strictness
•Configure in pyproject.toml with [tool.mypy] section
•# type: ignore[code] suppresses specific errors on a line
•reveal_type() shows mypy's inferred type (debugging tool)
•cast() tells mypy to trust your type assertion (no runtime effect)

Gotchas

•mypy only checks code that has type annotations (by default); use --disallow-untyped-defs for full coverage
•Third-party libraries without type stubs need ignore_missing_imports or py.typed stubs
•cast() has no runtime effect; if you are wrong, bugs still happen at runtime

pip install mypy then mypy your_file.py. Configure strictness in pyproject.toml. Use # type: ignore to suppress specific errors, reveal_type() for debugging, and cast() when you know better than mypy.

•mypy checks types statically; --strict for full checks
•type: ignore for exceptions; reveal_type() for debugging

# Run: mypy --strict your_file.py

# pyproject.toml
# [tool.mypy]
# strict = true
# ignore_missing_imports = true

# Suppress a specific error
result = dynamic_call()  # type: ignore[assignment]

# Debug mypy inference
reveal_type(my_variable)  # Shows inferred type

mypy only checks annotated code by default; use --disallow-untyped-defs

Question 8 / 15

How do you use overload to define multiple function signatures?

@overload (from typing) lets you define multiple type signatures for a single function, allowing mypy to infer different return types based on the input types.

The overloaded signatures are for the type checker only; the actual implementation is a single function that handles all cases. The @overload decorated functions should have ... as their body.

Use case: When a function's return type depends on its input types. For example, json.loads() returns dict for a JSON object string but list for a JSON array string.

Pseudo Code

1. Define @overload signatures (type checker only, body is ...)
2. Define the actual implementation without @overload
3. Implementation must handle all overload cases
4. mypy uses overload signatures to infer return type based on input

Code

from typing import overload, Literal

# Example 1: Return type depends on input type
@overload
def process(value: int) -> str: ...
@overload
def process(value: str) -> int: ...

def process(value: int | str) -> str | int:
    if isinstance(value, int):
        return str(value)
    return len(value)

result1 = process(42)      # mypy infers: str
result2 = process("hello") # mypy infers: int

# Example 2: Return type depends on Literal argument
@overload
def fetch_data(raw: Literal[True]) -> bytes: ...
@overload
def fetch_data(raw: Literal[False]) -> str: ...
@overload
def fetch_data(raw: bool = False) -> str | bytes: ...

def fetch_data(raw: bool = False) -> str | bytes:
    data = b"raw bytes from server"
    if raw:
        return data
    return data.decode('utf-8')

result_bytes = fetch_data(True)    # mypy infers: bytes
result_str = fetch_data(False)     # mypy infers: str
result_default = fetch_data()       # mypy infers: str | bytes

# Example 3: Different number of arguments
@overload
def create_point(x: float, y: float) -> tuple[float, float]: ...
@overload
def create_point(xy: tuple[float, float]) -> tuple[float, float]: ...

def create_point(x=None, y=None, xy=None):
    if xy is not None:
        return xy
    return (x, y)

# Example 4: Method overloading in a class
class Container:
    @overload
    def get(self, index: int) -> str: ...
    @overload
    def get(self, index: slice) -> list[str]: ...

    def get(self, index: int | slice) -> str | list[str]:
        data = ['a', 'b', 'c', 'd']
        return data[index]

c = Container()
item: str = c.get(0)            # mypy: str
items: list[str] = c.get(slice(0, 2))  # mypy: list[str]

Key Points

•@overload signatures are for the type checker only; the body must be ...
•The implementation function must NOT have @overload and must handle all cases
•mypy uses overloads to narrow return types based on input types
•Combine with Literal for flag-based return type differences
•Overload order matters: more specific signatures should come first

Gotchas

•@overload functions are never called at runtime; only the implementation runs
•The implementation signature must be compatible with all @overload variants
•At least two @overload variants are required before the implementation

@overload defines multiple type signatures for a function. Each overload has ... as body; the actual implementation handles all cases. mypy uses overloads to infer precise return types based on input types.

•Overload signatures have ... body; implementation has no @overload
•Enables precise return type inference based on input types

from typing import overload

@overload
def process(value: int) -> str: ...
@overload
def process(value: str) -> int: ...

def process(value: int | str) -> str | int:
    if isinstance(value, int):
        return str(value)
    return len(value)

process(42)      # mypy infers str
process("hello") # mypy infers int

Only the implementation runs at runtime; @overload bodies are never called

Question 9 / 15

What are ParamSpec and Concatenate for typing decorators?

ParamSpec (PEP 612, Python 3.10+) is a type variable that captures the entire parameter specification (all parameters and their types) of a callable. It solves the problem of typing decorators that need to preserve the wrapped function's signature.

Before ParamSpec, decorators had to use Callable[..., R] which lost all parameter type information.

Concatenate is used with ParamSpec to add extra parameters at the beginning of a function's parameter list (e.g., adding a self or request parameter).

Pseudo Code

1. P = ParamSpec('P') captures all params of a function
2. Use Callable[P, R] to represent a function with those params
3. The wrapper should also be Callable[P, R] to preserve types
4. Concatenate[ExtraArg, P] adds an argument before P's params

Code

from typing import TypeVar, ParamSpec, Callable, Concatenate
from functools import wraps
import time

P = ParamSpec('P')
R = TypeVar('R')

# Basic decorator that preserves types
def timer(func: Callable[P, R]) -> Callable[P, R]:
    @wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        start = time.time()
        result = func(*args, **kwargs)
        print(f"{func.__name__} took {time.time() - start:.3f}s")
        return result
    return wrapper

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

# mypy knows: greet(name: str, greeting: str = "Hello") -> str
result: str = greet("Alice")  # Fully typed!

# Logging decorator preserving types
def log_calls(func: Callable[P, R]) -> Callable[P, R]:
    @wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"Calling {func.__name__}")
        result = func(*args, **kwargs)
        print(f"Result: {result}")
        return result
    return wrapper

# Concatenate: adding extra parameters
def with_user(func: Callable[Concatenate[str, P], R]) -> Callable[P, R]:
    """Decorator that injects a username as the first argument."""
    @wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        username = "current_user"  # Get from auth context
        return func(username, *args, **kwargs)
    return wrapper

@with_user
def delete_item(username: str, item_id: int) -> bool:
    print(f"{username} deleting item {item_id}")
    return True

# mypy knows: delete_item(item_id: int) -> bool
# (username is injected by the decorator)
delete_item(42)  # Correct - username is auto-injected

# Retry decorator with ParamSpec
def retry(max_retries: int = 3) -> Callable[[Callable[P, R]], Callable[P, R]]:
    def decorator(func: Callable[P, R]) -> Callable[P, R]:
        @wraps(func)
        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except Exception:
                    if attempt == max_retries - 1:
                        raise
            raise RuntimeError("Unreachable")
        return wrapper
    return decorator

@retry(max_retries=3)
def fetch_data(url: str, timeout: int = 10) -> dict:
    return {}  # ... fetch ...

# mypy knows: fetch_data(url: str, timeout: int = 10) -> dict
fetch_data("https://api.example.com")

# Expected Output: (timing values are approximate)
# greet took 0.000s
# current_user deleting item 42

Key Points

•ParamSpec captures the full parameter signature of a callable
•P.args and P.kwargs are used in wrapper function signatures
•Concatenate[ExtraType, P] adds parameters before P's params
•Solves the problem of decorators losing type info (Callable[..., R] loses params)
•Python 3.12 uses def decorator[**P, R](...) syntax for cleaner declarations

Gotchas

•ParamSpec requires Python 3.10+; use typing_extensions for 3.8-3.9
•P.args and P.kwargs must be used together; you cannot use just one
•Concatenate only adds params at the beginning, not the end

ParamSpec('P') captures a function's full parameter spec for typing decorators. Use Callable[P, R] for both the wrapped and wrapper function. Concatenate[ExtraArg, P] adds parameters before the original ones.

•ParamSpec preserves full function signatures through decorators
•Use P.args and P.kwargs in the wrapper

from typing import ParamSpec, TypeVar, Callable
from functools import wraps

P = ParamSpec('P')
R = TypeVar('R')

def logged(func: Callable[P, R]) -> Callable[P, R]:
    @wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"Calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

Requires Python 3.10+ or typing_extensions

Question 10 / 15

What is TypeGuard and how does it help with type narrowing?

TypeGuard (PEP 647, Python 3.10+) is a special return type for functions that perform type checks. When a function returns TypeGuard[X], mypy narrows the type of the checked variable to X in the true branch.

This is useful when isinstance() is not sufficient -- for example, when checking if a list contains only strings, or when validating complex data structures.

Python 3.13 introduces TypeIs (PEP 742) which is a stricter version that also narrows in the false branch.

Pseudo Code

1. Define a function returning TypeGuard[TargetType]
2. Implement the type check logic inside
3. When the function returns True, mypy narrows the variable type
4. Use in if statements for type narrowing

Code

from typing import TypeGuard, Any

# Basic TypeGuard
def is_string_list(value: list[Any]) -> TypeGuard[list[str]]:
    """Check if all elements are strings."""
    return all(isinstance(item, str) for item in value)

def process(data: list[Any]) -> None:
    if is_string_list(data):
        # mypy knows data is list[str] here
        for item in data:
            print(item.upper())  # No error: item is str
    else:
        # mypy still thinks data is list[Any]
        print("Not all strings")

# TypeGuard for dict validation
def is_user_dict(value: dict[str, Any]) -> TypeGuard[dict[str, str | int]]:
    required_keys = {'name', 'age', 'email'}
    if not required_keys.issubset(value.keys()):
        return False
    return (
        isinstance(value.get('name'), str) and
        isinstance(value.get('age'), int) and
        isinstance(value.get('email'), str)
    )

def process_user(data: dict[str, Any]) -> None:
    if is_user_dict(data):
        # mypy narrows: data is dict[str, str | int]
        print(f"User: {data['name']}")

# TypeGuard with None filtering
def is_not_none(value: str | None) -> TypeGuard[str]:
    return value is not None

names: list[str | None] = ["Alice", None, "Bob", None, "Charlie"]

# Filter out None values with type safety
valid_names: list[str] = [name for name in names if is_not_none(name)]
# mypy knows valid_names is list[str]

# Without TypeGuard, you need explicit cast or type: ignore
valid_names_manual = [name for name in names if name is not None]
# mypy may still infer list[str | None] depending on version

# TypeGuard in a class
class Validator:
    @staticmethod
    def is_positive_int(value: Any) -> TypeGuard[int]:
        return isinstance(value, int) and value > 0

def set_quantity(value: Any) -> None:
    if Validator.is_positive_int(value):
        # mypy knows value is int
        print(f"Quantity: {value * 2}")

# Python 3.13: TypeIs (stricter, narrows both branches)
# from typing import TypeIs
# def is_str(value: str | int) -> TypeIs[str]:
#     return isinstance(value, str)
# # In true branch: str. In false branch: int.

Key Points

•TypeGuard[X] narrows the type to X when the function returns True
•Useful when isinstance() alone does not express the check (e.g., list[str] vs list[Any])
•Only narrows in the True branch; the False branch retains the original type
•Python 3.13 TypeIs narrows both branches (True -> X, False -> everything except X)
•The function must accept the broader type and return bool

Gotchas

•TypeGuard only narrows the first positional argument, not other variables
•If your TypeGuard function has a bug, mypy trusts it; runtime behavior may differ
•TypeGuard does not narrow in the False branch (use TypeIs for that in 3.13+)

TypeGuard[X] is a return type for type-checking functions. When the function returns True, mypy narrows the variable to type X. Useful for complex checks like 'is this a list of strings' that isinstance cannot express.

•TypeGuard narrows type to X when function returns True
•Only narrows in the True branch (TypeIs does both in 3.13+)

from typing import TypeGuard, Any

def is_str_list(val: list[Any]) -> TypeGuard[list[str]]:
    return all(isinstance(v, str) for v in val)

def process(data: list[Any]) -> None:
    if is_str_list(data):
        print(data[0].upper())  # mypy knows: list[str]

TypeGuard only narrows the first argument, not other variables

Question 11 / 15

How do you use Annotated for metadata-rich type hints?

Annotated (PEP 593, Python 3.9+) lets you attach metadata to type hints without affecting the type itself. The first argument is the actual type, and subsequent arguments are metadata that tools and frameworks can use.

Annotated[int, MinValue(0), MaxValue(100)] means 'an int with these validation constraints.'

Key users:

FastAPI uses Annotated for dependency injection and validation: Annotated[str, Query(max_length=50)]
Pydantic uses it for field validation: Annotated[int, Field(gt=0)]
Custom frameworks can define their own metadata types.

Pseudo Code

Annotated[Type, metadata1, metadata2, ...]
- First arg: the actual type
- Remaining args: metadata (ignored by mypy, used by frameworks)
- Frameworks read metadata at runtime via typing.get_type_hints(include_extras=True)

Code

from typing import Annotated, get_type_hints

# Basic Annotated usage
def process_age(age: Annotated[int, "must be positive"]) -> str:
    return f"Age: {age}"

# mypy sees: age: int (metadata is ignored by type checkers)

# Custom metadata classes
class MinValue:
    def __init__(self, value: int):
        self.value = value

class MaxValue:
    def __init__(self, value: int):
        self.value = value

class Description:
    def __init__(self, text: str):
        self.text = text

# Type aliases with Annotated
PositiveInt = Annotated[int, MinValue(0)]
Percentage = Annotated[float, MinValue(0), MaxValue(100)]
UserName = Annotated[str, MinValue(1), MaxValue(50), Description("User's display name")]

def create_user(name: UserName, age: PositiveInt) -> dict:
    return {'name': name, 'age': age}

# Access metadata at runtime
hints = get_type_hints(create_user, include_extras=True)
print(hints)  # {'name': Annotated[str, MinValue(1), MaxValue(50), ...], 'age': ...}

# Extract metadata from Annotated
from typing import get_args, get_origin

def get_metadata(hint):
    if get_origin(hint) is Annotated:
        args = get_args(hint)
        return args[0], args[1:]  # (type, metadata_tuple)
    return hint, ()

base_type, metadata = get_metadata(hints['name'])
print(base_type)   # <class 'str'>
print(metadata)    # (MinValue(1), MaxValue(50), Description("User's display name"))

# Runtime validation using Annotated metadata
def validate(func, **kwargs):
    hints = get_type_hints(func, include_extras=True)
    for param, hint in hints.items():
        if param == 'return':
            continue
        base, meta = get_metadata(hint)
        value = kwargs.get(param)
        for m in meta:
            if isinstance(m, MinValue) and isinstance(value, (int, float)):
                if value < m.value:
                    raise ValueError(f"{param} must be >= {m.value}")
            if isinstance(m, MaxValue) and isinstance(value, (int, float)):
                if value > m.value:
                    raise ValueError(f"{param} must be <= {m.value}")

# Pydantic v2 with Annotated
from pydantic import BaseModel, Field

class User(BaseModel):
    name: Annotated[str, Field(min_length=1, max_length=50)]
    age: Annotated[int, Field(gt=0, lt=150)]
    email: Annotated[str, Field(pattern=r'^[\w.-]+@[\w.-]+\.\w+$')]

# Expected Output: (object addresses will vary)
# {'name': typing.Annotated[str, <__main__.MinValue object at 0x...>, <__main__.MaxValue object at 0x...>, <__main__.Description object at 0x...>], 'age': typing.Annotated[int, <__main__.MinValue object at 0x...>], 'return': <class 'dict'>}
# <class 'str'>
# (<__main__.MinValue object at 0x...>, <__main__.MaxValue object at 0x...>, <__main__.Description object at 0x...>)

Key Points

•Annotated[Type, metadata] adds metadata without changing the type for checkers
•First argument is the type; remaining are metadata for frameworks
•Type aliases (PositiveInt = Annotated[int, ...]) create reusable annotated types
•get_type_hints(include_extras=True) retrieves Annotated metadata at runtime
•FastAPI and Pydantic heavily use Annotated for validation and dependency injection

Gotchas

•mypy completely ignores metadata; only the first argument (the type) matters for type checking
•get_type_hints() without include_extras=True strips Annotated metadata
•Annotated requires Python 3.9+; use typing_extensions for 3.7-3.8

Annotated[Type, metadata] attaches metadata to types. Type checkers see only the type; frameworks (FastAPI, Pydantic) use the metadata for validation, docs, etc. Use get_type_hints(include_extras=True) to read metadata at runtime.

•Type checkers ignore metadata; frameworks use it for validation
•Create reusable type aliases with Annotated

from typing import Annotated
from pydantic import BaseModel, Field

PositiveInt = Annotated[int, Field(gt=0)]

class User(BaseModel):
    name: Annotated[str, Field(min_length=1, max_length=50)]
    age: PositiveInt

get_type_hints() strips metadata without include_extras=True

Question 12 / 15

How do you handle forward references and circular imports in type hints?

Forward references occur when a type hint refers to a class that has not been defined yet (e.g., a class method returning its own type, or two classes referencing each other).

Solutions:

String literals ("ClassName"): Quote the type name as a string. Python evaluates it later.
from __future__ import annotations (PEP 563): Makes ALL annotations strings by default, evaluated lazily. This is the recommended approach.
TYPE_CHECKING constant: Import types only for type checking (not at runtime) to break circular imports.

from __future__ import annotations was planned to become the default in Python 3.10 but was postponed.

Pseudo Code

1. String forward reference: def method(self) -> 'MyClass':
2. from __future__ import annotations: all annotations become strings
3. TYPE_CHECKING: import only for type checkers, not runtime
4. Combine TYPE_CHECKING with string refs for circular imports

Code

# Problem: Class not yet defined
class TreeNode:
    def __init__(self, value: int, children: list['TreeNode'] | None = None):
        self.value = value
        self.children = children or []

    # Forward reference to own class
    def add_child(self, child: 'TreeNode') -> None:
        self.children.append(child)

    def clone(self) -> 'TreeNode':
        return TreeNode(self.value, [c.clone() for c in self.children])

# Solution 1: from __future__ import annotations (recommended)
from __future__ import annotations

class LinkedList:
    def __init__(self, value: int, next_node: LinkedList | None = None):
        self.value = value
        self.next_node = next_node  # No quotes needed!

    def append(self, value: int) -> LinkedList:
        node = self
        while node.next_node:
            node = node.next_node
        node.next_node = LinkedList(value)
        return self

# Solution 2: TYPE_CHECKING for circular imports
# file: models/user.py
from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    # This import only happens during type checking, not at runtime
    from models.order import Order

class User:
    def __init__(self, name: str) -> None:
        self.name = name
        self.orders: list[Order] = []  # Works because of TYPE_CHECKING

    def get_orders(self) -> list[Order]:
        return self.orders

# file: models/order.py
from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from models.user import User

class Order:
    def __init__(self, total: float, user: User) -> None:
        self.total = total
        self.user = user

# Solution 3: Resolve at runtime if needed
from typing import get_type_hints

# get_type_hints() resolves string annotations at runtime
# But it needs the class to be importable
hints = get_type_hints(User)
print(hints)  # {'name': <class 'str'>, 'return': <class 'NoneType'>}

# Common pattern: Self type (Python 3.11+)
from typing import Self

class Builder:
    def set_name(self, name: str) -> Self:
        self.name = name
        return self

    def set_age(self, age: int) -> Self:
        self.age = age
        return self

Key Points

•Use string literals ('ClassName') for forward references in type hints
•from __future__ import annotations makes all annotations strings (lazy evaluation)
•TYPE_CHECKING is True only during static analysis; imports inside are not executed at runtime
•Combine TYPE_CHECKING with from __future__ import annotations for circular imports
•Python 3.11+ Self type replaces -> 'ClassName' for methods returning self

Gotchas

•from __future__ import annotations makes all annotations strings; this breaks isinstance() on annotations
•get_type_hints() may fail if forward-referenced types are not importable at call time
•TYPE_CHECKING imports are not available at runtime; do not use them in function bodies

For forward references, use string literals ('ClassName') or from __future__ import annotations (makes all annotations strings). For circular imports, combine TYPE_CHECKING with string annotations so imports only happen during static analysis.

•from __future__ import annotations for lazy evaluation
•TYPE_CHECKING + string refs for circular imports

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from models.order import Order  # Only for type checkers

class User:
    orders: list[Order] = []  # Works at type-check time

class Node:
    children: list[Node]  # No quotes needed with __future__

TYPE_CHECKING imports are not available at runtime

Question 13 / 15

How do you type hint dictionaries with specific structures?

Python offers several ways to type dictionaries with known structures:

dict[KeyType, ValueType]: For homogeneous dicts where all keys are the same type and all values are the same type.
TypedDict: For dicts with specific key names and per-key value types.
Mapping[K, V]: Read-only dict interface (use for parameters you do not modify).
Pydantic BaseModel: For validated, structured data with automatic parsing.

TypedDict is the most useful for APIs and configuration, where you know the exact keys and their types.

Pseudo Code

dict[str, int] - all values are int
TypedDict - specific keys with specific value types
Mapping - read-only dict (for function parameters)
Required/NotRequired - mix required and optional keys

Code

from typing import TypedDict, Required, NotRequired, Mapping

# Basic dict typing
def word_count(text: str) -> dict[str, int]:
    counts: dict[str, int] = {}
    for word in text.split():
        counts[word] = counts.get(word, 0) + 1
    return counts

# TypedDict: specific key-value types
class UserDict(TypedDict):
    name: str
    age: int
    email: str

def format_user(user: UserDict) -> str:
    return f"{user['name']} ({user['age']}) - {user['email']}"

# mypy checks key names and value types
user: UserDict = {'name': 'Alice', 'age': 30, 'email': 'a@b.com'}
# user: UserDict = {'name': 'Alice'}  # mypy error: missing keys

# Optional keys (Python 3.11+)
class Config(TypedDict):
    host: str                    # Required
    port: int                    # Required
    debug: NotRequired[bool]     # Optional
    timeout: NotRequired[int]    # Optional

config: Config = {'host': 'localhost', 'port': 5432}  # OK
config2: Config = {'host': 'localhost', 'port': 5432, 'debug': True}  # Also OK

# Pre-3.11: total=False makes all keys optional
class OptionalConfig(TypedDict, total=False):
    host: str
    port: int
    debug: bool

# Inheritance for mixing required and optional (pre-3.11)
class RequiredFields(TypedDict):
    name: str
    email: str

class UserProfile(RequiredFields, total=False):
    bio: str
    age: int
    avatar_url: str

# Nested TypedDict
class Address(TypedDict):
    street: str
    city: str
    zip_code: str

class Company(TypedDict):
    name: str
    address: Address  # Nested TypedDict
    employees: list[UserDict]

company: Company = {
    'name': 'Acme',
    'address': {'street': '123 Main', 'city': 'NYC', 'zip_code': '10001'},
    'employees': [{'name': 'Alice', 'age': 30, 'email': 'a@b.com'}]
}

# Mapping for read-only dict parameters
def process_config(config: Mapping[str, str | int]) -> None:
    # Cannot modify: config['key'] = 'value'  # mypy error
    value = config.get('host')
    print(value)

Key Points

•dict[K, V] for homogeneous dicts; TypedDict for specific key-value structures
•NotRequired[] (3.11+) for optional keys; total=False for all-optional TypedDicts
•Inherit TypedDicts to mix required and optional keys (pre-3.11)
•Mapping[K, V] for read-only dict parameters (immutable interface)
•TypedDicts can be nested for complex structures

Gotchas

•TypedDict is still a regular dict at runtime; the type constraints are static only
•You cannot use TypedDict with ** unpacking in type-safe way easily
•dict[str, Any] should be used sparingly; prefer TypedDict for known structures

Use dict[str, int] for uniform dicts. Use TypedDict for dicts with specific keys and typed values. NotRequired[] (3.11+) for optional keys. Mapping for read-only dict parameters.

•TypedDict for specific keys; NotRequired for optional keys
•Static only; runtime behavior is a normal dict

from typing import TypedDict, NotRequired

class User(TypedDict):
    name: str             # Required
    email: str            # Required
    bio: NotRequired[str] # Optional

user: User = {'name': 'Alice', 'email': 'a@b.com'}  # OK
print(user['name'])  # mypy knows this is str

Alice

TypedDict constraints are static-only; runtime is a normal dict

Question 14 / 15

What is type narrowing and how does Python's type system support it?

Type narrowing is when the type checker reduces (narrows) a variable's type based on control flow. For example, after if isinstance(x, str):, mypy knows x is a str in that branch.

Mypy supports several narrowing patterns:

isinstance() - Most common; narrows to the checked type
is None / is not None - Narrows Optional types
assert - Narrows based on assertions
type() check - Less common than isinstance
Assignment - Reassigning narrows the type
TypeGuard - Custom narrowing functions
assert_never() - Exhaustiveness checking in match/if-elif chains

Pseudo Code

1. isinstance(x, Type) -> narrows x to Type
2. x is not None -> narrows Optional[X] to X
3. assert isinstance(x, Type) -> narrows below the assert
4. TypeGuard functions -> custom narrowing
5. assert_never(x) -> proves all cases handled (exhaustive check)

Code

from typing import assert_never

# isinstance narrowing
def process(value: int | str | list[int]) -> str:
    if isinstance(value, int):
        # mypy knows: value is int
        return str(value * 2)
    elif isinstance(value, str):
        # mypy knows: value is str
        return value.upper()
    else:
        # mypy knows: value is list[int]
        return str(sum(value))

# None narrowing
def greet(name: str | None) -> str:
    if name is None:
        return "Hello, stranger!"
    # mypy knows: name is str (narrowed from str | None)
    return f"Hello, {name.upper()}!"

# Early return narrowing
def get_length(value: str | None) -> int:
    if value is None:
        return 0
    # After early return, mypy knows value is str
    return len(value)

# Assert narrowing
def must_be_string(value: str | int) -> str:
    assert isinstance(value, str), "Expected a string"
    # mypy knows: value is str
    return value.upper()

# Truthiness narrowing
def process_optional(items: list[str] | None) -> int:
    if items:  # Truthy check narrows out None and empty list
        # mypy knows: items is list[str] (non-empty)
        return len(items)
    return 0

# Exhaustiveness checking with assert_never
from typing import Literal

def handle_status(status: Literal['active', 'inactive', 'pending']) -> str:
    if status == 'active':
        return 'User is active'
    elif status == 'inactive':
        return 'User is inactive'
    elif status == 'pending':
        return 'User is pending'
    else:
        assert_never(status)  # mypy error if any case is missing

# Pattern matching narrowing (Python 3.10+)
def describe(value: int | str | list[int]) -> str:
    match value:
        case int():
            return f"Integer: {value}"  # value is int
        case str():
            return f"String: {value}"   # value is str
        case list():
            return f"List of {len(value)} items"  # value is list[int]

# Narrowing in comprehensions/loops
def filter_strings(items: list[int | str]) -> list[str]:
    result: list[str] = []
    for item in items:
        if isinstance(item, str):
            result.append(item.upper())  # item is str
    return result

Key Points

•isinstance() is the primary narrowing mechanism
•is None / is not None narrows Optional types
•Early returns narrow types in the remaining code
•assert_never() provides exhaustiveness checking in if/elif chains
•Pattern matching (match/case) also narrows types

Gotchas

•Truthiness check (if items) narrows out None AND empty collections, which may not be desired
•isinstance() with tuple of types (isinstance(x, (int, str))) narrows to Union
•assert statements can be disabled with python -O; do not rely on them for production checks

Type narrowing reduces a variable's type based on control flow. isinstance() narrows to the checked type, is not None narrows Optional. assert_never() ensures exhaustive handling. Pattern matching also narrows types.

•isinstance and is None are the primary narrowing mechanisms
•assert_never ensures all cases are handled

def process(value: int | str | None) -> str:
    if value is None:
        return "none"           # narrowed: None
    if isinstance(value, int):
        return str(value * 2)   # narrowed: int
    return value.upper()        # narrowed: str

# Exhaustiveness
from typing import assert_never
def handle(x: Literal['a', 'b']) -> str:
    if x == 'a': return 'A'
    elif x == 'b': return 'B'
    else: assert_never(x)  # mypy error if case missed

Truthiness narrows out both None and empty collections

Question 15 / 15

What are the new type hint features in Python 3.12 (PEP 695)?

Python 3.12 (PEP 695) introduced a new, cleaner syntax for defining type parameters:

Type parameter syntax for functions: def func[T](x: T) -> T: replaces T = TypeVar('T').
Type parameter syntax for classes: class Stack[T]: replaces class Stack(Generic[T]).
type statement for type aliases: type Vector = list[float] replaces Vector: TypeAlias = list[float].
Bound and constrained type params: def func[T: int](x: T) or def func[T: (int, str)](x: T).
ParamSpec syntax: def deco[**P, R](func: Callable[P, R]).
TypeVarTuple syntax: def func[*Ts](*args: *Ts) for variadic generics.

These changes make generics much more readable and reduce boilerplate.

Pseudo Code

Old: T = TypeVar('T'); def func(x: T) -> T:
New: def func[T](x: T) -> T:

Old: class Stack(Generic[T]):
New: class Stack[T]:

Old: Vector: TypeAlias = list[float]
New: type Vector = list[float]

Code

# Old way (pre-3.12)
from typing import TypeVar, Generic, TypeAlias, ParamSpec, Callable

T_old = TypeVar('T_old')
def first_old(items: list[T_old]) -> T_old:
    return items[0]

class Stack_old(Generic[T_old]):
    def __init__(self) -> None:
        self._items: list[T_old] = []
    def push(self, item: T_old) -> None:
        self._items.append(item)

Vector_old: TypeAlias = list[float]

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

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()

type Vector = list[float]
type Matrix = list[Vector]

# Bound type parameters
def max_item[T: (int, float)](items: list[T]) -> T:
    return max(items)

# Bound to a class
class Animal:
    name: str

def get_name[T: Animal](animal: T) -> str:
    return animal.name

# Multiple type parameters
def zip_with[T, U, V](func: Callable[[T, U], V], xs: list[T], ys: list[U]) -> list[V]:
    return [func(x, y) for x, y in zip(xs, ys)]

# ParamSpec with new syntax
def logged[**P, R](func: Callable[P, R]) -> Callable[P, R]:
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"Calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

# TypeVarTuple (variadic generics) with new syntax
def first_of[*Ts](args: tuple[*Ts]) -> tuple[*Ts]:
    return args

# Generic class with multiple params
class Pair[T, U]:
    def __init__(self, first: T, second: U) -> None:
        self.first = first
        self.second = second

    def swap(self) -> 'Pair[U, T]':
        return Pair(self.second, self.first)

pair = Pair(1, "hello")  # Pair[int, str]
swapped = pair.swap()     # Pair[str, int]

# type statement with complex aliases
type JSONValue = str | int | float | bool | None | list['JSONValue'] | dict[str, 'JSONValue']
type Handler[T] = Callable[[T], None]

Key Points

•def func[T]() replaces TypeVar + def func(x: T); much cleaner
•class MyClass[T] replaces Generic[T] inheritance
•type X = ... replaces TypeAlias annotations
•[T: Base] for bound, [T: (int, str)] for constrained type vars
•[**P, R] for ParamSpec, [*Ts] for TypeVarTuple

Gotchas

•New syntax requires Python 3.12+; use TypeVar/Generic for older versions
•type statement creates lazy aliases (evaluated on demand), which changes behavior for forward refs
•Cannot mix old and new syntax in the same class/function definition

Python 3.12 adds def func[T]() syntax (replaces TypeVar), class MyClass[T] (replaces Generic), and type X = ... (replaces TypeAlias). Much cleaner and less boilerplate.

•[T] on functions/classes replaces TypeVar and Generic
•type statement replaces TypeAlias

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

class Stack[T]:
    def push(self, item: T) -> None: ...
    def pop(self) -> T: ...

type Vector = list[float]
type Handler[T] = Callable[[T], None]

Requires Python 3.12+; not backward compatible

Built by onllm.dev

Home GitHub Support awesomePrep