nene2-python 1.0.0__py3-none-any.whl

nene2/__init__.py

@@ -0,0 +1 @@
+"""NENE2 Python — minimal API framework."""

nene2/auth/__init__.py

@@ -0,0 +1,16 @@
+"""NENE2 authentication layer."""
+
+from .api_key import ApiKeyAuthMiddleware
+from .bearer_token import BearerTokenMiddleware
+from .exceptions import TokenVerificationException
+from .interfaces import TokenIssuerProtocol, TokenVerifierProtocol
+from .local_verifier import LocalTokenVerifier
+
+__all__ = [
+    "ApiKeyAuthMiddleware",
+    "BearerTokenMiddleware",
+    "LocalTokenVerifier",
+    "TokenIssuerProtocol",
+    "TokenVerificationException",
+    "TokenVerifierProtocol",
+]

nene2/auth/api_key.py

@@ -0,0 +1,39 @@
+"""API Key authentication middleware.
+
+Validates X-Api-Key header using a TokenVerifierProtocol.
+Returns 401 Problem Details when key is absent or invalid.
+"""
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from nene2.http.problem_details import problem_details_response
+
+from .exceptions import TokenVerificationException
+from .interfaces import TokenVerifierProtocol
+
+_API_KEY_HEADER = "X-Api-Key"
+
+
+class ApiKeyAuthMiddleware(BaseHTTPMiddleware):
+    """Require a valid X-Api-Key header on every request."""
+
+    def __init__(self, app: object, *, verifier: TokenVerifierProtocol) -> None:
+        super().__init__(app)  # type: ignore[arg-type]
+        self._verifier = verifier
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        api_key = request.headers.get(_API_KEY_HEADER, "")
+        try:
+            verified = bool(api_key) and self._verifier.verify(api_key)
+        except TokenVerificationException:
+            verified = False
+        if not verified:
+            return problem_details_response(
+                "unauthorized",
+                "Unauthorized",
+                401,
+                "A valid X-Api-Key header is required.",
+            )
+        return await call_next(request)

nene2/auth/bearer_token.py

@@ -0,0 +1,51 @@
+"""Bearer token authentication middleware.
+
+Validates Authorization: Bearer <token> header.
+Returns 401 Problem Details when token is absent or invalid.
+"""
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from nene2.http.problem_details import problem_details_response
+
+from .exceptions import TokenVerificationException
+from .interfaces import TokenVerifierProtocol
+
+_WWW_AUTH = 'Bearer realm="api"'
+
+
+class BearerTokenMiddleware(BaseHTTPMiddleware):
+    """Require a valid Bearer token on every request."""
+
+    def __init__(self, app: object, *, verifier: TokenVerifierProtocol) -> None:
+        super().__init__(app)  # type: ignore[arg-type]
+        self._verifier = verifier
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        auth = request.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            response = problem_details_response(
+                "unauthorized",
+                "Unauthorized",
+                401,
+                "A valid Bearer token is required.",
+            )
+            response.headers["WWW-Authenticate"] = _WWW_AUTH
+            return response
+        token = auth[len("Bearer ") :]
+        try:
+            verified = self._verifier.verify(token)
+        except TokenVerificationException:
+            verified = False
+        if not verified:
+            response = problem_details_response(
+                "unauthorized",
+                "Unauthorized",
+                401,
+                "The provided token is invalid or expired.",
+            )
+            response.headers["WWW-Authenticate"] = _WWW_AUTH
+            return response
+        return await call_next(request)

nene2/auth/exceptions.py

@@ -0,0 +1,8 @@
+"""Authentication exceptions."""
+
+
+class TokenVerificationException(Exception):
+    """Raised by TokenVerifierProtocol implementations when a token is invalid.
+
+    BearerTokenMiddleware maps this to a 401 Problem Details response.
+    """

nene2/auth/interfaces.py

@@ -0,0 +1,23 @@
+"""Authentication interfaces."""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class TokenVerifierProtocol(Protocol):
+    """Verify an authentication token.
+
+    Implementations may raise TokenVerificationException instead of returning False.
+    """
+
+    def verify(self, token: str) -> bool: ...
+
+
+@runtime_checkable
+class TokenIssuerProtocol(Protocol):
+    """Issue a signed bearer token from the given claims.
+
+    Production implementations wrap a JWT library (e.g. PyJWT).
+    """
+
+    def issue(self, claims: dict[str, object]) -> str: ...

nene2/auth/local_verifier.py

@@ -0,0 +1,17 @@
+"""Local token verifier — compares against a fixed set of allowed tokens.
+
+For development and testing only. In production, implement TokenVerifierProtocol
+against your actual auth backend (database, external IdP, JWT, etc.).
+"""
+
+import secrets
+
+
+class LocalTokenVerifier:
+    """Verify tokens against a fixed allowlist using constant-time comparison."""
+
+    def __init__(self, allowed_tokens: list[str]) -> None:
+        self._allowed = allowed_tokens
+
+    def verify(self, token: str) -> bool:
+        return any(secrets.compare_digest(token, allowed) for allowed in self._allowed)

nene2/config/__init__.py

@@ -0,0 +1,5 @@
+"""Typed config objects — equivalent to PHP AppConfig / DatabaseConfig."""
+
+from .settings import AppSettings
+
+__all__ = ["AppSettings"]

nene2/config/settings.py

@@ -0,0 +1,72 @@
+"""Typed application settings loaded from environment variables."""
+
+from pydantic import SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class AppSettings(BaseSettings):
+    """Application configuration loaded from environment variables."""
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    app_env: str = "local"
+    app_debug: bool = False
+    app_name: str = "nene2-python"
+    security_headers_enabled: bool = True
+    max_body_size: int = 1_048_576  # 1 MiB
+    throttle_enabled: bool = True
+    throttle_limit: int = 60
+    throttle_window: int = 60  # seconds
+
+    cors_enabled: bool = False
+    cors_origins: list[str] = []
+    cors_allow_credentials: bool = False
+    cors_allow_methods: list[str] = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
+    cors_allow_headers: list[str] = [
+        "Content-Type",
+        "Authorization",
+        "X-Api-Key",
+        "X-Request-Id",
+    ]
+
+    bearer_token_enabled: bool = False
+    bearer_tokens: list[str] = []
+
+    api_key_enabled: bool = False
+    api_keys: list[str] = []
+
+    db_adapter: str = "sqlite"
+    db_name: str = ":memory:"
+    db_host: str = "localhost"
+    db_port: int = 3306
+    db_user: str = ""
+    db_password: SecretStr = SecretStr("")
+
+    @field_validator("app_env")
+    @classmethod
+    def validate_app_env(cls, v: str) -> str:
+        allowed = {"local", "test", "production"}
+        if v not in allowed:
+            raise ValueError(f"app_env must be one of {allowed}")
+        return v
+
+    @field_validator("db_adapter")
+    @classmethod
+    def validate_adapter(cls, v: str) -> str:
+        allowed = {"sqlite", "mysql", "pgsql"}
+        if v not in allowed:
+            raise ValueError(f"db_adapter must be one of {allowed}")
+        return v
+
+    @property
+    def db_url(self) -> str:
+        """Build a SQLAlchemy connection URL from adapter + credentials."""
+        if self.db_adapter == "sqlite":
+            return f"sqlite:///{self.db_name}"
+        password = self.db_password.get_secret_value()
+        port = self.db_port
+        if self.db_adapter == "mysql":
+            return f"mysql+pymysql://{self.db_user}:{password}@{self.db_host}:{port}/{self.db_name}"
+        return (
+            f"postgresql+psycopg2://{self.db_user}:{password}@{self.db_host}:{port}/{self.db_name}"
+        )

nene2/database/__init__.py

@@ -0,0 +1,15 @@
+"""NENE2 database abstraction layer."""
+
+from .exceptions import DatabaseConnectionException
+from .health import DatabaseHealthCheck
+from .interfaces import DatabaseQueryExecutorInterface, DatabaseTransactionManagerInterface
+from .sqlalchemy_executor import SqlAlchemyQueryExecutor, SqlAlchemyTransactionManager
+
+__all__ = [
+    "DatabaseConnectionException",
+    "DatabaseHealthCheck",
+    "DatabaseQueryExecutorInterface",
+    "DatabaseTransactionManagerInterface",
+    "SqlAlchemyQueryExecutor",
+    "SqlAlchemyTransactionManager",
+]

nene2/database/exceptions.py

@@ -0,0 +1,5 @@
+"""Database exceptions."""
+
+
+class DatabaseConnectionException(Exception):
+    """Raised when a database connection cannot be established."""

nene2/database/health.py

@@ -0,0 +1,24 @@
+"""Database health check — verifies DB connectivity for /health endpoint."""
+
+import logging
+
+from nene2.http import HealthStatus
+
+from .interfaces import DatabaseQueryExecutorInterface
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseHealthCheck:
+    """Check database connectivity by executing a lightweight query."""
+
+    def __init__(self, executor: DatabaseQueryExecutorInterface) -> None:
+        self._executor = executor
+
+    def check(self) -> HealthStatus:
+        try:
+            self._executor.fetch_one("SELECT 1 AS ok")
+            return HealthStatus(status="ok", checks={"database": "ok"})
+        except Exception as exc:
+            logger.warning("database health check failed: %s", exc)
+            return HealthStatus(status="error", checks={"database": "error"})

nene2/database/interfaces.py

@@ -0,0 +1,51 @@
+"""Database abstraction interfaces.
+
+Equivalent to PHP Nene2\\Database\\DatabaseQueryExecutorInterface
+and DatabaseTransactionManagerInterface.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+
+class DatabaseQueryExecutorInterface(ABC):
+    """Execute parameterised SQL queries against a database."""
+
+    @abstractmethod
+    def fetch_all(self, sql: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]: ...
+
+    @abstractmethod
+    def fetch_one(
+        self, sql: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any] | None: ...
+
+    @abstractmethod
+    def write(self, sql: str, params: dict[str, Any] | None = None) -> int:
+        """Execute INSERT / UPDATE / DELETE.
+
+        Returns lastrowid for INSERT, affected rowcount for UPDATE/DELETE.
+        """
+        ...
+
+
+class DatabaseTransactionManagerInterface(ABC):
+    """Manage database transactions.
+
+    High-level API: use transactional() — it commits on success and rolls back on exception.
+    Low-level API: begin() / commit() / rollback() for manual control.
+    """
+
+    @abstractmethod
+    def transactional[T](self, callback: Callable[[DatabaseQueryExecutorInterface], T]) -> T:
+        """Run callback inside a transaction; commit on success, rollback on exception."""
+        ...
+
+    @abstractmethod
+    def begin(self) -> None: ...
+
+    @abstractmethod
+    def commit(self) -> None: ...
+
+    @abstractmethod
+    def rollback(self) -> None: ...

nene2/database/sqlalchemy_executor.py

@@ -0,0 +1,128 @@
+"""SQLAlchemy Core implementation of database interfaces.
+
+Supports SQLite, MySQL, and PostgreSQL via SQLAlchemy's engine URL.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from sqlalchemy import Connection, Engine, text
+from sqlalchemy.exc import OperationalError
+
+from .exceptions import DatabaseConnectionException
+from .interfaces import DatabaseQueryExecutorInterface, DatabaseTransactionManagerInterface
+
+
+class SqlAlchemyQueryExecutor(DatabaseQueryExecutorInterface):
+    """Execute queries using SQLAlchemy Core (connection-per-call, no ORM)."""
+
+    def __init__(self, engine: Engine) -> None:
+        self._engine = engine
+
+    def fetch_all(self, sql: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        try:
+            with self._engine.connect() as conn:
+                result = conn.execute(text(sql), params or {})
+                return [dict(row._mapping) for row in result]
+        except OperationalError as exc:
+            raise DatabaseConnectionException(str(exc)) from exc
+
+    def fetch_one(self, sql: str, params: dict[str, Any] | None = None) -> dict[str, Any] | None:
+        try:
+            with self._engine.connect() as conn:
+                result = conn.execute(text(sql), params or {})
+                row = result.fetchone()
+                return dict(row._mapping) if row else None
+        except OperationalError as exc:
+            raise DatabaseConnectionException(str(exc)) from exc
+
+    def write(self, sql: str, params: dict[str, Any] | None = None) -> int:
+        """Execute INSERT / UPDATE / DELETE and return a meaningful int.
+
+        Return value semantics:
+        - INSERT with AUTOINCREMENT/SERIAL column → ``lastrowid`` (the new row's PK, always > 0)
+        - INSERT without auto-PK, or multi-row INSERT → falls back to ``rowcount``
+        - UPDATE / DELETE → ``rowcount`` (number of rows affected; 0 means nothing matched)
+
+        Use the return value to detect missing rows::
+
+            affected = executor.write("UPDATE ... WHERE id = :id", {"id": pk})
+            if affected == 0:
+                raise NotFoundException(pk)
+        """
+        try:
+            with self._engine.begin() as conn:
+                result = conn.execute(text(sql), params or {})
+                return result.lastrowid or result.rowcount
+        except OperationalError as exc:
+            raise DatabaseConnectionException(str(exc)) from exc
+
+
+class _BoundQueryExecutor(DatabaseQueryExecutorInterface):
+    """Query executor bound to an existing connection (within a transaction)."""
+
+    def __init__(self, conn: Connection) -> None:
+        self._conn = conn
+
+    def fetch_all(self, sql: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        try:
+            result = self._conn.execute(text(sql), params or {})
+            return [dict(row._mapping) for row in result]
+        except OperationalError as exc:
+            raise DatabaseConnectionException(str(exc)) from exc
+
+    def fetch_one(self, sql: str, params: dict[str, Any] | None = None) -> dict[str, Any] | None:
+        try:
+            result = self._conn.execute(text(sql), params or {})
+            row = result.fetchone()
+            return dict(row._mapping) if row else None
+        except OperationalError as exc:
+            raise DatabaseConnectionException(str(exc)) from exc
+
+    def write(self, sql: str, params: dict[str, Any] | None = None) -> int:
+        try:
+            result = self._conn.execute(text(sql), params or {})
+        except OperationalError as exc:
+            raise DatabaseConnectionException(str(exc)) from exc
+        return result.lastrowid or result.rowcount
+
+
+class SqlAlchemyTransactionManager(DatabaseTransactionManagerInterface):
+    """Manage database transactions using SQLAlchemy.
+
+    Use transactional() for the recommended callback-based API.
+    Use begin() / commit() / rollback() for explicit transaction control.
+    """
+
+    def __init__(self, engine: Engine) -> None:
+        self._engine = engine
+        self._conn: Connection | None = None
+        # reason: RootTransaction is an internal SQLAlchemy type not exported in the public API
+        self._tx: Any = None
+
+    def transactional[T](self, callback: Callable[[DatabaseQueryExecutorInterface], T]) -> T:
+        try:
+            with self._engine.begin() as conn:
+                return callback(_BoundQueryExecutor(conn))
+        except OperationalError as exc:
+            raise DatabaseConnectionException(str(exc)) from exc
+
+    def begin(self) -> None:
+        self._conn = self._engine.connect()
+        self._tx = self._conn.begin()
+
+    def commit(self) -> None:
+        if self._tx is not None:
+            self._tx.commit()
+            self._tx = None
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+
+    def rollback(self) -> None:
+        if self._tx is not None:
+            self._tx.rollback()
+            self._tx = None
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None

nene2/http/__init__.py

@@ -0,0 +1,14 @@
+"""HTTP helpers — JSON responses, pagination, problem details, health."""
+
+from .health import HealthCheckProtocol, HealthStatus
+from .pagination import PaginationQuery, PaginationQueryParser, PaginationResponse
+from .problem_details import problem_details_response
+
+__all__ = [
+    "HealthCheckProtocol",
+    "HealthStatus",
+    "PaginationQuery",
+    "PaginationQueryParser",
+    "PaginationResponse",
+    "problem_details_response",
+]

nene2/http/health.py

@@ -0,0 +1,20 @@
+"""HealthCheckProtocol and HealthStatus — framework health check contract."""
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class HealthStatus:
+    status: str
+    checks: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def is_healthy(self) -> bool:
+        return self.status == "ok"
+
+
+class HealthCheckProtocol(Protocol):
+    """Contract for application health checks."""
+
+    def check(self) -> HealthStatus: ...

nene2/http/pagination.py

@@ -0,0 +1,93 @@
+"""Pagination helpers.
+
+Equivalent to PHP Nene2\\Http\\PaginationQueryParser, PaginationQuery, PaginationResponse.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from fastapi import Request
+
+from nene2.validation.exceptions import ValidationError, ValidationException
+
+
+@dataclass(frozen=True, slots=True)
+class PaginationQuery:
+    """Parsed and validated ?limit= / ?offset= parameters."""
+
+    limit: int
+    offset: int
+
+
+class PaginationQueryParser:
+    """Parses and validates pagination query parameters from a FastAPI Request."""
+
+    @staticmethod
+    def parse(
+        request: Request,
+        *,
+        default_limit: int = 20,
+        max_limit: int = 100,
+    ) -> PaginationQuery:
+        """Parse ?limit= and ?offset= from the request.
+
+        Raises ValidationException (→ 422) when values are out of range.
+        """
+        params = request.query_params
+
+        errors: list[ValidationError] = []
+        try:
+            limit = int(params.get("limit", default_limit))
+        except ValueError:
+            errors.append(ValidationError("limit", "limit must be an integer.", "invalid"))
+            limit = default_limit
+        try:
+            offset = int(params.get("offset", 0))
+        except ValueError:
+            errors.append(ValidationError("offset", "offset must be an integer.", "invalid"))
+            offset = 0
+
+        if limit < 1 or limit > max_limit:
+            errors.append(
+                ValidationError(
+                    field="limit",
+                    message=f"limit must be between 1 and {max_limit}.",
+                    code="out_of_range",
+                )
+            )
+        if offset < 0:
+            errors.append(
+                ValidationError(
+                    field="offset",
+                    message="offset must be 0 or greater.",
+                    code="out_of_range",
+                )
+            )
+        if errors:
+            raise ValidationException(errors)
+
+        return PaginationQuery(limit=limit, offset=offset)
+
+
+@dataclass(frozen=True, slots=True)
+class PaginationResponse:
+    """Standard list-endpoint response envelope.
+
+    Equivalent to PHP Nene2\\Http\\PaginationResponse.
+    The ``total`` key is omitted from the output when not provided.
+    """
+
+    items: list[Any]
+    limit: int
+    offset: int
+    total: int | None = field(default=None)
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "items": self.items,
+            "limit": self.limit,
+            "offset": self.offset,
+        }
+        if self.total is not None:
+            data["total"] = self.total
+        return data

nene2/http/problem_details.py

@@ -0,0 +1,37 @@
+"""RFC 9457 Problem Details response factory.
+
+Equivalent to PHP Nene2\\Error\\ProblemDetailsResponseFactory.
+"""
+
+from typing import Any
+
+from fastapi.responses import JSONResponse
+
+PROBLEM_DETAILS_BASE_URL = "https://nene2.dev/problems/"
+
+
+def problem_details_response(
+    problem_type: str,
+    title: str,
+    status: int,
+    detail: str | None = None,
+    extra: dict[str, Any] | None = None,
+    *,
+    base_url: str = PROBLEM_DETAILS_BASE_URL,
+) -> JSONResponse:
+    """Build an RFC 9457 Problem Details JSON response."""
+    body: dict[str, Any] = {
+        "type": base_url + problem_type,
+        "title": title,
+        "status": status,
+    }
+    if detail:
+        body["detail"] = detail
+    if extra:
+        body.update(extra)
+
+    return JSONResponse(
+        content=body,
+        status_code=status,
+        media_type="application/problem+json",
+    )

nene2/log/__init__.py

@@ -0,0 +1,5 @@
+"""NENE2 structured logging setup (structlog)."""
+
+from .setup import setup_logging
+
+__all__ = ["setup_logging"]