nyxa 0.0.1__py3-none-any.whl

nyxa/__init__.py

@@ -0,0 +1,296 @@
+"""Nyxa — a standalone backend framework for Python."""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # Declared for static analyzers; the real bindings resolve lazily via
+    # ``__getattr__`` below so ``import nyxa`` stays near-free.
+    from nyxa.command import Command
+    from nyxa.config.config import define_config
+    from nyxa.config.env import Env
+    from nyxa.context import Context
+    from nyxa.controller import Controller, Middleware
+    from nyxa.core.application import Application
+    from nyxa.core.container import (
+        CircularDependencyError,
+        Container,
+        ContainerError,
+        Inject,
+        Provider,
+        ResolutionError,
+        Scope,
+    )
+    from nyxa.db.collection import Collection
+    from nyxa.db.factory import Factory
+    from nyxa.db.manager import DB, Schema
+    from nyxa.db.migrations import Migration
+    from nyxa.db.model import Model
+    from nyxa.db.seeder import Seeder
+    from nyxa.db.traits import SoftDeletes
+    from nyxa.errors import NyxaError
+    from nyxa.events import Event, EventEmitter, Listener
+    from nyxa.exceptions import ExceptionHandler, HttpExceptionHandler
+    from nyxa.http.context import HttpContext, get_request, use
+    from nyxa.http.exceptions import (
+        BadRequestException,
+        ConflictException,
+        ForbiddenException,
+        HttpException,
+        InternalServerErrorException,
+        MethodNotAllowedException,
+        ModelNotFound,
+        NotFoundException,
+        ServiceUnavailableException,
+        TooManyRequestsException,
+        UnauthorizedException,
+        ValidationException,
+        abort,
+    )
+    from nyxa.http.params import Body, Cookie, Files, Form, Header, Ip, Path, Query
+    from nyxa.http.request import Request
+    from nyxa.http.response import Response, ResponseBuilder, use_response
+    from nyxa.http.streaming import sse_event, sse_stream
+    from nyxa.http.websocket import Ws, WsClosed
+    from nyxa.middleware import MiddlewareRegistry
+    from nyxa.process import Process
+    from nyxa.providers import ServiceProvider
+    from nyxa.routing import Route, RouteError, Router
+    from nyxa.routing.ambient import router
+    from nyxa.testing import TestClient
+
+
+def _package_version() -> str:
+    """Return the installed ``nyxa`` distribution version.
+
+    Source of truth is ``packages/nyxa/pyproject.toml`` (stamped by
+    ``.github/sync_version.py`` on release). Falls back when the package
+    metadata is not on ``sys.path`` yet (raw source tree).
+    """
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("nyxa")
+    except PackageNotFoundError:
+        from pathlib import Path
+        from tomllib import loads
+
+        try:
+            manifest = loads((Path(__file__).resolve().parents[2] / "pyproject.toml").read_text())
+            return str(manifest["project"]["version"])
+        except (KeyError, OSError):
+            return "0.0.0+local"
+
+
+__version__ = _package_version()
+
+
+__all__ = [
+    "DB",
+    "Application",
+    "BadRequestException",
+    "Body",
+    "CircularDependencyError",
+    "Collection",
+    "Command",
+    "ConflictException",
+    "Container",
+    "ContainerError",
+    "Context",
+    "Controller",
+    "Cookie",
+    "Env",
+    "Event",
+    "EventEmitter",
+    "ExceptionHandler",
+    "Factory",
+    "Files",
+    "ForbiddenException",
+    "Form",
+    "Header",
+    "HttpContext",
+    "HttpException",
+    "HttpExceptionHandler",
+    "Inject",
+    "InternalServerErrorException",
+    "Ip",
+    "Listener",
+    "MethodNotAllowedException",
+    "Middleware",
+    "MiddlewareRegistry",
+    "Migration",
+    "Model",
+    "ModelNotFound",
+    "NotFoundException",
+    "NyxaError",
+    "Path",
+    "Process",
+    "Provider",
+    "Query",
+    "Request",
+    "ResolutionError",
+    "Response",
+    "ResponseBuilder",
+    "Route",
+    "RouteError",
+    "Router",
+    "Schema",
+    "Scope",
+    "Seeder",
+    "ServiceProvider",
+    "ServiceUnavailableException",
+    "SoftDeletes",
+    "TestClient",
+    "TooManyRequestsException",
+    "UnauthorizedException",
+    "ValidationException",
+    "Ws",
+    "WsClosed",
+    "__version__",
+    "abort",
+    "define_config",
+    "get_request",
+    "router",
+    "sse_event",
+    "sse_stream",
+    "use",
+    "use_response",
+]
+
+# Every public name → the module that defines it. ``import nyxa`` pays for
+# nothing but this module object; a name imports its backing module on first
+# access and caches the result in ``globals()``.
+_LAZY = {
+    "Application": "nyxa.core.application",
+    "Command": "nyxa.command",
+    "Context": "nyxa.context",
+    "define_config": "nyxa.config.config",
+    "CircularDependencyError": "nyxa.core.container",
+    "Container": "nyxa.core.container",
+    "ContainerError": "nyxa.core.container",
+    "Inject": "nyxa.core.container",
+    "Provider": "nyxa.core.container",
+    "ResolutionError": "nyxa.core.container",
+    "Scope": "nyxa.core.container",
+    "Controller": "nyxa.controller",
+    "Middleware": "nyxa.controller",
+    "Env": "nyxa.config.env",
+    "Event": "nyxa.events",
+    "EventEmitter": "nyxa.events",
+    "Listener": "nyxa.events",
+    "NyxaError": "nyxa.errors",
+    "ExceptionHandler": "nyxa.exceptions",
+    "HttpExceptionHandler": "nyxa.exceptions",
+    "BadRequestException": "nyxa.http.exceptions",
+    "ConflictException": "nyxa.http.exceptions",
+    "ForbiddenException": "nyxa.http.exceptions",
+    "HttpException": "nyxa.http.exceptions",
+    "InternalServerErrorException": "nyxa.http.exceptions",
+    "MethodNotAllowedException": "nyxa.http.exceptions",
+    "ModelNotFound": "nyxa.http.exceptions",
+    "NotFoundException": "nyxa.http.exceptions",
+    "ServiceUnavailableException": "nyxa.http.exceptions",
+    "TooManyRequestsException": "nyxa.http.exceptions",
+    "UnauthorizedException": "nyxa.http.exceptions",
+    "ValidationException": "nyxa.http.exceptions",
+    "abort": "nyxa.http.exceptions",
+    "Body": "nyxa.http.params",
+    "Cookie": "nyxa.http.params",
+    "Files": "nyxa.http.params",
+    "Form": "nyxa.http.params",
+    "Header": "nyxa.http.params",
+    "Ip": "nyxa.http.params",
+    "Path": "nyxa.http.params",
+    "Query": "nyxa.http.params",
+    "HttpContext": "nyxa.http.context",
+    "get_request": "nyxa.http.context",
+    "use": "nyxa.http.context",
+    "Request": "nyxa.http.request",
+    "Response": "nyxa.http.response",
+    "ResponseBuilder": "nyxa.http.response",
+    "use_response": "nyxa.http.response",
+    "sse_event": "nyxa.http.streaming",
+    "sse_stream": "nyxa.http.streaming",
+    "Ws": "nyxa.http.websocket",
+    "WsClosed": "nyxa.http.websocket",
+    "MiddlewareRegistry": "nyxa.middleware",
+    "Process": "nyxa.process",
+    "ServiceProvider": "nyxa.providers",
+    "Route": "nyxa.routing",
+    "RouteError": "nyxa.routing",
+    "Router": "nyxa.routing",
+    "router": "nyxa.routing.ambient",
+    "TestClient": "nyxa.testing",
+    "Collection": "nyxa.db.collection",
+    "DB": "nyxa.db.manager",
+    "Schema": "nyxa.db.manager",
+    "Factory": "nyxa.db.factory",
+    "Migration": "nyxa.db.migrations",
+    "Model": "nyxa.db.model",
+    "Seeder": "nyxa.db.seeder",
+    "SoftDeletes": "nyxa.db.traits",
+}
+
+# Submodules reachable as attributes (``nyxa.db`` without an explicit
+# ``import nyxa.db``) — resolved lazily the same way.
+_MODULES = frozenset(
+    {
+        "adapters",
+        "application",
+        "asgi",
+        "bridge",
+        "build",
+        "cli",
+        "command",
+        "config",
+        "console",
+        "container",
+        "context",
+        "contracts",
+        "core",
+        "controller",
+        "db",
+        "discovery",
+        "env",
+        "errors",
+        "events",
+        "exceptions",
+        "helpers",
+        "http",
+        "ignitor",
+        "logging",
+        "manifest",
+        "middleware",
+        "openapi",
+        "plugins",
+        "process",
+        "providers",
+        "pytest_plugin",
+        "queue",
+        "routing",
+        "rsgi",
+        "scheduling",
+        "security",
+        "server",
+        "testing",
+        "types",
+        "workflows",
+        "wsgi",
+    }
+)
+
+
+# Any required — PEP 562 lazy re-export: the resolved type is unknowable at the
+# signature level (dynamic-attribute carve-out).
+def __getattr__(name: str) -> Any:  # noqa: ANN401 — see comment above
+    """Lazy public surface — names and submodules import on first access."""
+    import importlib
+
+    module = _LAZY.get(name)
+    if module is not None:
+        value = getattr(importlib.import_module(module), name)
+    elif name in _MODULES:
+        value = importlib.import_module(f"nyxa.{name}")
+    else:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    globals()[name] = value
+    return value

nyxa/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m nyxa`` — delegates to the console entry point."""
+
+from nyxa.cli import entrypoint
+
+if __name__ == "__main__":
+    entrypoint()

nyxa/_awaitable.py

@@ -0,0 +1,46 @@
+"""Fast awaitable probe for hot paths.
+
+``inspect.isawaitable`` falls through to an ABC ``isinstance`` for every value
+that is not a coroutine, which dominates the cost of the common case (a
+handler returned a plain model, dict or ``None``). Awaitability is a property
+of the *type* (the one exception, generator-based coroutines, is excluded), so
+negative answers are memoized per type.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable
+from types import CoroutineType, GeneratorType
+from typing import TypeGuard
+
+_NOT_AWAITABLE: set[type] = {type(None), bool, int, float, str, bytes, dict, list, tuple}
+_NOT_AWAITABLE_MAX = 4096
+
+
+def is_awaitable(obj: object) -> TypeGuard[Awaitable[object]]:
+    """Whether ``await obj`` is valid — same answer as :func:`inspect.isawaitable`.
+
+    Args:
+        obj: Any handler/listener/hook result.
+
+    Returns:
+        ``True`` for coroutines, futures and other awaitables.
+
+    Example:
+        >>> is_awaitable(1), is_awaitable(None)
+        (False, False)
+    """
+    kind = type(obj)
+    if kind is CoroutineType:
+        return True
+    if kind in _NOT_AWAITABLE:
+        return False
+    if inspect.isawaitable(obj):
+        return True
+    if kind is not GeneratorType and len(_NOT_AWAITABLE) < _NOT_AWAITABLE_MAX:
+        _NOT_AWAITABLE.add(kind)
+    return False
+
+
+__all__ = ["is_awaitable"]

nyxa/_current.py

@@ -0,0 +1,44 @@
+"""Process-local reference to the most recently created Application.
+
+Lets module-level helpers that have no app handle — bare
+``Job.dispatch(...)`` and the ``DB``/``Schema`` facades are the canonical
+cases — reach the lazily bound managers without importing feature stacks
+at boot. ``tick()`` orders app construction against facade bindings so
+"most recently bound wins" keeps working across lazy creation.
+"""
+
+from __future__ import annotations
+
+import weakref
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nyxa.core.application import Application
+
+_app: weakref.ReferenceType[Application] | None = None
+_app_seq = 0
+_tick = 0
+
+
+def tick() -> int:
+    """Monotonic sequence — bump on app creation and facade binds."""
+    global _tick
+    _tick += 1
+    return _tick
+
+
+def set_app(app: Application) -> None:
+    """Record ``app`` as the current application."""
+    global _app, _app_seq
+    _app = weakref.ref(app)
+    _app_seq = tick()
+
+
+def get_app() -> Application | None:
+    """The most recently created live application, or ``None``."""
+    return _app() if _app is not None else None
+
+
+def app_seq() -> int:
+    """The sequence at which the current app was created."""
+    return _app_seq

nyxa/_speedups.py

@@ -0,0 +1,170 @@
+"""Bundled native accelerators behind pure-Python references.
+
+``nyxa-speedups`` is a separate compiled distribution. Each helper here has a
+Python reference implementation with identical results; the native version
+handles the common inputs and returns ``None`` for anything else (non-ASCII,
+quoted cookies, unusual header items), which falls back to the reference.
+Set ``NYXA_NO_SPEEDUPS=1`` to force the Python versions.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from collections.abc import Callable, Iterable, Mapping
+from http.cookies import SimpleCookie
+from types import ModuleType
+from urllib.parse import parse_qsl
+
+from nyxa.types import FormValue, NativeHeaderIndex, NativeMatcher
+
+
+def _load() -> ModuleType | None:
+    if os.environ.get("NYXA_NO_SPEEDUPS"):
+        return None
+    try:
+        return importlib.import_module("nyxa_speedups")
+    except ImportError:
+        return None
+
+
+native: ModuleType | None = _load()
+"""The ``nyxa_speedups`` module, or ``None`` when absent or disabled."""
+
+
+def py_parse_query(qs: str) -> dict[str, str]:
+    """Reference: query-string parameters, last value wins, blanks kept."""
+    return dict(parse_qsl(qs, keep_blank_values=True))
+
+
+def py_parse_cookies(header: str) -> dict[str, str]:
+    """Reference: ``Cookie`` header as ``SimpleCookie`` reads it."""
+    jar = SimpleCookie(header)
+    return {k: morsel.value for k, morsel in jar.items()}
+
+
+def py_parse_query_multi(qs: str) -> dict[str, str | list[str]]:
+    """Reference: ``parse_qsl`` with repeated keys collapsed into lists."""
+    out: dict[str, str | list[str]] = {}
+    for k, v in parse_qsl(qs, keep_blank_values=True):
+        if k in out:
+            existing = out[k]
+            if isinstance(existing, list):
+                existing.append(v)
+            else:
+                out[k] = [existing, v]
+        else:
+            out[k] = v
+    return out
+
+
+def _with_fallback[T, R](fast: Callable[[T], R | None], reference: Callable[[T], R]) -> Callable[[T], R]:
+    """Wrap ``fast`` so a ``None`` result re-runs through ``reference``."""
+
+    def parse(value: T) -> R:
+        result = fast(value)
+        return result if result is not None else reference(value)
+
+    parse.__doc__ = reference.__doc__
+    return parse
+
+
+if native is not None:
+    parse_query: Callable[[str], dict[str, str]] = _with_fallback(native.parse_query, py_parse_query)
+    parse_cookies: Callable[[str], dict[str, str]] = _with_fallback(native.parse_cookies, py_parse_cookies)
+    parse_query_multi: Callable[[str], dict[str, str | list[str]]] = _with_fallback(
+        native.parse_query_multi, py_parse_query_multi
+    )
+else:
+    parse_query = py_parse_query
+    parse_cookies = py_parse_cookies
+    parse_query_multi = py_parse_query_multi
+
+Matcher: type[NativeMatcher] | None = native.Matcher if native is not None else None
+"""Native route matcher class (see ``RouteTree``), or ``None``."""
+
+scan_headers: Callable[[Iterable[tuple[bytes, bytes]]], tuple[bytes | None, bool] | None] | None = (
+    native.scan_headers if native is not None else None
+)
+"""``(x-request-id, declares_body)`` over ASGI headers, ``None`` to fall back; or ``None``."""
+
+encode_headers: Callable[[dict[str, str]], list[tuple[bytes, bytes]] | None] | None = (
+    native.encode_headers if native is not None else None
+)
+"""ASGI response header list for ASCII headers, ``None`` to fall back; or ``None``."""
+
+parse_multipart: (
+    Callable[
+        [bytes, bytes, int, int, int | None],
+        tuple[dict[str, FormValue], list[tuple[str, str, str, bytes]]] | None,
+    ]
+    | None
+) = getattr(native, "parse_multipart", None) if native is not None else None
+"""Multipart boundary scanner — ``(fields, file_parts)`` or ``None`` to fall back."""
+
+header_index: Callable[[Iterable[tuple[bytes, bytes]]], NativeHeaderIndex | None] | None = (
+    getattr(native, "header_index", None) if native is not None else None
+)
+"""Build a ``HeaderIndex`` over raw ASGI header pairs, ``None`` to fall back; or ``None``."""
+
+flatten_headers: Callable[[dict[str, str | list[str]]], list[tuple[str, str]] | None] | None = (
+    getattr(native, "flatten_headers", None) if native is not None else None
+)
+"""``header_items`` equivalent, ``None`` to fall back; or ``None``."""
+
+normalize_headers: Callable[[dict[str, str | list[str]], dict[str, object]], tuple[()] | None] | None = (
+    getattr(native, "normalize_headers", None) if native is not None else None
+)
+"""Default-header merge into a response's dict in place, ``None`` to fall back; or ``None``."""
+
+native_sign_cookie: Callable[[str, str, bool], str] | None = (
+    getattr(native, "sign_cookie", None) if native is not None else None
+)
+"""Fused ``<b64>.<hmac>`` signer, or ``None`` when the wheel is absent."""
+
+native_verify_cookie: Callable[[str, str, float | None], str | None] | None = (
+    getattr(native, "verify_cookie", None) if native is not None else None
+)
+"""Fused signed-cookie verify, ``None`` on invalid or unusual input; or ``None``."""
+
+url_build: Callable[[str, Mapping[str, object], Mapping[str, str], Mapping[str, str]], str | None] | None = (
+    getattr(native, "url_build", None) if native is not None else None
+)
+"""Route URL substitution + constraint checks, ``None`` to fall back; or ``None``."""
+
+validate_plan: (
+    Callable[
+        [dict[str, list[tuple[int, list[str], int]]], dict[str, object]],
+        dict[str, dict[str, list[int]]] | None,
+    ]
+    | None
+) = getattr(native, "validate_plan", None) if native is not None else None
+"""Native evaluation of a compiled validation plan's pure rules; or ``None``."""
+
+native_rule_ids: dict[str, int] = dict(getattr(native, "NATIVE_RULE_IDS", {})) if native is not None else {}
+"""rule name → plan id for the native-evaluable pure rules; empty when absent."""
+
+
+def py_paginate_to_json(rows: list[dict[str, object]], meta: Mapping[str, object]) -> bytes:
+    """Reference: ``{data, meta}`` envelope via orjson (plain JSON scalars only)."""
+    import orjson
+
+    return orjson.dumps({"data": rows, "meta": dict(meta)})
+
+
+def _native_paginate_to_json(rows: list[dict[str, object]], meta: Mapping[str, object]) -> bytes | None:
+    """Call the Rust encoder; ``None`` means fall back to Python."""
+    if native is None:
+        return None
+    fn = getattr(native, "paginate_to_json", None)
+    if fn is None:
+        return None
+    return fn(rows, dict(meta))
+
+
+paginate_to_json: Callable[[list[dict[str, object]], Mapping[str, object]], bytes] = (
+    (lambda rows, meta: _native_paginate_to_json(rows, meta) or py_paginate_to_json(rows, meta))
+    if native is not None
+    else py_paginate_to_json
+)
+"""``{data, meta}`` JSON bytes — native when installed, else orjson."""

nyxa/adapters/__init__.py

@@ -0,0 +1,72 @@
+"""Deployment adapters — the platform contract and the built-ins."""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from nyxa.adapters.asgi import AsgiAdapter
+    from nyxa.adapters.base import (
+        Adapter,
+        AdapterError,
+        Capabilities,
+        collect_adapters,
+        required_capabilities,
+        spawn,
+    )
+    from nyxa.adapters.cloudrun import CloudRunAdapter
+    from nyxa.adapters.container import ContainerAdapter
+    from nyxa.adapters.docker import DockerAdapter
+    from nyxa.adapters.fly import FlyAdapter
+    from nyxa.adapters.granian import GranianAdapter
+    from nyxa.adapters.native import NativeAdapter
+    from nyxa.adapters.railway import RailwayAdapter
+    from nyxa.adapters.render import RenderAdapter
+
+__all__ = [
+    "Adapter",
+    "AdapterError",
+    "AsgiAdapter",
+    "Capabilities",
+    "CloudRunAdapter",
+    "ContainerAdapter",
+    "DockerAdapter",
+    "FlyAdapter",
+    "GranianAdapter",
+    "NativeAdapter",
+    "RailwayAdapter",
+    "RenderAdapter",
+    "collect_adapters",
+    "required_capabilities",
+    "spawn",
+]
+
+_LAZY = {
+    "AsgiAdapter": "nyxa.adapters.asgi",
+    "Adapter": "nyxa.adapters.base",
+    "AdapterError": "nyxa.adapters.base",
+    "Capabilities": "nyxa.adapters.base",
+    "CloudRunAdapter": "nyxa.adapters.cloudrun",
+    "ContainerAdapter": "nyxa.adapters.container",
+    "collect_adapters": "nyxa.adapters.base",
+    "required_capabilities": "nyxa.adapters.base",
+    "spawn": "nyxa.adapters.base",
+    "DockerAdapter": "nyxa.adapters.docker",
+    "FlyAdapter": "nyxa.adapters.fly",
+    "GranianAdapter": "nyxa.adapters.granian",
+    "NativeAdapter": "nyxa.adapters.native",
+    "RailwayAdapter": "nyxa.adapters.railway",
+    "RenderAdapter": "nyxa.adapters.render",
+}
+
+
+# Any required — PEP 562 lazy re-export: the resolved type is unknowable at the
+# signature level (dynamic-attribute carve-out).
+def __getattr__(name: str) -> Any:  # noqa: ANN401 — see comment above
+    """Lazy attribute exports — keeps ``import nyxa.adapters`` cheap."""
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value
+    return value