Python Type Hints and Pydantic: Building Safer, Self-Documenting APIs

Python's optional type hints, introduced in PEP 484, allow you to annotate variable types without losing Python's dynamic nature. Static type checkers like mypy and pyright catch type errors before runtime—a significant improvement for large codebases.

Basic Type Hints

from typing import Optional, list

def create_article(
    title: str,
    tags: list[str],
    category_id: Optional[int] = None,
    published: bool = False
) -> dict:
    ...

Pydantic for Request Validation

from pydantic import BaseModel, EmailStr, field_validator

class ArticleCreate(BaseModel):
    title: str
    content: str
    category_id: int
    tags: list[str] = []

    @field_validator("title")
    @classmethod
    def title_not_empty(cls, v: str) -> str:
        if len(v.strip()) < 5:
            raise ValueError("Title must be at least 5 characters")
        return v.strip()

Pydantic v2 Performance

Pydantic v2 rewrote its core validation engine in Rust, making it 5-50x faster than v1. For high-throughput APIs validating thousands of requests per second, this is a significant improvement. Migrate using the pydantic-v1 compatibility layer if needed.

mypy Integration in CI

# pyproject.toml
[tool.mypy]
strict = true
plugins = ["pydantic.mypy"]

# GitHub Actions
- name: Type Check
  run: mypy app/ --ignore-missing-imports

Production Pydantic Validation Models

Below is a production schema design in Pydantic v2 incorporating custom phone/email validation, parameter coercions, and schema documentation:

import re
from pydantic import BaseModel, EmailStr, Field, field_validator

class EnterpriseSignUpSchema(BaseModel):
    name: str = Field(..., min_length=2, max_length=100)
    email: EmailStr
    phone: str = Field(..., description="UK or US formatted phone number")
    annual_revenue: float = Field(default=0.0, ge=0.0)

    @field_validator('phone')
    @classmethod
    def validate_phone_number(cls, value: str) -> str:
        cleaned = re.sub(r'\D', '', value)
        # Support 10-digit US (+1) or 11-digit UK (+44) formats
        if len(cleaned) not in (10, 11):
            raise ValueError("Phone number must contain exactly 10 (US) or 11 (UK) digits")
        return cleaned

Runtime & Concurrency Metrics Profile

Below is a runtime latency and throughput benchmark compiled in a containerized environment (2 vCPU, 4GB RAM) running under simulated concurrent request volumes:

US & UK Compliance and Data Governance

Modern applications operating across US and UK regions must establish comprehensive data governance frameworks. This includes meeting the security baselines of the US NIST Cybersecurity Framework and the UK Cyber Essentials certification. Enforcing encryption at rest and in transit, keeping audit logs, and maintaining a clear incident response plan are essential to comply with both CCPA and UK GDPR regulations.