voluptuous

Pythonvalidationdata-validationschematype-checkingJSONYAML

Validation Library

voluptuous

Overview

Voluptuous is a Python data validation library primarily intended for validating data coming into Python as JSON, YAML, and other formats. Despite its name, it provides a simple and readable syntax with detailed error messages. It supports complex data structures and allows schema definition using basic Python data types.

Details

Voluptuous is built on the following design principles:

Key Features

Simple Syntax: Define schemas using basic Python data types (dict, list, int, str, etc.)
Detailed Error Messages: Provides useful messages clearly indicating what went wrong during validation
Nested Structure Support: Complex data structures are treated the same way as any other type
Custom Validators: Easy to add custom validation logic
Type Coercion: Automatic conversion of data to expected types
Optional Fields: Flexible definition of required and optional fields

Design Philosophy

Validators are simple callables: No need to subclass anything, just use a function
Errors are simple exceptions: A validator can just raise Invalid(msg) with useful messages
Schemas are basic Python data structures: {int: str} does what you expect
Designed for more than just forms: Suitable for API data, configuration files, YAML, and more

Main Use Cases

Configuration file validation
API input data validation
YAML/JSON file validation
Form data validation
Environment variable validation

Pros and Cons

Pros

Low Learning Curve: Uses basic Python data types, making it intuitive to understand
No Dependencies: Lightweight implementation without external dependencies
High Flexibility: Easy to add custom validators and rules
Clear Error Messages: Makes debugging easier
Code Readability: Schema definitions are readable and serve as documentation
Pythonic API: Follows Python conventions and idioms

Cons

Performance: Slower compared to libraries like Pydantic
No Type Annotation Support: Cannot leverage Python 3.6+ type hints
No Object Conversion: Validated data remains as dict (unlike Pydantic's model objects)
Limited IDE Support: Type inference and autocomplete don't work well
Maintenance Frequency: Lower update frequency compared to other major validation libraries

Reference Pages

Code Examples

Basic Usage

from voluptuous import Schema, Required

# Define a basic schema
schema = Schema({
    Required('name'): str,
    Required('age'): int,
    'email': str  # Optional field
})

# Validate data
data = {
    'name': 'John Doe',
    'age': 30,
    'email': '[email protected]'
}

validated_data = schema(data)
print(validated_data)

Types and Validation

from voluptuous import Schema, All, Length, Range

# Schema with constraints
schema = Schema({
    Required('username'): All(str, Length(min=3, max=20)),
    Required('age'): All(int, Range(min=0, max=150)),
    Required('score'): All(float, Range(min=0.0, max=100.0))
})

# Valid data
data = {
    'username': 'user123',
    'age': 25,
    'score': 85.5
}

validated = schema(data)

Nested Structures

from voluptuous import Schema, Required

# Nested schema
address_schema = Schema({
    Required('street'): str,
    Required('city'): str,
    Required('zipcode'): str
})

person_schema = Schema({
    Required('name'): str,
    Required('addresses'): [address_schema]  # List of addresses
})

# Validate
data = {
    'name': 'Jane Smith',
    'addresses': [
        {
            'street': '123 Main St',
            'city': 'New York',
            'zipcode': '10001'
        }
    ]
}

validated = person_schema(data)

Custom Validators

from voluptuous import Schema, Invalid
from datetime import datetime

# Custom validator function
def valid_date(date_string):
    try:
        date = datetime.strptime(date_string, '%Y-%m-%d')
        if date > datetime.now():
            raise Invalid('Date cannot be in the future')
        return date_string
    except ValueError:
        raise Invalid('Invalid date format (YYYY-MM-DD)')

# Using custom validator
schema = Schema({
    Required('name'): str,
    Required('birth_date'): valid_date
})

data = {'name': 'Alice Johnson', 'birth_date': '1990-05-15'}
validated = schema(data)

Error Handling

from voluptuous import Schema, Required, Invalid, MultipleInvalid

schema = Schema({
    Required('name'): str,
    Required('age'): int,
    Required('email'): str
})

# Data with errors
invalid_data = {
    'name': 123,  # Wrong type
    'age': 'thirty',  # Wrong type
    # Missing email
}

try:
    validated = schema(invalid_data)
except MultipleInvalid as e:
    print("Validation errors:")
    for error in e.errors:
        print(f"- {error.path}: {error.message}")

Advanced Example - API Input Validation

from voluptuous import Schema, Required, Optional, All, Length, Email, In

# Schema for API endpoint
user_registration_schema = Schema({
    Required('username'): All(str, Length(min=3, max=30)),
    Required('password'): All(str, Length(min=8)),
    Required('email'): Email(),
    Required('user_type'): In(['customer', 'vendor', 'admin']),
    Optional('phone'): All(str, Length(min=10, max=15)),
    Optional('preferences'): {
        'newsletter': bool,
        'notifications': bool,
        'language': In(['en', 'es', 'fr'])
    }
})

# Usage example
def register_user(request_data):
    try:
        # Validate data
        validated_data = user_registration_schema(request_data)
        
        # Process user registration here
        return {'status': 'success', 'data': validated_data}
    
    except MultipleInvalid as e:
        return {
            'status': 'error',
            'errors': [{'field': str(err.path[0]), 'message': err.msg} 
                      for err in e.errors]
        }