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.