or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcompatibility.mdcore-validation.mderror-handling.mdindex.mdschema-rules.mdtype-system.md
tile.json

tessl/pypi-pykwalify

Python lib/cli for JSON/YAML schema validation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pykwalify@1.8.x

To install, run

npx @tessl/cli install tessl/pypi-pykwalify@1.8.0

index.mddocs/

PyKwalify

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.

Package Information

  • Package Name: pykwalify
  • Package Type: pypi
  • Language: Python
  • Installation: pip install pykwalify

Core Imports

from pykwalify.core import Core

For error handling:

from pykwalify.errors import SchemaError, CoreError

For type checking utilities:

from pykwalify.types import is_string, is_int, is_float

For compatibility utilities (cross-version support):

from pykwalify.compat import yml, basestring, unicode

Basic Usage

from pykwalify.core import Core
from pykwalify.errors import SchemaError

# File-based validation
try:
    c = Core(source_file="data.yaml", schema_files=["schema.yaml"])
    c.validate(raise_exception=True)
    print("Validation successful!")
except SchemaError as e:
    print(f"Schema validation failed: {e}")

# Data-based validation
data = {"name": "John", "age": 30}
schema = {"type": "map", "mapping": {"name": {"type": "str"}, "age": {"type": "int"}}}

c = Core(source_data=data, schema_data=schema)
is_valid = c.validate(raise_exception=False)
print(f"Data valid: {is_valid}")

Architecture

PyKwalify uses a rule-based validation system built around several key components:

  • Core: The main validation engine that processes data against schema rules
  • Rule: Individual schema rule objects that define validation constraints
  • Types System: Comprehensive type checking and validation functions
  • Error Hierarchy: Structured exception system for detailed error reporting

The library supports both programmatic validation through the Python API and command-line validation through the pykwalify CLI tool.

Capabilities

Core Validation

The main validation functionality through the Core class, supporting both file-based and data-based validation with comprehensive error reporting and flexible configuration options.

class Core:
    def __init__(
        self,
        source_file=None,
        schema_files=None,
        source_data=None,
        schema_data=None,
        extensions=None,
        strict_rule_validation=False,
        fix_ruby_style_regex=False,
        allow_assertions=False,
        file_encoding=None,
        schema_file_obj=None,
        data_file_obj=None
    ): ...
    
    def validate(self, raise_exception=True): ...

Core Validation

Schema Rules

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.

class Rule:
    def __init__(self, schema=None, parent=None, strict_rule_validation=False): ...
    def init(self, schema, path): ...
    def keywords(self): ...

Schema Rules

Type System

Comprehensive type checking and validation utilities for all supported data types including scalars, collections, timestamps, dates, emails, and URLs with built-in validation functions.

def is_string(obj): ...
def is_int(obj): ...
def is_float(obj): ...
def is_number(obj): ...
def is_bool(obj): ...
def is_timestamp(obj): ...
def is_date(obj): ...
def is_email(obj): ...
def is_url(obj): ...

Type System

Error Handling

Structured exception hierarchy with specific error types for different validation failures, providing detailed error messages and validation paths for debugging and error reporting.

class PyKwalifyException(RuntimeError): ...
class SchemaError(PyKwalifyException): ...
class CoreError(PyKwalifyException): ...
class RuleError(PyKwalifyException): ...
class NotMappingError(PyKwalifyException): ...
class NotSequenceError(PyKwalifyException): ...
class SchemaConflict(PyKwalifyException): ...

Error Handling

Command Line Interface

CLI functionality for validating YAML/JSON files from the command line with support for extensions, encoding options, and various validation flags.

def parse_cli(): ...
def run(cli_args): ...
def cli_entrypoint(): ...

Command Line Interface

Compatibility Layer

Cross-version compatibility utilities for Python 2/3 support and consistent YAML processing across different library versions.

yml: ruamel.yaml.YAML  # Global YAML loader instance
basestring: type       # Base string type (cross-version)
unicode: type          # Unicode string type (cross-version)
def u(x): ...          # Convert to unicode
def b(x): ...          # Convert to bytes
def nativestr(x): ...  # Convert to native string

Compatibility Layer

Package Utilities

Logging Configuration

def init_logging(log_level):
    """
    Initialize logging settings with default set to INFO.
    
    Args:
        log_level (int): Log level from 0-5 where 5=DEBUG, 4=INFO, 3=WARNING, 2=ERROR, 1=CRITICAL, 0=INFO
    """

Global Variables

__version__: str  # Package version string
__version_info__: tuple  # Version tuple
partial_schemas: dict  # Global partial schema storage
log_level_to_string_map: dict  # Log level mapping