telamon 0.1.0a0__py3-none-any.whl

telamon/__init__.py

@@ -0,0 +1,51 @@
+"""Telamon Admin: framework-agnostic admin panel for SQLAlchemy and Tortoise ORM."""
+
+from .core import (
+    Action,
+    AdminError,
+    AdminRequest,
+    AdminResponse,
+    AdminSite,
+    AuthProvider,
+    Backend,
+    FieldType,
+    FilterGroup,
+    ListQuery,
+    ModelAdmin,
+    ModelSchema,
+    NotFound,
+    PermissionDenied,
+    Repository,
+    SessionAuth,
+    SimpleAuth,
+    User,
+    ValidationError,
+    action,
+    hash_password,
+)
+
+__version__ = "0.1.0a0"
+
+__all__ = [
+    "Action",
+    "AdminError",
+    "AdminRequest",
+    "AdminResponse",
+    "AdminSite",
+    "AuthProvider",
+    "Backend",
+    "FieldType",
+    "FilterGroup",
+    "ListQuery",
+    "ModelAdmin",
+    "ModelSchema",
+    "NotFound",
+    "PermissionDenied",
+    "Repository",
+    "SessionAuth",
+    "SimpleAuth",
+    "User",
+    "ValidationError",
+    "action",
+    "hash_password",
+]

telamon/backends/beanie/__init__.py

@@ -0,0 +1,3 @@
+from .backend import BeanieBackend, BeanieRepository
+
+__all__ = ["BeanieBackend", "BeanieRepository"]

telamon/backends/beanie/backend.py

@@ -0,0 +1,147 @@
+"""Beanie ODM backend. ``Link[T]`` -> many_to_one, ``list[Link[T]]`` -> many_to_many,
+``BackLink[T]`` -> one_to_many (read-only). Requires ``init_beanie()`` before the first request.
+
+Documents are read and written through the raw pymongo collection that Beanie manages; links are
+stored as DBRefs exactly as Beanie stores them, so both sides stay compatible.
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any, cast, get_args, get_origin
+
+from beanie import Document
+from beanie.odm.fields import BackLink, Link
+from bson import DBRef
+
+from telamon.core.model_admin import ModelAdmin
+from telamon.core.schema import FieldSchema, FieldType, ModelSchema, Relation
+
+from ..mongo.backend import Driver, MongoBackend, MongoRepository
+from ..mongo.common import Ref, _unwrap, field_from_annotation, parse_pk
+
+_HIDDEN = {"revision_id"}
+
+
+class BeanieBackend(MongoBackend):
+    name = "beanie"
+
+    def __init__(self) -> None:  # database comes from init_beanie()
+        self._driver: Driver | None = None
+
+    @property
+    def driver(self) -> Driver:
+        if self._driver is None:
+            raise RuntimeError(
+                "Beanie is not initialised; call init_beanie() before using the admin"
+            )
+        return self._driver
+
+    @driver.setter
+    def driver(self, value: Driver) -> None:
+        self._driver = value
+
+    def supports(self, model: type) -> bool:
+        return isinstance(model, type) and issubclass(model, Document)
+
+    def introspect(self, model: type, admin: ModelAdmin) -> ModelSchema:
+        fields: list[FieldSchema] = []
+        doc = cast(type[Document], model)
+        for name, info in doc.model_fields.items():
+            if name in _HIDDEN:
+                continue
+            if name == "id":
+                f = field_from_annotation("id", info.annotation, info)
+                f.primary_key, f.read_only, f.has_default, f.required, f.nullable = (
+                    True,
+                    True,
+                    True,
+                    False,
+                    False,
+                )
+                fields.insert(0, f)
+                continue
+            core, nullable, _ = _unwrap(info.annotation)
+            origin = get_origin(core)
+            inner = get_args(core)[0] if origin in (list, set, tuple) and get_args(core) else None
+            if origin is Link:
+                target = get_args(core)[0]
+                ann: Any = (str | None) if nullable else str
+                fields.append(field_from_annotation(name, ann, info, extra_metadata=[Ref(target)]))
+            elif inner is not None and get_origin(inner) is Link:
+                target = get_args(inner)[0]
+                fields.append(
+                    field_from_annotation(name, list[str], info, extra_metadata=[Ref(target)])
+                )
+            elif origin is BackLink or (inner is not None and get_origin(inner) is BackLink):
+                link = core if origin is BackLink else inner
+                target = get_args(link)[0] if get_args(link) else Any
+                fields.append(
+                    FieldSchema(
+                        name,
+                        FieldType.ONE_TO_MANY,
+                        read_only=True,
+                        relation=Relation(model=target, kind=FieldType.ONE_TO_MANY),
+                        sortable=False,
+                        filterable=False,
+                    )
+                )
+            else:
+                fields.append(field_from_annotation(name, info.annotation, info))
+        label = model.__name__
+        return ModelSchema(
+            key=label.lower(), label=label, label_plural=f"{label}s", pk_field="id", fields=fields
+        )
+
+    def repository(self, model: type, schema: ModelSchema, admin: ModelAdmin) -> BeanieRepository:
+        return BeanieRepository(self, model, schema, admin)
+
+
+class BeanieRepository(MongoRepository):
+    id_path = ".$id"
+
+    @property
+    def driver(self) -> Driver:
+        _ = self.coll  # resolving the collection also wires the driver from init_beanie()
+        return self.backend.driver
+
+    @property
+    def coll(self) -> Any:
+        if self._coll is None:
+            doc = cast(type[Document], self.model)
+            self._coll = doc.get_pymongo_collection()  # raises if init_beanie() was not run
+            self.backend.driver = Driver(self._coll.database)
+        return self._coll
+
+    @property
+    def collection_name(self) -> str:
+        return str(cast(type[Document], self.model).get_collection_name())
+
+    def _target_collection(self, f: FieldSchema) -> str:
+        assert f.relation is not None
+        return str(f.relation.model.get_collection_name())
+
+    def _rel_value(self, f: FieldSchema, value: Any) -> Any:
+        if value is None:
+            return None
+        coll = self._target_collection(f)
+        if f.type == FieldType.MANY_TO_MANY:
+            return [DBRef(coll, parse_pk(v)) for v in value]
+        return DBRef(coll, parse_pk(value))
+
+    def _rel_ids(self, f: FieldSchema, stored: Any) -> builtins.list[Any]:
+        if stored is None:
+            return []
+        items = stored if isinstance(stored, list) else [stored]
+        out = []
+        for i in items:
+            if isinstance(i, DBRef):
+                out.append(i.id)
+            elif isinstance(i, dict) and "$id" in i:
+                out.append(i["$id"])
+            else:
+                out.append(i)
+        return out
+
+
+__all__ = ["BeanieBackend", "BeanieRepository"]

telamon/backends/memory/__init__.py

@@ -0,0 +1,201 @@
+"""In-memory backend: reference implementation of the Repository contract, used by core tests.
+
+Models are plain classes; their schema is passed explicitly. Rows are dicts keyed by pk.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from telamon.core.exceptions import ValidationError
+from telamon.core.filters import Condition, FilterGroup, Op
+from telamon.core.model_admin import ModelAdmin
+from telamon.core.query import ListQuery, Page
+from telamon.core.schema import FieldType, ModelSchema
+
+
+def matches(cond: Condition, value: Any) -> bool:  # noqa: C901
+    return bool(_matches(cond, value))
+
+
+def _matches(cond: Condition, value: Any) -> Any:
+    op, target = cond.op, cond.value
+    if op == Op.IS_NULL:
+        return (value is None) == bool(target)
+    if op == Op.EQ:
+        return value == target
+    if op == Op.NE:
+        return value != target
+    if value is None:
+        return False
+    if op == Op.LT:
+        return value < target
+    if op == Op.LTE:
+        return value <= target
+    if op == Op.GT:
+        return value > target
+    if op == Op.GTE:
+        return value >= target
+    if op == Op.IN:
+        if isinstance(value, list):  # many_to_many: any overlap
+            return any(v in (target or []) for v in value)
+        return value in (target or [])
+    if op == Op.NOT_IN:
+        if isinstance(value, list):
+            return not any(v in (target or []) for v in value)
+        return value not in (target or [])
+    if op == Op.CONTAINS:
+        return str(target) in str(value)
+    if op == Op.ICONTAINS:
+        return str(target).lower() in str(value).lower()
+    if op == Op.STARTSWITH:
+        return str(value).startswith(str(target))
+    if op == Op.ENDSWITH:
+        return str(value).endswith(str(target))
+    if op == Op.BETWEEN:
+        lo, hi = target
+        return lo <= value <= hi
+    raise ValueError(op)
+
+
+def matches_group(group: FilterGroup, row: dict[str, Any]) -> bool:
+    if group.is_empty():
+        return True
+    results = (
+        matches(i, row.get(i.field)) if isinstance(i, Condition) else matches_group(i, row)
+        for i in group.items
+    )
+    return all(results) if group.logic == "and" else any(results)
+
+
+class MemoryRepository:
+    def __init__(
+        self, backend: MemoryBackend, model: type, schema: ModelSchema, admin: ModelAdmin
+    ) -> None:
+        self.backend = backend
+        self.model = model
+        self.schema = schema
+        self.admin = admin
+        self.rows: dict[Any, dict[str, Any]] = backend.storage.setdefault(model, {})
+
+    def _next_pk(self) -> int:
+        existing = [p for p in self.rows if isinstance(p, int)]
+        return (max(existing) + 1) if existing else 1
+
+    def _apply(self, query: ListQuery) -> list[dict[str, Any]]:
+        rows = [r for r in self.rows.values() if matches_group(query.filters, r)]
+        if query.search:
+            term = query.search.lower()
+            searchable = [f.name for f in self.schema.fields if f.searchable]
+            rows = [r for r in rows if any(term in str(r.get(n) or "").lower() for n in searchable)]
+        for name, direction in reversed(query.sort):
+            rows.sort(key=lambda r: (r.get(name) is None, r.get(name)), reverse=direction == "desc")
+        return rows
+
+    async def list(self, query: ListQuery) -> Page[dict[str, Any]]:
+        rows = self._apply(query)
+        return Page(items=rows[query.offset : query.offset + query.limit], total=len(rows))
+
+    async def count(self, query: ListQuery) -> int:
+        return len(self._apply(query))
+
+    async def get(self, pk: Any) -> dict[str, Any] | None:
+        return self.rows.get(pk)
+
+    async def get_many(self, pks: Sequence[Any]) -> Sequence[dict[str, Any]]:
+        return [self.rows[p] for p in pks if p in self.rows]
+
+    def _check_relations(self, data: dict[str, Any]) -> None:
+        for name, value in data.items():
+            f = self.schema.field(name)
+            if not f.is_relation or f.relation is None or value is None:
+                continue
+            rows = self.backend.storage.get(f.relation.model, {})
+            ids = value if isinstance(value, list) else [value]
+            if any(i not in rows for i in ids):
+                raise ValidationError({name: "related object does not exist"})
+
+    async def create(self, data: dict[str, Any]) -> dict[str, Any]:
+        self._check_relations(data)
+        pk_name = self.schema.pk_field
+        row: dict[str, Any] = {
+            f.name: None for f in self.schema.fields if f.type != FieldType.ONE_TO_MANY
+        }
+        row.update(data)
+        if row.get(pk_name) is None:
+            row[pk_name] = self._next_pk()
+        if row[pk_name] in self.rows:
+            raise ValidationError({pk_name: "already exists"})
+        self.rows[row[pk_name]] = row
+        return row
+
+    async def update(self, obj: dict[str, Any], data: dict[str, Any]) -> dict[str, Any]:
+        self._check_relations(data)
+        obj.update(data)
+        return obj
+
+    async def delete(self, objs: Sequence[dict[str, Any]]) -> int:
+        n = 0
+        for o in objs:
+            if self.rows.pop(o[self.schema.pk_field], None) is not None:
+                n += 1
+        return n
+
+    def pk_of(self, obj: dict[str, Any]) -> Any:
+        return obj[self.schema.pk_field]
+
+    def label_of(self, obj: dict[str, Any]) -> str:
+        for f in self.schema.fields:
+            if f.type == FieldType.STRING and obj.get(f.name):
+                return str(obj[f.name])
+        return f"{self.schema.label} #{self.pk_of(obj)}"
+
+    def _related(self, f: Any, pk: Any) -> dict[str, Any]:
+        rows = self.backend.storage.get(f.relation.model, {})
+        target_schema = self.backend.schemas.get(f.relation.model)
+        row = rows.get(pk)
+        if row is None or target_schema is None:
+            return {"id": pk, "label": str(pk)}
+        repo = MemoryRepository(self.backend, f.relation.model, target_schema, self.admin)
+        return {"id": pk, "label": repo.label_of(row)}
+
+    def to_dict(self, obj: dict[str, Any]) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        for f in self.schema.fields:
+            if f.type == FieldType.ONE_TO_MANY:
+                continue
+            v = obj.get(f.name)
+            if f.type == FieldType.MANY_TO_ONE:
+                out[f.name] = None if v is None else self._related(f, v)
+            elif f.type == FieldType.MANY_TO_MANY:
+                out[f.name] = [self._related(f, i) for i in (v or [])]
+            else:
+                out[f.name] = v
+        return out
+
+
+class MemoryBackend:
+    name = "memory"
+
+    def __init__(self, schemas: dict[type, ModelSchema] | None = None) -> None:
+        self.schemas: dict[type, ModelSchema] = dict(schemas or {})
+        self.storage: dict[type, dict[Any, dict[str, Any]]] = {}
+
+    def add(self, model: type, schema: ModelSchema) -> None:
+        self.schemas[model] = schema
+
+    def supports(self, model: type) -> bool:
+        return model in self.schemas
+
+    def introspect(self, model: type, admin: ModelAdmin) -> ModelSchema:
+        import copy
+
+        return copy.deepcopy(self.schemas[model])
+
+    def repository(self, model: type, schema: ModelSchema, admin: ModelAdmin) -> MemoryRepository:
+        return MemoryRepository(self, model, schema, admin)
+
+    def seed(self, model: type, rows: list[dict[str, Any]]) -> None:
+        pk = self.schemas[model].pk_field
+        self.storage.setdefault(model, {}).update({r[pk]: dict(r) for r in rows})

telamon/backends/mongo/__init__.py

@@ -0,0 +1,4 @@
+from .backend import MongoBackend, MongoRepository
+from .common import Ref
+
+__all__ = ["MongoBackend", "MongoRepository", "Ref"]