Type hints and pydantic

A type hint is a note in the code saying what kind of value belongs where. Python ignores hints while running, but your editor and a type checker read them, so a mistake surfaces as you type rather than in production. This section covers the annotations worth writing, then pydantic, which uses the same syntax to check data arriving from outside your program — an API response, a form, a model's output — and to reject it clearly when it is wrong.

What a type hint is#

A type hint says what kind of value something should be. Python ignores hints while running. Your editor and a type checker read them and warn you before you run anything.

def greet(name: str) -> str:
    return f"Hello {name}"

count: int = 0
prices: list[float] = []
user: dict[str, str] = {}

The practical benefit is autocomplete. Once your editor knows a variable is a str, it can offer you every string method. Without hints it can only guess.

Values that might be missing#

This is the most useful thing type hints do. If a function might return nothing, say so, and the checker will insist that callers handle it.

def find_user(user_id: str) -> dict | None:
    ...

user = find_user("abc")
print(user["name"])          # warning: user might be None

if user is not None:
    print(user["name"])      # fine now

The common shapes#

from typing import Literal

names: list[str]
scores: dict[str, int]
pair: tuple[int, int]
value: int | str                        # either one
role: Literal["user", "assistant"]      # only these exact strings

Where hints stop being enough#

Nothing checks a hint at runtime. If an API sends you a string where you declared an int, Python will not complain and your code will break later with a confusing error. For data arriving from outside your program, you need real validation.

pydantic#

pydantic takes a class definition and turns it into a validator. You describe the shape once, and it checks incoming data against it and converts types where it safely can.

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    email: str | None = None      # optional, defaults to None

user = User(name="Jack", age=29)
user.name                          # 'Jack'

User(name="Jack", age="29")      # works: "29" converts to 29
User(name="Jack", age="abc")     # raises ValidationError

Field adds rules the type alone cannot express.

from pydantic import BaseModel, Field

class Invoice(BaseModel):
    number: str
    amount: float = Field(gt=0)                    # must be positive
    currency: str = Field(min_length=3, max_length=3)
    overdue: bool = False

When validation fails you get a list of every problem, not just the first, which makes it possible to tell a user everything that is wrong at once.

from pydantic import ValidationError

try:
    invoice = Invoice.model_validate_json(raw_text)
except ValidationError as e:
    for err in e.errors():
        field = ".".join(str(p) for p in err["loc"])
        print(f"{field}: {err['msg']}")

Why this matters for AI work#

A model returns text. That text is untrusted, exactly like input from a stranger. A pydantic model is where it stops being a guess and becomes something you can rely on. pydantic can also produce a JSON schema from your class, and that schema is exactly what tool definitions and structured output requests need.

Invoice.model_json_schema()
# Send this to the API as the required output shape,
# then validate the response with the same class.