adminsite 0.1.0a1__py3-none-any.whl

adminsite/__init__.py

@@ -0,0 +1,50 @@
+from importlib.metadata import version
+
+from adminsite.admin import Admin
+from adminsite.exceptions import (
+    AdminSiteError,
+    InvalidPathError,
+    NotAModelError,
+    PermissionDeniedError,
+    RecordNotFoundError,
+    RefusedError,
+    UnknownFieldError,
+)
+from adminsite.protocols import ModelInspector
+from adminsite.query import CountMode, Page, QuerySpec, Sort
+from adminsite.schema import (
+    FieldPath,
+    FieldSchema,
+    ModelSchema,
+    RelationDirection,
+    RelationSchema,
+)
+from adminsite.security import Permission
+from adminsite.views import ModelView, ViewRegistry
+
+__version__ = version("adminsite")
+
+__all__ = [
+    "Admin",
+    "AdminSiteError",
+    "CountMode",
+    "FieldPath",
+    "FieldSchema",
+    "InvalidPathError",
+    "ModelInspector",
+    "ModelSchema",
+    "ModelView",
+    "NotAModelError",
+    "Page",
+    "Permission",
+    "PermissionDeniedError",
+    "QuerySpec",
+    "RecordNotFoundError",
+    "RefusedError",
+    "RelationDirection",
+    "RelationSchema",
+    "Sort",
+    "UnknownFieldError",
+    "ViewRegistry",
+    "__version__",
+]

adminsite/actions/__init__.py

@@ -0,0 +1,4 @@
+from adminsite.actions.action import Action, action, action_of
+from adminsite.actions.selection import Selection
+
+__all__ = ["Action", "Selection", "action", "action_of"]

adminsite/actions/action.py

@@ -0,0 +1,70 @@
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from adminsite.security import Permission
+from adminsite.text import humanize
+
+MARKER = "__adminsite_action__"
+
+Handler = TypeVar("Handler", bound=Callable[..., Awaitable[Any]])
+
+
+@dataclass(frozen=True, slots=True)
+class Action:
+    """A button that runs over the rows the user picked."""
+
+    name: str
+    label: str
+    method: str
+    confirm: str = ""
+    permission: str = Permission.EDIT
+    dangerous: bool = False
+
+    @property
+    def needs_confirming(self) -> bool:
+        """Whether the user is asked before it runs."""
+        return bool(self.confirm)
+
+
+def action(
+    label: str = "",
+    *,
+    name: str = "",
+    confirm: str = "",
+    permission: str = Permission.EDIT,
+    dangerous: bool = False,
+) -> Callable[[Handler], Handler]:
+    """Mark a method as a bulk action.
+
+    ```python
+    @action("Mark as shipped", confirm="Mark these orders as shipped?")
+    async def ship(self, selection: Selection) -> str:
+        await selection.update(status="shipped")
+        return f"{await selection.count()} orders marked as shipped."
+    ```
+    """
+
+    def mark(handler: Handler) -> Handler:
+        chosen = name or handler.__name__
+        setattr(
+            handler,
+            MARKER,
+            Action(
+                name=chosen,
+                label=label or humanize(chosen),
+                method=handler.__name__,
+                confirm=confirm,
+                permission=permission,
+                dangerous=dangerous,
+            ),
+        )
+        return handler
+
+    return mark
+
+
+def action_of(candidate: object) -> Action | None:
+    """The action a method carries, if it was marked as one."""
+    found = getattr(candidate, MARKER, None)
+    return found if isinstance(found, Action) else None

adminsite/actions/selection.py

@@ -0,0 +1,105 @@
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import Select, delete, func, select, update
+from sqlalchemy.sql import Executable
+
+from adminsite.backends.sqlalchemy.session import SessionAdapter
+from adminsite.query import QuerySpec
+
+if TYPE_CHECKING:
+    from adminsite.views import ModelView
+
+
+@dataclass
+class Selection:
+    """The rows an action runs over.
+
+    Either the rows that were ticked, or every row the current search and
+    filters match. The second kind is never loaded into memory, so an
+    action over a large table stays one statement.
+    """
+
+    view: "ModelView"
+    session: SessionAdapter
+    spec: QuerySpec
+    keys: Sequence[str] = ()
+    everything: bool = False
+    request: Any = None
+
+    @property
+    def repository(self) -> Any:
+        """The repository of the view this selection belongs to."""
+        return self.view.repository
+
+    def statement(self) -> Select[Any]:
+        """A statement selecting the primary keys this covers."""
+        columns = [
+            getattr(self.view.model, name) for name in self.view.schema.primary_key
+        ]
+        rows: Select[Any] = select(*columns).select_from(self.view.model)
+        rows = self.view.scope_for(self.request)(rows)
+        rows = self.repository.narrow(rows, self.spec)
+
+        if not self.everything:
+            rows = rows.where(self._key_condition())
+        return rows
+
+    async def count(self) -> int:
+        """How many rows this covers."""
+        counted = select(func.count()).select_from(self.statement().subquery())
+        return int(await self.session.scalar(counted) or 0)
+
+    async def records(self) -> list[Any]:
+        """Load the records, for work that needs each one in turn."""
+        statement = self.repository.base_statement(
+            self.view.scope_for(self.request)
+        ).where(
+            self._primary_key_column().in_(select(self.statement().subquery().c[0]))
+        )
+        return list((await self.session.scalars(statement)).unique().all())
+
+    async def update(self, **values: Any) -> int:
+        """Change every row this covers, in one statement.
+
+        This does not run the save hooks, because it never loads the
+        records. Use `records` when the hooks matter.
+        """
+        if not values:
+            return 0
+        statement = (
+            update(self.view.model)
+            .where(
+                self._primary_key_column().in_(select(self.statement().subquery().c[0]))
+            )
+            .values(**values)
+        )
+        return await self._run(statement)
+
+    async def delete(self) -> int:
+        """Delete every row this covers, in one statement."""
+        statement = delete(self.view.model).where(
+            self._primary_key_column().in_(select(self.statement().subquery().c[0]))
+        )
+        return await self._run(statement)
+
+    async def _run(self, statement: Executable) -> int:
+        """Run a write and report how many rows it touched."""
+        result = await self.session.execute(statement)
+        return int(getattr(result, "rowcount", 0) or 0)
+
+    def _primary_key_column(self) -> Any:
+        return getattr(self.view.model, self.view.schema.primary_key[0])
+
+    def _key_condition(self) -> Any:
+        column = self._primary_key_column()
+        field = self.view.schema.field_named(self.view.schema.primary_key[0])
+        wanted = [self._as_key(field.python_type, key) for key in self.keys]
+        return column.in_(wanted)
+
+    def _as_key(self, python_type: type[Any], key: str) -> Any:
+        try:
+            return python_type(key)
+        except (TypeError, ValueError, ArithmeticError):
+            return key

adminsite/admin.py

@@ -0,0 +1,202 @@
+from collections.abc import Sequence
+from functools import partial
+from pathlib import Path
+from typing import Any
+
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.sessions import SessionMiddleware
+from starlette.requests import Request
+from starlette.responses import RedirectResponse, Response
+from starlette.routing import Mount, Route
+from starlette.staticfiles import StaticFiles
+
+from adminsite.auth import AuthProvider
+from adminsite.backends.sqlalchemy.inspector import SQLAlchemyInspector
+from adminsite.backends.sqlalchemy.session import Database, SessionSource
+from adminsite.exceptions import AdminSiteError
+from adminsite.fields import FieldRegistry, default_registry
+from adminsite.http import endpoints
+from adminsite.http.templating import Templates
+from adminsite.http.urls import Urls
+from adminsite.views import ModelView, ViewRegistry
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+class Admin:
+    """The admin itself: a small ASGI app you mount into your own.
+
+    ```python
+    admin = Admin(engine, title="Acme")
+    admin.add_view(OrderView)
+    app.mount("/admin", admin)
+    ```
+    """
+
+    def __init__(
+        self,
+        source: Database | SessionSource,
+        *,
+        title: str = "Admin",
+        views: Sequence[ModelView | type[ModelView]] = (),
+        inspector: SQLAlchemyInspector | None = None,
+        fields: FieldRegistry | None = None,
+        template_dirs: Sequence[str | Path] = (),
+        auth: AuthProvider | None = None,
+        secret_key: str = "",
+        session_cookie: str = "adminsite_session",
+    ) -> None:
+        if auth is not None and not secret_key:
+            raise AdminSiteError(
+                "Signing in needs a secret_key to sign the session cookie."
+            )
+        self.database = source if isinstance(source, Database) else Database(source)
+        self.title = title
+        self.inspector = inspector or SQLAlchemyInspector()
+        self.fields = fields or default_registry
+        self.views = ViewRegistry()
+        self.templates = Templates(template_dirs)
+        self.auth = auth
+        self.secret_key = secret_key
+        self.session_cookie = session_cookie
+        self._app: Starlette | None = None
+
+        for view in views:
+            self.add_view(view)
+
+    def add_view(self, view: ModelView | type[ModelView]) -> ModelView:
+        """Register a model with the admin."""
+        built = view(self.inspector, self.fields) if isinstance(view, type) else view
+        return self.views.add(built)
+
+    @property
+    def app(self) -> Starlette:
+        """The Starlette app behind the admin, built once."""
+        if self._app is None:
+            self._app = Starlette(routes=self.routes(), middleware=self.middleware())
+        return self._app
+
+    def middleware(self) -> list[Middleware]:
+        """The middleware the admin runs behind, if it needs any."""
+        if not self.secret_key:
+            return []
+        return [
+            Middleware(
+                SessionMiddleware,
+                secret_key=self.secret_key,
+                session_cookie=self.session_cookie,
+                same_site="lax",
+                https_only=False,
+            )
+        ]
+
+    def routes(self) -> list[Route | Mount]:
+        """Every route the admin answers."""
+        # The fixed paths come first, so a record cannot be called "new".
+        return [
+            Route("/", self._handler(endpoints.index), name="index"),
+            Mount(
+                "/static",
+                app=StaticFiles(directory=STATIC_DIR),
+                name="static",
+            ),
+            Route(
+                "/login",
+                self._handler(endpoints.login_form, guarded=False),
+                methods=["GET"],
+                name="login_form",
+            ),
+            Route(
+                "/login",
+                self._handler(endpoints.login, guarded=False),
+                methods=["POST"],
+                name="login",
+            ),
+            Route(
+                "/logout",
+                self._handler(endpoints.logout, guarded=False),
+                methods=["POST"],
+                name="logout",
+            ),
+            Route("/{view}", self._handler(endpoints.list_records), name="list"),
+            Route(
+                "/{view}/new",
+                self._handler(endpoints.create_form),
+                methods=["GET"],
+                name="create_form",
+            ),
+            Route(
+                "/{view}/new",
+                self._handler(endpoints.create_record),
+                methods=["POST"],
+                name="create",
+            ),
+            Route(
+                "/{view}/export",
+                self._handler(endpoints.export_records),
+                name="export",
+            ),
+            Route(
+                "/{view}/action/{name}",
+                self._handler(endpoints.run_action),
+                methods=["POST"],
+                name="action",
+            ),
+            Route(
+                "/{view}/lookup/{path}",
+                self._handler(endpoints.lookup),
+                name="lookup",
+            ),
+            Route(
+                "/{view}/{key}",
+                self._handler(endpoints.detail),
+                name="detail",
+            ),
+            Route(
+                "/{view}/{key}/edit",
+                self._handler(endpoints.edit_form),
+                methods=["GET"],
+                name="edit_form",
+            ),
+            Route(
+                "/{view}/{key}/edit",
+                self._handler(endpoints.edit_record),
+                methods=["POST"],
+                name="edit",
+            ),
+            Route(
+                "/{view}/{key}/delete",
+                self._handler(endpoints.delete_record),
+                methods=["POST"],
+                name="delete",
+            ),
+        ]
+
+    async def render(
+        self,
+        name: str,
+        request: Request,
+        context: dict[str, Any] | None = None,
+        status_code: int = 200,
+    ) -> Response:
+        """Render one of the admin templates."""
+        return await self.templates.render(name, request, self, context, status_code)
+
+    def _handler(self, endpoint: Any, guarded: bool = True) -> Any:
+        if not guarded or self.auth is None:
+            return partial(endpoint, self)
+
+        async def guard(request: Request) -> Response:
+            user = await self.auth.current_user(request) if self.auth else None
+            if user is None:
+                return RedirectResponse(Urls(request).login(), status_code=303)
+            request.scope["user_record"] = user
+            answer: Response = await endpoint(self, request)
+            return answer
+
+        return guard
+
+    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
+        """Let the admin be mounted like any other ASGI app."""
+        await self.app(scope, receive, send)

adminsite/auth/__init__.py

@@ -0,0 +1,4 @@
+from adminsite.auth.passwords import hash_password, verify_password
+from adminsite.auth.provider import AuthProvider, PasswordAuth
+
+__all__ = ["AuthProvider", "PasswordAuth", "hash_password", "verify_password"]

adminsite/auth/passwords.py

@@ -0,0 +1,46 @@
+import hashlib
+import secrets
+
+ALGORITHM = "pbkdf2_sha256"
+ITERATIONS = 600_000
+SALT_BYTES = 16
+
+
+def hash_password(password: str, *, iterations: int = ITERATIONS) -> str:
+    """Hash a password for storing.
+
+    ```python
+    from adminsite.auth import hash_password
+
+    hash_password("letmein")
+    ```
+
+    Keep the result, not the password. The format is
+    `pbkdf2_sha256$iterations$salt$hash`.
+    """
+    salt = secrets.token_hex(SALT_BYTES)
+    digest = _digest(password, salt, iterations)
+    return f"{ALGORITHM}${iterations}${salt}${digest}"
+
+
+def verify_password(password: str, stored: str) -> bool:
+    """Check a password against a stored hash, in constant time."""
+    try:
+        algorithm, rounds, salt, digest = stored.split("$")
+        iterations = int(rounds)
+    except ValueError:
+        return False
+    if algorithm != ALGORITHM:
+        return False
+    return secrets.compare_digest(digest, _digest(password, salt, iterations))
+
+
+def looks_hashed(value: str) -> bool:
+    """Whether a value is one of our hashes rather than a plain password."""
+    return value.startswith(f"{ALGORITHM}$")
+
+
+def _digest(password: str, salt: str, iterations: int) -> str:
+    return hashlib.pbkdf2_hmac(
+        "sha256", password.encode(), salt.encode(), iterations
+    ).hex()

adminsite/auth/provider.py

@@ -0,0 +1,86 @@
+from collections.abc import Mapping
+from typing import Any
+
+from starlette.requests import Request
+
+from adminsite.auth.passwords import looks_hashed, verify_password
+from adminsite.exceptions import AdminSiteError
+
+SESSION_KEY = "adminsite_user"
+
+
+class AuthProvider:
+    """Decides who may use the admin.
+
+    Subclass it and write `verify`. The session handling here is enough
+    for most projects, and `load_user` is where you turn the key kept in
+    the session back into whatever your application calls a user.
+    """
+
+    async def verify(self, username: str, password: str) -> Any | None:
+        """Return the user for these details, or nothing."""
+        raise NotImplementedError
+
+    async def load_user(self, key: str) -> Any | None:
+        """Turn the key kept in the session back into a user."""
+        return key
+
+    def identity(self, user: Any) -> str:
+        """The key to keep in the session for this user."""
+        return str(user)
+
+    async def current_user(self, request: Request) -> Any | None:
+        """Who is signed in, if anyone."""
+        session = request.scope.get("session")
+        if not session:
+            return None
+        key = session.get(SESSION_KEY)
+        return await self.load_user(key) if key else None
+
+    async def sign_in(
+        self, request: Request, username: str, password: str
+    ) -> Any | None:
+        """Check the details and remember the user."""
+        user = await self.verify(username, password)
+        if user is None:
+            return None
+        request.session[SESSION_KEY] = self.identity(user)
+        return user
+
+    async def sign_out(self, request: Request) -> None:
+        """Forget the user."""
+        session = request.scope.get("session")
+        if session:
+            session.pop(SESSION_KEY, None)
+
+
+class PasswordAuth(AuthProvider):
+    """Signs in against a fixed set of usernames and password hashes.
+
+    ```python
+    from adminsite.auth import PasswordAuth, hash_password
+
+    PasswordAuth({"nima": hash_password("letmein")})
+    ```
+
+    Passwords have to be hashed with `hash_password`, so a plain one
+    never ends up in your settings or your repository. This suits a
+    small internal tool. Anything larger should subclass `AuthProvider`
+    and check its own user table.
+    """
+
+    def __init__(self, users: Mapping[str, str]) -> None:
+        for username, stored in users.items():
+            if not looks_hashed(stored):
+                raise AdminSiteError(
+                    f"The password for {username!r} is not hashed. "
+                    "Use adminsite.auth.hash_password to hash it first."
+                )
+        self.users = dict(users)
+
+    async def verify(self, username: str, password: str) -> Any | None:
+        """Check the password against the stored hash."""
+        stored = self.users.get(username)
+        if stored is None:
+            return None
+        return username if verify_password(password, stored) else None

adminsite/backends/sqlalchemy/__init__.py

@@ -0,0 +1,37 @@
+from adminsite.backends.sqlalchemy.filters import (
+    BooleanFilter,
+    ChoiceFilter,
+    DateRangeFilter,
+    NumberRangeFilter,
+    RelationFilter,
+    SQLFilter,
+    SQLFilterContext,
+    TextFilter,
+    filter_for,
+)
+from adminsite.backends.sqlalchemy.inspector import SQLAlchemyInspector
+from adminsite.backends.sqlalchemy.repository import SQLAlchemyRepository
+from adminsite.backends.sqlalchemy.session import (
+    AsyncSessionAdapter,
+    Database,
+    SessionAdapter,
+    SyncSessionAdapter,
+)
+
+__all__ = [
+    "AsyncSessionAdapter",
+    "BooleanFilter",
+    "ChoiceFilter",
+    "Database",
+    "DateRangeFilter",
+    "NumberRangeFilter",
+    "RelationFilter",
+    "SQLAlchemyInspector",
+    "SQLAlchemyRepository",
+    "SQLFilter",
+    "SQLFilterContext",
+    "SessionAdapter",
+    "SyncSessionAdapter",
+    "TextFilter",
+    "filter_for",
+]