0
# PyKwalify
1
2
A comprehensive Python library for YAML and JSON schema validation, serving as a port of the Java Kwalify framework with significant added functionality. It enables developers to define validation schemas and validate data files against those schemas through both a Python API and command-line interface, supporting complex validation rules including type checking, sequence validation, mapping validation, and custom constraints.
3
4
## Package Information
5
6
- **Package Name**: pykwalify
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install pykwalify`
10
11
## Core Imports
12
13
```python
14
from pykwalify.core import Core
15
```
16
17
For error handling:
18
19
```python
20
from pykwalify.errors import SchemaError, CoreError
21
```
22
23
For type checking utilities:
24
25
```python
26
from pykwalify.types import is_string, is_int, is_float
27
```
28
29
For compatibility utilities (cross-version support):
30
31
```python
32
from pykwalify.compat import yml, basestring, unicode
33
```
34
35
## Basic Usage
36
37
```python
38
from pykwalify.core import Core
39
from pykwalify.errors import SchemaError
40
41
# File-based validation
42
try:
43
c = Core(source_file="data.yaml", schema_files=["schema.yaml"])
44
c.validate(raise_exception=True)
45
print("Validation successful!")
46
except SchemaError as e:
47
print(f"Schema validation failed: {e}")
48
49
# Data-based validation
50
data = {"name": "John", "age": 30}
51
schema = {"type": "map", "mapping": {"name": {"type": "str"}, "age": {"type": "int"}}}
52
53
c = Core(source_data=data, schema_data=schema)
54
is_valid = c.validate(raise_exception=False)
55
print(f"Data valid: {is_valid}")
56
```
57
58
## Architecture
59
60
PyKwalify uses a rule-based validation system built around several key components:
61
62
- **Core**: The main validation engine that processes data against schema rules
63
- **Rule**: Individual schema rule objects that define validation constraints
64
- **Types System**: Comprehensive type checking and validation functions
65
- **Error Hierarchy**: Structured exception system for detailed error reporting
66
67
The library supports both programmatic validation through the Python API and command-line validation through the `pykwalify` CLI tool.
68
69
## Capabilities
70
71
### Core Validation
72
73
The main validation functionality through the Core class, supporting both file-based and data-based validation with comprehensive error reporting and flexible configuration options.
74
75
```python { .api }
76
class Core:
77
def __init__(
78
self,
79
source_file=None,
80
schema_files=None,
81
source_data=None,
82
schema_data=None,
83
extensions=None,
84
strict_rule_validation=False,
85
fix_ruby_style_regex=False,
86
allow_assertions=False,
87
file_encoding=None,
88
schema_file_obj=None,
89
data_file_obj=None
90
): ...
91
92
def validate(self, raise_exception=True): ...
93
```
94
95
[Core Validation](./core-validation.md)
96
97
### Schema Rules
98
99
Schema rule definition and management through the Rule class, providing the building blocks for creating complex validation schemas with type constraints, length validation, pattern matching, and custom validation functions.
100
101
```python { .api }
102
class Rule:
103
def __init__(self, schema=None, parent=None, strict_rule_validation=False): ...
104
def init(self, schema, path): ...
105
def keywords(self): ...
106
```
107
108
[Schema Rules](./schema-rules.md)
109
110
### Type System
111
112
Comprehensive type checking and validation utilities for all supported data types including scalars, collections, timestamps, dates, emails, and URLs with built-in validation functions.
113
114
```python { .api }
115
def is_string(obj): ...
116
def is_int(obj): ...
117
def is_float(obj): ...
118
def is_number(obj): ...
119
def is_bool(obj): ...
120
def is_timestamp(obj): ...
121
def is_date(obj): ...
122
def is_email(obj): ...
123
def is_url(obj): ...
124
```
125
126
[Type System](./type-system.md)
127
128
### Error Handling
129
130
Structured exception hierarchy with specific error types for different validation failures, providing detailed error messages and validation paths for debugging and error reporting.
131
132
```python { .api }
133
class PyKwalifyException(RuntimeError): ...
134
class SchemaError(PyKwalifyException): ...
135
class CoreError(PyKwalifyException): ...
136
class RuleError(PyKwalifyException): ...
137
class NotMappingError(PyKwalifyException): ...
138
class NotSequenceError(PyKwalifyException): ...
139
class SchemaConflict(PyKwalifyException): ...
140
```
141
142
[Error Handling](./error-handling.md)
143
144
### Command Line Interface
145
146
CLI functionality for validating YAML/JSON files from the command line with support for extensions, encoding options, and various validation flags.
147
148
```python { .api }
149
def parse_cli(): ...
150
def run(cli_args): ...
151
def cli_entrypoint(): ...
152
```
153
154
[Command Line Interface](./cli.md)
155
156
### Compatibility Layer
157
158
Cross-version compatibility utilities for Python 2/3 support and consistent YAML processing across different library versions.
159
160
```python { .api }
161
yml: ruamel.yaml.YAML # Global YAML loader instance
162
basestring: type # Base string type (cross-version)
163
unicode: type # Unicode string type (cross-version)
164
def u(x): ... # Convert to unicode
165
def b(x): ... # Convert to bytes
166
def nativestr(x): ... # Convert to native string
167
```
168
169
[Compatibility Layer](./compatibility.md)
170
171
## Package Utilities
172
173
### Logging Configuration
174
175
```python { .api }
176
def init_logging(log_level):
177
"""
178
Initialize logging settings with default set to INFO.
179
180
Args:
181
log_level (int): Log level from 0-5 where 5=DEBUG, 4=INFO, 3=WARNING, 2=ERROR, 1=CRITICAL, 0=INFO
182
"""
183
```
184
185
### Global Variables
186
187
```python { .api }
188
__version__: str # Package version string
189
__version_info__: tuple # Version tuple
190
partial_schemas: dict # Global partial schema storage
191
log_level_to_string_map: dict # Log level mapping
192
```