lenapi 0.1.0__py3-none-any.whl

lenapi/database.py

@@ -0,0 +1,84 @@
+"""SQLAlchemy engine and session setup for lenApi applications."""
+
+from contextlib import asynccontextmanager, contextmanager
+from collections.abc import Mapping
+from typing import Any
+
+from sqlalchemy import Engine, create_engine, event
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+
+class Database:
+    """Own a SQLAlchemy engine and create one sync Session per request.
+
+    SQLAlchemy selects the database dialect from the URL. Install the matching
+    DBAPI driver for MySQL or PostgreSQL; SQLite uses Python's built-in driver.
+    """
+
+    def __init__(self, url: str = "sqlite:///lenapi.db", *, engine_options: Mapping[str, Any] | None = None) -> None:
+        options = {"pool_pre_ping": True, **(engine_options or {})}
+        self.engine: Engine = create_engine(url, **options)
+        if self.engine.dialect.name == "sqlite":
+            @event.listens_for(self.engine, "connect")
+            def enable_sqlite_foreign_keys(connection, _record):
+                cursor = connection.cursor()
+                cursor.execute("PRAGMA foreign_keys=ON")
+                cursor.close()
+        self.session_factory = sessionmaker(bind=self.engine, class_=Session)
+        if self.engine.dialect.name == "sqlite":
+            # SQLite creates a file on first connection; create it with Database().
+            with self.engine.connect():
+                pass
+
+    def session(self) -> Session:
+        """Create a session for manual use outside request handlers."""
+        return self.session_factory()
+
+    @contextmanager
+    def transaction(self):
+        """Yield a session that commits on success and rolls back on error.
+
+        Use the yielded session for all related SQLAlchemy operations inside the
+        block; do not call ``commit`` manually.
+        """
+        session = self.session_factory()
+        try:
+            with session.begin():
+                yield session
+        finally:
+            session.close()
+
+    def close(self) -> None:
+        """Dispose the engine's connection pool during application shutdown."""
+        self.engine.dispose()
+
+
+class AsyncDatabase:
+    """Async SQLAlchemy engine and request-scoped ``AsyncSession`` factory.
+
+    Install the driver for the chosen database, for example ``aiosqlite`` for
+    SQLite, ``asyncpg`` for PostgreSQL, or ``asyncmy`` for MySQL.
+    """
+
+    def __init__(self, url: str, *, engine_options: Mapping[str, Any] | None = None) -> None:
+        options = {"pool_pre_ping": True, **(engine_options or {})}
+        self.engine: AsyncEngine = create_async_engine(url, **options)
+        self.session_factory = async_sessionmaker(
+            bind=self.engine, class_=AsyncSession, expire_on_commit=False
+        )
+
+    def session(self) -> AsyncSession:
+        """Create an async session for use with ``async with``."""
+        return self.session_factory()
+
+    @asynccontextmanager
+    async def transaction(self):
+        """Yield an AsyncSession; commit on success and roll back on error."""
+        async with self.session_factory() as session:
+            async with session.begin():
+                yield session
+
+    async def close(self) -> None:
+        """Dispose the async connection pool during application shutdown."""
+        await self.engine.dispose()

lenapi/dependencies.py

@@ -0,0 +1,12 @@
+"""Dependency declaration helpers."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Depends:
+    """Mark a parameter for resolution from another callable."""
+
+    dependency: Callable[..., Any]

lenapi/logging.py

@@ -0,0 +1,13 @@
+"""Public standard-library loggers for lenApi applications."""
+
+import logging as _logging
+
+
+logger = _logging.getLogger("lenapi")
+
+
+def get_logger(name: str | None = None) -> _logging.Logger:
+    """Return lenApi's default logger or a named child logger."""
+    if not name:
+        return logger
+    return _logging.getLogger(f"lenapi.{name}")

lenapi/middleware.py

@@ -0,0 +1,144 @@
+"""Small ASGI middleware components for lenApi applications."""
+
+import secrets
+import time
+from collections.abc import Iterable
+
+
+class RequestIDMiddleware:
+    """Attach a safe request ID to ASGI state and the response headers."""
+
+    def __init__(self, app, *, header_name: str = "X-Request-ID") -> None:
+        self.app = app
+        self.header_name = header_name.encode("latin-1").lower()
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+        supplied = next(
+            (value.decode("latin-1") for name, value in scope.get("headers", [])
+             if name.lower() == self.header_name),
+            "",
+        )
+        if not supplied or len(supplied) > 128 or any(
+            not (character.isalnum() or character in "._-") for character in supplied
+        ):
+            supplied = secrets.token_hex(16)
+        scope.setdefault("state", {})["request_id"] = supplied
+
+        async def send_with_id(message):
+            if message["type"] == "http.response.start":
+                headers = list(message.get("headers", []))
+                headers.append((self.header_name, supplied.encode("latin-1")))
+                message = {**message, "headers": headers}
+            await send(message)
+
+        await self.app(scope, receive, send_with_id)
+
+
+class TimingMiddleware:
+    """Add elapsed request time as an ``X-Process-Time-Ms`` response header."""
+
+    def __init__(self, app, *, header_name: str = "X-Process-Time-Ms") -> None:
+        self.app = app
+        self.header_name = header_name.encode("latin-1").lower()
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+        started = time.perf_counter()
+
+        async def send_with_timing(message):
+            if message["type"] == "http.response.start":
+                elapsed_ms = (time.perf_counter() - started) * 1000
+                headers = list(message.get("headers", []))
+                headers.append((self.header_name, f"{elapsed_ms:.3f}".encode("ascii")))
+                message = {**message, "headers": headers}
+            await send(message)
+
+        await self.app(scope, receive, send_with_timing)
+
+
+class CORSMiddleware:
+    """Configurable CORS handling for browser clients."""
+
+    def __init__(
+        self,
+        app,
+        *,
+        allow_origins: Iterable[str],
+        allow_methods: Iterable[str] = ("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"),
+        allow_headers: Iterable[str] = ("*",),
+        allow_credentials: bool = False,
+        expose_headers: Iterable[str] = (),
+        max_age: int = 600,
+    ) -> None:
+        self.app = app
+        self.allow_origins = set(allow_origins)
+        self.allow_methods = {method.upper() for method in allow_methods}
+        self.allow_headers = {header.lower() for header in allow_headers}
+        self.allow_credentials = allow_credentials
+        self.expose_headers = tuple(expose_headers)
+        self.max_age = max_age
+        if "*" in self.allow_origins and allow_credentials:
+            raise ValueError("CORS wildcard origins cannot be combined with credentials")
+        if isinstance(max_age, bool) or max_age < 0:
+            raise ValueError("CORS max_age must be a non-negative integer")
+
+    def _origin_headers(self, origin: str) -> list[tuple[bytes, bytes]]:
+        allowed = "*" in self.allow_origins or origin in self.allow_origins
+        if not allowed:
+            return []
+        result = [(b"access-control-allow-origin", (origin if self.allow_credentials else
+                                                        ("*" if "*" in self.allow_origins else origin)).encode())]
+        result.append((b"vary", b"Origin"))
+        if self.allow_credentials:
+            result.append((b"access-control-allow-credentials", b"true"))
+        if self.expose_headers:
+            result.append((b"access-control-expose-headers", ", ".join(self.expose_headers).encode()))
+        return result
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+        headers = {name.lower(): value for name, value in scope.get("headers", [])}
+        origin = headers.get(b"origin", b"").decode("latin-1")
+        if not origin:
+            return await self.app(scope, receive, send)
+        cors_headers = self._origin_headers(origin)
+        if not cors_headers:
+            return await self.app(scope, receive, send)
+
+        is_preflight = scope.get("method", "GET").upper() == "OPTIONS" and b"access-control-request-method" in headers
+        if is_preflight:
+            requested_method = headers[b"access-control-request-method"].decode("latin-1").upper()
+            requested_headers = [
+                name.strip().lower()
+                for name in headers.get(b"access-control-request-headers", b"").decode("latin-1").split(",")
+                if name.strip()
+            ]
+            if requested_method not in self.allow_methods or (
+                "*" not in self.allow_headers and any(name not in self.allow_headers for name in requested_headers)
+            ):
+                await send({"type": "http.response.start", "status": 400,
+                            "headers": [(b"content-length", b"0")]})
+                await send({"type": "http.response.body", "body": b""})
+                return
+            cors_headers.extend([
+                (b"access-control-allow-methods", ", ".join(sorted(self.allow_methods)).encode()),
+                (b"access-control-max-age", str(self.max_age).encode()),
+            ])
+            if requested_headers:
+                value = ", ".join(requested_headers) if "*" in self.allow_headers else ", ".join(sorted(self.allow_headers))
+                cors_headers.append((b"access-control-allow-headers", value.encode()))
+            await send({"type": "http.response.start", "status": 204,
+                        "headers": cors_headers + [(b"content-length", b"0")]})
+            await send({"type": "http.response.body", "body": b""})
+            return
+
+        async def send_with_cors(message):
+            if message["type"] == "http.response.start":
+                message = {**message, "headers": list(message.get("headers", [])) + cors_headers}
+            await send(message)
+
+        await self.app(scope, receive, send_with_cors)

lenapi/model.py

@@ -0,0 +1,54 @@
+"""Model base class and field declarations for lenApi projects.
+
+Import this module with ``from lenapi import model`` and declare fields as
+``model.StringField(...)``, ``model.ForeignKeyField(...)``, and so on.
+"""
+
+from .models import (
+    AutoField,
+    Avg,
+    BigIntField,
+    BigIntegerField,
+    BooleanField,
+    CASCADE,
+    Count,
+    DateTimeField,
+    DecimalField,
+    EmailField,
+    Email_field,
+    FloatField,
+    ForeignKeyField,
+    ImageField,
+    IPField,
+    IP_field,
+    IntegerField,
+    JSONField,
+    ManyToManyField,
+    Max,
+    Min,
+    Model,
+    PhoneField,
+    Phone_field,
+    PROTECT,
+    SET_NULL,
+    StringField,
+    Sum,
+    TextField,
+    TExtfield,
+    UUIDField,
+    cascade,
+    null,
+    protected,
+)
+
+# Short alias for JSON column declarations: ``model.Json()``.
+Json = JSONField
+
+__all__ = [
+    "Model", "AutoField", "IntegerField", "BigIntField", "BigIntegerField", "DecimalField", "StringField", "EmailField", "IPField", "PhoneField", "TextField",
+    "Email_field", "IP_field", "Phone_field", "TExtfield",
+    "BooleanField", "FloatField", "DateTimeField", "JSONField", "Json", "UUIDField", "ImageField",
+    "Count", "Sum", "Min", "Max", "Avg",
+    "ForeignKeyField", "ManyToManyField", "CASCADE", "SET_NULL", "PROTECT",
+    "cascade", "null", "protected",
+]