Pydantic: The end of manual validations! ✨

Pydantic is a data validation and settings management library for Python. It uses Python type hints to validate and parse data, ensuring that your code works with properly structured and typed data. By leveraging Python’s dataclass-like model structure, Pydantic makes it easy to define schemas for complex data and automatically validate and serialize/deserialize data in a clean, Pythonic way. Let's explore the main features:

Data Validation

Automatically validate input data against a schema using Python's type hints.

from pydantic import BaseModel, ValidationError

class User(BaseModel):
    id: int
    name: str
    email: str

# Valid input
user = User(id=1, name="John Doe", email="john@example.com")
print(user)

# Invalid input
try:
    user = User(id="not-an-integer", name="Jane", email="jane@example.com")
except ValidationError as err:
    print(err)

Whenever you want to define data model, use pydantic.BaseModel!

Function Validation

Pydantic provides powerful tools for validating not just data models but also the input and output of functions. This is achieved using the @validate_call decorator, allowing you to enforce strict data validation for function arguments and return values. If the provided arguments or return type don’t match the expected types, a ValidationError is raised.

from pydantic import validate_call

@validate_call
def greet(name: str, age: int) -> str:
    return f"Hello {name}, you are {age} years old."

# Valid input
print(greet("Alice", 30))  # Output: Hello Alice, you are 30 years old.

# Invalid input
try:
    greet("Bob", "not-a-number")
except Exception as e:
    print(e)

By enabling the validate_return flag in @validate_call, Pydantic will also validate the return value of the function against its annotated return type. This ensures the function adheres to the expected output schema.

from pydantic import validate_call

@validate_call(validate_return=True)
def calculate_square(number: int) -> int:
    return number ** 2  # Correct return type

# Valid input and return
print(calculate_square(4))  # Output: 16

# Invalid return value
@validate_call(validate_return=True)
def broken_square(number: int) -> int:
    return str(number ** 2)  # Incorrect return type

try:
    broken_square(4)
except Exception as e:
    print(e)

Parsing

Pydantic can parse complex nested structures, including JSON data, into model objects.

from pydantic import BaseModel
from typing import List

class Item(BaseModel):
    name: str
    price: float

class Order(BaseModel):
    items: List[Item]
    total: float

# JSON-like data
data = {
    "items": [
        {"name": "Apple", "price": 1.2},
        {"name": "Banana", "price": 0.8}
    ],
    "total": 2.0
}

order = Order(**data) 
print(order) # items=[Item(name='Apple', price=1.2), Item(name='Banana', price=0.8)] total=2.0

Serialization and Deserialization

Pydantic models can be serialized into JSON or dictionaries and reconstructed back.

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str

# Create a model instance
user = User(id=1, name="Alice", email="alice@example.com")

# Serialize to dictionary and JSON
user_dict = user.model_dump()
user_json = user.model_dump(mode='json')

print("Dictionary:", user_dict)
print("JSON:", user_json)

# Deserialize back to the model
new_user = User.model_validate(user_json)
print("Parsed User:", new_user)

Flexible Validation

Data validation is not force-type validation. For example, if you define a model with id, due_date, and priority fields of types int, bool, and datetime respectively, you can pass:

numerical string as id
ISO-8601, UTC or strings of the other date formats as due_date
'yes'/'no', 'on'/'off', 'true'/'false', 1/0 etc. as priority

from sensei import APIModel
from datetime import datetime


class Task(APIModel):
    id: int
    due_date: datetime
    priority: bool


task = Task(due_date='2024-10-15T15:30:00', id="1", priority="yes")
print(task)

The result will be

Task(id=1, due_date=datetime.datetime(2024, 10, 15, 15, 30), priority=True)

Custom Validation

You can also define custom validation logic in your model using validators. They allow you to apply more complex validation rules that cannot be easily expressed using the built-in types or field constraints. Validator is defined through the field_validator decorator or Field object. You can pass one or more field names to field_validator, to determine what fields will use this validator, or '*' to apply validator for every field.

from typing import Any
from pydantic import Field, field_validator, EmailStr, BaseModel

class User(BaseModel):
    id: int
    username: str = Field(pattern=r'^\w+$')
    email: EmailStr
    age: int = Field(18, ge=14)
    is_active: bool = True
    roles: list[str]

    # Define validator executed 'before' internal parsing
    @field_validator('roles', mode='before')
    def _validate_roles(cls, value: Any):
        return value.split(',') if isinstance(value, str) else value

user = User(id=1, username='john', email='john@example.com', roles='student,singer')
print(user) # id=1 username='john' email='john@example.com' age=18 is_active=True roles=['student', 'singer']

Open-source Projects

There are a lot of open-source projects powered by Pydantic. Let's explore the best of them:

FastAPI

One of the most prominent use cases of Pydantic is in FastAPI, a modern web framework for building APIs with Python. FastAPI uses Pydantic models extensively for request body validation, query parameters, and response schemas.

Source: https://github.com/fastapi/fastapi
Docs: https://fastapi.tiangolo.com

Sensei

While FastAPI is designed for building APIs, Sensei is designed for wrapping these APIs quickly and easy. API Clients powered by Sensei ensure users they will get relevant data models and will not get confusing errors.

Source: https://github.com/CrocoFactory/sensei
Docs: https://sensei.crocofactory.dev

SQLModel and Typer

SQLModel and Typer are two remarkable projects developed by Sebastián Ramírez, the creator of FastAPI.

SQLModel is a library designed to streamline database interactions in Python applications. Built on top of SQLAlchemy and Pydantic, SQLModel combines the power of an ORM with the convenience of data validation and serialization.

Source: https://github.com/fastapi/sqlmodel
Docs: https://sqlmodel.tiangolo.com

Typer is a framework for creating command-line interface (CLI) applications using Python. It simplifies the process by using Python's type hints to automatically generate user-friendly CLI commands and help text.