fastapi-panel 0.1.0__py3-none-any.whl

fastapi_panel/__init__.py

@@ -0,0 +1,77 @@
+__version__ = "0.1.0"
+
+from .auth import AuthBackend, ModelAuth, StaticAuth
+from .filters import Filter, SimpleFilter
+from .forms import (
+    BooleanField,
+    CharField,
+    ChoiceField,
+    DateField,
+    DateTimeField,
+    DecimalField,
+    EmailField,
+    Field,
+    FileField,
+    FloatField,
+    ImageField,
+    IntegerField,
+    JSONField,
+    TextField,
+    TimeField,
+    UUIDField,
+    ValidationError,
+)
+from .log import AdminLog
+from .options import (
+    ImproperlyConfigured,
+    InlineAdmin,
+    ModelAdmin,
+    StackedInline,
+    TabularInline,
+    action,
+    display,
+)
+from .security import hash_password, verify_password
+from .site import AdminSite, autodiscover, register, site
+from .storage import LocalStorage, Storage
+
+__all__ = [
+    "AdminLog",
+    "AdminSite",
+    "AuthBackend",
+    "BooleanField",
+    "CharField",
+    "ChoiceField",
+    "DateField",
+    "DateTimeField",
+    "DecimalField",
+    "EmailField",
+    "Field",
+    "FileField",
+    "Filter",
+    "FloatField",
+    "ImageField",
+    "ImproperlyConfigured",
+    "InlineAdmin",
+    "IntegerField",
+    "JSONField",
+    "LocalStorage",
+    "ModelAdmin",
+    "ModelAuth",
+    "SimpleFilter",
+    "StackedInline",
+    "StaticAuth",
+    "Storage",
+    "TabularInline",
+    "TextField",
+    "TimeField",
+    "UUIDField",
+    "ValidationError",
+    "action",
+    "autodiscover",
+    "display",
+    "hash_password",
+    "register",
+    "site",
+    "verify_password",
+]

fastapi_panel/__main__.py

@@ -0,0 +1,97 @@
+import argparse
+import asyncio
+import getpass
+import importlib
+import os
+import sys
+from typing import Any
+
+from sqlalchemy.exc import DBAPIError
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from .auth import ModelAuth
+from .introspect import coerce_to_column
+from .security import hash_password
+from .site import MIN_PASSWORD_LENGTH, AdminSite, site
+
+
+def read_password() -> str:
+    password = getpass.getpass("Password: ")
+    if password != getpass.getpass("Again: "):
+        raise SystemExit("The passwords don't match.")
+    return password
+
+
+def find_site(target: str) -> AdminSite:
+    """`main` or `main:panel`. Importing runs your `site.mount(...)`, which is where the engine comes from."""
+    sys.path.insert(0, os.getcwd())
+    module_name, _, attr = target.partition(":")
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise SystemExit(f"Couldn't import {module_name!r}: {exc}") from None
+    if attr:
+        found = getattr(module, attr, None)
+        if not isinstance(found, AdminSite):
+            raise SystemExit(f"{target} is not an AdminSite.")
+        return found
+    return next((value for value in vars(module).values() if isinstance(value, AdminSite)), site)
+
+
+async def save_user(panel: AdminSite, *args: Any, **kwargs: Any) -> Any:
+    try:
+        return await panel.db.run(lambda session: panel.auth.create_user(session, *args, **kwargs))
+    finally:
+        # An open async connection would keep the process from exiting.
+        bind = panel.db.maker.kw.get("bind")
+        if isinstance(bind, AsyncEngine):
+            await bind.dispose()
+
+
+def create_user(args: argparse.Namespace) -> int:
+    panel = find_site(args.target)
+    if not hasattr(panel, "db"):
+        raise SystemExit(f"{args.target} doesn't call site.mount(), so there's no database to use.")
+    auth = panel.auth
+    if not isinstance(auth, ModelAuth):
+        raise SystemExit("createuser only works with ModelAuth. Other backends keep their users elsewhere.")
+
+    username = args.username or input("Username: ").strip()
+    if not username:
+        raise SystemExit("A username is required.")
+    extra = {}
+    for prop in auth.required_fields():
+        try:
+            extra[prop.key] = coerce_to_column(prop.columns[0], input(f"{prop.key}: ").strip())
+        except ValueError:
+            raise SystemExit(f"That's not a valid value for {prop.key}.") from None
+    password = os.environ.get("FASTAPI_PANEL_PASSWORD") or read_password()
+    if len(password) < MIN_PASSWORD_LENGTH:
+        raise SystemExit(f"Use at least {MIN_PASSWORD_LENGTH} characters.")
+
+    try:
+        asyncio.run(save_user(panel, username, password, superuser=not args.no_superuser, **extra))
+    except DBAPIError as exc:
+        raise SystemExit(f"Couldn't create the user: {exc.orig}. Do the tables exist, and is the name free?") from None
+    print(f"Created {username}.")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="python -m fastapi_panel")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("hash-password", help="hash a password for StaticAuth or your own user table")
+    creating = commands.add_parser("createuser", help="add a user to the table behind ModelAuth")
+    creating.add_argument("target", help="the module that mounts the panel, like main or app.main:panel")
+    creating.add_argument("--username")
+    creating.add_argument("--no-superuser", action="store_true", help="create a regular staff user")
+    args = parser.parse_args()
+
+    if args.command == "createuser":
+        return create_user(args)
+    print(hash_password(read_password()))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fastapi_panel/auth.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from sqlalchemy import inspect, select
+
+from .introspect import object_label, pk_criterion, pk_string
+from .security import DUMMY_HASH, hash_password, verify_password
+
+
+class AuthBackend:
+    """Tells the panel who may log in and what they may do.
+
+    Methods taking `session` run with an open database session. `check_password` runs
+    in a worker thread, so slow hashers are safe.
+    """
+
+    can_change_password = False
+
+    def find_user(self, session: Any, username: str) -> Any | None:
+        raise NotImplementedError
+
+    def get_user(self, session: Any, user_id: str) -> Any | None:
+        raise NotImplementedError
+
+    def check_password(self, user: Any | None, password: str) -> bool:
+        raise NotImplementedError
+
+    def user_id(self, user: Any) -> str:
+        raise NotImplementedError
+
+    def user_label(self, user: Any) -> str:
+        return object_label(user)
+
+    def is_allowed(self, user: Any) -> bool:
+        return True
+
+    def has_perm(self, user: Any, perm: str) -> bool:
+        return True
+
+    def session_hash(self, user: Any) -> str:
+        """Sessions die when this value changes. Derive it from the password hash."""
+        return ""
+
+    def set_password(self, session: Any, user: Any, password: str) -> None:
+        raise NotImplementedError
+
+
+class ModelAuth(AuthBackend):
+    """Log in against one of your own models.
+
+    `active_field` and `staff_field` must exist or be passed as None on purpose: without
+    this, every customer in a shared `users` table could log in to the panel.
+    Bring your own hasher through `verify` and `hasher` (bcrypt, argon2, passlib...).
+    """
+
+    can_change_password = True
+
+    def __init__(
+        self,
+        model: type,
+        *,
+        username_field: str = "username",
+        password_field: str = "password",
+        active_field: str | None = "is_active",
+        staff_field: str | None = "is_staff",
+        superuser_field: str | None = None,
+        permissions_field: str | None = None,
+        verify: Callable[[str, str], bool] = verify_password,
+        hasher: Callable[[str], str] = hash_password,
+    ) -> None:
+        columns = inspect(model).attrs
+        for name in (username_field, password_field, active_field, staff_field, superuser_field, permissions_field):
+            if name is not None and name not in columns:
+                raise ValueError(f"{model.__name__} has no field {name!r}. Pass the right name, or None to skip it.")
+        self.model = model
+        self.username_field = username_field
+        self.password_field = password_field
+        self.active_field = active_field
+        self.staff_field = staff_field
+        self.superuser_field = superuser_field
+        self.permissions_field = permissions_field
+        self.verify = verify
+        self.hasher = hasher
+
+    def find_user(self, session: Any, username: str) -> Any | None:
+        column = getattr(self.model, self.username_field)
+        return session.scalars(select(self.model).where(column == username)).first()
+
+    def get_user(self, session: Any, user_id: str) -> Any | None:
+        try:
+            return session.scalars(select(self.model).where(pk_criterion(self.model, user_id))).first()
+        except ValueError:
+            return None
+
+    def check_password(self, user: Any | None, password: str) -> bool:
+        if user is None:
+            verify_password(password, DUMMY_HASH)
+            return False
+        stored = getattr(user, self.password_field)
+        return bool(stored) and self.verify(password, stored)
+
+    def user_id(self, user: Any) -> str:
+        return pk_string(user)
+
+    def user_label(self, user: Any) -> str:
+        return str(getattr(user, self.username_field))
+
+    def is_allowed(self, user: Any) -> bool:
+        return all(getattr(user, name) for name in (self.active_field, self.staff_field) if name)
+
+    def has_perm(self, user: Any, perm: str) -> bool:
+        if self.superuser_field and getattr(user, self.superuser_field):
+            return True
+        if not self.permissions_field:
+            return self.superuser_field is None
+        granted = getattr(user, self.permissions_field) or []
+        return perm in granted or "*" in granted or f"{perm.split('.')[0]}.*" in granted
+
+    def session_hash(self, user: Any) -> str:
+        return hashlib.sha256(str(getattr(user, self.password_field)).encode()).hexdigest()
+
+    def set_password(self, session: Any, user: Any, password: str) -> None:
+        setattr(user, self.password_field, self.hasher(password))
+
+    def create_user(self, session: Any, username: str, password: str, *, superuser: bool, **extra: Any) -> Any:
+        user = self.model(**extra)
+        setattr(user, self.username_field, username)
+        self.set_password(session, user, password)
+        for name in (self.active_field, self.staff_field):
+            if name:
+                setattr(user, name, True)
+        if self.superuser_field:
+            setattr(user, self.superuser_field, superuser)
+        session.add(user)
+        session.commit()
+        return user
+
+    def required_fields(self) -> list[Any]:
+        """Other columns a new user can't be saved without, like an email."""
+        known = {self.username_field, self.password_field, self.active_field, self.staff_field, self.superuser_field}
+        return [
+            prop
+            for prop in inspect(self.model).column_attrs
+            if prop.key not in known
+            and not prop.columns[0].nullable
+            and not prop.columns[0].primary_key
+            and prop.columns[0].default is None
+            and prop.columns[0].server_default is None
+        ]
+
+
+@dataclass(frozen=True)
+class StaticUser:
+    username: str
+    password_hash: str
+
+    def __str__(self) -> str:
+        return self.username
+
+
+class StaticAuth(AuthBackend):
+    """Users kept in config, no table needed. Hashes come from `python -m fastapi_panel hash-password`."""
+
+    def __init__(self, users: Mapping[str, str]) -> None:
+        for username, encoded in users.items():
+            if not encoded.startswith("scrypt$"):
+                raise ValueError(f"Password for {username!r} must be a hash, not plain text.")
+        self.users = {name: StaticUser(name, encoded) for name, encoded in users.items()}
+
+    def find_user(self, session: Any, username: str) -> StaticUser | None:
+        return self.users.get(username)
+
+    get_user = find_user
+
+    def check_password(self, user: StaticUser | None, password: str) -> bool:
+        if user is None:
+            verify_password(password, DUMMY_HASH)
+            return False
+        return verify_password(password, user.password_hash)
+
+    def user_id(self, user: StaticUser) -> str:
+        return user.username
+
+    def session_hash(self, user: StaticUser) -> str:
+        return hashlib.sha256(user.password_hash.encode()).hexdigest()

fastapi_panel/db.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from sqlalchemy import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
+from sqlalchemy.orm import Session, sessionmaker
+from starlette.concurrency import run_in_threadpool
+
+T = TypeVar("T")
+
+
+class Database:
+    """Runs plain synchronous code against a sync or async engine.
+
+    Everything in the panel is written once, against a regular Session. Async engines
+    go through `run_sync`, which is why lazy loading just works in templates and hooks.
+    """
+
+    def __init__(self, bind: Any) -> None:
+        if isinstance(bind, AsyncEngine):
+            bind = async_sessionmaker(bind, expire_on_commit=False)
+        elif isinstance(bind, Engine):
+            bind = sessionmaker(bind, expire_on_commit=False)
+        if not isinstance(bind, (sessionmaker, async_sessionmaker)):
+            raise TypeError("engine must be an Engine, AsyncEngine or a sessionmaker")
+        self.maker = bind
+        self.is_async = isinstance(bind, async_sessionmaker)
+
+    async def run(self, fn: Callable[..., T], *args: Any) -> T:
+        if self.is_async:
+            session: AsyncSession
+            async with self.maker() as session:
+                return await session.run_sync(fn, *args)
+        return await run_in_threadpool(self._run_sync, fn, *args)
+
+    def _run_sync(self, fn: Callable[..., T], *args: Any) -> T:
+        session: Session
+        with self.maker() as session:
+            return fn(session, *args)

fastapi_panel/filters.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any
+
+import sqlalchemy as sa
+from sqlalchemy import extract, inspect
+
+from .introspect import coerce_to_column, humanize, object_label
+
+MAX_RELATION_OPTIONS = 50
+
+
+class Filter:
+    """A box in the changelist sidebar. Only registered filters ever read the query string."""
+
+    title = ""
+    parameter = ""
+
+    def options(self, session: Any, request: Any) -> list[tuple[str, str]]:
+        raise NotImplementedError
+
+    def apply(self, stmt: Any, value: str, request: Any) -> Any:
+        raise NotImplementedError
+
+
+class SimpleFilter(Filter):
+    """Subclass this for custom filters: set `title` and `parameter`, define `lookups` and `queryset`."""
+
+    def lookups(self, request: Any) -> list[tuple[str, str]]:
+        raise NotImplementedError
+
+    def queryset(self, request: Any, stmt: Any, value: str) -> Any:
+        raise NotImplementedError
+
+    def options(self, session: Any, request: Any) -> list[tuple[str, str]]:
+        return [(str(v), label) for v, label in self.lookups(request)]
+
+    def apply(self, stmt: Any, value: str, request: Any) -> Any:
+        if value not in {v for v, _ in self.options(None, request)}:
+            return stmt
+        return self.queryset(request, stmt, value)
+
+
+class _ColumnFilter(Filter):
+    def __init__(self, model: type, name: str) -> None:
+        self.model = model
+        self.name = name
+        self.parameter = name
+        self.title = humanize(name)
+        self.attr = getattr(model, name)
+
+
+class BooleanFilter(_ColumnFilter):
+    def options(self, session: Any, request: Any) -> list[tuple[str, str]]:
+        return [("1", "Yes"), ("0", "No")]
+
+    def apply(self, stmt: Any, value: str, request: Any) -> Any:
+        if value not in ("0", "1"):
+            return stmt
+        return stmt.where(self.attr.is_(value == "1"))
+
+
+class EnumFilter(_ColumnFilter):
+    def __init__(self, model: type, name: str) -> None:
+        super().__init__(model, name)
+        type_ = self.attr.type
+        if type_.enum_class:
+            self._values = {m.name: m for m in type_.enum_class}
+        else:
+            self._values = {e: e for e in type_.enums}
+
+    def options(self, session: Any, request: Any) -> list[tuple[str, str]]:
+        return [(key, humanize(key.lower())) for key in self._values]
+
+    def apply(self, stmt: Any, value: str, request: Any) -> Any:
+        if value not in self._values:
+            return stmt
+        return stmt.where(self.attr == self._values[value])
+
+
+class ValuesFilter(_ColumnFilter):
+    """Distinct values of a plain column, for low-cardinality text like a country code."""
+
+    def options(self, session: Any, request: Any) -> list[tuple[str, str]]:
+        stmt = sa.select(self.attr).where(self.attr.is_not(None)).distinct().order_by(self.attr)
+        return [(str(v), str(v)) for v in session.scalars(stmt.limit(MAX_RELATION_OPTIONS))]
+
+    def apply(self, stmt: Any, value: str, request: Any) -> Any:
+        try:
+            return stmt.where(self.attr == coerce_to_column(self.attr, value))
+        except ValueError:
+            return stmt
+
+
+class DateFilter(_ColumnFilter):
+    RANGES = {"today": 0, "7d": 7, "30d": 30, "365d": 365}
+
+    def __init__(self, model: type, name: str, site: Any) -> None:
+        super().__init__(model, name)
+        self.site = site
+
+    def options(self, session: Any, request: Any) -> list[tuple[str, str]]:
+        return [("today", "Today"), ("7d", "Past 7 days"), ("30d", "Past 30 days"), ("365d", "Past year")]
+
+    def apply(self, stmt: Any, value: str, request: Any) -> Any:
+        if value not in self.RANGES:
+            return stmt
+        today = self.site.now().replace(hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
+        start = today - dt.timedelta(days=self.RANGES[value])
+        if not isinstance(self.attr.type, sa.DateTime):
+            return stmt.where(self.attr >= start.date())
+        return stmt.where(self.attr >= self.site.from_local(start, bool(self.attr.type.timezone)))
+
+
+class RelationFilter(_ColumnFilter):
+    def __init__(self, model: type, name: str) -> None:
+        super().__init__(model, name)
+        self.target = self.attr.property.mapper.class_
+        self.target_pk = inspect(self.target).primary_key[0]
+
+    def options(self, session: Any, request: Any) -> list[tuple[str, str]]:
+        # shortcut: options stop at MAX_RELATION_OPTIONS, a SimpleFilter fits bigger tables better
+        key = inspect(self.target).get_property_by_column(self.target_pk).key
+        stmt = sa.select(self.target).limit(MAX_RELATION_OPTIONS)
+        return [(str(getattr(o, key)), object_label(o)) for o in session.scalars(stmt)]
+
+    def apply(self, stmt: Any, value: str, request: Any) -> Any:
+        try:
+            pk = coerce_to_column(self.target_pk, value)
+        except ValueError:
+            return stmt
+        match = self.target_pk == pk
+        return stmt.where(self.attr.any(match) if self.attr.property.uselist else self.attr.has(match))
+
+
+def make_filter(model: type, spec: Any, site: Any) -> Filter:
+    if isinstance(spec, type) and issubclass(spec, Filter):
+        return spec()
+    if isinstance(spec, Filter):
+        return spec
+    mapper = inspect(model)
+    if spec in mapper.relationships:
+        return RelationFilter(model, spec)
+    if spec not in mapper.column_attrs:
+        raise AttributeError(f"{model.__name__} has no column or relationship called {spec!r}")
+    type_ = getattr(getattr(model, spec).type, "impl_instance", getattr(model, spec).type)
+    if isinstance(type_, sa.Boolean):
+        return BooleanFilter(model, spec)
+    if isinstance(type_, sa.Enum):
+        return EnumFilter(model, spec)
+    if isinstance(type_, (sa.DateTime, sa.Date)):
+        return DateFilter(model, spec, site)
+    return ValuesFilter(model, spec)
+
+
+class DateHierarchy:
+    """Year > month > day drill-down above the changelist. Filters on ranges so indexes still apply.
+
+    shortcut: it groups by stored time, not the site timezone, because shifting needs SQL per database.
+    """
+
+    def __init__(self, model: type, name: str) -> None:
+        self.name = name
+        self.attr = getattr(model, name)
+
+    def _selection(self, params: Any) -> dict[str, int]:
+        selected: dict[str, int] = {}
+        for part in ("year", "month", "day"):
+            raw = params.get(f"{self.name}__{part}", "")
+            if not raw.isdigit():
+                break
+            selected[part] = int(raw)
+        return selected
+
+    def apply(self, stmt: Any, params: Any) -> Any:
+        selected = self._selection(params)
+        if not selected:
+            return stmt
+        try:
+            year = selected["year"]
+            month, day = selected.get("month", 1), selected.get("day", 1)
+            start = dt.datetime(year, month, day)
+            if "day" in selected:
+                end = start + dt.timedelta(days=1)
+            elif "month" in selected:
+                end = dt.datetime(year + month // 12, month % 12 + 1, 1)
+            else:
+                end = dt.datetime(year + 1, 1, 1)
+        except (ValueError, OverflowError):
+            return stmt
+        if getattr(self.attr.type, "timezone", False):
+            start, end = start.replace(tzinfo=dt.timezone.utc), end.replace(tzinfo=dt.timezone.utc)
+        return stmt.where(self.attr >= start, self.attr < end)
+
+    def links(self, session: Any, stmt: Any, params: Any, url: Any) -> dict[str, Any]:
+        selected = self._selection(params)
+        parts = ["year", "month", "day"]
+        current = parts[min(len(selected), 2)]
+        keep: dict[str, Any] = {}
+        crumbs = []
+        for part, value in selected.items():
+            keep[f"{self.name}__{part}"] = value
+            crumbs.append({"label": str(value), "url": url(**keep)})
+        if len(selected) == 3:
+            return {"crumbs": crumbs, "links": []}
+        column = extract(current, self.attr)
+        values = session.scalars(
+            stmt.with_only_columns(column).where(self.attr.is_not(None)).distinct().order_by(None).limit(40)
+        )
+        links = [
+            {"label": str(int(v)), "url": url(**keep, **{f"{self.name}__{current}": int(v)})} for v in sorted(values)
+        ]
+        clear = url(**{f"{self.name}__{p}": None for p in parts})
+        return {"crumbs": crumbs, "links": links, "clear": clear}