Mypy static checks: annotations do not validate runtime payloads

Operation contract

The positive module declares a function returning an integer amount. A separate module returns text under the same return annotation. Strict checking accepts the first and reports the incompatible return in the second. Each file is checked independently through the same interpreter and target syntax version, with caches disabled to keep this small fixture isolated.

Failure and ownership boundary

A type check can miss untyped or deliberately escaped paths, and an annotation does not reject untrusted JSON. The fixture also checks the expected diagnostic category rather than counting an arbitrary nonzero exit as success; tool startup failures would otherwise masquerade as a useful rejection. Python type hints: annotations do not enforce runtime arguments and Python JSON validation: reject duplicate members and non-integer amounts serve different boundaries.

Tested environment

Dependency check: this program was executed on CPython 3.14.6 with mypy==2.3.1. Install these versions in a separate virtual environment. The download includes the recorded environment snapshot; no third-party package is part of the website runtime.

Working program

from pathlib import Path
import subprocess
import sys
import tempfile

with tempfile.TemporaryDirectory() as directory:
    owned = Path(directory)
    accepted = owned / "accepted.py"
    rejected = owned / "rejected.py"
    accepted.write_text("def receipt_amount() -> int:\n    return 125\n", encoding="utf-8")
    rejected.write_text("def receipt_amount() -> int:\n    return '125'\n", encoding="utf-8")
    command = [sys.executable, "-I", "-m", "mypy", "--strict", "--python-version", "3.11",
               "--no-incremental", "--cache-dir", str(owned / "cache")]
    good = subprocess.run(command + [str(accepted)], cwd=directory, capture_output=True, text=True, timeout=10)
    bad = subprocess.run(command + [str(rejected)], cwd=directory, capture_output=True, text=True, timeout=10)
    if good.returncode != 0 or bad.returncode != 1 or "[return-value]" not in bad.stdout:
        raise RuntimeError("unexpected type-check result")
print("valid return accepted")
print("text return rejected by static check")

Output

valid return accepted
text return rejected by static check

Costs and limits

Static analysis cost depends on program size, imports and type relationships. This fixture uses two tiny independent files and does not claim a whole-service check. The 3.11 checker target is not execution on Python 3.11.

Common Mistakes

• A type annotation cannot sanitize a received payload.
• A failed checker process is not automatically the expected type diagnostic.

Connected lessons

Python type hints: annotations do not enforce runtime arguments, Python Protocol: structural intent without runtime validation, Python JSON validation: reject duplicate members and non-integer amounts.