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/0etc. aspriority
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.
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.
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.
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.
- Source: https://github.com/fastapi/typer
- Docs: https://typer.tiangolo.com
Top comments (0)