0
# Cerberus
1
2
Cerberus is a lightweight, extensible schema and data validation tool for Python dictionaries. It provides comprehensive validation capabilities including type checking, value constraints, custom validation rules, and document normalization with zero dependencies (except for Python <3.8 compatibility).
3
4
## Package Information
5
6
- **Package Name**: cerberus
7
- **Language**: Python
8
- **Installation**: `pip install cerberus`
9
10
## Core Imports
11
12
```python
13
from cerberus import Validator
14
```
15
16
Common pattern for basic validation:
17
18
```python
19
from cerberus import Validator, DocumentError, SchemaError
20
```
21
22
Advanced imports for custom types and error handling:
23
24
```python
25
from cerberus import (
26
Validator,
27
TypeDefinition,
28
schema_registry,
29
rules_set_registry
30
)
31
```
32
33
For error handling and tree navigation:
34
35
```python
36
from cerberus.errors import (
37
ValidationError,
38
ErrorList,
39
ErrorTree,
40
DocumentErrorTree,
41
SchemaErrorTree,
42
BasicErrorHandler,
43
ToyErrorHandler,
44
SchemaErrorHandler
45
)
46
```
47
48
For schema management and registries:
49
50
```python
51
from cerberus.schema import (
52
DefinitionSchema,
53
Registry,
54
SchemaRegistry,
55
RulesSetRegistry
56
)
57
```
58
59
For advanced customization:
60
61
```python
62
from cerberus.utils import validator_factory, readonly_classproperty
63
```
64
65
## Basic Usage
66
67
```python
68
from cerberus import Validator
69
70
# Simple validation with inline schema
71
schema = {'name': {'type': 'string'}, 'age': {'type': 'integer'}}
72
v = Validator(schema)
73
74
document = {'name': 'john', 'age': 30}
75
result = v.validate(document) # True
76
77
print(v.errors) # {} if valid
78
79
# Invalid document
80
invalid_doc = {'name': 123, 'age': 'thirty'}
81
v.validate(invalid_doc) # False
82
print(v.errors) # {'name': ['must be of string type'], 'age': ['must be of integer type']}
83
84
# Normalization and validation
85
normalized_doc = v.normalized(document)
86
print(normalized_doc) # Normalized version of document
87
```
88
89
## Architecture
90
91
Cerberus uses a flexible validation architecture built around several key components:
92
93
- **Validator**: The main validation engine that processes documents against schemas
94
- **Schema System**: Extensible schema definitions with rules, registries, and validation
95
- **Error System**: Comprehensive error reporting with customizable handlers and detailed feedback
96
- **Type System**: Extensible type definitions for custom validation logic
97
- **Normalization**: Document transformation and coercion capabilities
98
99
The library's design emphasizes extensibility through custom validators, type definitions, error handlers, and schema registries, making it suitable for both simple validation tasks and complex, domain-specific validation requirements.
100
101
## Capabilities
102
103
### Core Validation
104
105
Primary validation functionality using the Validator class for document validation, normalization, and error handling. Supports comprehensive validation rules, custom constraints, and flexible validation modes.
106
107
```python { .api }
108
class Validator:
109
def __init__(self, schema=None, ignore_none_values=False, allow_unknown=False,
110
require_all=False, purge_unknown=False, purge_readonly=False,
111
error_handler=None): ...
112
def validate(self, document, schema=None, update=False, normalize=True) -> bool: ...
113
def validated(self, *args, **kwargs): ...
114
def normalized(self, document, schema=None, always_return_document=False): ...
115
```
116
117
[Core Validation](./core-validation.md)
118
119
### Schema Management
120
121
Schema definition, validation, and storage system including registries for reusable schemas and rule sets. Provides structured schema validation and extensible schema definitions.
122
123
```python { .api }
124
class DefinitionSchema:
125
def __init__(self, validator, schema): ...
126
def validate(self, schema=None): ...
127
def update(self, schema): ...
128
129
class Registry:
130
def add(self, name, definition): ...
131
def get(self, name, default=None): ...
132
def extend(self, definitions): ...
133
```
134
135
[Schema Management](./schema-management.md)
136
137
### Error Handling
138
139
Comprehensive error representation, organization, and formatting system with customizable error handlers and detailed validation feedback.
140
141
```python { .api }
142
class ValidationError:
143
document_path: tuple
144
schema_path: tuple
145
code: int
146
rule: str
147
constraint: Any
148
value: Any
149
150
class BaseErrorHandler:
151
def __call__(self, errors): ...
152
def add(self, error): ...
153
def extend(self, errors): ...
154
```
155
156
[Error Handling](./error-handling.md)
157
158
### Type System
159
160
Custom type definition system for extending validation capabilities with domain-specific types and validation logic.
161
162
```python { .api }
163
TypeDefinition = namedtuple('TypeDefinition', 'name,included_types,excluded_types')
164
165
def validator_factory(name, bases=None, namespace={}): ...
166
```
167
168
[Type System](./type-system.md)
169
170
### Advanced Features
171
172
Advanced validation capabilities including normalization, custom validators, field dependencies, and complex validation scenarios.
173
174
```python { .api }
175
class Validator:
176
@property
177
def types_mapping(self): ...
178
@property
179
def validators(self): ...
180
@property
181
def coercers(self): ...
182
@property
183
def default_setters(self): ...
184
```
185
186
[Advanced Features](./advanced-features.md)
187
188
## Global Registry Instances
189
190
```python { .api }
191
schema_registry: SchemaRegistry
192
rules_set_registry: RulesSetRegistry
193
```
194
195
These global instances allow storing and retrieving schemas and rule sets by name throughout your application.
196
197
## Package Metadata
198
199
```python { .api }
200
__version__: str
201
```
202
203
The current version of the Cerberus package.
204
205
## Exception Classes
206
207
```python { .api }
208
class DocumentError(Exception): ...
209
class SchemaError(Exception): ...
210
```
211
212
Primary exceptions for document format issues and schema definition problems.