Type Hints and Pydantic for Safer Python APIs

Python's dynamic typing is fantastic for rapid prototyping, but in production backend systems, untyped code leads to subtle runtime bugs: AttributeError: 'NoneType' object has no attribute... or unexpected type mismatches in financial calculations. Python 3.5+ introduced static type hinting, and Pydantic turned type hints into runtime data validation engine powering modern frameworks like FastAPI.

1. The Basics of Python Type Hinting

Type hints tell IDEs, static analysis tools (like mypy), and developers what data types functions expect and return.

from typing import Optional, List, Dict

def calculate_discount(price: float, discount_percent: float = 10.0) -> float:
    return price * (1.0 - discount_percent / 100.0)

def find_user_emails(users: List[Dict[str, str]]) -> List[str]:
    return [user["email"] for user in users if "email" in user]

2. Pydantic v2: Data Validation Engine

Pydantic enforces type constraints at runtime when data enters your application boundary (e.g., HTTP request bodies or JSON payloads).

from pydantic import BaseModel, EmailStr, Field, HttpUrl
from typing import Optional, List

class UserRegistration(BaseModel):
    username: str = Field(min_length=3, max_length=50)
    email: EmailStr
    age: int = Field(gt=18, le=120)
    website: Optional[HttpUrl] = None
    tags: List[str] = []

# Valid creation
user = UserRegistration(
    username="prakashtank",
    email="prakash@example.com",
    age=28
)

# Printing as dictionary or JSON
print(user.model_dump())
print(user.model_dump_json())

3. Nested Models and Custom Validators

Pydantic seamlessly parses complex nested JSON arrays and objects, with support for custom validation logic via @field_validator.

from pydantic import BaseModel, field_validator

class Address(BaseModel):
    city: str
    country: str

class Organization(BaseModel):
    name: str
    address: Address

class SignupPayload(BaseModel):
    org: Organization
    admin_email: EmailStr

    @field_validator('admin_email')
    @classmethod
    def must_be_work_email(cls, v: str) -> str:
        if v.endswith('@gmail.com') or v.endswith('@yahoo.com'):
            raise ValueError('Must use a corporate work email address')
        return v

Conclusion

Leveraging type hints and Pydantic across your Python APIs eliminates entire classes of runtime errors before they reach production. It turns raw input strings into fully validated domain models while automatically generating OpenAPI documentation in FastAPI.

Building high-stakes Python APIs? Visit my AI integration development page to see how I craft robust backend systems.