Pydantic – Data Validation and Settings Management for Python

Overview

Pydantic is a Python library designed for data validation and settings management, leveraging Python's native type hinting system. It allows developers to define data structures using standard Python classes and annotations, then automatically validates incoming data against these definitions. This approach helps ensure data integrity, reduces runtime errors, and improves code readability by making data expectations explicit.

The library automatically infers schemas from type hints, providing features like data parsing, serialization, and deserialization. When data doesn't conform to the defined types, Pydantic raises clear, detailed validation errors, simplifying debugging and error handling. This makes it particularly useful in scenarios where data originates from external sources, such as API requests, configuration files, or databases, and needs to be reliably structured and validated before processing.

Pydantic is widely adopted in the Python ecosystem, notably as the core data validation library in popular web frameworks like FastAPI. Its integration with frameworks allows for automatic request body parsing, response serialization, and comprehensive OpenAPI schema generation. Beyond web development, Pydantic is also used for managing application settings, validating data models in data science workflows, and ensuring consistency across various data-intensive applications.

One of Pydantic's strengths lies in its balance between ease of use and performance. Version 2 introduced a Rust-based core, significantly improving parsing and validation speeds compared to its pure Python predecessor. This performance enhancement makes it suitable for high-throughput applications where data validation overhead needs to be minimized. The library also supports advanced validation scenarios, including custom validators, constrained types, and recursive models, providing flexibility for complex data requirements. Its ability to integrate seamlessly with Python's dataclasses and other standard library features further enhances its versatility for modern Python development.

Key features

• Data Validation with Type Hints: Automatically validates data against Python type hints, ensuring data integrity and reducing boilerplate code.
• Settings Management: Provides a robust way to define and load application settings from various sources, including environment variables, .env files, and custom configurations.
• Data Parsing and Serialization: Automatically parses raw input data into defined Python types and serializes Python objects back into formats like JSON or dictionaries.
• Error Handling: Generates detailed and user-friendly validation errors, making it easier to identify and resolve data issues.
• OpenAPI Schema Generation: When used with frameworks like FastAPI, Pydantic models automatically generate OpenAPI (Swagger) schemas for API documentation.
• Custom Validators: Allows developers to define custom validation logic using decorator-based syntax for specific data constraints beyond standard types.
• Recursive Models: Supports defining complex, nested data structures and validating them recursively.
• Performance Optimization: Pydantic V2 includes a Rust-based core for improved parsing and validation performance.
• Extensibility: Features like Pydantic-extra-types provide additional common types (e.g., phone numbers, URLs, UUIDs) for enhanced validation capabilities.

Pricing

Pydantic is an open-source project released under the MIT License, making it free to use for both commercial and non-commercial purposes. There are no licensing fees, subscriptions, or paid tiers associated with the core library or its official extensions. This pricing model aligns with many foundational Python libraries, providing broad accessibility for developers and organizations.

For more specific licensing information, refer to the official Pydantic documentation.

Common integrations

• FastAPI: Pydantic is the foundational data validation and serialization library for FastAPI, handling request body parsing, response modeling, and automatic OpenAPI schema generation. The FastAPI tutorial on request bodies provides examples.
• SQLModel: Built on top of Pydantic and SQLAlchemy, SQLModel provides a way to define database models using Pydantic-compatible classes, enabling both ORM functionality and data validation. The SQLModel documentation on creating database tables demonstrates its use.
• Django REST Framework: Pydantic can be integrated with Django REST Framework to replace or augment its default serializers, offering type-hint-based validation for API views.
• Flask: While not as tightly integrated as with FastAPI, Pydantic can be used in Flask applications for validating incoming request data or structuring responses.
• Aiohttp: For asynchronous web applications, Pydantic models can be used to validate data received by aiohttp servers or sent by aiohttp clients. Refer to the Aiohttp web reference for server-side processing.

Alternatives

• SQLModel: An ORM library that combines Pydantic with SQLAlchemy, allowing developers to define models once for both data validation and database interaction.
• Marshmallow: A popular Python library for object serialization/deserialization and validation, often used with web frameworks.
• Cattrs: A library for cattrs-based structural conversion, enabling flexible conversion of Python objects to and from various data structures.
• Python's native dataclasses: While not a direct validation library, dataclasses provide a way to define structured data classes, which can be extended with manual validation logic.
• typing.TypedDict: Part of Python's standard typing module, TypedDict allows for defining dictionaries with specific keys and value types, offering a basic form of structural type checking.

Getting started

To begin using Pydantic, first install it via pip:

pip install pydantic

Once installed, you can define a Pydantic model by inheriting from BaseModel and using Python type hints for your fields. Here's a basic example:

from pydantic import BaseModel, ValidationError

# 1. Define a Pydantic Model
class User(BaseModel):
    id: int
    name: str = "John Doe" # Field with a default value
    email: str
    is_active: bool = True

# 2. Create an instance with valid data
print("--- Valid Data Example ---")
try:
    user_data_valid = {
        "id": 123,
        "name": "Jane Smith",
        "email": "[email protected]"
    }
    user = User(**user_data_valid)
    print(f"User created: {user}")
    print(f"User ID: {user.id}")
    print(f"User Name: {user.name}")
    print(f"User Email: {user.email}")
    print(f"User Active: {user.is_active}")
except ValidationError as e:
    print(f"Validation Error: {e}")

# 3. Create an instance with invalid data (missing required field 'email')
print("\n--- Invalid Data Example (Missing Field) ---")
try:
    user_data_invalid_missing = {
        "id": 456,
        "name": "Peter Jones"
        # 'email' is missing, which is a required field
    }
    user_invalid = User(**user_data_invalid_missing)
    print(f"User created: {user_invalid}")
except ValidationError as e:
    print(f"Validation Error for missing field: {e}")

# 4. Create an instance with invalid data (wrong type for 'id')
print("\n--- Invalid Data Example (Wrong Type) ---")
try:
    user_data_invalid_type = {
        "id": "seven", # 'id' should be an int
        "name": "Alice",
        "email": "[email protected]"
    }
    user_invalid_type = User(**user_data_invalid_type)
    print(f"User created: {user_invalid_type}")
except ValidationError as e:
    print(f"Validation Error for wrong type: {e}")

# 5. Access validated data as a dictionary or JSON
print("\n--- Data Export Example ---")
user_to_export = User(id=789, email="[email protected]")
print(f"User as dictionary: {user_to_export.model_dump()}")
print(f"User as JSON string: {user_to_export.model_dump_json(indent=2)}")

This example demonstrates how to define a User model with various fields, including a default value for name and is_active. It then shows how to create instances with both valid and invalid data, triggering Pydantic's automatic validation and error reporting. Finally, it illustrates how to export the validated data into a dictionary or JSON string using model_dump() and model_dump_json() methods, respectively.