polyadmin 0.1.0b1__py3-none-any.whl

polyadmin/core/delete.py

@@ -0,0 +1,146 @@
+"""Delete previews (docs/deletes.md): an optional ModelAdmin capability that
+says what else a delete takes out and what forbids it, and the resolution
+that makes a host's answer safe to show one principal.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from polyadmin.core.authorization import resource_permission
+
+# How many records of a group are listed; the rest are counted.
+DELETE_PREVIEW_SAMPLE = 10
+
+
+@dataclass(frozen=True)
+class DeleteGroup:
+    """One related type's share of a preview. `resource` is a registered slug,
+    or "" for a type the admin does not manage (then `label` is required).
+    `label` is a host string translated at render; "" falls back to the
+    resource's verbose name. `objects` is a sample; `total` the full count,
+    raised to len(objects) when smaller.
+    """
+
+    resource: str = ""
+    label: str = ""
+    objects: Sequence[Any] = ()
+    total: int = 0
+
+
+@dataclass(frozen=True)
+class DeletePreview:
+    cascades: Sequence[DeleteGroup] = ()  # deleted along with the objects
+    protected: Sequence[DeleteGroup] = ()  # prevent the delete while they exist
+
+
+class DeletePreviewer(Protocol):
+    """An optional ModelAdmin capability: implement `delete_preview` to show
+    what else a delete takes out, and to block deletes your storage would
+    refuse. Same optional-capability shape as ListQuerier: implement more,
+    get more, and nothing breaks if you do not.
+
+    `objects` is always a list -- one record from the delete page, the whole
+    selection from delete_selected -- so an implementation over SQL can
+    answer a bulk delete with one count and one sample query per relation.
+    """
+
+    def delete_preview(self, objects: list[Any]) -> DeletePreview: ...
+
+
+@dataclass
+class ResolvedDeleteGroup:
+    label: str  # untranslated
+    total: int
+    model_admin: Any = None  # None for a type the admin does not manage
+    visible: list[Any] = field(default_factory=list)
+    texts: list[str] = field(default_factory=list)
+    hidden: int = 0
+    more: int = 0
+
+
+@dataclass
+class ResolvedDeletePreview:
+    cascades: list[ResolvedDeleteGroup] = field(default_factory=list)
+    protected: list[ResolvedDeleteGroup] = field(default_factory=list)
+    denied_types: list[str] = field(default_factory=list)  # untranslated labels
+    blocked: bool = False
+
+
+def previews_deletes(model_admin: Any) -> bool:
+    return callable(getattr(model_admin, "delete_preview", None))
+
+
+def resolve_delete_preview(admin: Any, model_admin: Any, principal: Any, objects: Sequence[Any]) -> ResolvedDeletePreview:
+    """Ask model_admin what deleting objects takes with it and filter the answer
+    for principal. Without the capability: an empty, non-blocking result, and
+    nothing is called.
+    """
+    if not previews_deletes(model_admin):
+        return ResolvedDeletePreview()
+    preview = model_admin.delete_preview(list(objects))
+    out = ResolvedDeletePreview()
+    for group in preview.cascades:
+        resolved = _resolve_group(admin, principal, group)
+        if resolved is None:
+            continue
+        out.cascades.append(resolved)
+        target = resolved.model_admin
+        if target is not None and not _allows(
+            admin, principal, target.can_delete, resource_permission(target.get_slug(), "delete"), target
+        ):
+            out.denied_types.append(resolved.label)
+    for group in preview.protected:
+        resolved = _resolve_group(admin, principal, group)
+        if resolved is not None:
+            out.protected.append(resolved)
+    out.blocked = bool(out.protected or out.denied_types)
+    return out
+
+
+def _resolve_group(admin: Any, principal: Any, group: DeleteGroup) -> ResolvedDeleteGroup | None:
+    total = max(group.total, len(group.objects))
+    if total == 0:
+        return None
+    sample = list(group.objects)[:DELETE_PREVIEW_SAMPLE]
+    resolved = ResolvedDeleteGroup(label=group.label, total=total, more=total - len(sample))
+    if not group.resource:
+        if not group.label:
+            raise ValueError("A DeleteGroup needs a resource or a label.")
+        resolved.texts = [str(obj) for obj in sample]
+        return resolved
+    try:
+        target = admin.get_model_admin(group.resource)
+    except KeyError:
+        raise ValueError(f"delete_preview names unregistered resource {group.resource!r}.") from None
+    resolved.model_admin = target
+    resolved.label = resolved.label or target.get_verbose_name()
+    # The detail page's two checks: the coarse one against the resource, then
+    # the per-object one. A record failing either is counted, never named.
+    permission = resource_permission(target.get_slug(), "view")
+    viewable = _allows(admin, principal, target.can_view, permission, target)
+    for obj in sample:
+        if viewable and _allows(admin, principal, True, permission, obj):
+            resolved.visible.append(obj)
+        else:
+            resolved.hidden += 1
+    return resolved
+
+
+def _allows(admin: Any, principal: Any, capability: bool, permission: str, resource: Any) -> bool:
+    """compute_permissions' rule for one check: the static toggle, then the
+    Authorizer if there is one."""
+    if not capability:
+        return False
+    return admin.authorizer is None or admin.authorizer.can(principal, permission, resource)
+
+
+def selection_fingerprint(model_admin: Any, objects: Sequence[Any]) -> str:
+    """The hex SHA-256 of the records' primary keys, sorted and newline-joined.
+    The delete_selected confirmation carries it so "all N matching" deletes
+    exactly the set that was reviewed."""
+    pks = sorted(str(model_admin.get_pk(obj)) for obj in objects)
+    return hashlib.sha256("\n".join(pks).encode()).hexdigest()

polyadmin/core/exporter.py

@@ -0,0 +1,136 @@
+"""Exporter: turns a ModelAdmin's list query result into a downloadable
+file. The adapter feeds it the *same* filtered/ordered
+result set `execute_list_query` produced for the list view, so an
+export always represents exactly the dataset the user was looking at,
+respecting the resource's configured columns (`list_display`).
+
+CSV streams row-by-row all the way to the HTTP response and never
+holds more than one row in memory. XLSX is written with openpyxl's
+write-only mode, which avoids materializing a Python object per row
+--but the zip container format has to be finalized before any bytes
+go out, so unlike CSV it is buffered once, not chunked, to the client.
+Large XLSX exports should stay reasonable in row count for that reason.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+from collections.abc import Iterable, Iterator
+from typing import Any
+
+from polyadmin.core.admin import Admin
+from polyadmin.core.field import Field
+from polyadmin.core.model_admin import ModelAdmin
+
+
+def cell_value(admin: Admin, field: Field, obj: Any) -> Any:
+    """A field's export-friendly value: relation fields resolve to
+    their target's display label (or a comma-joined list of them for
+    ManyToMany) rather than exporting a raw Python object.
+    """
+    value = field.get_value(obj)
+    if field.field_type in ("foreignkey", "onetoone"):
+        if value is None:
+            return ""
+        target_admin = admin.get_model_admin(field.relation.target)
+        return target_admin.get_field(field.relation.display_field).get_value(value)
+    if field.field_type == "manytomany":
+        if not value:
+            return ""
+        target_admin = admin.get_model_admin(field.relation.target)
+        display_field = target_admin.get_field(field.relation.display_field)
+        return ", ".join(str(display_field.get_value(item)) for item in value)
+    return value
+
+
+class Exporter:
+    format: str
+    content_type: str
+
+    def file_extension(self) -> str:
+        raise NotImplementedError
+
+    def stream(
+        self,
+        admin: Admin,
+        model_admin: ModelAdmin,
+        objects: Iterable[Any],
+        columns: list[str],
+        header: list[str] | None = None,
+    ) -> Iterator[bytes]:
+        raise NotImplementedError
+
+
+class CSVExporter(Exporter):
+    format = "csv"
+    content_type = "text/csv"
+
+    def file_extension(self) -> str:
+        return "csv"
+
+    def stream(
+        self,
+        admin: Admin,
+        model_admin: ModelAdmin,
+        objects: Iterable[Any],
+        columns: list[str],
+        header: list[str] | None = None,
+    ) -> Iterator[bytes]:
+        fields = [model_admin.get_field(name) for name in columns]
+        buffer = io.StringIO()
+        writer = csv.writer(buffer)
+
+        writer.writerow(header or [field.label for field in fields])
+        yield buffer.getvalue().encode("utf-8")
+        buffer.seek(0)
+        buffer.truncate(0)
+
+        for obj in objects:
+            writer.writerow([cell_value(admin, field, obj) for field in fields])
+            yield buffer.getvalue().encode("utf-8")
+            buffer.seek(0)
+            buffer.truncate(0)
+
+
+class XLSXExporter(Exporter):
+    format = "xlsx"
+    content_type = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+
+    def file_extension(self) -> str:
+        return "xlsx"
+
+    def stream(
+        self,
+        admin: Admin,
+        model_admin: ModelAdmin,
+        objects: Iterable[Any],
+        columns: list[str],
+        header: list[str] | None = None,
+    ) -> Iterator[bytes]:
+        from openpyxl import Workbook
+
+        fields = [model_admin.get_field(name) for name in columns]
+        workbook = Workbook(write_only=True)
+        sheet = workbook.create_sheet(model_admin.get_verbose_name())
+
+        sheet.append(header or [field.label for field in fields])
+        for obj in objects:
+            row = [cell_value(admin, field, obj) for field in fields]
+            # openpyxl only accepts str/int/float/bool/datetime cells --
+            # coerce anything else (None, UUID, dict/list from a JSON
+            # field, ...) to a plain string.
+            sheet.append(
+                [
+                    ""
+                    if value is None
+                    else value
+                    if isinstance(value, (str, int, float, bool))
+                    else str(value)
+                    for value in row
+                ]
+            )
+
+        buffer = io.BytesIO()
+        workbook.save(buffer)
+        yield buffer.getvalue()

polyadmin/core/field.py

@@ -0,0 +1,201 @@
+"""Field abstraction.
+
+A Field represents a model property plus its admin presentation, not
+merely an HTML input. Context-aware rendering (list/detail/form/filter)
+is added in Phase 2; this module defines the data-level contract that
+rendering will build on.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from polyadmin.i18n import gettext
+
+if TYPE_CHECKING:
+    from polyadmin.core.relation import Relation
+
+_UNSET = object()
+
+
+class Field:
+    """Base class for all admin field types."""
+
+    field_type: str = "field"
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        label: str | None = None,
+        required: bool = False,
+        readonly: bool = False,
+        disabled: bool = False,
+        default: Any = _UNSET,
+        help_text: str = "",
+        placeholder: str = "",
+        validators: Sequence[Callable[[Any], None]] = (),
+    ) -> None:
+        self.name = name
+        self.label = label or name.replace("_", " ").title()
+        self.required = required
+        self.readonly = readonly
+        self.disabled = disabled
+        self.default = default
+        self.help_text = help_text
+        self.placeholder = placeholder
+        self.validators = list(validators)
+
+    @property
+    def has_default(self) -> bool:
+        return self.default is not _UNSET
+
+    def get_value(self, obj: Any) -> Any:
+        """Read this field's value off a model instance."""
+        value = getattr(obj, self.name, _UNSET)
+        if value is _UNSET:
+            return self.default if self.has_default else None
+        return value
+
+    def parse_form_value(self, raw: Any) -> Any:
+        """Coerce a raw submitted form value into this field's Python
+        type. An empty string becomes None for every field type so that
+        `required` validation (which treats None and "" the same) still
+        fires; adapters are responsible for feeding booleans in as
+        checkbox presence rather than a raw string.
+        """
+        if raw is None or raw == "":
+            return None
+        if self.field_type == "integer":
+            try:
+                return int(raw)
+            except (TypeError, ValueError):
+                return raw
+        if self.field_type == "decimal":
+            try:
+                return float(raw)
+            except (TypeError, ValueError):
+                return raw
+        if self.field_type == "json":
+            import json
+
+            try:
+                return json.loads(raw)
+            except (TypeError, ValueError):
+                return raw
+        return raw
+
+    def validate(self, value: Any) -> list[str]:
+        """Run configured validators, returning a list of error messages."""
+        errors: list[str] = []
+        if self.required and (value is None or value == ""):
+            errors.append(gettext("%(label)s is required.") % {"label": gettext(self.label)})
+            return errors
+        for validator in self.validators:
+            try:
+                validator(value)
+            except ValueError as exc:
+                # A static English message translates from the host's
+                # catalog; one already translated misses and passes through.
+                errors.append(gettext(str(exc)))
+        return errors
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"{type(self).__name__}({self.name!r})"
+
+
+class StringField(Field):
+    field_type = "string"
+
+
+class TextField(Field):
+    field_type = "text"
+
+
+class IntegerField(Field):
+    field_type = "integer"
+
+
+class DecimalField(Field):
+    field_type = "decimal"
+
+
+class BooleanField(Field):
+    field_type = "boolean"
+
+
+class DateField(Field):
+    field_type = "date"
+
+
+class DateTimeField(Field):
+    field_type = "datetime"
+
+
+class EmailField(Field):
+    field_type = "email"
+
+
+class URLField(Field):
+    field_type = "url"
+
+
+class UUIDField(Field):
+    field_type = "uuid"
+
+
+class EnumField(Field):
+    field_type = "enum"
+
+    def __init__(self, name: str, *, choices: Sequence[Any], **kwargs: Any) -> None:
+        super().__init__(name, **kwargs)
+        self.choices = list(choices)
+
+
+class JSONField(Field):
+    field_type = "json"
+
+
+class PasswordField(Field):
+    field_type = "password"
+
+
+class ForeignKeyField(Field):
+    """A single related object. `get_value` returns the
+    related object itself (or None), not a scalar -- rendering resolves
+    its display label via `relation.display_field` on the target
+    ModelAdmin.
+    """
+
+    field_type = "foreignkey"
+
+    def __init__(self, name: str, *, relation: Relation, **kwargs: Any) -> None:
+        super().__init__(name, **kwargs)
+        self.relation = relation
+
+    def get_value(self, obj: Any) -> Any:
+        # A relation with get_related builds the related object from what the
+        # row carries (typically an id and a label read over HTTP); without one
+        # the row's attribute of this field's name is the related object.
+        if self.relation.get_related is not None:
+            return self.relation.get_related(obj)
+        return super().get_value(obj)
+
+
+class OneToOneField(ForeignKeyField):
+    field_type = "onetoone"
+
+
+class ManyToManyField(Field):
+    """A collection of related objects."""
+
+    field_type = "manytomany"
+
+    def __init__(self, name: str, *, relation: Relation, **kwargs: Any) -> None:
+        super().__init__(name, **kwargs)
+        self.relation = relation
+
+    def get_value(self, obj: Any) -> Any:
+        value = self.relation.get_related(obj) if self.relation.get_related is not None else super().get_value(obj)
+        return value if value is not None else []