Validation & Matching

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_cli/_utilities/validation.py
• src/flext_cli/_utilities/matching.py
• examples/ex_12_pydantic_driven_cli.py
• tests/unit/test_matching_cov.py
• tests/unit/test_constants.py
• tests/unit/_cases/test_rules_cov/testsflextclirulescov_part_04.py

Validation and Matching within the flext-cli project provide a robust framework for ensuring data integrity and identifying specific string patterns or errors. This system leverages Pydantic for schema-driven validation and regex-based matching for CLI-specific output analysis, such as identifying "File Not Found" errors or "Usage" discrepancies.

The system is designed to work within a "Railway Pattern" using p.Result and r result contracts, allowing for fallible flows that either succeed with a value or fail with a descriptive error. This ensures that CLI applications can handle invalid input, missing files, or business rule violations gracefully.
Sources: examples/ex_12_pydantic_driven_cli.py:1-40, examples/README.md:1-20

Validation Architecture

Validation in flext-cli is primarily driven by Pydantic models, which handle type conversion, required field checks, and business rule enforcement. The workflow typically involves normalizing raw CLI input into a JSON-compatible mapping before validating it against a typed model.

Railway Validation Flow

The validation process follows a sequential pipeline where each step must succeed for the next to execute. If any step fails, the error is propagated through the Result object.

This diagram illustrates the multi-stage validation pipeline used to convert raw input into a trusted configuration object.
Sources: examples/ex_12_pydantic_driven_cli.py:53-100

Key Validation Components

Component	Responsibility	Source File
validate_required_fields	Checks presence of mandatory keys in a mapping.	ex_12_pydantic_driven_cli.py:103-116
convert_and_validate_with_pydantic	Uses model_validate for schema and type enforcement.	ex_12_pydantic_driven_cli.py:119-130
validate_business_rules	Enforces complex logic (e.g., port overrides for SSL).	ex_12_pydantic_driven_cli.py:133-143
rules_validate_matcher	Validates JSON configurations against specific rule matchers.	testsflextclirulescov_part_04.py:11-30

Pattern Matching & Error Classification

The matching system provides utilities for string analysis, specifically targeting common CLI scenarios like usage errors or missing files. It supports simple substring matching and complex regular expressions.

Matching Utilities

The FlextCliUtilitiesMatching class (referenced via u.Cli in tests) provides the core logic for identifying patterns in CLI output or user messages.

• Simple Matching: Case-insensitive substring searches across multiple patterns.
• Regex Matching: Evaluates strings against compiled regular expression authorities.
• Error Classification: Pre-defined regexes for identifying file_not_found_error and cli_usage_error.

This flow shows how the matching utilities determine if a message satisfies specific criteria.
Sources: tests/unit/test_matching_cov.py:18-70, tests/unit/test_constants.py:110-120

Standardized Error Matchers

The project uses compiled regexes to classify representative CLI messages, ensuring consistent error handling across the platform.

Matcher Function	Patterns Detected
file_not_found_error	"No such file or directory", "FileNotFoundError", etc.
cli_usage_error	"Missing option", "Got unexpected extra arguments", "No such option".
matches	Arbitrary user-defined substring patterns.
Sources: tests/unit/test_matching_cov.py:58-70, tests/_constants_parts/tests_yaml_output.py:43-60

Implementation Example: Pydantic Validation

The following snippet demonstrates the integration of Pydantic validation within the CLI pipeline, utilizing the Result contract to handle validation failures.

def convert_and_validate_with_pydantic(
    data: t.JsonMapping,
) -> p.Result[m.Examples.AdvancedDatabaseConfig]:
    """Convert raw data to validated Pydantic model."""
    try:
        return r[m.Examples.AdvancedDatabaseConfig].ok(
            m.Examples.AdvancedDatabaseConfig.model_validate(
                data,
            ),
        )
    except c.ValidationError as error:
        return r[m.Examples.AdvancedDatabaseConfig].fail(
            f"Pydantic validation failed: {error}",
        )

Sources: examples/ex_12_pydantic_driven_cli.py:119-130

Summary

Validation & Matching in flext-cli provides a dual-layer approach to data integrity. Structured validation via Pydantic ensures that internal models and configurations are strictly typed and logically sound. Complementary matching utilities allow the CLI to interact intelligently with external system output and user input by classifying errors and patterns using standardized regex authorities.