Type Hints for Safer Data and AI Code

Type hints tell readers and tools what kind of value a variable, argument, or return is supposed to be. Python does not enforce them at runtime, but they catch a huge class of bugs in your editor before you ever run the code, and they make data and AI pipelines far easier to read. Modern AI libraries lean on them heavily, so reading them fluently is a real skill.

What You'll Learn

• The syntax for hinting variables, arguments, and returns
• How to hint lists, dicts, and "maybe missing" values
• Why hints help even though Python ignores them at runtime
• How a type checker turns hints into real safety

Basic Syntax

A type hint goes after a colon for variables and arguments, and after an arrow for return types:

name: str = "alice"
count: int = 0

def average(values: list[float]) -> float:
    return sum(values) / len(values)

Read average(values: list[float]) -> float as "takes a list of floats, returns a float." Nothing changes at runtime; the value is in clarity and tooling.

Hinting Collections

Use the built-in container types with the element type in square brackets:

scores: list[float] = [0.9, 0.8]
labels: dict[str, int] = {"cat": 0, "dog": 1}
names: set[str] = {"alice", "bob"}
point: tuple[float, float] = (1.0, 2.0)

For data work this is gold: a glance tells you a function returns dict[str, list[float]] rather than some mystery shape.

Optional and Union: "Maybe Missing" Values

Real data has gaps. When a value can be a type or None, say so. Modern Python uses the | syntax:

def find_user(user_id: int) -> dict | None:
    # returns the user dict, or None if not found
    ...

age: int | None = None     # might get filled in later

dict | None means "a dict or None." This documents that callers must handle the missing case, and a type checker will warn them if they forget.

Why Bother If Python Ignores Them?

Three concrete payoffs:

The bugs hints catch are exactly the slippery ones: passing a string where a number was expected, returning None that the caller treats as a list, mixing up the order of arguments.

Turning Hints Into Real Checks

To actually enforce hints, run a static type checker. The widely used one is mypy:

pip install mypy
mypy your_script.py

It reads your hints and reports mismatches without running your code. Many editors run a checker in the background and underline problems as you type. The hints are the input; the checker is what turns them into safety.

A Practical Example

Hints make a data function self-documenting:

from dataclasses import dataclass

@dataclass
class Prediction:
    label: str
    confidence: float

def top_prediction(preds: list[Prediction]) -> Prediction | None:
    if not preds:
        return None
    return max(preds, key=lambda p: p.confidence)

Anyone reading top_prediction knows instantly what goes in, what comes out, and that the empty case returns None.

Try It

Run this. The hints document the shapes. Try changing the return to a wrong type in your editor with mypy installed and watch it complain (here it just runs, since Python does not enforce hints at runtime).

Key Takeaways

• Type hints use name: type for variables and arguments and -> type for returns.
• Hint collections with list[float], dict[str, int], tuple[float, float], and so on.
• Use Type | None for values that might be missing, and handle that case.
• Python ignores hints at runtime; their value is editor autocomplete, readability, and catching bugs early.
• Run a checker like mypy to turn hints into real, code-free verification.