super-easy-validator-python 0.1.0__py3-none-any.whl

super_easy_validator_python/validator.py

@@ -0,0 +1,685 @@
+"""The validation engine: traversal, operators, groups and strict mode."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from . import codes
+from .checks import check_single
+from .paths import (
+    has_index_syntax,
+    is_array,
+    is_object,
+    is_slice_key,
+    lookup,
+    resolve,
+    resolve_indexed_path,
+)
+from .rules import (
+    GROUP_ATLEAST,
+    GROUP_ATMOST,
+    assert_known_token,
+    assert_valid_tokens,
+    custom_error,
+    group_size,
+    has_token,
+    is_group_key,
+    is_operator_key,
+    tokenize,
+)
+from .types import (
+    BRANCH_CASE,
+    BRANCH_DEFAULT,
+    BRANCH_THEN,
+    OP_AND,
+    OP_OR,
+    OP_SWITCH,
+    Config,
+    Data,
+    Detail,
+    InvalidRuleError,
+    Result,
+    Rules,
+)
+
+_MISSING = object()
+
+
+def validate(rules: Rules, data: Optional[Data], config: Optional[Config] = None) -> Result:
+    """Check data against rules.
+
+    Returns a Result whose ``errors`` is None when everything passed. A
+    malformed rule raises InvalidRuleError: that is a mistake in the rules, not
+    a validation failure.
+    """
+    cfg = config or Config()
+
+    _assert_valid_rules(rules, "")
+
+    details: list[Detail] = []
+    _walk(rules, data, cfg, "", details)
+
+    return _finish(details, cfg)
+
+
+def _finish(details: list[Detail], cfg: Config) -> Result:
+    """Apply the quote style and collapse duplicate messages."""
+    quote = cfg.quote_char
+    seen: set[str] = set()
+    out: list[Detail] = []
+
+    for d in details:
+        message = d["message"].replace('"', quote)
+        if message in seen:
+            continue
+        seen.add(message)
+        out.append({"field": d["field"], "message": message, "code": d["code"]})
+
+    if not out:
+        return Result()
+    return Result([d["message"] for d in out], out)
+
+
+# --- rule validation, before any data is examined -------------------------
+
+
+def _assert_valid_rules(rules: Rules, prefix: str) -> None:
+    if not isinstance(rules, dict):
+        raise InvalidRuleError(prefix or "rules", "must be a dict")
+
+    for key, value in rules.items():
+        field = f"{prefix}.{key}" if prefix else key
+
+        if is_group_key(key):
+            if not isinstance(value, (str, list)):
+                raise InvalidRuleError(field, "must be a rule string or a list of rule strings")
+            continue
+
+        _assert_valid_rule_value(value, field)
+
+
+def _assert_valid_rule_value(value: Any, field: str) -> None:
+    if value is None:
+        raise InvalidRuleError(field, "has an invalid rule: it must not be None")
+
+    if callable(value):
+        return
+
+    if isinstance(value, str):
+        tokens = value.split("|")
+        assert_valid_tokens(tokens, field)
+        _assert_user_regexes(tokens, field)
+        return
+
+    if isinstance(value, list):
+        if value and all(isinstance(e, str) for e in value):
+            assert_valid_tokens(value, field)
+            _assert_user_regexes(value, field)
+            return
+        if len(value) != 1:
+            raise InvalidRuleError(field, "has an invalid rule: a list rule must have exactly one element")
+        _assert_valid_rule_value(value[0], field)
+        return
+
+    if isinstance(value, dict):
+        if _is_operator_node(value):
+            _assert_valid_operator(value, field)
+            return
+        _assert_valid_rules(value, field)
+        return
+
+    raise InvalidRuleError(field, f"has an invalid rule: unsupported rule type {type(value).__name__}")
+
+
+def _assert_user_regexes(tokens: list[str], field: str) -> None:
+    from .formats import translate_user_regex
+
+    for t in tokens:
+        if t.startswith("regex:"):
+            try:
+                translate_user_regex(t[len("regex:") :])
+            except ValueError as exc:
+                raise InvalidRuleError(field, str(exc)) from None
+
+
+def _is_operator_node(value: dict) -> bool:
+    return any(is_operator_key(k) for k in value)
+
+
+def _operator_of(node: dict) -> tuple[str, list[Any]]:
+    for op in (OP_OR, OP_AND, OP_SWITCH):
+        if op in node:
+            branches = node[op]
+            return op, branches if isinstance(branches, list) else []
+    return "", []
+
+
+def _assert_valid_operator(node: dict, field: str) -> None:
+    operators = [op for op in (OP_OR, OP_AND, OP_SWITCH) if op in node]
+    if len(operators) > 1:
+        raise InvalidRuleError(field, f"cannot combine {' and '.join(operators)} in one object")
+
+    operator = operators[0]
+    extras = sorted(k for k in node if k != operator)
+    if extras:
+        raise InvalidRuleError(
+            field,
+            f"cannot mix '{operator}' with other keys (found: {', '.join(extras)}); "
+            "wrap them in a branch instead",
+        )
+
+    branches = node[operator]
+    if not isinstance(branches, list):
+        raise InvalidRuleError(field, f"has an invalid rule: '{operator}' must be a list of branches")
+    if not branches:
+        raise InvalidRuleError(field, f"has an invalid rule: '{operator}' needs at least one branch")
+
+    if operator == OP_SWITCH:
+        _assert_valid_switch(branches, field)
+        return
+
+    for branch in branches:
+        _assert_valid_rule_value(branch, field)
+        if operator == OP_OR and _only_modifiers(branch):
+            raise InvalidRuleError(
+                field,
+                "has an invalid rule: a '$or' branch cannot be only 'optional' or 'nullable', "
+                "because it would accept any value. Use '$and' to make the field optional.",
+            )
+
+
+def _assert_valid_switch(branches: list[Any], field: str) -> None:
+    defaults = 0
+
+    for branch in branches:
+        if not isinstance(branch, dict):
+            raise InvalidRuleError(
+                field,
+                "has an invalid rule: every '$switch' branch must be an object with 'case' and 'then'",
+            )
+
+        extras = sorted(k for k in branch if k not in (BRANCH_CASE, BRANCH_THEN, BRANCH_DEFAULT))
+        if extras:
+            raise InvalidRuleError(
+                field,
+                "has an invalid rule: a '$switch' branch accepts only 'case', 'then' and 'default' "
+                f"(found: {', '.join(extras)})",
+            )
+
+        if branch.get(BRANCH_CASE) is None:
+            raise InvalidRuleError(field, "has an invalid rule: a '$switch' branch needs a 'case'")
+        if branch.get(BRANCH_THEN) is None:
+            raise InvalidRuleError(field, "has an invalid rule: a '$switch' branch needs a 'then'")
+
+        if BRANCH_DEFAULT in branch:
+            flag = branch[BRANCH_DEFAULT]
+            if not isinstance(flag, bool):
+                raise InvalidRuleError(field, "has an invalid rule: '$switch' 'default' must be a boolean")
+            if flag:
+                defaults += 1
+
+        _assert_valid_rule_value(branch[BRANCH_CASE], field)
+        _assert_valid_rule_value(branch[BRANCH_THEN], field)
+
+    if defaults > 1:
+        raise InvalidRuleError(
+            field, "has an invalid rule: only one '$switch' branch may be marked 'default'"
+        )
+
+
+def _only_modifiers(branch: Any) -> bool:
+    tokens = tokenize(branch)
+    if tokens is None:
+        return False
+    return all(t in ("", "optional", "nullable") for t in tokens)
+
+
+# --- traversal ------------------------------------------------------------
+
+
+def _walk(rules: Rules, data: Any, cfg: Config, prefix: str, out: list[Detail]) -> None:
+    if data is None:
+        name = prefix or "data"
+        out.append({"field": name, "message": f'"{name}" is required', "code": codes.DATA_REQUIRED})
+        return
+
+    if not isinstance(data, (dict, list)):
+        name = prefix or "data"
+        out.append(
+            {
+                "field": name,
+                "message": f'"{name}" must be of type object/array',
+                "code": codes.DATA_NOT_OBJECT,
+            }
+        )
+        return
+
+    for key, value in rules.items():
+        if is_group_key(key):
+            _check_group(key, value, data, prefix, out)
+            continue
+
+        field = f"{prefix}.{key}" if prefix else key
+        _apply_rule(key, field, value, data, cfg, prefix, out)
+
+    if cfg.strict:
+        _strict_check(rules, data, prefix, out)
+
+
+def _apply_rule(
+    key: str, field: str, value: Any, data: Data, cfg: Config, prefix: str, out: list[Detail]
+) -> None:
+    if callable(value):
+        _run_custom(value, key, field, data, cfg, out)
+        return
+
+    if isinstance(value, dict):
+        if _is_operator_node(value):
+            _apply_operator(value, key, field, prefix, data, cfg, out)
+        else:
+            _apply_nested(value, key, field, data, cfg, out)
+        return
+
+    if isinstance(value, list) and not (value and all(isinstance(e, str) for e in value)):
+        _apply_tuple(value[0], key, field, data, cfg, out)
+        return
+
+    tokens = tokenize(value)
+    if tokens is not None:
+        _apply_tokens(tokens, key, field, data, cfg, prefix, out)
+
+
+def _apply_tokens(
+    tokens: list[str], key: str, field: str, data: Data, cfg: Config, prefix: str, out: list[Detail]
+) -> None:
+    indexing = cfg.array_indexing_check and has_index_syntax(key)
+
+    if indexing and is_slice_key(key):
+        selected, labels = resolve_indexed_path(data, key)
+        if not is_array(selected):
+            out.append({"field": key, "message": f'"{key}" must be an array', "code": codes.NOT_ARRAY})
+            return
+        for i, element in enumerate(selected):
+            label = labels[i] if i < len(labels) else f"{key}[{i}]"
+            check_single(label, prefix, element, element is not None, tokens, out)
+        return
+
+    value = resolve(data, key, cfg.array_indexing_check)
+    present = _is_present(data, key, cfg)
+    check_single(key, prefix, value, present, tokens, out)
+
+
+def _is_present(data: Data, key: str, cfg: Config) -> bool:
+    """Whether the key selects anything at all.
+
+    A resolved value of None is ambiguous — the key may be absent, or present
+    and holding None — so presence is decided separately.
+    """
+    if cfg.array_indexing_check and has_index_syntax(key):
+        value, _ = resolve_indexed_path(data, key)
+        return value is not None
+    if "." not in key:
+        return isinstance(data, dict) and key in data
+    return resolve(data, key, cfg.array_indexing_check) is not None
+
+
+def _apply_nested(sub: Rules, key: str, field: str, data: Data, cfg: Config, out: list[Detail]) -> None:
+    value = data.get(key) if isinstance(data, dict) else None
+    if value is None:
+        out.append({"field": field, "message": f'"{field}" is required', "code": codes.REQUIRED})
+        return
+    if not is_object(value):
+        out.append(
+            {"field": field, "message": f'"{field}" must be of type object', "code": codes.NOT_OBJECT}
+        )
+        return
+    _walk(sub, value, cfg, field, out)
+
+
+def _apply_tuple(sub: Any, key: str, field: str, data: Data, cfg: Config, out: list[Detail]) -> None:
+    value = data.get(key) if isinstance(data, dict) else None
+    if value is None:
+        out.append({"field": field, "message": f'"{field}" is required', "code": codes.REQUIRED})
+        return
+    _apply_tuple_value(sub, field, value, cfg, out)
+
+
+def _apply_tuple_value(sub: Any, field: str, value: Any, cfg: Config, out: list[Detail]) -> None:
+    if not is_array(value):
+        out.append(
+            {"field": field, "message": f'"{field}" must be of type array', "code": codes.NOT_ARRAY}
+        )
+        return
+
+    nested = isinstance(sub, list) and len(sub) == 1
+    inner = sub[0] if nested else sub
+
+    for i, element in enumerate(value):
+        path = f"{field}[{i}]"
+
+        if nested:
+            _apply_tuple_value(inner, path, element, cfg, out)
+            continue
+
+        if element is None:
+            out.append({"field": path, "message": f'"{path}" is required', "code": codes.REQUIRED})
+            continue
+        if not is_object(element):
+            out.append(
+                {
+                    "field": path,
+                    "message": f'"{path}" must be of type object/array',
+                    "code": codes.NOT_OBJECT,
+                }
+            )
+            continue
+        _walk(sub, element, cfg, path, out)
+
+
+def _run_custom(
+    fn: Callable[[Any, Any], Any], key: str, field: str, data: Data, cfg: Config, out: list[Detail]
+) -> None:
+    value = resolve(data, key, cfg.array_indexing_check)
+    result = _call_custom(fn, value, data, field)
+    if result is None:
+        return
+    out.append({"field": field, "message": result["message"], "code": result["code"]})
+
+
+def _call_custom(fn: Callable[[Any, Any], Any], value: Any, parent: Any, field: str) -> Optional[dict]:
+    """Run a user function, converting a bad return or a crash into a rule error."""
+    try:
+        result = fn(value, parent)
+    except InvalidRuleError:
+        raise
+    except Exception as exc:
+        raise InvalidRuleError(field, f"custom rule raised an error: {exc}") from None
+
+    if result is None:
+        return None
+
+    if not isinstance(result, dict):
+        raise InvalidRuleError(
+            field,
+            "has an invalid custom rule: the function must return None, or a dict with "
+            f"'message' and 'code' (received {result!r})",
+        )
+
+    message = result.get("message")
+    code = result.get("code", codes.CUSTOM_RULE_FAILED)
+    if not isinstance(message, str) or not message:
+        raise InvalidRuleError(
+            field, "has an invalid custom rule: the returned dict needs a non-empty 'message'"
+        )
+    if not isinstance(code, str) or not code:
+        code = codes.CUSTOM_RULE_FAILED
+
+    return {"message": message, "code": code}
+
+
+# --- operators ------------------------------------------------------------
+
+
+def _branch_errors(
+    branch: Any, key: str, field: str, value: Any, present: bool, parent: Data, cfg: Config
+) -> list[Detail]:
+    short_key = field.rsplit(".", 1)[-1] if "." in field else field
+    parent_name = field.rsplit(".", 1)[0] if "." in field else ""
+
+    if callable(branch):
+        result = _call_custom(branch, value, parent, field)
+        if result is None:
+            return []
+        return [{"field": field, "message": result["message"], "code": result["code"]}]
+
+    wrapper: Rules = {short_key: branch}
+    inner: Data = {short_key: value} if present else {}
+
+    branch_cfg = Config(cfg.quotes, cfg.strict, cfg.array_indexing_check)
+    if has_index_syntax(short_key):
+        branch_cfg.array_indexing_check = False
+
+    details: list[Detail] = []
+    _walk(wrapper, inner, branch_cfg, parent_name, details)
+    return details
+
+
+def _branch_has_modifier(branch: Any, modifier: str) -> bool:
+    tokens = tokenize(branch)
+    return tokens is not None and has_token(tokens, modifier)
+
+
+def _any_branch_has(branches: list[Any], modifier: str) -> bool:
+    return any(_branch_has_modifier(b, modifier) for b in branches)
+
+
+def _apply_operator(
+    node: dict, key: str, field: str, prefix: str, data: Data, cfg: Config, out: list[Detail]
+) -> None:
+    value = resolve(data, key, cfg.array_indexing_check)
+    present = _is_present(data, key, cfg)
+    operator, branches = _operator_of(node)
+
+    if operator == OP_SWITCH:
+        _apply_switch(branches, key, field, value, present, data, cfg, out)
+    elif operator == OP_AND:
+        _apply_and(branches, key, field, value, present, data, cfg, out)
+    else:
+        _apply_or(branches, key, field, value, present, data, cfg, out)
+
+
+def _apply_and(
+    branches: list[Any],
+    key: str,
+    field: str,
+    value: Any,
+    present: bool,
+    data: Data,
+    cfg: Config,
+    out: list[Detail],
+) -> None:
+    if not present and _any_branch_has(branches, "optional"):
+        return
+    if present and value is None and _any_branch_has(branches, "nullable"):
+        return
+
+    object_branches = [b for b in branches if isinstance(b, dict) and not _is_operator_node(b)]
+    merged: Optional[Rules] = None
+    if len(object_branches) > 1:
+        merged = {}
+        for b in object_branches:
+            merged.update(b)
+
+    merged_done = False
+    for branch in branches:
+        if _only_modifiers(branch):
+            continue
+        if merged is not None and isinstance(branch, dict) and branch in object_branches:
+            if merged_done:
+                continue
+            merged_done = True
+            out.extend(_branch_errors(merged, key, field, value, present, data, cfg))
+            continue
+        out.extend(_branch_errors(branch, key, field, value, present, data, cfg))
+
+
+def _apply_switch(
+    branches: list[Any],
+    key: str,
+    field: str,
+    value: Any,
+    present: bool,
+    data: Data,
+    cfg: Config,
+    out: list[Detail],
+) -> None:
+    fallback: Any = _MISSING
+
+    for branch in branches:
+        if branch.get(BRANCH_DEFAULT) is True:
+            fallback = branch[BRANCH_THEN]
+        case_errors = _branch_errors(branch[BRANCH_CASE], key, field, value, present, data, cfg)
+        if not case_errors:
+            out.extend(_branch_errors(branch[BRANCH_THEN], key, field, value, present, data, cfg))
+            return
+
+    if fallback is not _MISSING:
+        out.extend(_branch_errors(fallback, key, field, value, present, data, cfg))
+        return
+
+    out.append(
+        {
+            "field": field,
+            "message": f'"{field}" does not match any case',
+            "code": codes.NO_CASE_MATCHED,
+        }
+    )
+
+
+def _apply_or(
+    branches: list[Any],
+    key: str,
+    field: str,
+    value: Any,
+    present: bool,
+    data: Data,
+    cfg: Config,
+    out: list[Detail],
+) -> None:
+    if not present and _any_branch_has(branches, "optional"):
+        return
+    if present and value is None and _any_branch_has(branches, "nullable"):
+        return
+
+    attempts: list[tuple[list[Detail], bool]] = []
+    for branch in branches:
+        errors = _branch_errors(branch, key, field, value, present, data, cfg)
+        if not errors:
+            return
+        attempts.append((errors, _branch_type_matches(branch, value)))
+
+    if not attempts:
+        return
+
+    for errors, _ in attempts:
+        if errors and all(e["code"] == codes.UNEXPECTED_FIELD for e in errors):
+            out.extend(errors)
+            return
+
+    pool = [a for a in attempts if a[1]] or attempts
+    best = min(pool, key=lambda a: len(a[0]))
+    out.extend(e for e in best[0] if e["code"] != codes.UNEXPECTED_FIELD)
+
+
+def _branch_type_matches(branch: Any, value: Any) -> bool:
+    """Whether a branch is shaped for this value's type."""
+    if callable(branch):
+        return True
+
+    if isinstance(branch, dict):
+        if _is_operator_node(branch):
+            return True
+        return is_object(value)
+
+    if isinstance(branch, list):
+        if branch and all(isinstance(e, str) for e in branch):
+            return _tokens_match_type(branch, value)
+        return is_array(value)
+
+    if isinstance(branch, str):
+        return _tokens_match_type(branch.split("|"), value)
+
+    return False
+
+
+def _tokens_match_type(tokens: list[str], value: Any) -> bool:
+    from .checks import is_number
+
+    if any(t.startswith("arrayof:") for t in tokens):
+        return is_array(value)
+    if "object" in tokens:
+        return is_object(value)
+    if "array" in tokens:
+        return is_array(value)
+    if "string" in tokens:
+        return isinstance(value, str)
+    if "number" in tokens:
+        return is_number(value)
+    if "boolean" in tokens:
+        return isinstance(value, bool)
+    return not is_object(value) and not is_array(value)
+
+
+# --- group keys -----------------------------------------------------------
+
+
+def _check_group(kind: str, value: Any, data: Data, prefix: str, out: list[Detail]) -> None:
+    if isinstance(value, str):
+        groups = [value.split("|")]
+    elif isinstance(value, list):
+        groups = [g.split("|") for g in value if isinstance(g, str)]
+    else:
+        return
+
+    for tokens in groups:
+        size = group_size(tokens)
+        names = [t for t in tokens if ":" not in t]
+        if not names:
+            continue
+
+        count = sum(1 for n in names if lookup(data, n) is not None)
+
+        if kind == GROUP_ATLEAST and count >= size:
+            continue
+        if kind == GROUP_ATMOST and count <= size:
+            continue
+
+        labelled = [f"{prefix}.{n}" if prefix else n for n in names]
+        message = _group_message(kind, labelled, size)
+        override = custom_error(tokens)
+        code = codes.ATLEAST_NOT_MET if kind == GROUP_ATLEAST else codes.ATMOST_EXCEEDED
+        out.append(
+            {
+                "field": labelled[0],
+                "message": override if override is not None else message,
+                "code": code,
+            }
+        )
+
+
+def _group_message(kind: str, names: list[str], size: int) -> str:
+    size_word = "one" if size == 1 else str(size)
+    last = names[-1]
+    leading = ", ".join(f'"{n}"' for n in names[:-1])
+    and_word = "and" if len(names) > 1 else ""
+
+    if kind == GROUP_ATLEAST:
+        is_are = "is" if size == 1 else "are"
+        parts = [f"at least {size_word} of", leading, and_word, f'"{last}"', is_are, "required"]
+    else:
+        parts = [f"at most {size_word} of", leading, and_word, f'"{last}"', "can be given"]
+
+    return " ".join(p for p in parts if p)
+
+
+# --- strict mode ----------------------------------------------------------
+
+
+def _strict_check(rules: Rules, data: Data, prefix: str, out: list[Detail]) -> None:
+    if not isinstance(data, dict):
+        return
+
+    allowed = set()
+    for key in rules:
+        if is_group_key(key) or "." in key:
+            continue
+        bracket = key.find("[")
+        allowed.add(key[:bracket] if bracket > 0 else key)
+
+    for key in data:
+        if "." in key or key in allowed:
+            continue
+        label = f"{prefix}.{key}" if prefix else key
+        out.append(
+            {"field": label, "message": f'"{label}" is not required', "code": codes.UNEXPECTED_FIELD}
+        )