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
```