or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

basic-types.mdcompound-types.mdcontrib-modules.mddynamic-fields.mdexceptions.mdindex.mdmodels.mdnetwork-types.mdutilities.md
tile.json

tessl/pypi-schematics

Python Data Structures for Humans - a library for data validation and transformation using structured models

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/schematics@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-schematics@2.1.0

index.mddocs/

Schematics

A Python library for data validation and transformation using structured models. Schematics provides a type system for defining data structures with field-level validation, format conversion, and comprehensive error handling - enabling developers to build robust APIs, data processors, and validation systems without database dependencies.

Package Information

  • Package Name: schematics
  • Language: Python
  • Installation: pip install schematics

Core Imports

from schematics.models import Model

Common for working with field types:

from schematics.types import StringType, IntType, DateTimeType, ListType, ModelType

For error handling:

from schematics.exceptions import ValidationError, ConversionError

Basic Usage

from schematics.models import Model
from schematics.types import StringType, IntType, DateTimeType, EmailType

# Define a data model
class User(Model):
    name = StringType(required=True, max_length=100)
    email = EmailType(required=True)
    age = IntType(min_value=0, max_value=120)
    created_at = DateTimeType()

# Create an instance and validate data
user_data = {
    'name': 'John Doe',
    'email': 'john@example.com',
    'age': 30
}

user = User(user_data)
user.validate()  # Raises ValidationError if invalid

# Convert to different formats
native_dict = user.to_native()      # Python objects  
primitive_dict = user.to_primitive() # JSON-serializable

# Export with field filtering
filtered = user.export(fields=['name', 'email'])

Architecture

Schematics uses a field-based type system built around several core concepts:

  • Model: Container class defining data structure with fields and validation rules
  • Field Types: Typed field classes handling conversion, validation, and serialization
  • Validation System: Multi-level validation with field and model-level rules
  • Export System: Flexible data serialization with filtering and format control
  • Exception Hierarchy: Structured error handling with detailed validation feedback

This design enables schematics to serve as a validation layer for APIs, data pipelines, configuration systems, and any application requiring structured data handling without database coupling.

Capabilities

Model System

Core model definition and data management functionality including model creation, field registration, data import/export, and validation orchestration.

class Model:
    def __init__(self, raw_data=None, **context)
    def validate(self, **context)
    def import_data(self, raw_data, **context)  
    def export(self, fields=None, exclude=None, **context)
    def to_native(self)
    def to_primitive(self)

Model System

Basic Field Types

Essential field types for common data including strings, numbers, dates, booleans, and specialized types like UUIDs and hashes with comprehensive validation options.

class StringType(BaseType):
    def __init__(self, regex=None, max_length=None, min_length=None, **kwargs)

class IntType(BaseType):
    def __init__(self, min_value=None, max_value=None, **kwargs)
    
class DateTimeType(BaseType):
    def __init__(self, formats=None, **kwargs)
    
class BooleanType(BaseType):
    def __init__(self, **kwargs)

Basic Field Types

Compound Field Types

Advanced field types for complex data structures including lists, dictionaries, nested models, and polymorphic model fields with recursive validation.

class ListType(BaseType):
    def __init__(self, field, min_size=None, max_size=None, **kwargs)
    
class DictType(BaseType):
    def __init__(self, field=None, **kwargs)
    
class ModelType(BaseType):
    def __init__(self, model_class, **kwargs)
    
class PolyModelType(BaseType):
    def __init__(self, model_spec, **kwargs)

Compound Field Types

Network Field Types

Specialized field types for network-related data including URLs, email addresses, IP addresses, and MAC addresses with protocol-specific validation.

class URLType(BaseType):
    def __init__(self, verify_exists=False, **kwargs)
    
class EmailType(BaseType):
    def __init__(self, **kwargs)
    
class IPAddressType(BaseType):
    def __init__(self, **kwargs)

Network Field Types

Exception System

Comprehensive exception hierarchy for handling validation errors, conversion failures, and data processing issues with detailed error information and field-level granularity.

class ValidationError(FieldError):
    def __init__(self, message, **kwargs)
    
class ConversionError(FieldError):
    def __init__(self, message, **kwargs)
    
class DataError(BaseError):
    def __init__(self, errors, partial_data=None, **kwargs)

Exception System

Dynamic Fields

Advanced field functionality including serializable computed fields, calculated properties, and dynamic field generation for flexible data modeling.

def serializable(func=None, **field_kwargs)
def calculated(func, **field_kwargs)

class Serializable:
    def __init__(self, **kwargs)

Dynamic Fields

Utilities and Helpers

Utility classes and functions supporting Schematics functionality including role-based field filtering, validation helpers, and collection utilities.

class Role(Set):
    def __init__(self, function, fields)

def import_string(import_name)
def listify(value)
def get_ident()
class Constant(int)

Utilities and Helpers

Contrib Modules

Additional field types and utilities provided as contrib modules including MongoDB integration, enum support, and state machine functionality.

class ObjectIdType(BaseType):  # MongoDB ObjectId support
    def __init__(self, auto_fill=False, **kwargs)

class EnumType(BaseType):  # Python enum support  
    def __init__(self, enum, use_values=False, **kwargs)

class Machine:  # Simple state machine
    def __init__(self, data, *args)

Contrib Modules

Types

# Export control constants
NATIVE: int = 0        # Native Python objects
PRIMITIVE: int = 1     # JSON-serializable primitives  
DROP: int = 0         # Drop/exclude fields
NONEMPTY: int = 1     # Only non-empty fields
NOT_NONE: int = 2     # Only non-None fields
DEFAULT: int = 10     # Default export behavior
ALL: int = 99         # Export all fields

# Context and validation types
class Context:
    def __init__(self, **kwargs)
    
class ValidationContext:
    def __init__(self, **kwargs)

# Special value representing undefined field state
class Undefined:
    """Sentinel value representing undefined/unset field state."""
    pass