simplibs-validate 0.1.0__py3-none-any.whl

simplibs/validate/__init__.py

@@ -0,0 +1,46 @@
+"""Root package for simplibs-validate."""
+
+# 1. Direct core module imports
+from .raise_invalid import raise_invalid
+from .validate import validate
+
+# 2. Extract __all__ lists BEFORE star-imports (prevents SimpleNamespace shadow overriding)
+from .exceptions import __all__ as _exceptions_all
+from .rules import __all__ as _rules_all
+from .tools import __all__ as _tools_all
+from .validators import __all__ as _validators_all
+
+# 3. Re-export public members into root namespace
+from .exceptions import *
+from .rules import *
+from .tools import *
+from .validators import *
+
+# 4. Assemble root __all__
+__all__ = (
+    ["validate", "raise_invalid"]
+    + _exceptions_all
+    + _rules_all
+    + _tools_all
+    + _validators_all
+)
+
+
+_DESIGN_NOTES = r"""
+# simplibs-validate — Root Package API Facade
+
+## Purpose
+The root `simplibs.validate` package acts as a unified top-level facade. It re-exports
+all primary public components across exceptions, rule shortcuts/classes, decorators, 
+and high-level type validators for maximum developer convenience.
+
+## Sub-Packages Architecture Registry
+
+| Sub-Package                   | Primary Focus | Re-exported at Root | Description                                                                 |
+| :---------------------------- | :------------ | :------------------ | :-------------------------------------------------------------------------- |
+| `simplibs.validate.exceptions` | Exceptions    | Yes                 | Exception hierarchy (`ValidateError`, `ValidationError`, `ParamError`).      |
+| `simplibs.validate.rules`      | Rules Engine  | Yes                 | Validation rules, rule shortcuts, and operator compositions (`&`, `\|`, `~`).|
+| `simplibs.validate.tools`      | Decorators    | Yes                 | Core decorators (`validate_call`, `validate_dataclass`, `log_this`).        |
+| `simplibs.validate.validators` | Function API  | Yes                 | Type-specific functions (`validate_int`, `validate_str`, etc.).          |
+| `simplibs.validate.testing`    | Test Suite    | No                  | Assertion contracts and test utilities (excluded from root wildcard).       |
+"""

simplibs/validate/exceptions/ParamError.py

@@ -0,0 +1,31 @@
+from .ValidateError import ValidateError
+
+
+class ParamError(ValidateError):
+    """Exception raised for invalid parameter or decorator configuration.
+
+    Signals a developer error made while constructing validation rules or configuring
+    decorators, as opposed to a `ValidationError`, which signals invalid input data.
+    """
+
+    pass
+
+
+_DESIGN_NOTES = """
+# ParamError — Developer Configuration Exception
+
+## Purpose
+The `ParamError` class is used to catch and format errors that arise from
+invalid decorator configuration or passing invalid parameters into rule constructors.
+It inherits directly from `ValidateError`.
+
+---
+
+## 1. Architectural Role
+
+* **Inheritance from `ValidateError`:**
+  Inherits stack-frame filtering and diagnostic card generation from `ValidateError`.
+* **Semantic Distinction:**
+  Lets users catch configuration errors (`except ParamError`) separately from data
+  validation errors (`except ValidationError`).
+"""

simplibs/validate/exceptions/ValidateError.py

@@ -0,0 +1,44 @@
+from simplibs.exception import SimpleException
+
+
+class ValidateError(SimpleException):
+    """Root exception class for all errors originating from simplibs-validate.
+
+    Serves as the single common ancestor (root exception) for every error raised
+    within the library. Lets users catch any error from the library with a single
+    except block:
+
+        try:
+            ...
+        except ValidateError as e:
+            ...
+    """
+
+    # Skips the library's internal frames when resolving the error's origin
+    # location. This way, the diagnostic message points directly to the
+    # user's own code, not to the library's internals.
+    skip_locations = ("simplibs/validate",)
+
+
+_DESIGN_NOTES = """
+# ValidateError — Root Library Exception
+
+## Purpose
+The `ValidateError` class forms the single, unified root exception type for the
+entire `simplibs-validate` library. It inherits directly from `SimpleException`.
+
+---
+
+## 1. Architectural Role & Design
+
+### Root Exception
+* Serves purely as the abstract root exception for the library hierarchy.
+* Specific subtypes (`ValidationError` for input data failures, `ParamError` for
+  developer configuration errors) inherit directly from this class.
+* Catching `ValidateError` catches any error originating from the library.
+
+### Stack Trace Filtering (`skip_locations`)
+* Setting `skip_locations = ("simplibs/validate",)` ensures that the
+  diagnostic report from `simplibs-exception` marks the origin of the error
+  as the line in the user's own codebase that triggered the failure.
+"""

simplibs/validate/exceptions/ValidationError.py

@@ -0,0 +1,30 @@
+from .ValidateError import ValidateError
+
+
+class ValidationError(ValidateError):
+    """Exception raised when input data fails validation against a Rule.
+
+    Signals an invalid data value supplied at runtime (e.g., invalid function
+    arguments or invalid dataclass field values).
+    """
+
+    pass
+
+
+_DESIGN_NOTES = """
+# ValidationError — Data Validation Exception
+
+## Purpose
+The `ValidationError` class is raised whenever runtime data fails to satisfy a
+`Rule`. It inherits directly from `ValidateError`.
+
+---
+
+## 1. Architectural Role
+
+* **Inheritance from `ValidateError`:**
+  Inherits stack-frame filtering and diagnostic card generation from `ValidateError`.
+* **Semantic Distinction:**
+  Allows users to catch runtime input failures (`except ValidationError`) separately
+  from developer configuration mistakes (`except ParamError`).
+"""

simplibs/validate/exceptions/__init__.py

@@ -0,0 +1,31 @@
+from .build_validation_error import build_validation_error
+from .ParamError import ParamError
+from .ValidateError import ValidateError
+from .ValidationError import ValidationError
+
+__all__ = [
+    "ValidateError",
+    "ValidationError",
+    "ParamError",
+    "build_validation_error",
+]
+
+
+_DESIGN_NOTES = """
+# Validation Exceptions Sub-Package
+
+## Purpose
+Defines the exception hierarchy for the entire `simplibs-validate` library:
+the root exception type (`ValidateError`), specialized subtypes for data failures
+(`ValidationError`) and configuration errors (`ParamError`), and the exception builder
+factory.
+
+## Internal Components Registry
+
+| Component                 | Type     | Description                                                                 |
+| :------------------------ | :------- | :-------------------------------------------------------------------------- |
+| `ValidateError`           | Class    | Abstract root exception for all errors raised by the library.               |
+| `ValidationError`        | Class    | Subclass of `ValidateError` raised when runtime input data fails validation. |
+| `ParamError`               | Class    | Subclass of `ValidateError` raised for invalid rule/decorator setup.        |
+| `build_validation_error`   | Function | Builds an exception instance for user-supplied callables/lambdas.           |
+"""

simplibs/validate/exceptions/build_validation_error.py

@@ -0,0 +1,52 @@
+from typing import Any, Callable
+# Inners
+from .ValidationError import ValidationError
+
+
+def build_validation_error(
+    rule: Callable[[Any], bool],
+    value: Any,
+    value_name: str | None = None,
+    context: str | None = None,
+) -> Exception:
+    """Build a structured `ValidationError` exception for a failed user function or lambda."""
+    rule_name = getattr(rule, "__name__", str(rule))
+
+    return ValidationError(
+        error_name="VALIDATION_ERROR",
+        label=value_name,
+        expected=f"value satisfying callable condition '{rule_name}'",
+        value=value,
+        problem=f"Value failed validation check executed by callable '{rule_name}'.",
+        context=context,
+        how_to_fix=(
+            f"Provide a value that evaluates to True when passed to '{rule_name}'.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# build_validation_error — Exception Factory for User-Defined Rules
+
+## Purpose
+This function exists solely to build a structured `ValidationError` exception
+for cases where validation runs through a user-supplied ad-hoc rule (one that
+does not inherit from the `Rule` class). This covers any callable object —
+an anonymous function (`lambda`), a plain function, or an object with a
+`__call__` method — that returns a `bool`.
+
+---
+
+## 1. Rationale
+
+* **Built-in vs. User Rules:**
+  Internal built-in rules (derived from `Rule`) have their own
+  `build_exception()` methods, where they define precise, rule-specific
+  `expected`, `problem`, and `how_to_fix` messages.
+* **Fallback for Ad-Hoc Functions:**
+  If the user passes a rule such as `lambda x: x > 0`, the system has no
+  access to any class with a predefined error message. `build_validation_error`
+  extracts the function/lambda name and generates a consistent diagnostic
+  card on its behalf.
+"""

simplibs/validate/raise_invalid.py

@@ -0,0 +1,84 @@
+from typing import Any, Callable, NoReturn
+# Inners
+from .rules.base_class import Rule
+from .exceptions import build_validation_error
+
+
+def raise_invalid(
+    value: Any,
+    rule: Rule | Callable[[Any], bool],
+    *,
+    value_name: str | None = None,
+    context: str | None = None,
+) -> NoReturn:
+    """Unconditionally raise a validation exception associated with the given rule.
+
+    This function does not evaluate the truthiness of the rule (`is_valid` / callable is not called).
+    It serves as a direct shortcut for scenarios where conditional code has already verified a failure,
+    and the sole objective is to construct and raise the corresponding `ValidationError`.
+
+    Args:
+        value: The value that failed validation.
+        rule: A rule instance (`Rule`) or callable object used to construct the exception.
+        value_name: The name of the validated parameter/variable for diagnostic reporting.
+        context: Additional context describing the validation failure.
+
+    Raises:
+        ValidationError: Always raises the exception constructed by the rule or fallback factory.
+    """
+
+    # 1. Rule instance handling
+    if isinstance(rule, Rule):
+        raise rule.build_exception(
+            value,
+            value_name=value_name,
+            context=context,
+        )
+
+    # 2. Callable handling (plain function / lambda)
+    raise build_validation_error(
+        rule,
+        value,
+        value_name=value_name,
+        context=context,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_invalid — Unconditional Validation Exception Trigger
+
+## Purpose
+The `raise_invalid()` function provides a direct shortcut for raising
+structured validation exceptions without re-evaluating conditions. It is
+designed for the "happy path" pattern where control flow guards have already
+detected a failure condition inline.
+
+---
+
+## 1. Execution Pipeline
+
+1. **Bypassing Evaluation Logic:**
+   * Unlike `validate()`, this function **never calls** `rule(value)` or
+     `rule.is_valid(value)`.
+   * It assumes the calling context has already determined validation
+     failure.
+
+2. **Exception Construction & Dispatch:**
+   * **`isinstance(rule, Rule)`:** Delegates exception construction to
+     `rule.build_exception()`.
+   * **Callable / Lambda:** Delegates construction to the universal fallback
+     factory `build_validation_error()`.
+   * The resulting exception is raised immediately (`NoReturn`).
+
+---
+
+## 2. Design Choices & Rationale
+
+### Semantic Distinction from `validate()`
+* Using `validate()` makes sense when the developer wants the library to
+  evaluate the condition and trigger errors automatically.
+* Using `raise_invalid()` is ideal under an `if not condition:` block,
+  explicitly communicating intent: *"The condition has already been checked;
+  now assemble and raise the diagnostic error card."*
+* Avoids double-executing potentially expensive rule logic.
+"""