nyxa 0.1.0__py3-none-any.whl

nyxa/__init__.py

@@ -0,0 +1,100 @@
+"""nyxa — FastAPI scaffolding CLI and shared runtime bases."""
+
+from nyxa.abort import (
+    abort,
+    conflict,
+    forbidden,
+    gone,
+    not_found,
+    too_many_requests,
+    unauthorized,
+    validation_error,
+)
+from nyxa.auth_stubs import check, current_user, guest, user
+from nyxa.container import (
+    Container,
+    ContainerError,
+    bind,
+    container,
+    has,
+    inject,
+    instance,
+    make,
+    resolve,
+    singleton,
+)
+from nyxa.context import ContextMiddleware, context
+from nyxa.cors import configure_cors
+from nyxa.errors import (
+    AppError,
+    ConflictError,
+    ForbiddenError,
+    GoneError,
+    NotFoundError,
+    TooManyRequestsError,
+    UnauthorizedError,
+    ValidationError,
+)
+from nyxa.events import EventDispatcher, dispatcher
+from nyxa.helpers import clear_config_cache, config, env, settings
+from nyxa.logging_config import configure_logging
+from nyxa.providers import ServiceProvider
+from nyxa.registry import register
+from nyxa.requests import FormRequest
+from nyxa.response import accepted, created, json_response, no_content, success
+from nyxa.routing import Controller, Route, route
+
+__all__ = [
+    "AppError",
+    "ConflictError",
+    "Container",
+    "ContainerError",
+    "ContextMiddleware",
+    "Controller",
+    "EventDispatcher",
+    "ForbiddenError",
+    "FormRequest",
+    "GoneError",
+    "NotFoundError",
+    "Route",
+    "ServiceProvider",
+    "TooManyRequestsError",
+    "UnauthorizedError",
+    "ValidationError",
+    "abort",
+    "accepted",
+    "bind",
+    "check",
+    "clear_config_cache",
+    "config",
+    "configure_cors",
+    "configure_logging",
+    "conflict",
+    "container",
+    "context",
+    "created",
+    "current_user",
+    "dispatcher",
+    "env",
+    "forbidden",
+    "gone",
+    "guest",
+    "has",
+    "inject",
+    "instance",
+    "json_response",
+    "make",
+    "no_content",
+    "not_found",
+    "register",
+    "resolve",
+    "route",
+    "settings",
+    "singleton",
+    "success",
+    "too_many_requests",
+    "unauthorized",
+    "user",
+    "validation_error",
+]
+__version__ = "0.1.0"

nyxa/abort.py

@@ -0,0 +1,105 @@
+"""Abort helpers that raise :class:`~nyxa.errors.AppError` subclasses."""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+from nyxa.errors import (
+    AppError,
+    ConflictError,
+    ForbiddenError,
+    GoneError,
+    NotFoundError,
+    TooManyRequestsError,
+    UnauthorizedError,
+    ValidationError,
+)
+
+
+def unauthorized(message: str | None = None, *, code: str | None = None) -> NoReturn:
+    """Abort with HTTP 401 (:class:`~nyxa.errors.UnauthorizedError`).
+
+    Args:
+        message: Optional override for the default message.
+        code: Optional override for the default error code.
+    """
+    raise UnauthorizedError(message, code=code)
+
+
+def forbidden(message: str | None = None, *, code: str | None = None) -> NoReturn:
+    """Abort with HTTP 403 (:class:`~nyxa.errors.ForbiddenError`).
+
+    Args:
+        message: Optional override for the default message.
+        code: Optional override for the default error code.
+    """
+    raise ForbiddenError(message, code=code)
+
+
+def not_found(message: str | None = None, *, code: str | None = None) -> NoReturn:
+    """Abort with HTTP 404 (:class:`~nyxa.errors.NotFoundError`).
+
+    Args:
+        message: Optional override for the default message.
+        code: Optional override for the default error code.
+    """
+    raise NotFoundError(message, code=code)
+
+
+def conflict(message: str | None = None, *, code: str | None = None) -> NoReturn:
+    """Abort with HTTP 409 (:class:`~nyxa.errors.ConflictError`).
+
+    Args:
+        message: Optional override for the default message.
+        code: Optional override for the default error code.
+    """
+    raise ConflictError(message, code=code)
+
+
+def gone(message: str | None = None, *, code: str | None = None) -> NoReturn:
+    """Abort with HTTP 410 (:class:`~nyxa.errors.GoneError`).
+
+    Args:
+        message: Optional override for the default message.
+        code: Optional override for the default error code.
+    """
+    raise GoneError(message, code=code)
+
+
+def validation_error(
+    errors: Any,
+    message: str | None = None,
+    *,
+    code: str | None = None,
+) -> NoReturn:
+    """Abort with HTTP 422 (:class:`~nyxa.errors.ValidationError`).
+
+    Args:
+        errors: Field-level validation details included in the JSON body.
+        message: Optional override for the default message.
+        code: Optional override for the default error code.
+    """
+    raise ValidationError(errors, message, code=code)
+
+
+def too_many_requests(message: str | None = None, *, code: str | None = None) -> NoReturn:
+    """Abort with HTTP 429 (:class:`~nyxa.errors.TooManyRequestsError`).
+
+    Args:
+        message: Optional override for the default message.
+        code: Optional override for the default error code.
+    """
+    raise TooManyRequestsError(message, code=code)
+
+
+def abort(status: int, message: str | None = None, *, code: str | None = None) -> NoReturn:
+    """Abort with an arbitrary HTTP status via :class:`~nyxa.errors.AppError`.
+
+    Args:
+        status: HTTP status code for the response.
+        message: Optional message (defaults to ``Application error``).
+        code: Optional error code (defaults to ``app_error``).
+    """
+    exc = AppError(message, code=code)
+    exc.status_code = status
+    raise exc

nyxa/app.py

@@ -0,0 +1,85 @@
+"""nyxa CLI entrypoints (`nyxa`, `artisan`, and `dev`)."""
+
+from __future__ import annotations
+
+import sys
+from importlib import import_module
+
+import typer
+import uvicorn
+
+from nyxa import init_cmd, list_cmd
+from nyxa.config import clear_settings_cache, load_settings
+
+# ``nyxa.make`` CLI module (not the container ``make`` function exported from ``nyxa``).
+make_cmd = import_module("nyxa.make")
+
+app = typer.Typer(
+    name="nyxa",
+    help="Batteries-included scaffolding CLI for Python API backends on FastAPI.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+init_cmd.register(app)
+make_cmd.register(app)
+list_cmd.register(app)
+
+try:
+    from nyxa_db.cli import register as register_db
+
+    register_db(app)
+except ImportError:
+    pass
+
+try:
+    from nyxa_auth.cli import register as register_auth
+
+    register_auth(app)
+except ImportError:
+    pass
+
+try:
+    from nyxa_queue.cli import register as register_queue
+
+    register_queue(app)
+except ImportError:
+    pass
+
+try:
+    from nyxa_cache.cli import register as register_cache
+
+    register_cache(app)
+except ImportError:
+    pass
+
+try:
+    from nyxa_mail.cli import register as register_mail
+
+    register_mail(app)
+except ImportError:
+    pass
+
+
+def _clear_terminal() -> None:
+    """Clear the screen and scrollback buffer."""
+    sys.stdout.write("\033[2J\033[3J\033[H")
+    sys.stdout.flush()
+
+
+def dev() -> None:
+    """Run the API with settings from optional `nyxa.toml`."""
+    clear_settings_cache()
+    settings = load_settings()
+    dev_cfg = settings.resolved_dev()
+    _clear_terminal()
+    uvicorn.run(
+        dev_cfg.module,
+        host=dev_cfg.host,
+        port=dev_cfg.port,
+        reload=dev_cfg.reload,
+    )
+
+
+if __name__ == "__main__":
+    app()

nyxa/auth_stubs.py

@@ -0,0 +1,34 @@
+"""Auth convenience stubs (current user / id / check) over request context."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from nyxa.context import USER_CONTEXT_KEY, context
+
+
+def current_user() -> Any | None:
+    """Return the authenticated user from request context, or ``None`` if guest.
+
+    ``nyxa-auth`` writes the user into context when resolving JWT auth.
+    Apps without auth never set the key and always see a guest.
+
+    Returns:
+        User object stored under ``USER_CONTEXT_KEY``, or ``None``.
+    """
+    return context.get(USER_CONTEXT_KEY)
+
+
+def user() -> Any | None:
+    """Alias of :func:`current_user`."""
+    return current_user()
+
+
+def guest() -> bool:
+    """Return ``True`` when no authenticated user is in context."""
+    return current_user() is None
+
+
+def check() -> bool:
+    """Return ``True`` when an authenticated user is in context."""
+    return current_user() is not None

nyxa/config.py

@@ -0,0 +1,277 @@
+"""Load optional project-root `nyxa.toml` with built-in defaults."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field, replace
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_PATHS: dict[str, str] = {
+    "errors": "http/exception/errors",
+    "handlers": "http/exception/handlers",
+    "requests": "http/requests",
+    "responses": "http/responses",
+    "middleware": "http/middleware",
+    "controllers": "http/controllers",
+    "dependencies": "http/dependencies",
+    "services": "services",
+    "schemas": "schemas",
+    "enums": "domain/enums",
+    "config": "config",
+    "events": "events",
+    "listeners": "listeners",
+    "jobs": "jobs",
+    "models": "models",
+    "policies": "policies",
+    "providers": "providers",
+    "tests": "tests",
+}
+
+DEFAULT_ERROR_BASE = "nyxa.errors:AppError"
+DEFAULT_ENV_FILE = ".env"
+
+
+@dataclass(frozen=True, slots=True)
+class DevSettings:
+    """Uvicorn settings for `nyxa` / `dev`."""
+
+    module: str
+    host: str = "0.0.0.0"
+    port: int = 8000
+    reload: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class CorsSettings:
+    """CORS middleware settings from ``[cors]`` or ``CORS_ORIGINS``."""
+
+    origins: list[str] = field(default_factory=list)
+    allow_credentials: bool = False
+    allow_methods: list[str] = field(default_factory=lambda: ["*"])
+    allow_headers: list[str] = field(default_factory=lambda: ["*"])
+
+
+@dataclass(frozen=True, slots=True)
+class LoggingSettings:
+    """Logging settings from ``[logging]`` or ``NYXA_LOG_*`` env."""
+
+    json: bool = False
+    level: str = "INFO"
+
+
+@dataclass(frozen=True, slots=True)
+class NyxaSettings:
+    """Resolved project settings for generators and runtime registration."""
+
+    root: Path
+    app: str
+    src: str = "src"
+    paths: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_PATHS))
+    error_base: str = DEFAULT_ERROR_BASE
+    env_file: str = DEFAULT_ENV_FILE
+    env_environment: str | None = None
+    middleware_global: list[str] = field(default_factory=list)
+    providers_boot: list[str] = field(default_factory=list)
+    cors: CorsSettings | None = None
+    logging: LoggingSettings | None = None
+    dev: DevSettings | None = None
+
+    @property
+    def app_dir(self) -> Path:
+        """Filesystem path to the application package."""
+        return self.root / self.src / self.app
+
+    @property
+    def tests_dir(self) -> Path:
+        """Filesystem path to the tests directory."""
+        return self.root / self.paths.get("tests", "tests")
+
+    def path(self, key: str) -> Path:
+        """Return an absolute path under the app package for a `[paths]` key."""
+        relative = self.paths.get(key, DEFAULT_PATHS[key])
+        return self.app_dir / relative
+
+    def package(self, key: str) -> str:
+        """Return a dotted package name for a `[paths]` key under the app."""
+        relative = self.paths.get(key, DEFAULT_PATHS[key])
+        return f"{self.app}." + relative.replace("/", ".").replace("\\", ".")
+
+    def error_base_parts(self) -> tuple[str, str]:
+        """Split `error_base` into `(module, attr)`."""
+        module, _, attr = self.error_base.partition(":")
+        if not module or not attr:
+            raise ValueError(f"Invalid [bases].error value: {self.error_base!r}")
+        return module, attr
+
+    def resolved_dev(self) -> DevSettings:
+        """Return dev settings, defaulting module to `{app}.main:app`."""
+        if self.dev is not None:
+            return self.dev
+        return DevSettings(module=f"{self.app}.main:app")
+
+
+def find_project_root(start: Path | None = None) -> Path:
+    """Walk upward to the consumer app root.
+
+    Prefers an ancestor with ``nyxa.toml`` so commands work from nested
+    package dirs in a monorepo. Falls back to the nearest ``pyproject.toml``.
+    """
+    current = (start or Path.cwd()).resolve()
+    ancestors = [current, *current.parents]
+
+    for path in ancestors:
+        if (path / "nyxa.toml").is_file():
+            return path
+
+    for path in ancestors:
+        if (path / "pyproject.toml").is_file():
+            return path
+
+    raise FileNotFoundError(
+        "Could not find project root (nyxa.toml or pyproject.toml)."
+    )
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    with path.open("rb") as handle:
+        return tomllib.load(handle)
+
+
+def _app_from_pyproject(root: Path) -> str | None:
+    data = _read_toml(root / "pyproject.toml")
+    tool = data.get("tool", {})
+    for key in ("nyxa", "artisan"):
+        app = tool.get(key, {}).get("app")
+        if isinstance(app, str) and app:
+            return app
+    return None
+
+
+@lru_cache(maxsize=8)
+def load_settings(start: str | None = None) -> NyxaSettings:
+    """Load settings from `nyxa.toml` / pyproject.
+
+    Pass *start* as a string path for cacheability; use ``None`` for cwd.
+    """
+    root = find_project_root(Path(start) if start else None)
+    file_data = _read_toml(root / "nyxa.toml")
+
+    app = file_data.get("app") or _app_from_pyproject(root)
+    if not app:
+        # Last resort: first package under src/ that isn't a known tool package
+        src_dir = root / str(file_data.get("src", "src"))
+        candidates = [
+            p.name
+            for p in src_dir.iterdir()
+            if p.is_dir() and (p / "__init__.py").exists() and p.name not in {"nyxa", "cli"}
+        ] if src_dir.is_dir() else []
+        if not candidates:
+            raise RuntimeError(
+                "Could not determine app package name. "
+                "Set `app` in nyxa.toml or run `nyxa init <name>`."
+            )
+        app = sorted(candidates)[0]
+
+    src = str(file_data.get("src", "src"))
+    paths = dict(DEFAULT_PATHS)
+    paths.update({k: str(v) for k, v in (file_data.get("paths") or {}).items()})
+
+    bases = file_data.get("bases") or {}
+    error_base = str(bases.get("error", DEFAULT_ERROR_BASE))
+
+    env_data = file_data.get("env") or {}
+    env_file = str(env_data.get("file", DEFAULT_ENV_FILE))
+    raw_environment = env_data.get("environment")
+    env_environment = str(raw_environment) if raw_environment else None
+
+    middleware_data = file_data.get("middleware") or {}
+    raw_global = middleware_data.get("global") or []
+    if isinstance(raw_global, str):
+        middleware_global = [raw_global]
+    else:
+        middleware_global = [str(item) for item in raw_global]
+
+    providers_data = file_data.get("providers") or {}
+    raw_boot = providers_data.get("boot") or []
+    if isinstance(raw_boot, str):
+        providers_boot = [raw_boot]
+    else:
+        providers_boot = [str(item) for item in raw_boot]
+
+    cors_data = file_data.get("cors") or {}
+    cors: CorsSettings | None = None
+    if cors_data:
+        raw_origins = cors_data.get("origins") or []
+        if isinstance(raw_origins, str):
+            origins = [raw_origins]
+        else:
+            origins = [str(item) for item in raw_origins]
+        raw_methods = cors_data.get("allow_methods")
+        raw_headers = cors_data.get("allow_headers")
+        cors = CorsSettings(
+            origins=origins,
+            allow_credentials=bool(cors_data.get("allow_credentials", False)),
+            allow_methods=(
+                [str(m) for m in raw_methods]
+                if isinstance(raw_methods, list)
+                else (["*"] if raw_methods is None else [str(raw_methods)])
+            ),
+            allow_headers=(
+                [str(h) for h in raw_headers]
+                if isinstance(raw_headers, list)
+                else (["*"] if raw_headers is None else [str(raw_headers)])
+            ),
+        )
+
+    logging_data = file_data.get("logging") or {}
+    logging_settings: LoggingSettings | None = None
+    if logging_data:
+        logging_settings = LoggingSettings(
+            json=bool(logging_data.get("json", False)),
+            level=str(logging_data.get("level", "INFO")),
+        )
+
+    dev_data = file_data.get("dev") or {}
+    module = dev_data.get("module") or f"{app}.main:app"
+    dev = DevSettings(
+        module=str(module),
+        host=str(dev_data.get("host", "0.0.0.0")),
+        port=int(dev_data.get("port", 8000)),
+        reload=bool(dev_data.get("reload", True)),
+    )
+
+    return NyxaSettings(
+        root=root,
+        app=str(app),
+        src=src,
+        paths=paths,
+        error_base=error_base,
+        env_file=env_file,
+        env_environment=env_environment,
+        middleware_global=middleware_global,
+        providers_boot=providers_boot,
+        cors=cors,
+        logging=logging_settings,
+        dev=dev,
+    )
+
+
+def clear_settings_cache() -> None:
+    """Clear the cached settings (useful after init / tests)."""
+    load_settings.cache_clear()
+    try:
+        from nyxa.helpers import clear_config_cache
+
+        clear_config_cache()
+    except ImportError:
+        pass
+
+
+def with_overrides(settings: NyxaSettings, **kwargs: Any) -> NyxaSettings:
+    """Return a copy of *settings* with selected fields replaced."""
+    return replace(settings, **kwargs)