0
# Voluptuous
1

2
A Python data validation library designed for validating data coming into Python applications as JSON, YAML, and other formats. Voluptuous provides schema-based validation with support for complex nested data structures, comprehensive error reporting, and flexible validation composition.
3

4
## Package Information
5

6
- **Package Name**: voluptuous
7
- **Language**: Python
8
- **Installation**: `pip install voluptuous`
9

10
## Core Imports
11

12
```python
13
import voluptuous
14
```
15

16
Common patterns for schema validation:
17

18
```python
19
from voluptuous import Schema, Required, Optional, All, Any, Coerce
20
```
21

22
For specific validators:
23

24
```python
25
from voluptuous import Range, Length, Email, Url, Match, Boolean
26
```
27

28
For error handling:
29

30
```python
31
from voluptuous import Invalid, MultipleInvalid, SchemaError
32
```
33

34
## Basic Usage
35

36
```python
37
from voluptuous import Schema, Required, Optional, All, Any, Range, Length, Email
38

39
# Define a schema for user data
40
user_schema = Schema({
41
    Required('name'): All(str, Length(min=1, max=100)),
42
    Required('email'): Email(),
43
    Required('age'): All(int, Range(min=0, max=150)),
44
    Optional('website'): Any(None, Url()),
45
    Optional('tags', default=[]): [str],
46
})
47

48
# Validate data
49
user_data = {
50
    'name': 'John Doe',
51
    'email': 'john@example.com',
52
    'age': 30,
53
    'website': 'https://johndoe.com'
54
}
55

56
try:
57
    validated_data = user_schema(user_data)
58
    print(validated_data)
59
except Invalid as e:
60
    print(f"Validation error: {e}")
61
```
62

63
## Architecture
64

65
Voluptuous uses a composable validation system with three key concepts:
66

67
- **Schema**: The main validation framework that defines rules for data structures
68
- **Validators**: Composable functions and classes that validate specific aspects of data
69
- **Markers**: Special decorators for schema keys (Required, Optional, Exclusive, Inclusive)
70

71
This design enables complex validation rules through simple composition, supports nested data structures, provides detailed error reporting with path information, and allows custom validation logic integration.
72

73
## Capabilities
74

75
### Core Schema Framework
76

77
The foundational schema system for defining validation rules, handling required/optional fields, managing extra keys, and composing complex validation logic.
78

79
```python { .api }
80
class Schema:
81
    def __init__(self, schema, required=False, extra=PREVENT_EXTRA): ...
82
    def __call__(self, data): ...
83
    def extend(self, schema, required=None, extra=None): ...
84
    @classmethod
85
    def infer(cls, data, **kwargs): ...
86

87
class Required:
88
    def __init__(self, schema, msg=None, default=UNDEFINED, description=None): ...
89

90
class Optional:
91
    def __init__(self, schema, msg=None, default=UNDEFINED, description=None): ...
92

93
class Exclusive:
94
    def __init__(self, schema, group_of_exclusion, msg=None, description=None): ...
95

96
class Inclusive:
97
    def __init__(self, schema, group_of_inclusion, msg=None, description=None, default=UNDEFINED): ...
98
```
99

100
[Core Schema](./core-schema.md)
101

102
### Validation Composers
103

104
Logical composition of multiple validators using boolean-like operations (Any/Or, All/And), union types with discriminants, and flexible validation count requirements.
105

106
```python { .api }
107
class Any:
108
    def __init__(self, *validators, msg=None, required=False, discriminant=None): ...
109

110
class All:
111
    def __init__(self, *validators, msg=None, required=False, discriminant=None): ...
112

113
class Union:
114
    def __init__(self, *validators, msg=None, discriminant=None): ...
115

116
class SomeOf:
117
    def __init__(self, validators, min_valid=None, max_valid=None): ...
118
```
119

120
[Validation Composers](./validation-composers.md)
121

122
### Type Coercion & Conversion
123

124
Type conversion and coercion with error handling, truth value validation, and human-readable boolean conversion.
125

126
```python { .api }
127
class Coerce:
128
    def __init__(self, type, msg=None): ...
129

130
def Boolean(v): ...
131
def IsTrue(v): ...
132
def IsFalse(v): ...
133

134
def truth(f): ...
135
```
136

137
[Type Validators](./type-validators.md)
138

139
### String & Pattern Validation
140

141
Regular expression matching, string replacement, email and URL validation, file system path validation, and date/time format validation.
142

143
```python { .api }
144
class Match:
145
    def __init__(self, pattern, msg=None): ...
146

147
class Replace:
148
    def __init__(self, pattern, substitution, msg=None): ...
149

150
def Email(v): ...
151
def Url(v): ...
152
def FqdnUrl(v): ...
153
def IsFile(v): ...
154
def IsDir(v): ...
155
def PathExists(v): ...
156

157
class Datetime:
158
    def __init__(self, format=None, msg=None): ...
159

160
class Date:
161
    def __init__(self, format=None, msg=None): ...
162
```
163

164
[String & Pattern Validators](./string-pattern-validators.md)
165

166
### Range & Collection Validation
167

168
Numeric range validation, sequence length validation, membership testing, numeric precision validation, exact value matching, and complex sequence validation patterns.
169

170
```python { .api }
171
class Range:
172
    def __init__(self, min=None, max=None, min_included=True, max_included=True, msg=None): ...
173

174
class Length:
175
    def __init__(self, min=None, max=None, msg=None): ...
176

177
class In:
178
    def __init__(self, container, msg=None): ...
179

180
class Contains:
181
    def __init__(self, item, msg=None): ...
182

183
class ExactSequence:
184
    def __init__(self, validators, msg=None): ...
185

186
class Equal:
187
    def __init__(self, target, msg=None): ...
188

189
class Number:
190
    def __init__(self, precision=None, scale=None, msg=None, yield_decimal=False): ...
191
```
192

193
[Range & Collection Validators](./range-collection-validators.md)
194

195
### Utility Transformers
196

197
String transformation utilities, default value handling, value setting, and collection conversion utilities.
198

199
```python { .api }
200
def Lower(v): ...
201
def Upper(v): ...
202
def Capitalize(v): ...
203
def Title(v): ...
204
def Strip(v): ...
205

206
class DefaultTo:
207
    def __init__(self, default_value, msg=None): ...
208

209
class SetTo:
210
    def __init__(self, value): ...
211

212
class Set:
213
    def __init__(self, msg=None): ...
214
```
215

216
[Utility Transformers](./utility-transformers.md)
217

218
### Error Handling
219

220
Comprehensive exception hierarchy for validation errors with path tracking, multiple error aggregation, and detailed error reporting.
221

222
```python { .api }
223
class Invalid(Exception):
224
    def __init__(self, message, path=None, error_message=None, error_type=None): ...
225
    @property
226
    def msg(self): ...
227
    @property
228
    def path(self): ...
229
    def prepend(self, path): ...
230

231
class MultipleInvalid(Invalid):
232
    def __init__(self, errors=None): ...
233
    def add(self, error): ...
234
```
235

236
[Error Handling](./error-handling.md)
237

238
## Constants
239

240
```python { .api }
241
PREVENT_EXTRA = 0  # Disallow extra keys not in schema
242
ALLOW_EXTRA = 1    # Include extra keys in output  
243
REMOVE_EXTRA = 2   # Exclude extra keys from output
244
UNDEFINED = Undefined()  # Sentinel for undefined values
245
```
246

247
## Type Definitions
248

249
```python { .api }
250
Schemable = Union[
251
    Schema, Object,
252
    collections.abc.Mapping,
253
    list, tuple, frozenset, set,
254
    bool, bytes, int, str, float, complex,
255
    type, object, dict, None, Callable
256
]
257

258
DefaultFactory = Union[Undefined, Callable[[], Any]]
259
```