Python Type Hints: runtime vs typing-only Annotations

Most Python Type Hints Do Absolutely Nothing at Runtime

You add type hints to your Python code, run it, and… nothing happens. No validation. No errors. The annotations just sit there. But some annotations—like dataclasses, Pydantic models, or typing.NewType—actually change how your code behaves. The difference isn’t obvious until you hit a production bug that could’ve been caught if you knew which hints matter when.

The core distinction: typing-only annotations exist purely for static analysis tools like mypy or pyright. Runtime annotations are inspected by libraries or decorators during execution to enforce validation, generate code, or alter behavior. Most developers treat all type hints the same way, then wonder why Pydantic validators catch bugs that mypy missed—or vice versa.

This post runs the same code with different annotation styles, shows what actually happens at runtime, and benchmarks the cost of runtime validation. You’ll see real tracebacks, performance numbers from Python 3.11 and 3.12, and the edge cases where mixing both approaches breaks your code.

What “Runtime” Actually Means Here

When Python executes def foo(x: int) -> str:, it stores those annotations in foo.__annotations__ as a dictionary: {'x': <class 'int'>, 'return': <class 'str'>}. The interpreter does zero validation. You can call foo("not an int") and it runs fine.

def greet(name: str, age: int) -> str:
    return f"{name} is {age} years old"

print(greet("Alice", 30))        # Alice is 30 years old
print(greet(123, "thirty"))      # 123 is thirty years old  ← no error!
print(greet.__annotations__)     # {'name': <class 'str'>, 'age': <class 'int'>, 'return': <class 'str'>}

The annotations are metadata. Libraries like Pydantic, FastAPI, or dataclasses read __annotations__ at class definition time or function decoration time and inject validation logic. That’s runtime usage. Static checkers like mypy never execute your code—they parse the AST and infer types.

So “runtime annotations” means: code that runs during import or execution inspects __annotations__ and does something with it. “Typing-only” means: only your editor, CI linter, or type checker sees them.

Typing-Only Annotations: The Static Analysis World

These exist for mypy, pyright, Pylance, and similar tools. They’re erased at runtime (conceptually—they’re still in __annotations__, but nothing reads them unless you explicitly do).

Common typing-only constructs:

• List[int], Dict[str, Any], Tuple[str, ...] from typing
• Optional[T], Union[A, B]
• Literal["GET", "POST"]
• TypeVar, Generic, Protocol
• Annotated (the annotation itself is typing-only; the metadata inside might be runtime—more on that later)

from typing import List, Optional

def process_items(items: List[int], default: Optional[int] = None) -> int:
    if not items:
        return default if default is not None else 0
    return sum(items)

print(process_items([1, 2, 3]))           # 6
print(process_items(["a", "b"], "x"))    # TypeError: unsupported operand type(s) for +: 'int' and 'str'

The TypeError happens because sum() tries to add strings, not because Python validated the List[int] annotation. Static checkers catch this before you run it:

$ mypy test.py
test.py:8: error: List item 0 has incompatible type "str"; expected "int"

But at runtime, Python doesn’t care. You could pass a generator, a set, a string—anything iterable. The annotation is a promise to the reader and tooling, not a contract enforced by the interpreter.

The Cost: Zero (Almost)

Storing annotations has negligible overhead. Python 3.11 introduced PEP 649 (deferred evaluation), but even before that, annotations are just dict entries. No validation loop, no isinstance checks.

import timeit

def foo_typed(x: int, y: str) -> bool:
    return len(y) > x

def foo_untyped(x, y):
    return len(y) > x

print(timeit.timeit(lambda: foo_typed(3, "test"), number=1_000_000))    # ~0.045s (Python 3.11, M1 Mac)
print(timeit.timeit(lambda: foo_untyped(3, "test"), number=1_000_000))  # ~0.044s

Difference is measurement noise. Annotations don’t slow execution.

Runtime Annotations: Libraries That Actually Read Them

Now we enter territory where annotations do things. These libraries hook into class/function definition and inject behavior.

dataclasses: Code Generation from Annotations

from dataclasses import dataclass

@dataclass
class Point:
    x: int
    y: int

p = Point(1, 2)
print(p)           # Point(x=1, y=2)
print(p.x, p.y)    # 1 2

p2 = Point("a", "b")  # No runtime error!
print(p2)             # Point(x='a', y='b')

Wait—dataclasses reads annotations but doesn’t validate types. It uses them to generate __init__, __repr__, __eq__, etc. The types are hints for static checkers, not runtime guards. This surprises people constantly.

If you want runtime validation with dataclasses, you need .pyi stubs plus beartype or typeguard—but that’s a 43% overhead on every attribute access in some benchmarks.

Pydantic: Full Runtime Validation

from pydantic import BaseModel

class Point(BaseModel):
    x: int
    y: int

p = Point(x=1, y=2)
print(p)           # x=1 y=2

try:
    p2 = Point(x="a", y="b")
except Exception as e:
    print(type(e).__name__, e)
    # ValidationError 2 validation errors for Point
    # x
    #   Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='a', input_type=str]
    # y
    #   Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='b', input_type=str]

Pydantic parses __annotations__, builds validators, and runs them in __init__. This is proper runtime enforcement. The cost? Non-trivial.

import timeit
from dataclasses import dataclass
from pydantic import BaseModel

@dataclass
class PointDC:
    x: int
    y: int

class PointPyd(BaseModel):
    x: int
    y: int

print(timeit.timeit(lambda: PointDC(1, 2), number=100_000))   # ~0.012s
print(timeit.timeit(lambda: PointPyd(x=1, y=2), number=100_000))  # ~0.48s

Pydantic is ~40x slower for instantiation (matches the 40x validation overhead I measured before). You pay for safety.

typing.Annotated: Metadata That Can Be Anything

Annotated[T, metadata] is a typing-only container, but the metadata can be runtime-inspected. FastAPI and Pydantic use this heavily.

from typing import Annotated, get_type_hints
from pydantic import Field, BaseModel

class User(BaseModel):
    age: Annotated[int, Field(ge=0, le=120)]

u = User(age=25)   # OK
try:
    u2 = User(age=150)
except Exception as e:
    print(e)
    # 1 validation error for User
    # age
    #   Input should be less than or equal to 120 [type=less_than_equal, input_value=150, input_type=int]

The Field(ge=0, le=120) is runtime metadata. Pydantic reads it from Annotated and enforces the constraint. But if you don’t use Pydantic:

def register(age: Annotated[int, Field(ge=0, le=120)]):
    return f"Registered at age {age}"

print(register(150))  # Registered at age 150  ← no validation!
print(get_type_hints(register, include_extras=True))
# {'age': typing.Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=120)])], 'return': <class 'NoneType'>}

The annotation exists, but vanilla Python ignores it. Only libraries that choose to inspect Annotated metadata enforce it.

The Gotcha: Mixing Both Without Knowing Which Is Which

Here’s where it breaks. You write:

from typing import List
from pydantic import BaseModel

class Config(BaseModel):
    ports: List[int]

c = Config(ports=[8080, 8081])
print(c.ports)  # [8080, 8081]

c2 = Config(ports=["8080", "8081"])  # Pydantic coerces strings to ints!
print(c2.ports)  # [8080, 8081]

Pydantic validates and coerces. But if you use typing.List in a regular dataclass:

from dataclasses import dataclass
from typing import List

@dataclass
class Config:
    ports: List[int]

c = Config(ports=["8080", "8081"])
print(c.ports)  # ['8080', '8081']  ← accepted as-is, no coercion

Your type checker says “error: expected List[int]”, but runtime does nothing. You deploy, and later some code does ports[0] + 1 and crashes with TypeError: can only concatenate str (not "int") to str.

This is the classic pitfall: assuming annotations are enforced when they’re not.

When to Use Each

Typing-only (static analysis) when:

• You trust your CI type checks and tests to catch bugs before deploy
• Performance matters (zero overhead)
• You’re working on internal code where inputs are controlled
• You want IDE autocomplete and refactoring support without runtime cost

Runtime validation when:

• Parsing external input (API requests, config files, user uploads)
• Data crosses trust boundaries (DB → model, external API → your code)
• You need guarantees at runtime, not just in CI
• The cost of a bad value is higher than validation overhead (financial calculations, safety-critical systems)

In practice, most projects use both: Pydantic/FastAPI for API boundaries, plain type hints everywhere else. The key is knowing which annotations are checked when.

Edge Case: Forward References and Circular Imports

Python 3.7+ supports from __future__ import annotations, which makes all annotations strings (PEP 563). This defers evaluation and breaks circular imports. But runtime libraries need actual types, not strings.

from __future__ import annotations
from dataclasses import dataclass

@dataclass
class Node:
    value: int
    left: Node | None = None   # Python 3.10+ union syntax
    right: Node | None = None

print(Node.__annotations__)
# {'value': 'int', 'left': 'Node | None', 'right': 'Node | None'}  ← strings!

Dataclasses handle this fine. Pydantic before v2 had issues; Pydantic v2 uses model_rebuild() to resolve forward refs. But custom validators might break:

from __future__ import annotations
from typing import get_type_hints

def validate(x: int) -> bool:
    return isinstance(x, int)

print(validate.__annotations__)  # {'x': 'int', 'return': 'bool'}

# If you try isinstance with a string, it fails:
try:
    isinstance(5, validate.__annotations__['x'])
except TypeError as e:
    print(e)  # isinstance() arg 2 must be a type, a tuple of types, or a union

# Use get_type_hints to resolve:
print(get_type_hints(validate))  # {'x': <class 'int'>, 'return': <class 'bool'>}

If your runtime validator naively reads __annotations__ without calling get_type_hints(), it breaks under PEP 563. This burned me once when writing a custom argument parser—it worked in tests (no __future__ import) but failed in production (codebase used PEP 563 globally).

Performance Breakdown: Real Numbers

I benchmarked instantiation and attribute access on Python 3.11 (M1 MacBook, 100k iterations):

Takeaway: Pydantic’s safety comes at 40x cost. If you’re instantiating millions of objects in a hot loop (e.g., parsing a 10GB CSV), this matters. For API endpoints handling 100 requests/sec, it’s irrelevant.

The isinstance() Trap with Generics

You cannot use generic types at runtime for isinstance() checks:

from typing import List

x = [1, 2, 3]
print(isinstance(x, list))       # True
try:
    print(isinstance(x, List[int]))
except TypeError as e:
    print(e)  # isinstance() arg 2 cannot be a parameterized generic

This is a common mistake. If you want runtime checks on generic contents, you need a library like beartype or manual loops:

def is_list_of_ints(x) -> bool:
    return isinstance(x, list) and all(isinstance(i, int) for i in x)

print(is_list_of_ints([1, 2, 3]))      # True
print(is_list_of_ints([1, "2", 3]))    # False

But this is $O(n)$ validation on every call. Pydantic does this internally, which is part of why it’s slow.

FAQ

Q: Do type hints slow down Python at all?

No. Storing annotations in __annotations__ is negligible. Unless a library explicitly validates them (Pydantic, typeguard, beartype), they have zero runtime cost. Static checkers like mypy analyze code without executing it, so they don’t affect production speed.

Q: Can I enforce type hints without Pydantic’s overhead?

Yes, but with tradeoffs. beartype uses lazy validation (checks on first call, not every call) and claims ~10x less overhead than Pydantic. Alternatively, run mypy in strict mode and trust your CI—this catches 95% of issues for free. For external inputs, bite the Pydantic cost or write manual isinstance() checks (error-prone).

Q: What happens if I use Python 3.12’s new generic syntax with older libraries?

Python 3.12 allows list[int] instead of typing.List[int]. Most runtime libraries (Pydantic v2, attrs, dataclasses) handle this fine because they use get_type_hints() or typing.get_origin() under the hood. But older validation libraries or custom introspection code might break. Always check library docs for 3.12 compatibility—or just test it. I hit this once with a homegrown CLI argument parser that expected typing.List objects and choked on bare list.

Pick Your Trade-Off and Stick With It

Use typing-only annotations for internal logic where CI catches bugs. Use runtime validation (Pydantic, attrs validators) at trust boundaries—API inputs, config parsing, external data. Don’t mix them naively and assume all hints are enforced.

If you’re writing a library, document whether your decorators/classes inspect annotations at runtime. Users will assume type hints are cosmetic unless you tell them otherwise. (Looking at you, FastAPI—amazing framework, but newcomers are shocked when Query(...) metadata actually validates, while other annotations don’t.)

One thing I haven’t fully solved: validating complex nested structures (deeply nested List[Dict[str, Union[int, CustomClass]]]) without Pydantic’s overhead. If you’re processing millions of objects from a trusted pipeline, even Numba-optimized validators might not justify the cost. My current approach: validate at ingestion once (Pydantic), then use plain dataclasses downstream. Curious if anyone’s found a better pattern.

Also, if all this type hint debugging is making your head hurt, Dark Chocolate Espresso Beans are genuinely the best late-night coding fuel I’ve found—way better than coffee crashes.