nyxa-forms 0.0.1__py3-none-any.whl

nyxa_forms/__init__.py

@@ -0,0 +1,23 @@
+"""nyxa-forms — web validation: FormRequest, rule strings, error bags, old input."""
+
+from nyxa_forms.provider import FormsProvider
+from nyxa_forms.request import FormRequest
+from nyxa_forms.validator import (
+    Enum,
+    Password,
+    PasswordRule,
+    ValidationException,
+    Validator,
+    rule,
+)
+
+__all__ = [
+    "Enum",
+    "FormRequest",
+    "FormsProvider",
+    "Password",
+    "PasswordRule",
+    "ValidationException",
+    "Validator",
+    "rule",
+]

nyxa_forms/commands.py

@@ -0,0 +1,71 @@
+"""``make:request`` — scaffold a FormRequest under ``app/requests/``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from nyxa.command import Command
+
+
+class MakeRequestCommand(Command):
+    """``nyxa make:request`` — generate a FormRequest class."""
+
+    signature = (
+        "make:request {name : resource/module name (post → app/requests/post.py)} "
+        "{--fields= : field specs name:type[:rules…],comma-separated} "
+        "{--update : emit only the Update class} "
+        "{--describe= : natural-language intent — AI/fallback fills rules} "
+        "{--force : overwrite existing}"
+    )
+    help = "Generate a FormRequest under app/requests/ (--fields for rule bodies)."
+    needs_app = False
+
+    def handle(
+        self,
+        name: str,
+        fields: str | None = None,
+        update: bool = False,
+        describe: str | None = None,
+        force: bool = False,
+    ) -> int:
+        """Write ``app/requests/<name>.py`` (optionally field-driven rules).
+
+        ``name`` is the resource/module name: ``post`` writes
+        ``app/requests/post.py`` holding the ``Store`` and ``Update``
+        FormRequest classes.
+
+        Args:
+            name: Resource/module name (must be a valid identifier).
+            fields: Optional ``name:type[:rules…]`` specs; when set, rules are
+                generated via the shared field grammar for both classes.
+            update: Emit only the ``Update`` class.
+            describe: Natural-language AI fill of the request rules.
+            force: Overwrite an existing file.
+
+        Returns:
+            ``0`` on success, ``1`` on invalid name or refusal to overwrite.
+        """
+        import re
+
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", name):
+            self.error(f"invalid resource name {name!r}")
+            return 1
+        from nyxa.cli.make import make_form_request
+
+        make_form_request(
+            name,
+            fields,
+            for_update=update,
+            io=self.io,
+            force=force,
+        )
+        if describe:
+            from nyxa.cli.ai_scaffold import fill
+
+            root = Path.cwd()
+            snake = "".join(f"_{c.lower()}" if c.isupper() else c for c in name).lstrip("_")
+            target = root / "app" / "requests" / f"{snake}.py"
+            if target.is_file():
+                body = fill(describe, "form request", name, target.read_text())
+                target.write_text(body)
+        return 0

nyxa_forms/handler.py

@@ -0,0 +1,35 @@
+"""``FormsExceptionHandler`` — HTML redirect-back vs JSON 422 for validation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, override
+
+from nyxa.exceptions import ExceptionHandler
+
+if TYPE_CHECKING:
+    from nyxa.http.context import HttpContext
+    from nyxa.http.response import Response
+
+
+class FormsExceptionHandler(ExceptionHandler):
+    """Wraps the app's handler — ``ValidationException`` becomes a
+    redirect-back + flashed errors/old-input for HTML requests, 422
+    JSON otherwise. Everything else delegates to the previous handler.
+    """
+
+    def __init__(self, inner: ExceptionHandler) -> None:
+        """Wrap ``inner`` — the app's previous handler."""
+        self.inner = inner
+
+    @override
+    async def handle(self, error: Exception, ctx: HttpContext) -> Response:
+        """Redirect-back with flash for HTML validation failures."""
+        from nyxa.http.response import Response
+        from nyxa_forms.helpers import flash_old, with_errors
+        from nyxa_forms.validator import ValidationException
+
+        if isinstance(error, ValidationException) and not ctx.request.wants_json():
+            with_errors(ctx, error.bag)
+            flash_old(ctx, error.data)
+            return Response.redirect(ctx.request.header("referer") or "/", status=303)
+        return await self.inner.handle(error, ctx)

nyxa_forms/helpers.py

@@ -0,0 +1,134 @@
+"""Flash/old-input + redirect helpers layered on ``nyxa-session``."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Protocol, TypeGuard, overload, runtime_checkable
+
+if TYPE_CHECKING:
+    from nyxa.http.context import HttpContext
+    from nyxa.http.response import Response
+
+
+@runtime_checkable
+class _FlashSession(Protocol):
+    """Session bag surface used for one-request form flashes."""
+
+    def get(self, key: str, default: object = None) -> object:
+        """Read one session value."""
+        ...
+
+    def flash(self, key: str, value: object) -> None:
+        """Persist one value for the next request."""
+        ...
+
+
+def _session(ctx: HttpContext) -> _FlashSession | None:
+    """Narrow the optional session-store object held in request state.
+
+    Args:
+        ctx: Request context whose session middleware may have populated state.
+
+    Returns:
+        A compatible flash session, or ``None`` when unavailable.
+    """
+    value: object = ctx.state.get("session")
+    return value if isinstance(value, _FlashSession) else None
+
+
+def _object_dict(value: object) -> TypeGuard[dict[str, object]]:
+    """Validate a dynamic form bag as a string-keyed mapping."""
+    return isinstance(value, dict) and all(isinstance(key, str) for key in value)
+
+
+def _object_list(value: object) -> TypeGuard[list[object]]:
+    """Narrow one field's dynamic error messages to a list."""
+    return isinstance(value, list)
+
+
+def old(ctx: HttpContext, key: str, default: object = "") -> object:
+    """Return a prior request's flashed value for one field.
+
+    Args:
+        ctx: Current request context.
+        key: Field name whose old input is requested.
+        default: Value returned when the field was not flashed.
+
+    Returns:
+        Flashed field value or ``default``.
+    """
+    session = _session(ctx)
+    if session is None:
+        return default
+    bag: object = session.get("_old", {})
+    return bag.get(key, default) if _object_dict(bag) else default
+
+
+@overload
+def errors(ctx: HttpContext, key: None = None) -> dict[str, object]: ...
+
+
+@overload
+def errors(ctx: HttpContext, key: str) -> list[object]: ...
+
+
+def errors(ctx: HttpContext, key: str | None = None) -> dict[str, object] | list[object]:
+    """Return the flashed validation bag or messages for one field.
+
+    Args:
+        ctx: Current request context.
+        key: Optional field whose validation messages are requested.
+
+    Returns:
+        A copied error bag or a field's message list; malformed state yields empty data.
+    """
+    session = _session(ctx)
+    if session is None:
+        return {} if key is None else []
+    raw_bag: object = session.get("errors", {})
+    if not _object_dict(raw_bag):
+        return {} if key is None else []
+    if key is None:
+        return raw_bag
+    raw_messages: object = raw_bag.get(key, [])
+    return raw_messages if _object_list(raw_messages) else []
+
+
+def with_errors(ctx: HttpContext, bag: Mapping[str, object]) -> None:
+    """Flash a validation error bag for the next request.
+
+    Args:
+        ctx: Current request context.
+        bag: Field names mapped to their validation messages.
+    """
+    session = _session(ctx)
+    if session is not None:
+        session.flash("errors", dict(bag))
+
+
+def flash_old(ctx: HttpContext, data: Mapping[str, object]) -> None:
+    """Flash request input for ``old()`` repopulation.
+
+    Args:
+        ctx: Current request context.
+        data: Input fields to make available to the next request.
+    """
+    session = _session(ctx)
+    if session is not None:
+        session.flash("_old", dict(data))
+
+
+def back(ctx: HttpContext, *, fallback: str = "/") -> Response:
+    """Redirect to the referer, using ``fallback`` when none is present.
+
+    Args:
+        ctx: Current request context.
+        fallback: Relative URL used when the request has no referer.
+
+    Returns:
+        Redirect response to the request referer or fallback URL.
+    """
+    from nyxa.http.response import Response
+
+    url = ctx.request.header("referer") or fallback
+    return Response.redirect(url)

nyxa_forms/kind.py

@@ -0,0 +1,58 @@
+"""``FormRequest`` contract kind — route injection via contract_kinds()."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from nyxa_forms.request import FormRequest
+
+if TYPE_CHECKING:
+    from nyxa.contracts import Decoder, Encoder
+    from nyxa.http.request import Request
+    from nyxa.types import JSONValue
+
+
+class FormRequestKind:
+    """Contract kind resolving ``FormRequest`` subclasses on routes."""
+
+    name = "form_request"
+
+    def matches(self, model: object) -> bool:
+        """Whether ``model`` is a ``FormRequest`` subclass."""
+        return isinstance(model, type) and issubclass(model, FormRequest)
+
+    def request_decoder(self, model: type) -> Decoder:
+        """Build a decoder returning a validated ``FormRequest``."""
+        assert issubclass(model, FormRequest)
+
+        async def decode(request: Request) -> FormRequest:
+            """Validate the request payload into a FormRequest.
+
+            Awaitable by design — ``serve._dispatch`` awaits decoders that
+            return coroutines, which is how db-aware rules work.
+            """
+            from nyxa.http.context import current_ctx
+
+            ctx = current_ctx()
+            payload = request._payload()
+            data = dict(payload) if isinstance(payload, dict) else {}
+            instance = model()
+            await instance.validate_against(ctx, data)
+            return instance
+
+        return decode
+
+    def encoder(self, model: type) -> Encoder:
+        """Encode (unused — FormRequests are input contracts)."""
+
+        def encode(value: object) -> bytes:
+            """Serialize a value — FormRequests are input-only contracts."""
+            import orjson
+
+            return orjson.dumps(value)
+
+        return encode
+
+    def schema(self, model: type) -> dict[str, JSONValue]:
+        """No OpenAPI schema for rule-string contracts."""
+        return {}

nyxa_forms/provider.py

@@ -0,0 +1,109 @@
+"""FormsProvider — FormRequest contract kind, ``ctx.validate_web``, helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine, Iterable, Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, override
+
+from nyxa.providers import ServiceProvider
+
+if TYPE_CHECKING:
+    from nyxa.contracts import ContractKind
+    from nyxa.http.context import HttpContext
+
+_STUBS = Path(__file__).parent / "stubs"
+
+
+class FormsProvider(ServiceProvider):
+    """Registers the forms surface: validator macros + FormRequest kind."""
+
+    name = "forms"
+
+    @override
+    def contract_kinds(self) -> Iterable[ContractKind]:
+        """The ``FormRequest`` model family for route injection."""
+        from nyxa_forms.kind import FormRequestKind
+
+        return [FormRequestKind()]
+
+    @override
+    def boot(self) -> None:
+        """Wrap the exception handler — HTML validation → redirect+flash."""
+        from nyxa_forms.handler import FormsExceptionHandler
+
+        self.app.use_exception_handler(FormsExceptionHandler(self.app.exception_handler))
+
+    @override
+    def macros(self) -> Mapping[type, Mapping[str, object]]:
+        """``ctx.validate_web``, ``ctx.old``, ``ctx.errors``, ``ctx.back``."""
+        from nyxa.http.context import HttpContext
+        from nyxa_forms.helpers import back, errors, old
+
+        def _validate_web(
+            ctx: HttpContext,
+        ) -> Callable[[dict[str, str]], Coroutine[object, object, dict[str, object]]]:
+            """``ctx.validate_web`` — the request validator factory."""
+
+            async def validate(rules: dict[str, str]) -> dict[str, object]:
+                """Validate request input against ``rules`` — raises on fail."""
+                from nyxa_forms.validator import Validator
+
+                payload = ctx.request._payload()
+                data = dict(payload) if isinstance(payload, dict) else {}
+                v = Validator(data, rules, app=ctx.app, ctx=ctx)
+                return await v.validate()
+
+            return validate
+
+        def _old(ctx: HttpContext) -> Callable[[str], object]:
+            """``ctx.old`` — flashed-input getter factory."""
+
+            def get(key: str, default: object = "") -> object:
+                """``ctx.old("email")`` — flashed input or ``default``."""
+                return old(ctx, key, default)
+
+            return get
+
+        def _errors(ctx: HttpContext) -> Callable[[], object]:
+            """``ctx.errors`` — flashed error-bag getter factory."""
+
+            def get(key: str | None = None) -> object:
+                """``ctx.errors()`` bag or ``ctx.errors("email")`` messages."""
+                return errors(ctx, key)
+
+            return get
+
+        def _back(ctx: HttpContext) -> Callable[[], object]:
+            """``ctx.back`` — redirect-to-referer factory."""
+
+            def go(*, fallback: str = "/") -> object:
+                """``ctx.back()`` — redirect to the referer."""
+                return back(ctx, fallback=fallback)
+
+            return go
+
+        return {
+            HttpContext: {
+                "validate_web": property(_validate_web),
+                "old": property(_old),
+                "errors": property(_errors),
+                "back": property(_back),
+            }
+        }
+
+    @override
+    def commands(self) -> Iterable[type]:
+        """``make:request``."""
+        from nyxa_forms.commands import MakeRequestCommand
+
+        return [MakeRequestCommand]
+
+    @override
+    def configure(self) -> None:
+        """``nyxa add nyxa-forms`` — write ``config/forms.py`` + a request stub."""
+        target = self.app.root / "config" / "forms.py"
+        if not target.exists():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text((_STUBS / "config_forms.stub").read_text())
+        print(f"nyxa-forms configured — config at {target}")

nyxa_forms/request.py

@@ -0,0 +1,135 @@
+"""``FormRequest`` — authorize + rules + validated() for web forms."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Mapping
+from typing import TYPE_CHECKING
+
+from nyxa_forms.validator import RuleSpec, Validator
+
+if TYPE_CHECKING:
+    from nyxa.http.context import HttpContext
+
+
+class FormRequest:
+    """Base class for injectable, self-validating web requests.
+
+    ::
+
+        class StorePost(FormRequest):
+            def rules(self) -> dict[str, str]:
+                return {"title": "required|max:255", "body": "required"}
+
+            def authorize(self, ctx) -> bool:
+                return ctx.user is not None
+
+        @app.router.post("/posts")
+        def store(ctx, request: StorePost):
+            Post.create(request.validated())
+
+    A handler param typed to a ``FormRequest`` subclass is injected by
+    the contract kind registered by ``FormsProvider``.
+
+    Pipeline: ``prepare_for_validation`` → ``authorize`` → build
+    validator (``with_validator`` hook) → rules + ``sometimes`` →
+    ``after`` hook → ``validated``.
+    """
+
+    _validated: dict[str, object]
+    _errors: dict[str, list[str]]
+    _data: dict[str, object]
+    ctx: HttpContext | None = None
+
+    #: halt all rule evaluation at the first failure when True
+    stop_on_first_failure = False
+
+    def authorize(self, ctx: HttpContext | None) -> bool:
+        """Whether the request is allowed — default: always."""
+        return True
+
+    def rules(self) -> Mapping[str, RuleSpec]:
+        """Validation rules for this request."""
+        return {}
+
+    def messages(self) -> Mapping[str, str]:
+        """Custom ``field.rule`` messages."""
+        return {}
+
+    def attributes(self) -> Mapping[str, str]:
+        """Field name → friendly name used in generated messages."""
+        return {}
+
+    def prepare_for_validation(
+        self, data: dict[str, object]
+    ) -> dict[str, object] | Awaitable[dict[str, object] | None] | None:
+        """Mutate/replace input before rules run (sync or async).
+
+        Return the new payload, or ``None`` to keep in-place edits —
+        for trimming, merging route params, or normalizing input.
+        """
+        return None
+
+    def with_validator(self, validator: Validator) -> Awaitable[None] | None:
+        """Configure the validator before rules run (e.g. ``sometimes()``)."""
+        return None
+
+    def after(self, validator: Validator) -> Awaitable[None] | None:
+        """Post-validation hook — ``validator.add_error`` fails the request."""
+        return None
+
+    def validated(self, *keys: str) -> dict[str, object]:
+        """Validated input — optionally filtered to top-level ``keys``."""
+        if keys:
+            return {k: self._validated[k] for k in keys if k in self._validated}
+        return dict(self._validated)
+
+    def errors(self) -> dict[str, list[str]]:
+        """The error bag after a failed validation (empty on success)."""
+        return self._errors
+
+    def input(self, key: str | None = None, default: object = None) -> object:
+        """Raw (prepared) request input — all, or one key."""
+        return self._data if key is None else self._data.get(key, default)
+
+    async def _maybe_await[T](self, result: T | Awaitable[T]) -> T:
+        """Await ``result`` when it is awaitable, else return it."""
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    async def validate_against(self, ctx: HttpContext | None, data: dict[str, object]) -> None:
+        """Run the prepare → authorize → rules → after pipeline; raises."""
+        from nyxa.http.exceptions import ForbiddenException
+        from nyxa_forms.validator import ValidationException
+
+        self.ctx = ctx
+        prepared = await self._maybe_await(self.prepare_for_validation(data))
+        if prepared is not None:
+            data = prepared
+        self._data = data
+        if not self.authorize(ctx):
+            raise ForbiddenException("This action is unauthorized")
+        app = ctx.app if ctx is not None else None
+        telemetry = app.telemetry if app is not None else None
+        v = Validator(
+            data,
+            self.rules(),
+            app=app,
+            messages=self.messages(),
+            attributes=self.attributes(),
+            ctx=ctx,
+            stop_on_first_failure=self.stop_on_first_failure,
+        )
+        await self._maybe_await(self.with_validator(v))
+        await v.fails()
+        await self._maybe_await(self.after(v))
+        if v.errors():
+            self._errors = v.errors()
+            if telemetry is not None:
+                telemetry.emit("form.failed", request=type(self).__name__, fields=len(self._errors))
+            raise ValidationException(self._errors, data)
+        self._validated = v.validated()
+        self._errors = {}
+        if telemetry is not None:
+            telemetry.emit("form.validated", request=type(self).__name__)

nyxa_forms/stubs/config_forms.stub

@@ -0,0 +1,3 @@
+"""Forms configuration — validation behavior for web requests."""
+
+config = {}