validate-nested 0.1.0__py3-none-any.whl

validate_nested/__init__.py

@@ -0,0 +1,36 @@
+"""validate-nested — a tiny, framework-agnostic DSL for validating the shape of
+nested dicts / JSON responses.
+
+    from validate_nested import validate
+    from validate_nested.lambdas import equal, length, empty
+
+    model = {
+        "ids": (list, length(3)),
+        "ids[*]": dict,
+        "state": (str, equal("ok")),
+        "message": empty(str),
+        "error_code": (int, equal(0)),
+    }
+
+    r = validate(response, model)        # -> Result(ok, failures, skipped)
+    assert r.ok, r.report()              # idiomatic immediate check
+"""
+from validate_nested.engine import validate
+from validate_nested.result import Failure, Result, format_failure, render_failures
+from validate_nested.rules import ComplexRule
+from validate_nested.soft import SoftValidator
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "validate",
+    "SoftValidator",
+    "Result",
+    "Failure",
+    "format_failure",
+    "render_failures",
+    "ComplexRule",
+    "lambdas",
+]
+
+from validate_nested import lambdas  # noqa: E402  (re-exported for convenience)

validate_nested/_utils/__init__.py

@@ -0,0 +1,3 @@
+from validate_nested._utils.paths import dict_paths, path_getter, stringify_dict
+
+__all__ = ["dict_paths", "path_getter", "stringify_dict"]

validate_nested/_utils/paths.py

@@ -0,0 +1,66 @@
+"""Small dict/path helpers copied (and trimmed) from the original framework so the
+library carries no external dependencies."""
+import re
+
+
+def dict_paths(d):
+    """Yield every leaf/branch path in a nested dict/list as a dotted string,
+    e.g. {"a": [{"b": 1}]} -> "a", "a[0]", "a[0].b"."""
+    q = [(d, [])]
+    while q:
+        n, p = q.pop(0)
+        if p:
+            yield ".".join(map(str, p))
+        if isinstance(n, dict):
+            for k, v in n.items():
+                q.append((v, p + [k]))
+        elif isinstance(n, list):
+            for i, v in enumerate(n):
+                q.append((v, p + ["[" + str(i) + "]"]))
+
+
+def path_getter(record, path, default=None):
+    """Resolve a dotted/indexed path inside a nested dict/list, returning `default`
+    if any segment is missing. Supports list indices: "a.b[0].c"."""
+    if default is None:
+        default = {}
+    path_parts = [part for part in re.split(r"[\.\[\]]+", path) if part]
+    value = record
+    for part in path_parts:
+        if isinstance(value, list) and part.isdigit():
+            idx = int(part)
+            if -len(value) <= idx < len(value):
+                value = value[idx]
+            else:
+                return default
+        elif isinstance(value, dict):
+            value = value.get(part, default)
+        else:
+            return default
+        if value == default:
+            return default
+    return value
+
+
+def stringify_dict(d):
+    """Recursively stringify every leaf of a dict/list (lambdas are shortened to their
+    `<lambda>` head). Used to render rule/validation details safely."""
+    if isinstance(d, dict):
+        for k, v in d.items():
+            if isinstance(v, (dict, list)):
+                d[k] = stringify_dict(v)
+            else:
+                if "<lambda>" in str(v):
+                    d[k] = str(v).split("<lambda>")[0] + "<lambda>"
+                else:
+                    d[k] = str(v)
+    elif isinstance(d, list):
+        for i, v in enumerate(d):
+            if isinstance(v, (dict, list)):
+                d[i] = stringify_dict(v)
+            else:
+                if "<lambda>" in str(v):
+                    d[i] = str(v).split("<lambda>")[0] + "<lambda>"
+                else:
+                    d[i] = str(v)
+    return d

validate_nested/engine.py

@@ -0,0 +1,204 @@
+"""The validation engine.
+
+``validate(record, model)`` walks the model, runs every rule against the record and
+returns a :class:`Result` — it never raises or asserts. Callers decide what to do::
+
+    r = validate(record, model)
+    assert r.ok, r.report()
+"""
+import logging
+
+from validate_nested._utils.paths import path_getter
+from validate_nested.result import Failure, Result
+from validate_nested.rules import (
+    ComplexRule,
+    NotExists,
+    convert_paths_to_template,
+    process_validation_rules,
+)
+
+log = logging.getLogger("validate_nested")
+
+
+def _type_name(t):
+    """Readable type name(s): dict -> 'dict', (int, str) -> 'int or str'."""
+    if isinstance(t, tuple):
+        return " or ".join(getattr(x, "__name__", str(x)) for x in t)
+    return getattr(t, "__name__", str(t))
+
+
+class SkipSignal(Exception):
+    """Raised internally when a ``skip()``-marked rule fails. ``validate`` catches it
+    and turns it into ``Result.skipped`` — the engine itself never skips anything."""
+
+
+class _Checker:
+    """Validates a single (type_hint, path) pair against one record. Collects failures
+    into ``self.failures`` instead of asserting."""
+
+    def __init__(self, value, record, **kwargs):
+        self.record = record
+        self.failures = []
+
+        # boolean rules from the model body
+        self._opt = kwargs.pop("opt", None)
+        self._required = kwargs.pop("required", None)
+        self._not_exist = kwargs.pop("not_exist", None)
+        self._undefined = kwargs.pop("undefined", None)
+        self._empty = kwargs.pop("empty", None)
+        self._not_empty = kwargs.pop("not_empty", None)
+        self._skip = kwargs.pop("skip", None)
+        self.validators = kwargs.pop("validators", [])
+
+        # options
+        self._additional_assert_msg = kwargs.pop("add_msg", None)
+        self._replace_assert_msg = kwargs.pop("assert_msg", "")
+        self._to_int = kwargs.pop("to_int", None)
+        self._to_float = kwargs.pop("to_float", None)
+        # any leftover kwargs are ignored (host-specific context)
+
+        self.type_hint, self.original_path = value
+        self.exist = True
+        self.value = path_getter(self.record, self.original_path, default=NotExists())
+
+    def _message(self, default):
+        if self._replace_assert_msg:
+            return self._replace_assert_msg
+        if self._additional_assert_msg:
+            return f"{self._additional_assert_msg}, {default}"
+        return default
+
+    def _check(self, default, condition):
+        if condition:
+            return
+        msg = self._message(default)
+        if self._skip:
+            raise SkipSignal(msg)
+        self.failures.append(Failure(path=self.original_path, message=msg))
+
+    def _has_failures(self):
+        return bool(self.failures)
+
+    def process(self):
+        value = self.value
+
+        if isinstance(value, NotExists):
+            self.exist = False
+
+        # rule: not_exist() — the path must be absent
+        if self._not_exist:
+            self._check(
+                default=f"must be absent, got {_type_name(type(value))}",
+                condition=isinstance(value, NotExists),
+            )
+            return not self._has_failures()
+
+        # rule: opt() — absent value is acceptable (unless required is also set)
+        if self._opt and isinstance(value, NotExists):
+            return not self._required
+
+        # type check
+        if isinstance(value, NotExists):
+            assert_type_msg = "is missing"
+        else:
+            assert_type_msg = f"expected {_type_name(self.type_hint)}, got {_type_name(type(value))}"
+
+        self._check(default=assert_type_msg, condition=isinstance(value, self.type_hint))
+
+        # if a double type was given, narrow the type hint to the actual type for len checks
+        if isinstance(self.type_hint, tuple):
+            self.type_hint = type(value)
+
+        # length checks (only for sized types that actually exist)
+        if (
+            self.exist
+            and self.type_hint in (list, dict, str)
+            and isinstance(value, self.type_hint)
+        ):
+            if self._empty:
+                self._check(
+                    default=f"expected empty, got length {len(value)}",
+                    condition=(len(value) == 0),
+                )
+            if self._not_empty:
+                self._check(
+                    default="expected non-empty, got empty",
+                    condition=(len(value) > 0),
+                )
+            if self._undefined and len(value) == 0:
+                self.exist = False
+
+        # validators ('lambdas') — only when the value exists
+        if self.exist and self.validators:
+            for lambda_info in self.validators:
+                current_length = len(lambda_info)
+                lambda_info.extend([""] * (3 - current_length))
+                _lambda, lambda_assert_msg, _lambda_details = lambda_info
+
+                template_value = value
+                try:
+                    if self._to_int:
+                        template_value = int(value)
+                    if self._to_float:
+                        template_value = float(value)
+                    result = _lambda(template_value)
+                except Exception as error:
+                    error_msg = f"{lambda_assert_msg} — error on {template_value!r}: {error}"
+                    self._check(default=error_msg, condition=(not error))
+                else:
+                    if _lambda.__qualname__.startswith("length.<locals>.<lambda>"):
+                        lambda_msg = f"{lambda_assert_msg}, got length {len(template_value)}"
+                    else:
+                        lambda_msg = f"{lambda_assert_msg}, got {template_value!r}"
+                    self._check(default=lambda_msg, condition=result)
+
+        return self.exist and not self._has_failures()
+
+
+def validate(record, model, **options):
+    """Validate ``record`` against ``model`` and return a :class:`Result`.
+
+    Never raises (except ``ValueError`` on an empty model). All failed checks are
+    collected into ``result.failures``; ``result.ok`` is True iff nothing failed.
+    A fired ``skip()`` rule short-circuits and sets ``result.skipped``.
+    """
+    if not model:
+        raise ValueError("model cannot be empty")
+
+    log.debug("validating against model: %r", model)
+
+    t_dict = convert_paths_to_template(record)
+    failures = []
+
+    for template_path, rules in model.items():
+        path_options = dict(options)
+        if isinstance(rules, ComplexRule):
+            path_options.update(rules.options)
+            rules = rules.value
+
+        type_hint, validators, rule_options = process_validation_rules(rules)
+        rule_options.update(path_options)
+
+        # expand a wildcard template (ids[*]) to every concrete path, else use as-is
+        concrete_paths = t_dict.get(template_path) or [template_path]
+
+        path_ok = True
+        for concrete_path in concrete_paths:
+            checker = _Checker(
+                value=(type_hint, concrete_path),
+                record=record,
+                validators=validators,
+                **rule_options,
+            )
+            try:
+                path_result = checker.process()
+            except SkipSignal as signal:
+                return Result(ok=not failures, failures=failures, skipped=str(signal))
+            failures.extend(checker.failures)
+            path_ok = path_ok and path_result
+
+        # required + failed: stop and don't run the remaining model keys
+        if rule_options.get("required") and not path_ok:
+            break
+
+    return Result(ok=not failures, failures=failures)

validate_nested/lambdas.py

@@ -0,0 +1,216 @@
+"""The validator DSL.
+
+Two kinds of helpers:
+
+* string-marker rules (``empty``, ``opt``, ``required``, ``skip`` ...) — return a
+  tuple whose first item is a marker string the engine recognises;
+* value validators (``length``, ``equal``, ``approx`` ...) — return a ``LambdaInfo``
+  carrying the check plus a short reason used when it fails. The engine appends the
+  actual value, e.g. ``should be equal to 'ok', got 'err'``.
+
+Used inside a model:: ``{"ids": (list, length(3)), "state": (str, equal("ok"))}``.
+"""
+from collections import namedtuple
+
+
+class LambdaInfo(
+    namedtuple("LambdaInfo", ("func_lambda", "lambda_assert_msg", "lambda_details"))
+):
+    def __repr__(self):
+        return f"{self.lambda_details}"
+
+
+def predicate(func, message, name=None):
+    """Build a one-off custom validator from any callable ``value -> bool``.
+
+    The engine appends ``, got <value>`` to ``message`` on failure::
+
+        is_even = predicate(lambda v: v % 2 == 0, "should be even")
+        model = {"count": (int, is_even)}        # fails as: should be even, got 3
+
+    ``func`` may be a lambda or a plain function — it's wrapped internally so the engine
+    always recognises it as a validator. For a reusable/parametrised validator, write a
+    function that returns a ``LambdaInfo`` directly (that's how the built-ins are made).
+    """
+    return LambdaInfo(
+        func_lambda=lambda v: func(v),
+        lambda_assert_msg=message,
+        lambda_details=name or getattr(func, "__name__", "predicate"),
+    )
+
+
+# ── string-marker (boolean) rules ──────────────────────────────────────────────
+def to_int(*args):
+    return "to_int", *args
+
+
+def to_float(*args):
+    return "to_float", *args
+
+
+def undefined(*args):
+    return "undefined", *args
+
+
+def empty(*args):
+    return "empty", *args
+
+
+def not_empty(*args):
+    return "not_empty", *args
+
+
+def opt(*args):
+    return "opt", *args
+
+
+def skip(*args):
+    return "skip", *args
+
+
+def not_exist(*args):
+    return "not_exist", *args
+
+
+def required(*args):
+    return "required", *args
+
+
+# ── value validators (parametrised) ────────────────────────────────────────────
+def length(size: int):
+    return LambdaInfo(
+        func_lambda=lambda v: len(v) == size,
+        lambda_assert_msg=f"should have length {size}",
+        lambda_details=f"{length.__name__}({size}): lambda v: len(v) == {size}",
+    )
+
+
+def equal(value):
+    return LambdaInfo(
+        func_lambda=lambda v: v == value,
+        lambda_assert_msg=f"should be equal to {value!r}",
+        lambda_details=f"{equal.__name__}({value}): lambda v: v == {value}",
+    )
+
+
+def lower_match(value):
+    return LambdaInfo(
+        func_lambda=lambda v: v.lower() == value.lower(),
+        lambda_assert_msg=f"should be equal to {value!r} (case-insensitive)",
+        lambda_details=f"{lower_match.__name__}({value.lower()}): lambda v: v.lower() == {value.lower()}",
+    )
+
+
+def not_equal(value):
+    return LambdaInfo(
+        func_lambda=lambda v: v != value,
+        lambda_assert_msg=f"should not be equal to {value!r}",
+        lambda_details=f"{not_equal.__name__}({value}): lambda v: v != {value}",
+    )
+
+
+def approx(value, delta=0.01):
+    return LambdaInfo(
+        # |v - value| <= delta (same semantics as the original pytest.approx(abs=delta),
+        # but with no test-framework dependency)
+        func_lambda=lambda v: abs(v - value) <= delta,
+        lambda_assert_msg=f"should be approximately {value} (±{delta})",
+        lambda_details=f"{approx.__name__}({value}): lambda v: abs(v - {value}) <= {delta}",
+    )
+
+
+def count(value, amount):
+    return LambdaInfo(
+        func_lambda=lambda v: v.count(value) == amount,
+        lambda_assert_msg=f"should contain {value!r} exactly {amount} time(s)",
+        lambda_details=f"{count.__name__}({value}): lambda v: v.count({value}) == {amount}",
+    )
+
+
+def exists_in(value):
+    return LambdaInfo(
+        func_lambda=lambda v: v in value,
+        lambda_assert_msg=f"should be one of {list(value)}",
+        lambda_details=f"{exists_in.__name__}({value}): lambda v: v in {value}",
+    )
+
+
+def contains(value):
+    if isinstance(value, str):
+        return LambdaInfo(
+            func_lambda=lambda v: value in v,
+            lambda_assert_msg=f"should contain {value!r}",
+            lambda_details=f"{contains.__name__}({value}): lambda v: {value} in v",
+        )
+    elif isinstance(value, list):
+        return LambdaInfo(
+            func_lambda=lambda v: all(elem in v for elem in value),
+            lambda_assert_msg=f"should contain all of {value}",
+            lambda_details=f"{contains.__name__}({value}): lambda v: all(elem in v for elem in {value})",
+        )
+
+
+def ends(value):
+    return LambdaInfo(
+        func_lambda=lambda v: v.endswith(value),
+        lambda_assert_msg=f"should end with {value!r}",
+        lambda_details=f"{ends.__name__}({value}): lambda v: v.endswith(value)",
+    )
+
+
+def in_range(start, stop):
+    return LambdaInfo(
+        func_lambda=lambda v: start < v < stop,
+        lambda_assert_msg=f"should be in range ({start}, {stop})",
+        lambda_details=f"{in_range.__name__}({start}, {stop}): lambda v: {start} < v < {stop}",
+    )
+
+
+def less(value):
+    return LambdaInfo(
+        func_lambda=lambda v: v < value,
+        lambda_assert_msg=f"should be less than {value}",
+        lambda_details=f"{less.__name__}({value}): lambda v: v < {value}",
+    )
+
+
+def more(value):
+    return LambdaInfo(
+        func_lambda=lambda v: v > value,
+        lambda_assert_msg=f"should be greater than {value}",
+        lambda_details=f"{more.__name__}({value}): lambda v: v > {value}",
+    )
+
+
+def split_length(size, sep=","):
+    return LambdaInfo(
+        func_lambda=lambda v: len(v.split(sep)) == size,
+        lambda_assert_msg=f"should split by {sep!r} into {size} parts",
+        lambda_details=f"{split_length.__name__}({size}, {sep}): lambda v: len(v.split({sep})) == {size}",
+    )
+
+
+# ── parameter-less predefined validators ───────────────────────────────────────
+valid_score = LambdaInfo(
+    func_lambda=lambda v: 0 < v <= 1,
+    lambda_assert_msg="should be a valid score (0 < v <= 1)",
+    lambda_details="valid_score: lambda v: 0 < v <= 1",
+)
+
+positive_number = LambdaInfo(
+    func_lambda=lambda v: v >= 0,
+    lambda_assert_msg="should be >= 0",
+    lambda_details="positive_number: lambda v: v >= 0",
+)
+
+non_zero = LambdaInfo(
+    func_lambda=lambda v: v > 0,
+    lambda_assert_msg="should be > 0",
+    lambda_details="non_zero: lambda v: v > 0",
+)
+
+split_positive_numbers = LambdaInfo(
+    func_lambda=lambda v: all([float(elem) >= 0 for elem in v.split(",")]),
+    lambda_assert_msg="all comma-separated parts should be >= 0",
+    lambda_details='split_positive_numbers: lambda v: all([float(elem) >= 0 for elem in v.split(",")])',
+)

validate_nested/result.py

@@ -0,0 +1,67 @@
+"""Neutral, framework-agnostic result types.
+
+The engine never raises or asserts on its own — ``validate`` returns a :class:`Result`.
+You decide what to do with it; the idiomatic immediate check is::
+
+    r = validate(record, model)
+    assert r.ok, r.report()
+"""
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional
+
+
+@dataclass
+class Failure:
+    """A single failed check.
+
+    ``path`` is where in the record it failed; ``message`` is the default
+    human-readable reason (expected vs actual).
+    """
+
+    path: str
+    message: str
+
+    def __str__(self):
+        return f"[{self.path}] {self.message}"
+
+
+def format_failure(failure: "Failure") -> str:
+    """Default single-failure renderer (override by passing ``formatter=`` to report)."""
+    return f"  - [{failure.path}] {failure.message}"
+
+
+def render_failures(failures: List["Failure"], formatter: Callable[["Failure"], str] = None) -> str:
+    """Join failures into one readable multi-line message."""
+    fmt = formatter or format_failure
+    header = f"{len(failures)} validation failure(s):"
+    return "\n".join([header, *(fmt(f) for f in failures)])
+
+
+@dataclass
+class Result:
+    """Outcome of a :func:`validate_nested.validate` call.
+
+    * ``ok``       — True when no check failed
+    * ``failures`` — list of :class:`Failure`
+    * ``skipped``  — reason string if a ``skip()`` rule fired, else None
+    """
+
+    ok: bool
+    failures: List[Failure] = field(default_factory=list)
+    skipped: Optional[str] = None
+
+    def __bool__(self):
+        return self.ok
+
+    def report(self, formatter: Callable[[Failure], str] = None) -> str:
+        """Render this result as a readable message — meant for an assert message::
+
+            assert r.ok, r.report()
+
+        Pass ``formatter`` (a callable ``Failure -> str``) to customise each line.
+        """
+        if self.skipped is not None:
+            return f"skipped: {self.skipped}"
+        if not self.failures:
+            return "ok"
+        return render_failures(self.failures, formatter)

validate_nested/rules.py

@@ -0,0 +1,113 @@
+"""Model parsing: turns a model value (a type, a marker, a validator, or a tuple of
+those) into ``(type_hint, validators, boolean_rules)`` the engine can act on."""
+import logging
+import re
+from collections import namedtuple
+
+from validate_nested._utils.paths import dict_paths
+
+log = logging.getLogger("validate_nested")
+
+# A model entry may be wrapped to attach per-path options, e.g. ComplexRule(value, options)
+ComplexRule = namedtuple("ComplexRule", ["value", "options"])
+
+
+class CustomType(type):
+    def __repr__(cls):
+        return f"<class {cls.__name__}>"
+
+
+class NotExists(metaclass=CustomType):
+    """Sentinel returned by path lookups when a key is missing in the record."""
+
+    def __str__(self):
+        return "not exists in dict"
+
+
+def convert_paths_to_template(record):
+    """Index the record's concrete paths under their ``[*]`` wildcard template, so a
+    model key like ``ids[*]`` can be expanded to ``ids[0]``, ``ids[1]`` ..."""
+    t_dict = {}
+    for path in dict_paths(record):
+        path = path.replace(".[", "[")
+        template_path = re.sub(r"\[.*?\]", "[*]", path)
+        if template_path not in t_dict:
+            t_dict[template_path] = []
+        if path not in t_dict[template_path]:
+            t_dict[template_path].append(path)
+    return t_dict
+
+
+def unpack_rules(items, validators):
+    """Flatten a (possibly nested) rule tuple, peeling LambdaInfo validators off into
+    ``validators`` and returning the remaining markers/types."""
+    unpacked = []
+
+    if isinstance(items, tuple):
+        for item in items:
+            if isinstance(item, tuple) and any(
+                callable(sub_item) and sub_item.__name__ == "<lambda>"
+                for sub_item in item
+            ):
+                validators.append(list(item))
+            else:
+                unpacked.extend(unpack_rules(item, validators))
+    else:
+        unpacked.append(items)
+
+    return unpacked
+
+
+def process_validation_rules(validation_rules):
+    """Split a model value into a type hint, a list of validators and a flat dict of
+    boolean rule flags.
+
+    Rule semantics:
+      * ``required`` — stop further checks and fail if this rule failed
+      * ``skip``     — signal a skip if this rule failed (host decides what to do)
+      * ``opt``      — value may be absent; if absent, pass (unless combined with required)
+      * ``not_exist``— assert the path is absent
+      * ``undefined``— don't assume empty-vs-filled (skips the len check)
+      * ``empty`` / ``not_empty`` — assert len == 0 / len > 0 (not_empty is the default)
+      * ``to_int`` / ``to_float`` — coerce the value before running validators
+    """
+    type_hint, validators = None, []
+    boolean_rules = dict(
+        {
+            "not_exist": False,
+            "required": False,
+            "opt": False,
+            "undefined": False,
+            "empty": False,
+            "not_empty": True,
+            "skip": False,
+            "to_int": False,
+            "to_float": False,
+        }
+    )
+
+    # unpack the model body into markers/types (validators are peeled off in-place)
+    unpacked_rules = unpack_rules(validation_rules, validators)
+
+    # extract type hint(s)
+    type_hint = tuple(item for item in unpacked_rules if isinstance(item, type))
+    if len(type_hint) == 1:
+        type_hint = type_hint[0]
+
+    # extract boolean rules (marker strings)
+    boolean_rules.update({item: True for item in unpacked_rules if isinstance(item, str)})
+
+    # exclusive options
+    if boolean_rules.get("empty"):
+        boolean_rules["not_empty"] = False
+
+    if boolean_rules.get("undefined"):
+        boolean_rules["empty"] = False
+        boolean_rules["not_empty"] = False
+
+    log.debug(
+        "processed rules: %r -> type_hint=%r validators=%r boolean_rules=%r",
+        validation_rules, type_hint, validators, boolean_rules,
+    )
+
+    return type_hint, validators, boolean_rules

validate_nested/soft.py

@@ -0,0 +1,52 @@
+"""Soft validation across several calls.
+
+A single ``validate`` call already checks the *whole* model and reports every failure
+at once. ``SoftValidator`` extends that across multiple calls in one block, raising a
+single aggregated ``AssertionError`` at the end (handy in one test asserting several
+records).
+
+    with SoftValidator() as soft:
+        soft.validate(resp_a, model_a)
+        soft.validate(resp_b, model_b)
+    # raises here if either failed, listing all failures
+"""
+from validate_nested.engine import validate
+from validate_nested.result import render_failures
+
+
+class SoftValidator:
+    def __init__(self, formatter=None):
+        self.formatter = formatter
+        self.failures = []
+        self.skipped = []
+
+    def validate(self, record, model, **options):
+        """Validate and accumulate failures; returns the individual Result."""
+        result = validate(record, model, **options)
+        self.failures.extend(result.failures)
+        if result.skipped is not None:
+            self.skipped.append(result.skipped)
+        return result
+
+    @property
+    def ok(self):
+        return not self.failures
+
+    def report(self):
+        """Readable message for everything collected so far."""
+        return render_failures(self.failures, self.formatter)
+
+    def assert_ok(self):
+        """Raise now if anything has failed so far."""
+        if self.failures:
+            raise AssertionError(self.report())
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        # don't mask an exception already propagating out of the block
+        if exc_type is not None:
+            return False
+        self.assert_ok()
+        return False

validate_nested-0.1.0.dist-info/METADATA

@@ -0,0 +1,470 @@
+Metadata-Version: 2.4
+Name: validate-nested
+Version: 0.1.0
+Summary: A tiny, framework-agnostic DSL for validating the shape of nested dicts / JSON responses.
+Author: Sergei Murashov
+License: MIT
+Project-URL: Homepage, https://github.com/ant1kdream/validate-nested
+Project-URL: Repository, https://github.com/ant1kdream/validate-nested
+Project-URL: Issues, https://github.com/ant1kdream/validate-nested/issues
+Project-URL: Changelog, https://github.com/ant1kdream/validate-nested/blob/main/CHANGELOG.md
+Keywords: validation,json,schema,dict,testing,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Dynamic: license-file
+
+# validate-nested
+
+[![CI](https://github.com/ant1kdream/validate-nested/actions/workflows/ci.yml/badge.svg)](https://github.com/ant1kdream/validate-nested/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/validate-nested.svg)](https://pypi.org/project/validate-nested/)
+[![Python versions](https://img.shields.io/pypi/pyversions/validate-nested.svg)](https://pypi.org/project/validate-nested/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**A tiny, dependency-free DSL for validating the *shape* of nested dicts / JSON responses
+of any depth.**
+
+Describe what a response should look like with a compact `model` dict and let the engine
+check types, lengths, values, presence and per-item rules in one pass — then plug the
+result into *any* test framework, or none.
+
+```python
+from validate_nested import validate
+from validate_nested.lambdas import equal, length, more
+
+# a nested response — dotted paths and [*] reach into it
+response = {
+    "status": "ok",
+    "page": {"size": 3, "index": 0},
+    "results": [
+        {"id": "a1", "score": 0.91},
+        {"id": "b2", "score": 0.40},   # <- too low
+        {"id": "c3", "score": 0.95},
+    ],
+}
+
+model = {
+    "status":           (str, equal("ok")),    # top-level field
+    "page.size":        (int, equal(3)),        # dotted path into a nested dict
+    "results":          (list, length(3)),      # the list itself
+    "results[*].id":    str,                    # a field of every list item
+    "results[*].score": (float, more(0.5)),     # per-item value check
+}
+
+r = validate(response, model)        # -> Result(ok, failures, skipped); never raises
+assert r.ok, r.report()
+```
+
+The failing item is reported by its exact path:
+
+```text
+1 validation failure(s):
+  - [results[1].score] should be greater than 0.5, got 0.4
+```
+
+No classes to declare, no schema files — the model *is* the spec, inline where you use it.
+
+### Nesting of any depth
+
+Paths reach as deep as the data goes, and `[*]` wildcards stack — one flat model describes
+a whole tree of orders → items → tags:
+
+```python
+from validate_nested import validate
+from validate_nested.lambdas import equal, length, more, contains, not_empty
+
+response = {
+    "status": "ok",
+    "meta": {
+        "page": {"index": 0, "size": 2},
+        "total": 2,
+    },
+    "orders": [
+        {
+            "id": "ORD-1",
+            "customer": {"id": 42, "email": "ada@example.io"},
+            "items": [
+                {"sku": "A-1", "price": 9.99,  "tags": ["new"]},
+                {"sku": "B-2", "price": 19.50, "tags": ["sale", "hot"]},
+            ],
+            "shipping": {"country": "DE", "zip": "10115"},
+        },
+    ],
+}
+
+model = {
+    "status":                     (str, equal("ok")),
+    "meta.page.index":            int,                  # dotted path, 3 levels down
+    "meta.total":                 (int, more(0)),
+    "orders":                     (list, not_empty()),
+    "orders[*].id":               (str, not_empty()),
+    "orders[*].customer.email":   (str, contains("@")),  # wildcard then a dotted path
+    "orders[*].items":            (list, not_empty()),
+    "orders[*].items[*].sku":     str,                   # wildcard inside a wildcard
+    "orders[*].items[*].price":   (float, more(0)),
+    "orders[*].items[*].tags[*]": str,                   # three wildcards deep
+    "orders[*].shipping.country": (str, length(2)),
+}
+
+assert validate(response, model).ok
+```
+
+If, say, the second item of the first order had a negative price, that one element is
+pinpointed — every other item still validates:
+
+```text
+1 validation failure(s):
+  - [orders[0].items[1].price] should be greater than 0, got -1.0
+```
+
+---
+
+## Why
+
+- **Terse.** One dict describes a whole response. No model class per shape.
+- **Structural + value checks together.** `(int, equal(0))`, `(list, length(3))`, `ids[*]`.
+- **Framework-agnostic.** The engine returns data; *you* decide how to report (plain
+  code, immediate `assert`, soft-aggregate, or pytest).
+- **Zero dependencies.** Pure Python 3.8+. `pytest` is only needed to run the tests.
+
+---
+
+## Install
+
+```bash
+pip install validate-nested    # core, no dependencies
+```
+
+---
+
+## The model
+
+A model is `{path: rule}`. A **rule** is a type, a marker, a validator, or a tuple of those.
+
+### Types
+
+```python
+{"age": int, "name": str, "tags": list, "meta": dict, "score": float}
+```
+
+A tuple of types is a union (`(int, str)` = "either"). See [tests/test_types.py](tests/test_types.py).
+
+### Type + value validators
+
+Combine a type with one or more validators in a tuple:
+
+```python
+{"score": (float, valid_score), "ids": (list, length(3)), "state": (str, equal("ok"))}
+```
+
+Each validator has its own file:
+[`valid_score`](tests/lambdas/test_valid_score.py),
+[`length`](tests/lambdas/test_length.py),
+[`equal`](tests/lambdas/test_equal.py) — and the full list is in the validators table below.
+
+### Paths & wildcards
+
+Dotted paths, the `[*]` wildcard (every item of a list), and explicit indices:
+
+```python
+{
+    "data.user.id": int,                  # nested
+    "items[*]": dict,                     # every element of items
+    "items[*].price": float,              # price of every element
+    "items[0].sku": str,                  # a specific element by index
+    "orders[*].items[*].price": float,    # nested wildcards
+}
+```
+
+A failure carries the concrete index (`items[1].price`), an out-of-range index is
+reported as missing, and the two styles can be mixed. See
+[tests/test_lists.py](tests/test_lists.py).
+
+### Presence & coercion markers
+
+**Built-in only** (you can't define custom markers). They tune presence, emptiness and
+coercion:
+
+| Marker | Meaning |
+|---|---|
+| [`not_empty()`](tests/rules/test_not_empty.py) | `len > 0` (the **default** for sized types) |
+| [`empty()`](tests/rules/test_empty.py) | `len == 0` |
+| [`opt()`](tests/rules/test_opt.py) | value may be absent → passes if missing |
+| [`required()`](tests/rules/test_required.py) | if this rule fails, stop and don't check the rest |
+| [`not_exist()`](tests/rules/test_not_exist.py) | the path must be **absent** |
+| [`undefined()`](tests/rules/test_undefined.py) | don't assume empty-vs-filled (skip the len check) |
+| [`to_int()`](tests/rules/test_to_int.py) / [`to_float()`](tests/rules/test_to_float.py) | coerce before running validators, e.g. `(str, to_int(equal(5)))` |
+| [`skip()`](tests/test_skip.py) | if this rule fails, signal a **skip** instead of a failure |
+
+```python
+{
+    "id":       required(str),             # must be present, a string
+    "tags":     not_empty(list),           # a non-empty list
+    "notes":    empty(str),                # an empty string
+    "nickname": opt(str),                  # may be absent
+    "legacy":   not_exist(),               # must be absent
+    "count":    (str, to_int(equal(5))),   # coerce "5" -> 5 before checking
+}
+```
+
+Markers compose. The key idiom is `required(opt(...))` — an **optional gate**: the field
+may be absent (then it and its children pass), but **if present** its shape is checked
+first, and if that fails the children are skipped:
+
+```python
+model = {
+    "profile":      required(opt(dict)),       # may be absent; if present, must be a dict
+    "profile.name": (str, equal("Ada")),       # only reached when profile is a valid dict
+}
+
+validate({"other": 1},               model).ok   # True  — profile absent, children skipped
+validate({"profile": {"name": "Ada"}}, model).ok # True  — present and valid
+validate({"profile": "oops"},        model).ok   # False — [profile] expected dict, got str
+```
+
+(`required(not_exist())` composes the same way.) See
+[tests/rules/test_required.py](tests/rules/test_required.py) and
+[tests/rules/test_opt.py](tests/rules/test_opt.py).
+
+### Validators — built-in (`from validate_nested.lambdas import ...`)
+
+| Validator | Passes when |
+|---|---|
+| [`equal(x)`](tests/lambdas/test_equal.py) / [`not_equal(x)`](tests/lambdas/test_not_equal.py) | value `==` / `!=` x |
+| [`length(n)`](tests/lambdas/test_length.py) | `len(value) == n` |
+| [`approx(x, delta=0.01)`](tests/lambdas/test_approx.py) | `abs(value - x) <= delta` |
+| [`contains(x)`](tests/lambdas/test_contains.py) | substring / all items in value |
+| [`exists_in((a, b, ...))`](tests/lambdas/test_exists_in.py) | value is one of |
+| [`in_range(a, b)`](tests/lambdas/test_in_range.py) | `a < value < b` |
+| [`less(x)`](tests/lambdas/test_less.py) / [`more(x)`](tests/lambdas/test_more.py) | `value < x` / `value > x` |
+| [`ends(x)`](tests/lambdas/test_ends.py) | `value.endswith(x)` |
+| [`count(value, amount)`](tests/lambdas/test_count.py) | value appears `amount` times |
+| [`split_length(n, sep=",")`](tests/lambdas/test_split_length.py) | `len(value.split(sep)) == n` |
+| [`lower_match(x)`](tests/lambdas/test_lower_match.py) | case-insensitive equality |
+| [`valid_score`](tests/lambdas/test_valid_score.py) / [`positive_number`](tests/lambdas/test_positive_number.py) / [`non_zero`](tests/lambdas/test_non_zero.py) | `0 < v <= 1` / `v >= 0` / `v > 0` |
+| [`split_positive_numbers`](tests/lambdas/test_split_positive_numbers.py) | all comma-split parts `>= 0` |
+
+```python
+{
+    "title":   (str, length(8)),                       # exactly 8 chars
+    "status":  (str, exists_in(("open", "closed"))),   # one of
+    "score":   (float, in_range(0, 1)),                # 0 < score < 1
+    "tags":    (list, contains("urgent")),             # list contains "urgent"
+    "ref":     (str, ends(".pdf")),                    # ends with ".pdf"
+    "retries": (int, less(5)),                         # < 5
+}
+```
+
+### Extending — custom validators
+
+Need a check the built-ins don't cover? Two ways, both drop straight into a model
+(including over `[*]` list items):
+
+```python
+from validate_nested.lambdas import predicate, LambdaInfo
+
+# 1) inline, the short way — predicate(callable, message)
+is_even = predicate(lambda v: v % 2 == 0, "should be even")
+model = {"count": (int, is_even)}              # fails as: should be even, got 3
+
+# 2) reusable / parametrised — a function returning LambdaInfo
+#    (this is exactly how the built-ins like equal() and length() are written)
+def divisible_by(n):
+    return LambdaInfo(
+        func_lambda=lambda v: v % n == 0,
+        lambda_assert_msg=f"should be divisible by {n}",
+        lambda_details=f"divisible_by({n})",
+    )
+model = {"size": (int, divisible_by(3))}
+```
+
+> ⚠️ **A bare `lambda` is silently ignored.** `(int, lambda v: v > 0)` won't run — the
+> engine only recognises a validator once it's wrapped (`predicate(...)` or
+> `LambdaInfo(...)`). Always wrap; never drop a raw `lambda` into a model.
+
+Runnable examples (and custom `report(formatter=...)`):
+[tests/test_extending.py](tests/test_extending.py).
+
+---
+
+## Consumption modes
+
+### 1. Pure — inspect the result
+
+```python
+result = validate(record, model)
+if not result.ok:
+    for f in result.failures:
+        print(f.path, f.message)
+```
+
+`result.ok` is True only when **every** path passed (a later passing field never masks an
+earlier failure), and `bool(result) == result.ok` — so `validate` reads cleanly as a gate,
+guarding work that should run only on a well-formed record:
+
+```python
+if validate(response, model):          # proceed only when the shape is right
+    enqueue(response["orders"])
+```
+
+See [tests/test_conditions.py](tests/test_conditions.py).
+
+### 2. Immediate — assert on the result
+
+`validate` is the only entry point; you decide when to assert. `Result.report()`
+renders a readable message for the assert line:
+
+```python
+r = validate(record, model)
+assert r.ok, r.report()                 # AssertionError lists every failure
+assert r.ok, r.report(formatter=my_fmt) # custom message per failure
+```
+
+### 3. Soft — aggregate across several checks
+
+```python
+from validate_nested import SoftValidator
+
+with SoftValidator() as soft:
+    soft.validate(resp_a, model_a)
+    soft.validate(resp_b, model_b)
+# raises once at block end, listing every failure from both
+```
+
+See [tests/test_modes.py](tests/test_modes.py).
+
+### 4. pytest (optional)
+
+There is **no** shipped pytest helper — `validate` is all you need, and you wire the
+`Result` however you like (this also keeps the namespace clear of `pytest-check` & co.).
+A typical wiring is three lines; define your own once and reuse it:
+
+```python
+def validate_or_skip(record, model):       # your helper — keep it wherever you like
+    r = validate(record, model)
+    if r.skipped:
+        pytest.skip(r.skipped)              # a fired skip() rule -> skip the test
+    assert r.ok, r.report()                 # any other failure -> fail with the report
+    return r
+
+def test_search():
+    validate_or_skip(response.json(), {"state": (str, equal("ok")), "hits[*]": dict})
+```
+
+Not using pytest? Route the result anywhere — `unittest`'s `skipTest`, a logger, a custom
+exception. See [tests/test_skip.py](tests/test_skip.py) for skip wired both ways.
+
+### 5. Compose your own — e.g. a request helper
+
+`validate` is a building block — wrap it in whatever helper fits your domain. A common
+one validates an HTTP response's **status code as a gate**, then its body, and *only* its
+body if the code was right. Mark `status` `required` so a wrong code fails once and
+short-circuits — the `body.*` rules behind it are never checked (no cascade of
+"missing body field" noise behind an error response):
+
+```python
+from validate_nested import validate
+from validate_nested.lambdas import required, equal
+
+def validate_request(response, expected_code, model):
+    record = {"status": response.status_code, "body": response.json()}
+    gate = {"status": required((int, equal(expected_code)))}
+    r = validate(record, {**gate, **model})
+    assert r.ok, r.report()
+    return r
+
+# body rules are written against body.* paths:
+validate_request(response, 200, {"body.id": int, "body.state": (str, equal("ok"))})
+```
+
+A wrong code reports only `[status] ...` (the body is never inspected); a right code with
+a bad body reports `[body.state] ...`. See
+[tests/test_request_pattern.py](tests/test_request_pattern.py).
+
+---
+
+## skip semantics
+
+`skip()` is a test-control concern, so the **core never skips anything** — when a
+`skip()`-marked rule fails, `validate` returns `Result(skipped="<reason>")`. You decide:
+
+```python
+r = validate(record, {"feature": skip(dict)})
+if r.skipped:
+    pytest.skip(r.skipped)   # or unittest's skipTest, a log call, your own — your choice
+```
+
+Override the default skip reason per field with `ComplexRule(value=skip(...),
+options={"assert_msg": "..."})`. See [tests/test_skip.py](tests/test_skip.py).
+
+---
+
+## Custom messages
+
+`Failure(path, message)` is neutral. Render it your way with a `formatter` (a callable
+`Failure -> str`):
+
+```python
+r = validate(record, model)
+assert r.ok, r.report(formatter=lambda f: f"{f.path} is wrong: {f.message}")
+```
+
+See [tests/test_modes.py](tests/test_modes.py) (`test_custom_formatter`).
+
+---
+
+## Advanced — per-field message (`ComplexRule`)
+
+`report(formatter=...)` reshapes *every* failure at once. To override just **one field's**
+message, wrap its rule in `ComplexRule(value=<rule>, options={...})` — `assert_msg`
+replaces the message, `add_msg` prepends context.
+
+Its most useful case is giving a `skip()` a readable reason: by default a fired skip
+carries the raw mismatch text (`expected dict, got str`), which says nothing about *why*
+you skipped. `assert_msg` fixes that:
+
+```python
+from validate_nested import ComplexRule, validate
+from validate_nested.lambdas import skip
+
+model = {"beta_feature": ComplexRule(skip(dict), {"assert_msg": "beta disabled in this env"})}
+r = validate(record, model)
+# r.skipped == "beta disabled in this env"   (not "expected dict, got str")
+```
+
+See [tests/test_complex_rule.py](tests/test_complex_rule.py) (messages) and
+[tests/test_skip.py](tests/test_skip.py) (custom skip reason).
+
+---
+
+## Result API
+
+```python
+Result(
+    ok:       bool,              # True iff nothing failed
+    failures: list[Failure],     # each has .path and .message
+    skipped:  str | None,        # reason if a skip() rule fired
+)
+bool(result)  # == result.ok
+```
+
+---
+
+## License
+
+MIT.

validate_nested-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+validate_nested/__init__.py,sha256=bVym5tjmZmsNlzT0ts4RnZ9PYZD4nE80Z1sxiPbpwJk,1038
+validate_nested/engine.py,sha256=tj55YfJm9tQaMoiEdoJa_8ywp9OXVZL94rhSlTAo-qY,7628
+validate_nested/lambdas.py,sha256=2J4jXvMepUSIVnBgu7wElyhNqeElc8rQ2wEzntfsGNI,7046
+validate_nested/result.py,sha256=osDqk6ap0C5r5m3vBTpshN5wnsV6UTArBZc60sFCcNk,2062
+validate_nested/rules.py,sha256=0wQ7Fg7m_m0OMywQj0OfrcF0hyj1T_tYlql7AHfUYAQ,3911
+validate_nested/soft.py,sha256=HB4DREmQcwWDLmDBbMmIGnbK3Nt1Rl3hk4ZJgllm6Q0,1714
+validate_nested/_utils/__init__.py,sha256=-s1eYRQt2I4MGqYvaRro_HFXaB7BkMy1AHKYh5czDbI,140
+validate_nested/_utils/paths.py,sha256=1ZUv_FnesgB8ScBJmhhmxkbaVrI1D6ZQm9apIcX_Yek,2269
+validate_nested-0.1.0.dist-info/licenses/LICENSE,sha256=2AeXfTPpJHhcn4olaonIiTEeIs_Hw8Y8fcZ4lNqxyGc,1072
+validate_nested-0.1.0.dist-info/METADATA,sha256=E4RtmDEmNLYxIFDJtYvtfY4na56qbImRs4ew2TAWrNU,17560
+validate_nested-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+validate_nested-0.1.0.dist-info/top_level.txt,sha256=bV9F7Q4Si-fVjcVR2HLwu1Q-ZWT3inEVNwUj15nush8,16
+validate_nested-0.1.0.dist-info/RECORD,,

validate_nested-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

validate_nested-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergei Murashov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

validate_nested-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+validate_nested