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

super_easy_validator_python/rules.py

@@ -0,0 +1,205 @@
+"""The rule vocabulary, and helpers for reading a rule's tokens."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .types import GROUP_ATLEAST, GROUP_ATMOST, OP_AND, OP_OR, OP_SWITCH, InvalidRuleError
+
+BARE_RULES = frozenset(
+    {
+        "optional",
+        "nullable",
+        "string",
+        "number",
+        "boolean",
+        "array",
+        "object",
+        "email",
+        "url",
+        "domain",
+        "name",
+        "fullname",
+        "username",
+        "alpha",
+        "alphanumeric",
+        "phone",
+        "phonecode",
+        "objectid",
+        "uuid",
+        "date",
+        "dateonly",
+        "time",
+        "lower",
+        "upper",
+        "ip",
+        "int",
+        "positive",
+        "negative",
+        "natural",
+        "whole",
+    }
+)
+
+ARGUMENT_RULES = frozenset(
+    {
+        "equal",
+        "size",
+        "min",
+        "max",
+        "regex",
+        "decimalsize",
+        "decimalmin",
+        "decimalmax",
+        "enums",
+        "field",
+        "error",
+    }
+)
+
+DATA_TYPES = frozenset({"string", "number", "boolean", "array", "object"})
+
+STRING_FORMATS = frozenset(
+    {
+        "email",
+        "url",
+        "domain",
+        "name",
+        "fullname",
+        "username",
+        "alpha",
+        "alphanumeric",
+        "phone",
+        "phonecode",
+        "objectid",
+        "uuid",
+        "date",
+        "dateonly",
+        "time",
+        "lower",
+        "upper",
+        "ip",
+    }
+)
+
+NUMBER_TYPES = frozenset({"int", "positive", "negative", "natural", "whole"})
+
+#: Tokens that put later tokens into a numeric context.
+NUMERIC_CONTEXT = frozenset({"number", "positive", "negative", "int", "whole", "natural"})
+
+#: Rules dropped from this port, reported with an explanation rather than a
+#: bare "unknown rule".
+DROPPED_RULES = {
+    "symbol": "'symbol' has no Python equivalent and is not supported",
+    "bigint": "'bigint' is not needed: Python integers are already arbitrary precision, so use 'int'",
+    "mongoid": "'mongoid' is not supported; use 'objectid'",
+}
+
+OPERATORS = frozenset({OP_OR, OP_AND, OP_SWITCH})
+GROUP_KEYS = frozenset({GROUP_ATLEAST, GROUP_ATMOST})
+
+
+def is_operator_key(key: str) -> bool:
+    return key in OPERATORS
+
+
+def is_group_key(key: str) -> bool:
+    return key in GROUP_KEYS
+
+
+def split_arg(token: str) -> Optional[tuple[str, str]]:
+    """Split "min:5" into ("min", "5"). Returns None for a bare rule."""
+    i = token.find(":")
+    if i <= 0:
+        return None
+    return token[:i], token[i + 1 :]
+
+
+def assert_known_token(token: str, field: str) -> None:
+    """Reject an unknown rule, so a typo surfaces on first run."""
+    if token.startswith("arrayof:"):
+        inner = token[len("arrayof:") :]
+        if not inner:
+            raise InvalidRuleError(field, "has an invalid rule: 'arrayof:' needs a rule after the colon")
+        assert_known_token(inner, field)
+        return
+
+    if token in BARE_RULES:
+        return
+
+    if token in DROPPED_RULES:
+        raise InvalidRuleError(field, f"has an unknown rule: {DROPPED_RULES[token]}")
+
+    parts = split_arg(token)
+    if parts is not None:
+        prefix, _ = parts
+        if prefix in ARGUMENT_RULES:
+            return
+        raise InvalidRuleError(field, f"has an unknown rule: '{prefix}:'")
+
+    raise InvalidRuleError(field, f"has an unknown rule: '{token}'")
+
+
+def assert_valid_tokens(tokens: list[str], field: str) -> None:
+    for token in tokens:
+        if not isinstance(token, str):
+            raise InvalidRuleError(field, "has an invalid rule: every rule in the list must be a string")
+        if token == "":
+            continue
+        assert_known_token(token, field)
+
+
+def tokenize(value: Any) -> Optional[list[str]]:
+    """Split a rule value into tokens, or None if it is not a token rule."""
+    if isinstance(value, str):
+        return value.split("|")
+    if isinstance(value, list) and value and all(isinstance(e, str) for e in value):
+        return list(value)
+    if isinstance(value, list) and not value:
+        return None
+    return None
+
+
+def find_prefixed(tokens: list[str], prefix: str) -> Optional[str]:
+    for t in tokens:
+        if t.startswith(prefix):
+            return t[len(prefix) :]
+    return None
+
+
+def custom_field(tokens: list[str], key: str) -> Optional[str]:
+    """A field: override, suppressed for keys ending in an array index."""
+    from .paths import ends_with_index
+
+    if ends_with_index(key):
+        return None
+    return find_prefixed(tokens, "field:")
+
+
+def custom_error(tokens: list[str]) -> Optional[str]:
+    return find_prefixed(tokens, "error:")
+
+
+def group_size(tokens: list[str]) -> int:
+    """The size: threshold in a $atleast/$atmost rule, defaulting to 1."""
+    raw = find_prefixed(tokens, "size:")
+    if raw is None:
+        return 1
+    try:
+        return int(raw)
+    except ValueError:
+        return 1
+
+
+def has_token(tokens: list[str], want: str) -> bool:
+    return want in tokens
+
+
+def numeric_context(previous: list[str]) -> bool:
+    """Whether an earlier token makes this a numeric comparison."""
+    return any(t in NUMERIC_CONTEXT for t in previous)
+
+
+def string_context(previous: list[str]) -> bool:
+    """Whether an earlier token selects the "numeric string" behaviour."""
+    return "string" in previous or "arrayof:string" in previous

super_easy_validator_python/types.py

@@ -0,0 +1,136 @@
+"""Public types.
+
+Rules are a plain dict with string keys. A rule value may be:
+
+    str             a pipe-separated rule, e.g. "optional|email"
+    list[str]       the same rules, for patterns containing a literal "|"
+    dict            a nested object rule, or an operator node
+    [dict]          a single-element list, for arrays of objects
+    callable        a custom rule
+
+An operator node is a rule value whose single key is "$or", "$and" or
+"$switch". Because rules are plain dicts, a whole rule tree can be loaded from
+JSON or built at runtime.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+Rules = dict[str, Any]
+Data = dict[str, Any]
+
+#: A custom rule receives the value and its parent, and returns None to pass
+#: or a dict with "message" and "code" to fail.
+CustomRule = Callable[[Any, Any], Optional[dict[str, str]]]
+
+#: One validation failure: {"field": ..., "message": ..., "code": ...}
+Detail = dict[str, str]
+
+OP_OR = "$or"
+OP_AND = "$and"
+OP_SWITCH = "$switch"
+
+GROUP_ATLEAST = "$atleast"
+GROUP_ATMOST = "$atmost"
+
+BRANCH_CASE = "case"
+BRANCH_THEN = "then"
+BRANCH_DEFAULT = "default"
+
+QUOTE_NONE = "none"
+QUOTE_SINGLE = "single-quotes"
+QUOTE_DOUBLE = "double-quotes"
+QUOTE_BACKTICK = "backtick"
+
+_QUOTE_CHARS = {
+    QUOTE_NONE: "",
+    QUOTE_SINGLE: "'",
+    QUOTE_DOUBLE: '"',
+    QUOTE_BACKTICK: "`",
+}
+
+
+class Result:
+    """What validate() returns.
+
+    ``errors`` and ``details`` are both None when everything passed, so
+    ``if result.errors:`` is the idiom. When validation fails they are the
+    same length and share indexes: ``errors[i] == details[i]["message"]``.
+    """
+
+    __slots__ = ("errors", "details")
+
+    def __init__(
+        self,
+        errors: Optional[list[str]] = None,
+        details: Optional[list[Detail]] = None,
+    ) -> None:
+        self.errors = errors
+        self.details = details
+
+    @property
+    def valid(self) -> bool:
+        """True when nothing failed."""
+        return not self.errors
+
+    def raise_for_errors(self) -> None:
+        """Raise ValidationError if anything failed, for callers who prefer
+        exceptions to checking a flag."""
+        if self.errors:
+            raise ValidationError(self.errors, self.details or [])
+
+    def __bool__(self) -> bool:
+        return self.valid
+
+    def __iter__(self):
+        """Allow ``errors, details = validate(...)``."""
+        yield self.errors
+        yield self.details
+
+    def __repr__(self) -> str:
+        if not self.errors:
+            return "Result(valid=True)"
+        return f"Result(errors={self.errors!r})"
+
+
+class ValidationError(Exception):
+    """Raised by Result.raise_for_errors()."""
+
+    def __init__(self, errors: list[str], details: list[Detail]) -> None:
+        super().__init__("; ".join(errors))
+        self.errors = errors
+        self.details = details
+
+
+class InvalidRuleError(Exception):
+    """A malformed rule: a mistake in your rules, not in the data.
+
+    Raised rather than returned, because it signals a programming error that
+    no amount of different input would fix.
+    """
+
+    def __init__(self, field: str, reason: str) -> None:
+        super().__init__(f"[super-easy-validator] '{field}' {reason}")
+        self.field = field
+        self.reason = reason
+
+
+class Config:
+    """Validation options. The defaults match the npm package."""
+
+    __slots__ = ("quotes", "strict", "array_indexing_check")
+
+    def __init__(
+        self,
+        quotes: str = QUOTE_NONE,
+        strict: bool = False,
+        array_indexing_check: bool = True,
+    ) -> None:
+        self.quotes = quotes
+        self.strict = strict
+        self.array_indexing_check = array_indexing_check
+
+    @property
+    def quote_char(self) -> str:
+        return _QUOTE_CHARS.get(self.quotes, "")