swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/testing/test_case.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any, Self
+
+from swiftpy.core.application import Application
+from swiftpy.testing.http_client import TestClient, TestResponse
+
+
+class TestCase:
+    """
+    Base test case for SwiftPY applications.
+    Provides an in-process TestClient, lifecycle helpers, and HTTP convenience methods.
+    """
+
+    __test__ = False
+    app: Application | None = None
+    _client: TestClient | None = None
+
+    def create_app(self) -> Application:
+        """Create and return an Application instance for testing."""
+        return Application()
+
+    def get_app(self) -> Application:
+        """Retrieve the test application instance."""
+        if self.app is None:
+            self.app = self.create_app()
+        return self.app
+
+    @property
+    def client(self) -> TestClient:
+        """Retrieve or create the in-process TestClient."""
+        if self._client is None:
+            self._client = TestClient(self.get_app())
+        return self._client
+
+    async def startup(self) -> None:
+        """Start the underlying ASGI lifespan on the test client."""
+        await self.client.startup()
+
+    async def shutdown(self) -> None:
+        """Shut down the underlying ASGI lifespan on the test client if created."""
+        if self._client is not None:
+            await self._client.shutdown()
+
+    def reset(self) -> None:
+        """Reset cached application and TestClient state between test runs."""
+        self._client = None
+        self.app = None
+
+    async def __aenter__(self) -> Self:
+        await self.startup()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.shutdown()
+
+    async def get(
+        self,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+        query: dict[str, Any] | None = None,
+    ) -> TestResponse:
+        return await self.client.get(path, headers=headers, query=query)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        data: bytes | str | Mapping[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        query: dict[str, Any] | None = None,
+    ) -> TestResponse:
+        return await self.client.post(
+            path, json=json, data=data, headers=headers, query=query
+        )
+
+    async def put(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        data: bytes | str | Mapping[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        query: dict[str, Any] | None = None,
+    ) -> TestResponse:
+        return await self.client.put(
+            path, json=json, data=data, headers=headers, query=query
+        )
+
+    async def patch(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        data: bytes | str | Mapping[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        query: dict[str, Any] | None = None,
+    ) -> TestResponse:
+        return await self.client.patch(
+            path, json=json, data=data, headers=headers, query=query
+        )
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        data: bytes | str | Mapping[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        query: dict[str, Any] | None = None,
+    ) -> TestResponse:
+        return await self.client.delete(
+            path, json=json, data=data, headers=headers, query=query
+        )
+
+
+__all__ = ["TestCase"]

swiftpy/validation/__init__.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from swiftpy.validation.exceptions import ValidationException
+from swiftpy.validation.form_request import FormRequest
+from swiftpy.validation.protocols import ValidatorRule
+from swiftpy.validation.rules import (
+    BailRule,
+    BetweenRule,
+    BoolRule,
+    EmailRule,
+    ExistsRule,
+    FloatRule,
+    InRule,
+    IntRule,
+    MaxRule,
+    MinRule,
+    NotInRule,
+    NullableRule,
+    RegexRule,
+    RequiredRule,
+    RuleRegistry,
+    StrRule,
+    UniqueRule,
+    UrlRule,
+    bail,
+    between,
+    bool_,
+    boolean,
+    default_registry,
+    email,
+    exists,
+    float_,
+    in_,
+    int_,
+    integer,
+    max_,
+    min_,
+    not_in,
+    nullable,
+    regex,
+    register_rule,
+    required,
+    str_,
+    string,
+    unique,
+    url,
+)
+from swiftpy.validation.validator import ValidationResult, Validator, validate
+
+__all__ = [
+    "BailRule",
+    "BetweenRule",
+    "BoolRule",
+    "EmailRule",
+    "ExistsRule",
+    "FloatRule",
+    "FormRequest",
+    "InRule",
+    "IntRule",
+    "MaxRule",
+    "MinRule",
+    "NotInRule",
+    "NullableRule",
+    "RegexRule",
+    "RequiredRule",
+    "RuleRegistry",
+    "StrRule",
+    "UniqueRule",
+    "UrlRule",
+    "ValidationException",
+    "ValidationResult",
+    "Validator",
+    "ValidatorRule",
+    "bail",
+    "between",
+    "bool_",
+    "boolean",
+    "default_registry",
+    "email",
+    "exists",
+    "float_",
+    "in_",
+    "int_",
+    "integer",
+    "max_",
+    "min_",
+    "not_in",
+    "nullable",
+    "regex",
+    "register_rule",
+    "required",
+    "str_",
+    "string",
+    "unique",
+    "url",
+    "validate",
+]

swiftpy/validation/exceptions.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from swiftpy.http.exceptions import HttpException
+
+
+class ValidationException(HttpException):
+    """
+    Exception raised when validation fails.
+    Carries structured field error messages and defaults to HTTP status 422.
+    """
+
+    def __init__(
+        self,
+        errors: dict[str, list[str]],
+        message: str = "The given data was invalid.",
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.errors = errors
+        super().__init__(
+            message=message,
+            status_code=422,
+            headers=headers,
+        )
+
+
+__all__ = ["ValidationException"]

swiftpy/validation/form_request.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any, ClassVar, Self
+from weakref import WeakKeyDictionary
+
+from swiftpy.core.config import ConfigurationError
+from swiftpy.core.container import Container, get_container
+from swiftpy.http.request import Request
+from swiftpy.validation.rules.registry import RuleRegistry, default_registry
+from swiftpy.validation.validator import ValidationResult
+
+
+class FormRequest:
+    """
+    Base class for typed request validation. Handlers can declare a parameter
+    typed with a FormRequest subclass; SwiftPY automatically validates incoming
+    request payloads and returns HTTP 422 if validation fails.
+    """
+
+    schema: ClassVar[dict[str, Any]] = {}
+    _cached_parsed_rules: ClassVar[dict[str, list[Any]] | None] = None
+    _cached_parsed_by_registry: ClassVar[
+        WeakKeyDictionary[RuleRegistry, dict[str, list[Any]]] | None
+    ] = None
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._cached_parsed_rules = None
+        cls._cached_parsed_by_registry = None
+
+    def __init__(
+        self,
+        data: dict[str, Any] | None = None,
+        raw_data: dict[str, Any] | None = None,
+        request: Request | None = None,
+        validation_result: ValidationResult | None = None,
+    ) -> None:
+        self.data: dict[str, Any] = data or {}
+        self.raw_data: dict[str, Any] = (
+            raw_data if raw_data is not None else dict(self.data)
+        )
+        self.request = request
+        self.validation_result = validation_result
+
+    def rules(self) -> dict[str, Any]:
+        """
+        Define validation rules. Defaults to returning the class 'schema' attribute.
+        Can be overridden in subclasses for dynamic rules.
+        """
+        return self.schema
+
+    def messages(self) -> dict[str, str]:
+        """
+        Define custom validation error messages keyed by 'field.rule', 'field', or 'rule'.
+        Can be overridden in subclasses.
+        """
+        return {}
+
+    @classmethod
+    def _requires_di_resolution(cls) -> bool:
+        """Return True only when cls.__init__ declares required dependency parameters."""
+        if cls.__init__ is FormRequest.__init__:
+            return False
+        sig = inspect.signature(cls.__init__)
+        for idx, param in enumerate(sig.parameters.values()):
+            if idx == 0:
+                continue
+            if param.kind in (
+                inspect.Parameter.VAR_POSITIONAL,
+                inspect.Parameter.VAR_KEYWORD,
+            ):
+                continue
+            if param.default is inspect.Parameter.empty:
+                return True
+        return False
+
+    @classmethod
+    def resolve_instance(
+        cls,
+        *,
+        data: dict[str, Any] | None = None,
+        raw_data: dict[str, Any] | None = None,
+        request: Request | None = None,
+        validation_result: ValidationResult | None = None,
+        container: Container | None = None,
+    ) -> Self:
+        """
+        Instantiate a FormRequest using explicit DI resolution only when required,
+        avoiding broad TypeError fallbacks that mask constructor bugs.
+        """
+        cont = container
+        if cont is None:
+            try:
+                cont = get_container()
+            except RuntimeError:
+                pass
+
+        if cont is not None and cont.has(cls):
+            instance = cont.resolve(cls)
+        elif cls._requires_di_resolution():
+            if cont is not None and cont.can_resolve(cls):
+                instance = cont.resolve(cls)
+            else:
+                raise ConfigurationError(
+                    f"Failed to resolve dependencies for {cls.__name__}"
+                )
+        elif cls.__init__ is FormRequest.__init__:
+            instance = cls(
+                data=data,
+                raw_data=raw_data,
+                request=request,
+                validation_result=validation_result,
+            )
+        else:
+            sig = inspect.signature(cls.__init__)
+            params = sig.parameters
+            has_varkw = any(
+                p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()
+            )
+            init_kwargs: dict[str, Any] = {}
+            candidate_kwargs: dict[str, Any] = {
+                "data": data,
+                "raw_data": raw_data,
+                "request": request,
+                "validation_result": validation_result,
+            }
+            for key, val in candidate_kwargs.items():
+                if val is not None and (has_varkw or key in params):
+                    init_kwargs[key] = val
+            instance = cls(**init_kwargs)
+
+        if data is not None:
+            instance.data = data
+        elif not hasattr(instance, "data"):
+            instance.data = {}
+        if raw_data is not None:
+            instance.raw_data = raw_data
+        elif not hasattr(instance, "raw_data"):
+            instance.raw_data = dict(instance.data)
+        if request is not None or not hasattr(instance, "request"):
+            instance.request = request
+        if validation_result is not None or not hasattr(
+            instance, "validation_result"
+        ):
+            instance.validation_result = validation_result
+        return instance
+
+    @classmethod
+    def get_rules(
+        cls,
+        container: Container | None = None,
+        request: Request | None = None,
+    ) -> dict[str, Any]:
+        """
+        Resolve validation rules for this class.
+        Fails closed with ConfigurationError if rule resolution fails (D-9).
+        """
+        instance = cls.resolve_instance(request=request, container=container)
+        try:
+            rules_def = instance.rules()
+            if not isinstance(rules_def, dict):
+                raise ConfigurationError(
+                    f"'{cls.__name__}.rules()' must return a dict, got {type(rules_def).__name__}"
+                )
+            return rules_def
+        except ConfigurationError:
+            raise
+        except Exception as exc:
+            raise ConfigurationError(
+                f"Failed to resolve validation rules for {cls.__name__}: {exc}"
+            ) from exc
+
+    @classmethod
+    def prepare_validation(
+        cls,
+        *,
+        registry: RuleRegistry | None = None,
+        container: Container | None = None,
+        request: Request | None = None,
+    ) -> tuple[Self, dict[str, list[Any]], dict[str, str]]:
+        """
+        Resolve FormRequest instance with current request context and return
+        (instance, parsed_rules, custom_messages).
+        Dynamic rules() overrides are evaluated per request rather than frozen on the class.
+        """
+        instance = cls.resolve_instance(request=request, container=container)
+        try:
+            rules_def = instance.rules()
+            if not isinstance(rules_def, dict):
+                raise ConfigurationError(
+                    f"'{cls.__name__}.rules()' must return a dict, got {type(rules_def).__name__}"
+                )
+            messages_def = instance.messages()
+            if not isinstance(messages_def, dict):
+                raise ConfigurationError(
+                    f"'{cls.__name__}.messages()' must return a dict, got {type(messages_def).__name__}"
+                )
+        except ConfigurationError:
+            raise
+        except Exception as exc:
+            raise ConfigurationError(
+                f"Failed to resolve validation metadata for {cls.__name__}: {exc}"
+            ) from exc
+
+        reg = registry or default_registry
+        is_static_schema = cls.rules is FormRequest.rules
+        if is_static_schema:
+            cached = cls._get_cached_static_rules(reg)
+            if cached is not None:
+                return instance, cached, messages_def
+
+        parsed: dict[str, list[Any]] = {}
+        for field_name, rule_def in rules_def.items():
+            parsed[field_name] = reg.parse_rules(rule_def)
+
+        if is_static_schema:
+            cls._set_cached_static_rules(reg, parsed)
+
+        return instance, parsed, messages_def
+
+    @classmethod
+    def _get_cached_static_rules(
+        cls, registry: RuleRegistry
+    ) -> dict[str, list[Any]] | None:
+        if registry is default_registry:
+            return cls._cached_parsed_rules
+        if cls._cached_parsed_by_registry is not None:
+            return cls._cached_parsed_by_registry.get(registry)
+        return None
+
+    @classmethod
+    def _set_cached_static_rules(
+        cls, registry: RuleRegistry, parsed: dict[str, list[Any]]
+    ) -> None:
+        if registry is default_registry:
+            cls._cached_parsed_rules = parsed
+            return
+        if cls._cached_parsed_by_registry is None:
+            cls._cached_parsed_by_registry = WeakKeyDictionary()
+        cls._cached_parsed_by_registry[registry] = parsed
+
+    @classmethod
+    def get_parsed_rules(
+        cls,
+        registry: RuleRegistry | None = None,
+        container: Container | None = None,
+        request: Request | None = None,
+    ) -> dict[str, list[Any]]:
+        """
+        Resolve and parse validation rules. Static schema classes cache per registry;
+        dynamic rules() subclasses are evaluated per call with request context.
+        """
+        reg = registry or default_registry
+        is_static_schema = cls.rules is FormRequest.rules
+        if is_static_schema:
+            cached = cls._get_cached_static_rules(reg)
+            if cached is not None:
+                return cached
+
+        rules_dict = cls.get_rules(container=container, request=request)
+        parsed: dict[str, list[Any]] = {}
+        for field_name, rule_def in rules_dict.items():
+            parsed[field_name] = reg.parse_rules(rule_def)
+
+        if is_static_schema:
+            cls._set_cached_static_rules(reg, parsed)
+        return parsed
+
+    @classmethod
+    def clear_rule_cache(cls) -> None:
+        """Clear the parsed rules cache for this class (useful for tests)."""
+        cls._cached_parsed_rules = None
+        if cls._cached_parsed_by_registry is not None:
+            cls._cached_parsed_by_registry.clear()
+
+    def validated(self) -> dict[str, Any]:
+        """Return the dictionary of validated, cleaned parameters."""
+        return dict(self.data)
+
+    def all(self) -> dict[str, Any]:
+        """Return all raw input parameters."""
+        return dict(self.raw_data)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.data.get(key, default)
+
+    def __getitem__(self, item: str) -> Any:
+        return self.data[item]
+
+    def __contains__(self, item: str) -> bool:
+        return item in self.data
+
+    def __getattr__(self, name: str) -> Any:
+        if name in self.data:
+            return self.data[name]
+        raise AttributeError(
+            f"'{self.__class__.__name__}' object has no attribute '{name}'"
+        )
+
+
+__all__ = ["FormRequest"]

swiftpy/validation/protocols.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ValidatorRule(Protocol):
+    """
+    Protocol for validation rules.
+    Rules can be synchronous or asynchronous.
+    """
+
+    def validate(
+        self,
+        field: str,
+        value: Any,
+        data: dict[str, Any],
+    ) -> bool | Awaitable[bool]:
+        """
+        Validate whether the given field value is valid according to this rule.
+        Can be synchronous (returning bool) or asynchronous (returning Awaitable[bool]).
+        """
+        ...
+
+    def message(self, field: str) -> str:
+        """
+        Return the validation error message when this rule fails.
+        """
+        ...
+
+
+__all__ = ["ValidatorRule"]

swiftpy/validation/rules/__init__.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from swiftpy.validation.rules.builtin import (
+    BailRule,
+    BetweenRule,
+    BoolRule,
+    EmailRule,
+    FloatRule,
+    InRule,
+    IntRule,
+    MaxRule,
+    MinRule,
+    NotInRule,
+    RegexRule,
+    StrRule,
+    UrlRule,
+    bail,
+    between,
+    bool_,
+    boolean,
+    email,
+    float_,
+    in_,
+    int_,
+    integer,
+    max_,
+    min_,
+    not_in,
+    regex,
+    str_,
+    string,
+    url,
+)
+from swiftpy.validation.rules.exists import ExistsRule, exists
+from swiftpy.validation.rules.registry import (
+    RuleRegistry,
+    default_registry,
+    register_rule,
+)
+from swiftpy.validation.rules.required import (
+    NullableRule,
+    RequiredRule,
+    nullable,
+    required,
+)
+from swiftpy.validation.rules.unique import UniqueRule, unique
+
+__all__ = [
+    "BailRule",
+    "BetweenRule",
+    "BoolRule",
+    "EmailRule",
+    "ExistsRule",
+    "FloatRule",
+    "InRule",
+    "IntRule",
+    "MaxRule",
+    "MinRule",
+    "NotInRule",
+    "NullableRule",
+    "RegexRule",
+    "RequiredRule",
+    "RuleRegistry",
+    "StrRule",
+    "UniqueRule",
+    "UrlRule",
+    "bail",
+    "between",
+    "bool_",
+    "boolean",
+    "default_registry",
+    "email",
+    "exists",
+    "float_",
+    "in_",
+    "int_",
+    "integer",
+    "max_",
+    "min_",
+    "not_in",
+    "nullable",
+    "regex",
+    "register_rule",
+    "required",
+    "str_",
+    "string",
+    "unique",
+    "url",
+]