lenapi 0.1.0__py3-none-any.whl

lenapi/mongodb.py

@@ -0,0 +1,262 @@
+"""Optional MongoDB integration using the official PyMongo driver.
+
+MongoDB documents are Pydantic models, separate from LenApi's SQLAlchemy
+``Model`` classes and Alembic migrations.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MultipleDocumentsFound(LookupError):
+    """Raised when ``MongoDocument.get`` matches more than one document."""
+
+
+class MongoDatabase:
+    """Own sync and async PyMongo clients for one MongoDB database.
+
+    Install with ``pip install 'lenapi[mongodb]'``. Network I/O stays lazy until
+    the first query or an explicit ``ping()`` / ``aping()`` call.
+    """
+
+    def __init__(self, uri: str | None = None, database_name: str | None = None,
+                 *, client=None, async_client=None, **client_options) -> None:
+        self.uri = uri or os.getenv("MONGODB_URI")
+        self.database_name = database_name or os.getenv("MONGODB_DATABASE")
+        if not self.uri:
+            raise ValueError("Pass uri or set MONGODB_URI")
+        if not self.database_name:
+            raise ValueError("Pass database_name or set MONGODB_DATABASE")
+        MongoClient = AsyncMongoClient = None
+        if client is None or async_client is None:
+            try:
+                from pymongo import AsyncMongoClient, MongoClient
+            except ImportError as exc:
+                raise ImportError("MongoDB support requires `pip install 'lenapi[mongodb]'`") from exc
+        self.client = client if client is not None else MongoClient(self.uri, **client_options)
+        self.async_client = async_client if async_client is not None else AsyncMongoClient(self.uri, **client_options)
+        self.database = self.client[self.database_name]
+        self.async_database = self.async_client[self.database_name]
+
+    def collection(self, name: str):
+        """Return a synchronous PyMongo collection."""
+        return self.database[name]
+
+    def acollection(self, name: str):
+        """Return an asynchronous PyMongo collection."""
+        return self.async_database[name]
+
+    def ping(self) -> bool:
+        """Check connectivity synchronously."""
+        return self.client.admin.command("ping").get("ok") == 1.0
+
+    async def aping(self) -> bool:
+        """Check connectivity asynchronously."""
+        result = await self.async_client.admin.command("ping")
+        return result.get("ok") == 1.0
+
+    def close(self) -> None:
+        """Close the synchronous client."""
+        self.client.close()
+
+    async def aclose(self) -> None:
+        """Close both clients; await this from ASGI shutdown or async code."""
+        self.client.close()
+        await self.async_client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_exc):
+        self.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_exc):
+        await self.aclose()
+
+
+def _object_id(value):
+    if isinstance(value, str) and len(value) == 24:
+        try:
+            from bson import ObjectId
+            if ObjectId.is_valid(value):
+                return ObjectId(value)
+        except ImportError:
+            pass
+    return value
+
+
+def _mongo_filter(filters: dict[str, Any]) -> dict[str, Any]:
+    result = dict(filters)
+    if "id" in result:
+        result["_id"] = _object_id(result.pop("id"))
+    if "_id" in result:
+        result["_id"] = _object_id(result["_id"])
+    return result
+
+
+def _document_values(document: dict[str, Any]) -> dict[str, Any]:
+    result = dict(document)
+    if "_id" in result:
+        result["id"] = str(result.pop("_id"))
+    return result
+
+
+class MongoDocument(BaseModel):
+    """Pydantic document base for MongoDB collections.
+
+    Bind each subclass to a ``MongoDatabase``. The default collection is the
+    lower-case class name; override ``collection_name`` to choose another.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+    id: str | None = Field(default=None, alias="_id")
+    collection_name: ClassVar[str | None] = None
+    _mongo_database: ClassVar[MongoDatabase | None] = None
+
+    @classmethod
+    def bind(cls, database: MongoDatabase):
+        """Bind this document class to a configured MongoDatabase."""
+        cls._mongo_database = database
+        return cls
+
+    @classmethod
+    def _collection_name(cls) -> str:
+        return cls.collection_name or cls.__name__.lower()
+
+    @classmethod
+    def _database(cls) -> MongoDatabase:
+        if cls._mongo_database is None:
+            raise RuntimeError(f"Bind {cls.__name__} to MongoDatabase first: {cls.__name__}.bind(db)")
+        return cls._mongo_database
+
+    @classmethod
+    def _from_document(cls, value: dict[str, Any] | None):
+        return None if value is None else cls.model_validate(_document_values(value))
+
+    def _as_document(self) -> dict[str, Any]:
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+    def save(self):
+        """Insert this document, or update its existing document by ``id``."""
+        collection = type(self)._database().collection(type(self)._collection_name())
+        values = self._as_document()
+        if self.id is None:
+            result = collection.insert_one(values)
+            self.id = str(result.inserted_id)
+        else:
+            values.pop("_id", None)
+            collection.update_one({"_id": _object_id(self.id)}, {"$set": values}, upsert=True)
+        return self
+
+    async def asave(self):
+        """Async insert or update."""
+        collection = type(self)._database().acollection(type(self)._collection_name())
+        values = self._as_document()
+        if self.id is None:
+            result = await collection.insert_one(values)
+            self.id = str(result.inserted_id)
+        else:
+            values.pop("_id", None)
+            await collection.update_one({"_id": _object_id(self.id)}, {"$set": values}, upsert=True)
+        return self
+
+    @classmethod
+    def create(cls, **values):
+        """Validate, insert, and return a document."""
+        return cls(**values).save()
+
+    @classmethod
+    async def acreate(cls, **values):
+        """Async validate, insert, and return a document."""
+        return await cls(**values).asave()
+
+    @classmethod
+    def get(cls, **filters):
+        """Return one matching document, or ``None``; reject duplicate matches."""
+        collection = cls._database().collection(cls._collection_name())
+        query = _mongo_filter(filters)
+        cursor = collection.find(query).limit(2)
+        rows = list(cursor)
+        if len(rows) > 1:
+            raise MultipleDocumentsFound(f"More than one {cls.__name__} matches the query")
+        return cls._from_document(rows[0]) if rows else None
+
+    @classmethod
+    async def aget(cls, **filters):
+        """Async form of ``get``."""
+        collection = cls._database().acollection(cls._collection_name())
+        cursor = collection.find(_mongo_filter(filters)).limit(2)
+        rows = await cursor.to_list(length=2)
+        if len(rows) > 1:
+            raise MultipleDocumentsFound(f"More than one {cls.__name__} matches the query")
+        return cls._from_document(rows[0]) if rows else None
+
+    @classmethod
+    def filter(cls, **filters):
+        """Return all documents matching a MongoDB query."""
+        collection = cls._database().collection(cls._collection_name())
+        return [cls._from_document(row) for row in collection.find(_mongo_filter(filters))]
+
+    @classmethod
+    async def afilter(cls, **filters):
+        """Async form of ``filter``."""
+        collection = cls._database().acollection(cls._collection_name())
+        cursor = collection.find(_mongo_filter(filters))
+        rows = await cursor.to_list(length=None)
+        return [cls._from_document(row) for row in rows]
+
+    @classmethod
+    def all(cls):
+        """Return every document in the collection."""
+        return cls.filter()
+
+    @classmethod
+    async def aall(cls):
+        """Async form of ``all``."""
+        return await cls.afilter()
+
+    @classmethod
+    def count(cls, **filters) -> int:
+        return cls._database().collection(cls._collection_name()).count_documents(_mongo_filter(filters))
+
+    @classmethod
+    async def acount(cls, **filters) -> int:
+        return await cls._database().acollection(cls._collection_name()).count_documents(_mongo_filter(filters))
+
+    def delete(self) -> bool:
+        """Delete this persisted document; return whether one was removed."""
+        if self.id is None:
+            return False
+        result = type(self)._database().collection(type(self)._collection_name()).delete_one(
+            {"_id": _object_id(self.id)}
+        )
+        return result.deleted_count == 1
+
+    async def adelete(self) -> bool:
+        """Async form of ``delete``."""
+        if self.id is None:
+            return False
+        result = await type(self)._database().acollection(type(self)._collection_name()).delete_one(
+            {"_id": _object_id(self.id)}
+        )
+        return result.deleted_count == 1
+
+    @classmethod
+    def ensure_index(cls, keys, **options):
+        """Create a collection index using PyMongo index key syntax."""
+        return cls._database().collection(cls._collection_name()).create_index(keys, **options)
+
+    @classmethod
+    async def aensure_index(cls, keys, **options):
+        """Async form of ``ensure_index``."""
+        return await cls._database().acollection(cls._collection_name()).create_index(keys, **options)
+
+
+__all__ = ["MongoDatabase", "MongoDocument", "MultipleDocumentsFound"]

lenapi/openapi.py

@@ -0,0 +1,181 @@
+"""OpenAPI generation from lenApi routes and Pydantic models."""
+
+import inspect
+from typing import Any
+
+from pydantic import BaseModel, TypeAdapter
+
+from .background import BackgroundTasks
+from .dependencies import Depends
+from .request import Request
+from .parameters import Body
+from .security import APIKeyAuth, BasicAuth, HMACAuth, JWTAuth, OIDCAuth, OpaqueBearerAuth, SessionAuth, WebhookAuth
+
+
+def _add_definitions(schema: dict[str, Any], components: dict[str, Any]) -> dict[str, Any]:
+    for name, definition in schema.pop("$defs", {}).items():
+        components.setdefault(name, definition)
+    return schema
+
+
+def _model_ref(model: type[BaseModel], components: dict[str, Any]) -> dict[str, str]:
+    if model.__name__ not in components:
+        schema = model.model_json_schema(ref_template="#/components/schemas/{model}")
+        components[model.__name__] = _add_definitions(schema, components)
+    return {"$ref": f"#/components/schemas/{model.__name__}"}
+
+
+def _type_schema(annotation: Any, components: dict[str, Any]) -> dict[str, Any]:
+    schema = TypeAdapter(annotation).json_schema(ref_template="#/components/schemas/{model}")
+    return _add_definitions(schema, components)
+
+
+def _auth_schemes(dependency, seen=None) -> dict[str, dict[str, str]]:
+    seen = set() if seen is None else seen
+    if dependency in seen:
+        return {}
+    seen.add(dependency)
+    if isinstance(dependency, JWTAuth):
+        return {"BearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}}
+    if isinstance(dependency, BasicAuth):
+        return {"BasicAuth": {"type": "http", "scheme": "basic"}}
+    if isinstance(dependency, APIKeyAuth):
+        name = "ApiKey_" + "".join(char if char.isalnum() else "_" for char in dependency.header_name)
+        return {name: {"type": "apiKey", "in": "header", "name": dependency.header_name}}
+    if isinstance(dependency, SessionAuth):
+        return {"SessionCookie": {"type": "apiKey", "in": "cookie", "name": dependency.cookie_name}}
+    if isinstance(dependency, HMACAuth):
+        return {
+            "HMACTimestamp": {"type": "apiKey", "in": "header", "name": "X-LenAPI-Timestamp"},
+            "HMACNonce": {"type": "apiKey", "in": "header", "name": "X-LenAPI-Nonce"},
+            "HMACSignature": {"type": "apiKey", "in": "header", "name": "X-LenAPI-Signature"},
+        }
+    if isinstance(dependency, WebhookAuth):
+        schemes = {
+            "WebhookSignature": {
+                "type": "apiKey", "in": "header", "name": dependency.signature_header
+            }
+        }
+        if dependency.timestamp_header:
+            schemes["WebhookTimestamp"] = {
+                "type": "apiKey", "in": "header", "name": dependency.timestamp_header
+            }
+        if dependency.event_id_header and dependency.security_store is not None:
+            schemes["WebhookEventId"] = {
+                "type": "apiKey", "in": "header", "name": dependency.event_id_header
+            }
+        return schemes
+    if isinstance(dependency, (OpaqueBearerAuth, OIDCAuth)):
+        return {"BearerToken": {"type": "http", "scheme": "bearer"}}
+    try:
+        parameters = inspect.signature(dependency).parameters.values()
+    except (TypeError, ValueError):
+        return {}
+    schemes = {}
+    for parameter in parameters:
+        if isinstance(parameter.default, Depends):
+            schemes.update(_auth_schemes(parameter.default.dependency, seen))
+    return schemes
+
+
+def build_openapi(app, *, title: str, version: str) -> dict[str, Any]:
+    components: dict[str, Any] = {}
+    paths: dict[str, Any] = {}
+    security_schemes: dict[str, dict[str, str]] = {}
+
+    for route in app.routes:
+        for method in route.methods:
+            operation: dict[str, Any] = {
+                "operationId": f"{route.endpoint.__name__}_{method.lower()}",
+                "summary": route.endpoint.__name__.replace("_", " ").capitalize(),
+                "responses": {"200": {"description": "Successful response"}},
+            }
+            if route.request_body is not None:
+                operation["requestBody"] = route.request_body
+            if route.api_flag:
+                operation["x-lenapi-throttle"] = {
+                    "key": "client_ip",
+                    "cool_time_seconds": route.cool_time,
+                }
+            parameters = []
+            request_body = operation.get("requestBody")
+            for name, parameter in inspect.signature(route.endpoint).parameters.items():
+                annotation = parameter.annotation
+                if isinstance(parameter.default, Body):
+                    request_body = {
+                        "required": True,
+                        "content": {"application/json": {"schema": {}}},
+                    }
+                    continue
+                if name == "request" and annotation in (Request, inspect.Parameter.empty):
+                    continue
+                if annotation is BackgroundTasks:
+                    continue
+                if isinstance(parameter.default, Depends):
+                    schemes = _auth_schemes(parameter.default.dependency)
+                    if schemes:
+                        security_schemes.update(schemes)
+                        existing = operation.get("security", [{}])[0]
+                        existing.update({name: [] for name in schemes})
+                        operation["security"] = [existing]
+                    continue
+                if getattr(annotation, "__module__", "").startswith("sqlalchemy"):
+                    continue
+                if inspect.isclass(annotation) and issubclass(annotation, BaseModel):
+                    request_body = {
+                        "required": parameter.default is inspect.Parameter.empty,
+                        "content": {"application/json": {"schema": _model_ref(annotation, components)}},
+                    }
+                    continue
+                if annotation is inspect.Parameter.empty:
+                    schema = {"type": "string"}
+                else:
+                    try:
+                        schema = _type_schema(annotation, components)
+                    except Exception:
+                        schema = {"type": "string"}
+                in_path = name in route.parameter_names
+                parameters.append({
+                    "name": name,
+                    "in": "path" if in_path else "query",
+                    "required": in_path or parameter.default is inspect.Parameter.empty,
+                    "schema": schema,
+                })
+            if parameters:
+                operation["parameters"] = parameters
+            if request_body is not None:
+                operation["requestBody"] = request_body
+            if route.response_model is not None:
+                operation["responses"]["200"]["content"] = {
+                    "application/json": {"schema": _type_schema(route.response_model, components)}
+                }
+            paths.setdefault(route.path, {})[method.lower()] = operation
+
+    return {
+        "openapi": "3.1.0",
+        "info": {"title": title, "version": version},
+        "paths": paths,
+        "components": {
+            "schemas": components,
+            **({"securitySchemes": security_schemes} if security_schemes else {}),
+        },
+    }
+
+
+def swagger_html(openapi_url: str) -> str:
+    return f'''<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>API docs</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script>
+      window.onload = () => SwaggerUIBundle({{ url: {openapi_url!r}, dom_id: '#swagger-ui' }});
+    </script>
+  </body>
+</html>'''

lenapi/parameters.py

@@ -0,0 +1,8 @@
+"""Request parameter markers."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Body:
+    """Read a JSON request body without applying a schema or validation."""