Separate hints from runtime validation
Why you care
Half the "TypeError at 2 am on a Monday" incidents in Python ETL come from one invisible gap: Python's type hints are metadata, not enforcement. The runtime compiles and executes your code without reading a single annotation. A passing mypy run tells you the code is consistently annotated; it does not mean external data is safe. Interviewers ask "what is the difference between a type hint and runtime validation" because the answer reveals whether you know where type safety actually comes from — and where it stops.
Explain like I'm 5
A restaurant menu says "this dish is spicy". The kitchen does not refuse to cook it without chillies; the menu is a message to the waiter. Only a bouncer at the kitchen door — someone who checks every tray — actually stops the wrong ingredient. Annotations are menus; a boundary validator (Pydantic, isinstance, or a dataclass __post_init__) is the bouncer. The menu and the bouncer do different jobs. You need both.
Core concept
Three facts to carry:
x: int = 3stores{'x': int}in__annotations__. Python never reads it during execution.def f(a: int) -> str— call it withf("hello")and it runs fine, returning whatever the body computes.typing.get_type_hints(f)retrieves annotations at runtime. This is how validators and frameworks introspect them; Python itself does not call it automatically.
Static checkers — mypy, pyright, Pylance — read annotations before the code runs, flag mismatches, and exit non-zero if the check fails. They work on the text, not the running program.
Decision rule. Add hints everywhere for IDE feedback and CI gates. Add runtime validation only at trust boundaries: API request parsing, config file loading, CSV deserialisation, database row mapping (Pydantic v2 boundary validation and schemas). Inside a module where you control every caller, trust typed code and do not re-validate; the mypy gate is enough. When not to add isinstance guards: hot loops and pure internal helpers. Enforce at entry, trust thereafter.
Under the hood
In Python 3.14 (released 2025-10-07, PEP 649), annotations on functions and classes become lazily evaluated by default — Python defers evaluating them until something first reads __annotations__. The key change from 3.12: annotations are no longer evaluated at definition time. f.__annotations__["x"] still returns the real int class (not a string), so ann is int stays True. Three things change in 3.14 that worked in 3.12: (1) a class body no longer stores a ready-made __annotations__ dict in cls.__dict__ (it stores a function that builds it on demand), so code that reads cls.__dict__['__annotations__'] directly gets a KeyError, or None from .get(); (2) a forward reference to a name not yet defined no longer fails when the def runs, it raises NameError later, when something reads __annotations__; (3) code that assumed annotations are strings only gets strings under from __future__ import annotations (PEP 563), never from the 3.14 default. The new annotationlib module is the supported way to read them; inspect.get_annotations(cls) (3.10+) works on both versions. Libraries like dataclasses and Pydantic were updated for 3.14; your in-house introspection code is what needs auditing (Read the 3.11 to 3.14 migration map).
Minimal example Annotations do not change what Python accepts
def multiply(a: int, b: int) -> int:
return a * b
result = multiply("row", 3) # str × int is valid Python; no error
print(result)
print(type(result))
print(multiply.__annotations__)rowrowrow
<class 'str'>
{'a': <class 'int'>, 'b': <class 'int'>, 'return': <class 'int'>}In production Config loaded from JSON carries the wrong types silently
from dataclasses import dataclass
from pathlib import Path
import json
@dataclass
class JobConfig:
batch_size: int
source_key: str
dry_run: bool
def load_config(raw: dict) -> JobConfig:
"""Annotations present, but no runtime check: wrong types accepted."""
return JobConfig(
batch_size=raw["batch_size"],
source_key=raw["source_key"],
dry_run=raw["dry_run"],
)
Path("job_config.json").write_text(
'{"batch_size": "500", "source_key": "s3://bucket/feed.csv", "dry_run": "false"}'
)
raw = json.loads(Path("job_config.json").read_text())
cfg = load_config(raw)
print(type(cfg.batch_size), cfg.batch_size)
print(type(cfg.dry_run), cfg.dry_run)
print(bool(cfg.dry_run)) # "false" is a non-empty string — truthy in Python<class 'str'> 500
<class 'str'> false
TrueSee it happen Where hints stop and validation begins
- Annotations live in the source as metadata. Python stores them in __annotations__ and moves on.
- mypy reads those annotations at CI time and flags mismatches before the code ships.
- At runtime, Python compiles and executes the source. It does not read a single annotation.
- External data — an API payload, a CSV row, a config file — arrives with no guarantee it matches the declared types.
- A boundary validator checks and coerces data before it enters the typed interior, where mypy's guarantee holds.
In your world
The situation
Your nightly Jenkins job loads a batch_size from a JSON config file on S3 and later calls range(cfg.batch_size) to chunk the Postgres inserts.
What actually breaks
A platform team changes the config writer to emit "batch_size": "500" (a JSON string) instead of 500. The hint says int, mypy never ran on the config-loading module, and the job crashes with TypeError: 'str' object cannot be interpreted as an integer inside the chunking loop — three layers below the config load. The stack trace points nowhere useful.
What you'd do on Monday
Validate and coerce at the loading boundary, not at the call site:
from dataclasses import dataclass
from pathlib import Path
import json
@dataclass
class JobConfig:
batch_size: int
source_key: str
dry_run: bool
def load_config(raw: dict) -> JobConfig:
dry_raw = raw["dry_run"]
dry_run = (dry_raw.lower() == "true") if isinstance(dry_raw, str) else bool(dry_raw)
return JobConfig(
batch_size=int(raw["batch_size"]),
source_key=str(raw["source_key"]),
dry_run=dry_run,
)
Path("job_config.json").write_text(
'{"batch_size": "500", "source_key": "s3://bucket/feed.csv", "dry_run": "false"}'
)
raw = json.loads(Path("job_config.json").read_text())
cfg = load_config(raw)
print(type(cfg.batch_size), cfg.batch_size)
print(type(cfg.dry_run), cfg.dry_run)<class 'int'> 500
<class 'bool'> FalseImagine you work at Booking.com
The numbers
Illustrative: 50M requests × ~10 config-object constructions per service restart wave = 500M constructions per deploy cycle. An isinstance check on every construction adds roughly 0.5 µs each — 250 s of CPU per wave — entirely avoidable if you validate once at the boundary and trust typed code downstream.
What the Scenario-A answer does here
The Scenario A fix (explicit coercion in load_config) works at this scale, but if CI never runs mypy, the same string-not-int slip recurs in the next config key that gets added. A single boundary model catches the full shape; re-checking at every call site is redundant and expensive.
What flips at this scale
At this scale the flip is a static-analysis gate in CI, not a per-call isinstance guard. mypy/pyright in CI catches type mismatches before deploy; a Pydantic model (Pydantic v2 boundary validation and schemas) validates each incoming API request once. Everything downstream trusts the types.
The trade-off you'd defend
I would defend a strict pyright gate in CI over scattered isinstance guards, trading two minutes of CI time for zero per-call overhead and a single, visible validation point.
Illustrative numbers to make the arithmetic visible; not Booking.com-published figures.
Gotchas
A passing mypy run does not mean external data is safe
mypy exits 0, but the job crashes with TypeError or AttributeError on data loaded from S3 or a database.
mypy checks the annotation contract between your functions; it cannot see what arrives at runtime from outside the Python process.
Add runtime validation at every trust boundary — the point where data enters from a source you do not control.
cls.__dict__['__annotations__'] is gone in Python 3.14
Code that reads cls.__dict__.get('__annotations__', {}) to build a type map gets an empty map on Python 3.14, so every field falls through to the default branch; the ['__annotations__'] form raises KeyError.
Under PEP 649 the class body stores a function that builds the annotations on first access, not the finished dict. cls.__annotations__ goes through the type's descriptor and still works; cls.__dict__ is just the raw namespace.
Use inspect.get_annotations(cls) (3.10+, own annotations only, same as the old __dict__ read) or typing.get_type_hints(cls) (also resolves strings and merges base classes). Cache the result per class on hot paths.
mypy only checks what it can reach
A module with no annotations is silently ignored by mypy; errors there reach production.
mypy skips un-annotated modules in its default configuration.
Enable --strict or at minimum --check-untyped-defs in mypy.ini. Add annotations to new modules from day one.
Tricky questions
Yes — that is the whole point of type hints.
mypy guarantees the contract between annotated functions is consistent. It cannot see what Python receives from json.loads, a database query or os.environ. A str variable annotated as int that arrives from JSON is invisible to the checker until you add a runtime validator at the entry point.
Yes, hints are just documentation — you can add them any time.
Adding from __future__ import annotations (PEP 563) makes all annotations compile-time strings. On Python 3.14, annotations are lazily evaluated but still return real types on access — the two mechanisms are different. Code that compares __annotations__ values to classes breaks under PEP 563, and code that reads cls.__dict__['__annotations__'] breaks on 3.14. Add hints one module at a time and test framework introspection after each batch.
Scenario question
You're handed a 3-year-old ETL script with no type hints. The team wants to add hints "for safety". What is the first real step, and what will and won't it do?
Model answer
I would add hints to the public functions first and run mypy in CI with --strict. That catches internal contract violations and gives the IDE autocomplete. Then I would identify every point where data arrives from outside the codebase: S3 file reads, Postgres query results, HTTP payloads. Those get a runtime validator, not just a hint. The trade-off is that hints without a CI gate are decorations, and a CI gate without boundary validators still lets bad data in. You need both layers. I would do the CI gate first because it costs nothing to run and immediately flags existing inconsistencies.
Interview corner
CommonWhat is the difference between a type hint and runtime validation?
__annotations__ and read by mypy or the IDE, but Python never checks it during execution. Runtime validation is code that actually inspects the value and raises an exception if it is wrong. You need both: hints for internal contract checking, validators at the boundary where data arrives from outside your code.”TrickIf mypy passes, is the code type-safe?
json.loads, a database row or os.environ. A string that arrives as an int annotation is invisible to the checker until you validate at the entry point. I think of mypy as auditing the plumbing between functions; a boundary validator is the filter on the pipe before it enters the building.”Experience checkWhere has missing runtime validation caused a real incident?
int, mypy passed, but nobody had added int() at the load point. The job crashed three layers down with a TypeError that pointed at the chunking loop, not the config load. I now coerce at the boundary and assert types before any computation depends on them.”Memory hook
Hints tell mypy what you mean; a boundary validator tells Python what you require.
If the data comes from outside your code, annotate it and validate it.
Self-check
Does Python raise an error if you pass a string to a parameter annotated as int?
No. Python stores the annotation but never checks it during execution. The function runs with whatever argument you pass.
What does
typing.get_type_hints(f)return thatf.__annotations__does not?get_type_hintsresolves forward references and handlesfrom __future__ import annotations(PEP 563) string annotations, always returning a dict of real type objects. In Python 3.12 withoutfrom __future__ import annotations, both return the same dict. In 3.14 (PEP 649),f.__annotations__also returns real types; butcls.__dict__['__annotations__']skips the lazy descriptor and breaks —get_type_hintsis safe in all versions.Name two places in an ETL pipeline that qualify as trust boundaries.
Anywhere external data enters: the JSON config loader, S3 CSV parser, Postgres query result mapper, HTTP request deserialiser. Any two of these count.
Run the production example as-is, then change batch_size in the JSON to the integer 500 (no quotes). Run again. Confirm that the first run prints <class 'str'> 500 and the second prints <class 'int'> 500 — showing that the dataclass annotation does nothing; the JSON type is what arrives. Paste both outputs.