phzyx-forge 0.1.0__py3-none-any.whl

phzyx/admin/__init__.py

@@ -0,0 +1,153 @@
+"""Phzyx AdminBoard core — headless admin service and SPA assets."""
+
+from pkgutil import extend_path
+
+from phzyx.admin.actions import (
+    AdminAction,
+    BulkAction,
+    list_admin_actions,
+    list_bulk_actions,
+    run_admin_action,
+    run_bulk_action,
+)
+from phzyx.admin.async_service import AsyncAdminService
+from phzyx.admin.audit import AuditEvent, AuditLog
+from phzyx.admin.auth import AllowAll, Authz, DenyWrites, require_authz
+from phzyx.admin.errors import (
+    AdminError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    UnauthorizedError,
+    ValidationAdminError,
+)
+from phzyx.admin.export_copy import copy_payload, export_csv, export_json
+from phzyx.admin.i18n import DEFAULT_CATALOG, I18n
+from phzyx.admin.identity import decode_identity, encode_identity
+from phzyx.admin.layouts import LayoutPrefs, LayoutStore
+from phzyx.admin.media import MediaItem, MediaLibrary
+from phzyx.admin.opener import OpenMeta, open_meta_for_key
+from phzyx.admin.relation_manager import RelationManager, all_relation_managers
+from phzyx.admin.resource import (
+    ColumnConfig,
+    FieldsetConfig,
+    RelationConfig,
+    ResourceConfig,
+    infer_resource,
+    m2m_relation,
+    override_resource,
+    wire_relations,
+)
+from phzyx.admin.search import SearchHit, global_search
+from phzyx.admin.security import (
+    assert_no_mass_assignment,
+    csp_headers,
+    csrf_cookie_notes,
+    is_production_like,
+)
+from phzyx.admin.service import AdminService, ListResult
+from phzyx.admin.settings import AdminSettings, SettingsStore
+from phzyx.admin.storage import LocalStorage, MemoryStorage, StorageBackend, guess_content_type
+from phzyx.admin.storage_cloud import AzureBlobStorage, GCSStorage, S3CompatibleStorage
+from phzyx.admin.stream_export import (
+    BOUNDED_RSS_NOTE,
+    DEFAULT_EXPORT_POLICY,
+    EXCEL_MAX_ROWS,
+    ExportPolicy,
+    export_xlsx,
+    stream_csv,
+    stream_json_array,
+    stream_jsonl,
+)
+from phzyx.admin.themes import (
+    DEFAULT_THEME,
+    PRIMARY_THEMES,
+    ThemeName,
+    normalize_theme,
+    resolve_theme,
+    theme_tokens_css,
+)
+from phzyx.admin.widgets import CountWidget, resource_count_widgets
+
+__path__ = extend_path(__path__, __name__)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BOUNDED_RSS_NOTE",
+    "DEFAULT_EXPORT_POLICY",
+    "DEFAULT_THEME",
+    "EXCEL_MAX_ROWS",
+    "PRIMARY_THEMES",
+    "AdminAction",
+    "AdminError",
+    "AdminService",
+    "AdminSettings",
+    "AsyncAdminService",
+    "AllowAll",
+    "CountWidget",
+    "DEFAULT_CATALOG",
+    "I18n",
+    "RelationManager",
+    "SearchHit",
+    "AuditEvent",
+    "AuditLog",
+    "Authz",
+    "AzureBlobStorage",
+    "BulkAction",
+    "ColumnConfig",
+    "ConflictError",
+    "DenyWrites",
+    "FieldsetConfig",
+    "ExportPolicy",
+    "ForbiddenError",
+    "GCSStorage",
+    "LayoutPrefs",
+    "LayoutStore",
+    "ListResult",
+    "LocalStorage",
+    "MediaItem",
+    "MediaLibrary",
+    "MemoryStorage",
+    "NotFoundError",
+    "OpenMeta",
+    "RelationConfig",
+    "m2m_relation",
+    "ResourceConfig",
+    "S3CompatibleStorage",
+    "SettingsStore",
+    "StorageBackend",
+    "ThemeName",
+    "UnauthorizedError",
+    "ValidationAdminError",
+    "__version__",
+    "assert_no_mass_assignment",
+    "copy_payload",
+    "csp_headers",
+    "csrf_cookie_notes",
+    "decode_identity",
+    "encode_identity",
+    "all_relation_managers",
+    "export_csv",
+    "export_json",
+    "export_xlsx",
+    "global_search",
+    "guess_content_type",
+    "resource_count_widgets",
+    "infer_resource",
+    "is_production_like",
+    "list_admin_actions",
+    "list_bulk_actions",
+    "normalize_theme",
+    "open_meta_for_key",
+    "override_resource",
+    "require_authz",
+    "resolve_theme",
+    "run_admin_action",
+    "run_bulk_action",
+    "stream_csv",
+    "stream_json_array",
+    "stream_jsonl",
+    "theme_tokens_css",
+    "wire_relations",
+]

phzyx/admin/actions.py

@@ -0,0 +1,269 @@
+"""Admin action registry — row / bulk / global (Diamond D2/D5)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from phzyx.admin.auth import require_authz
+from phzyx.admin.errors import NotFoundError, ValidationAdminError
+from phzyx.admin.identity import decode_identity
+
+if TYPE_CHECKING:
+    from phzyx.admin.service import AdminService
+
+Scope = Literal["row", "bulk", "global"]
+
+# client: SPA-side execution hint (no server mutation body required)
+ClientKind = str | None  # export:csv | export:json | export:xlsx | copy:json | None
+
+
+@dataclass(frozen=True, slots=True)
+class AdminAction:
+    """Declarative admin action (Diamond D5)."""
+
+    name: str
+    label: str
+    description: str = ""
+    scope: Scope = "bulk"
+    confirm: bool = False
+    danger: bool = False
+    client: ClientKind = None  # if set, SPA runs client handler
+
+
+# Backward-compatible alias
+BulkAction = AdminAction
+
+Handler = Callable[["AdminService", str, Sequence[str], Any | None], dict[str, Any]]
+
+
+def action_deactivate(
+    service: AdminService,
+    resource: str,
+    identities: Sequence[str],
+    principal: Any | None = None,
+) -> dict[str, Any]:
+    """Set ``active=False`` on each identity when the model has that field."""
+    res = service.get_resource(resource)
+    if not any(c.name == "active" for c in res.columns):
+        raise ValidationAdminError("resource has no active field")
+    updated = 0
+    for ident in identities:
+        key = decode_identity(res.model, ident)
+        obj = service.session.get(res.model, key)
+        if obj is None:
+            continue
+        service.session.update(obj, active=False)
+        updated += 1
+    service.session.commit()
+    if service.audit:
+        pid = getattr(principal, "id", None) if principal else None
+        service.audit.record(
+            "bulk_deactivate",
+            resource,
+            principal_id=pid,
+            count=updated,
+        )
+    return {"action": "deactivate", "updated": updated, "ok": True}
+
+
+def action_activate(
+    service: AdminService,
+    resource: str,
+    identities: Sequence[str],
+    principal: Any | None = None,
+) -> dict[str, Any]:
+    """Set ``active=True`` on selected identities."""
+    res = service.get_resource(resource)
+    if not any(c.name == "active" for c in res.columns):
+        raise ValidationAdminError("resource has no active field")
+    updated = 0
+    for ident in identities:
+        key = decode_identity(res.model, ident)
+        obj = service.session.get(res.model, key)
+        if obj is None:
+            continue
+        service.session.update(obj, active=True)
+        updated += 1
+    service.session.commit()
+    if service.audit:
+        pid = getattr(principal, "id", None) if principal else None
+        service.audit.record("bulk_activate", resource, principal_id=pid, count=updated)
+    return {"action": "activate", "updated": updated, "ok": True}
+
+
+DEFAULT_HANDLERS: dict[str, Handler] = {
+    "deactivate": action_deactivate,
+    "activate": action_activate,
+}
+
+# Prefer DEFAULT_HANDLERS; keep alias for D2 imports
+DEFAULT_BULK_HANDLERS = DEFAULT_HANDLERS
+
+
+def default_actions(*, has_active: bool) -> list[AdminAction]:
+    """Built-in catalog: server mutations + client export/copy."""
+    acts: list[AdminAction] = [
+        AdminAction(
+            name="export_csv",
+            label="Export CSV",
+            description="Download resource as CSV",
+            scope="global",
+            client="export:csv",
+        ),
+        AdminAction(
+            name="export_json",
+            label="Export JSON",
+            description="Download resource as JSON",
+            scope="global",
+            client="export:json",
+        ),
+        AdminAction(
+            name="export_xlsx",
+            label="Export Excel",
+            description="Download resource as Excel",
+            scope="global",
+            client="export:xlsx",
+        ),
+        AdminAction(
+            name="copy_json",
+            label="Copy JSON",
+            description="Copy selection or all as JSON",
+            scope="bulk",
+            client="copy:json",
+            confirm=False,
+        ),
+        AdminAction(
+            name="copy_row_json",
+            label="Copy JSON",
+            description="Copy this row as JSON",
+            scope="row",
+            client="copy:json",
+            confirm=False,
+        ),
+    ]
+    if has_active:
+        acts.extend(
+            [
+                AdminAction(
+                    name="deactivate",
+                    label="Deactivate",
+                    description="Set active=false on selected rows",
+                    scope="bulk",
+                    confirm=True,
+                    danger=False,
+                ),
+                AdminAction(
+                    name="activate",
+                    label="Activate",
+                    description="Set active=true on selected rows",
+                    scope="bulk",
+                    confirm=True,
+                ),
+                AdminAction(
+                    name="deactivate",
+                    label="Deactivate",
+                    description="Set active=false on this row",
+                    scope="row",
+                    confirm=True,
+                ),
+                AdminAction(
+                    name="activate",
+                    label="Activate",
+                    description="Set active=true on this row",
+                    scope="row",
+                    confirm=True,
+                ),
+            ]
+        )
+    return acts
+
+
+DEFAULT_BULK_ACTIONS: tuple[AdminAction, ...] = tuple(
+    a for a in default_actions(has_active=True) if a.scope == "bulk" and not a.client
+)
+
+
+def _public(a: AdminAction) -> dict[str, Any]:
+    return {
+        "name": a.name,
+        "label": a.label,
+        "description": a.description,
+        "scope": a.scope,
+        "confirm": a.confirm,
+        "danger": a.danger,
+        "client": a.client,
+    }
+
+
+def list_admin_actions(
+    resource_name: str,
+    *,
+    has_active: bool,
+    scope: str | None = None,
+) -> list[dict[str, Any]]:
+    """Public action descriptors for SPA (Diamond D5)."""
+    _ = resource_name
+    out = [_public(a) for a in default_actions(has_active=has_active)]
+    if scope:
+        out = [a for a in out if a["scope"] == scope]
+    return out
+
+
+def list_bulk_actions(resource_name: str, has_active: bool) -> list[dict[str, Any]]:
+    """Backward-compatible bulk-only list (D2)."""
+    return list_admin_actions(resource_name, has_active=has_active, scope="bulk")
+
+
+def run_admin_action(
+    service: AdminService,
+    resource: str,
+    action: str,
+    identities: Sequence[str] | None = None,
+    *,
+    principal: Any | None = None,
+    handlers: dict[str, Handler] | None = None,
+) -> dict[str, Any]:
+    """Run a server-side action (row or bulk)."""
+    require_authz(service.authz, principal, f"action:{action}", resource)
+    # Client-only actions should not hit the server runner
+    catalog = {
+        a.name: a
+        for a in default_actions(
+            has_active=any(c.name == "active" for c in service.get_resource(resource).columns)
+        )
+        if a.client is None
+    }
+    reg_probe = handlers or DEFAULT_HANDLERS
+    if action not in catalog and action not in reg_probe and action not in DEFAULT_HANDLERS:
+        raise NotFoundError(f"unknown action {action}")
+
+    idents = list(identities or [])
+    if not idents:
+        raise ValidationAdminError("identities required")
+    reg = handlers or DEFAULT_HANDLERS
+    handler = reg.get(action)
+    if handler is None:
+        raise NotFoundError(f"unknown action {action}")
+    return handler(service, resource, idents, principal)
+
+
+def run_bulk_action(
+    service: AdminService,
+    resource: str,
+    action: str,
+    identities: Sequence[str],
+    *,
+    principal: Any | None = None,
+    handlers: dict[str, Handler] | None = None,
+) -> dict[str, Any]:
+    """Backward-compatible bulk runner (D2)."""
+    return run_admin_action(
+        service,
+        resource,
+        action,
+        identities,
+        principal=principal,
+        handlers=handlers,
+    )

phzyx/admin/async_service.py

@@ -0,0 +1,263 @@
+"""Async AdminService — battle-ready CRUD over AsyncSession."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from phzyx.admin.audit import AuditLog
+from phzyx.admin.auth import AllowAll, AllowAllFields, Authz, FieldAuthz, require_authz
+from phzyx.admin.errors import ConflictError, NotFoundError, ValidationAdminError
+from phzyx.admin.filters import build_where
+from phzyx.admin.identity import decode_identity, encode_identity
+from phzyx.admin.resource import ResourceConfig
+from phzyx.admin.security import assert_no_mass_assignment
+from phzyx.admin.service import ListResult, _validation_error
+from phzyx.admin.unique_checks import raise_if_unique_violations_async
+from phzyx.orm.errors import ConflictError as OrmConflict
+from phzyx.orm.insert_prep import utcnow
+from phzyx.orm.keyset import default_order_columns, order_from_columns
+from phzyx.orm.session_async import AsyncSession
+from phzyx.schema.model import get_table_info
+
+
+def _identity_key(model: type[Any], obj: Any) -> Any:
+    pk = get_table_info(model).primary_key
+    if len(pk) == 1:
+        return getattr(obj, pk[0])
+    return {c: getattr(obj, c) for c in pk}
+
+
+def _serialize(model: type[Any], obj: Any) -> dict[str, Any]:
+    data = obj.model_dump(mode="json")
+    data["_identity"] = encode_identity(model, _identity_key(model, obj))
+    return data
+
+
+@dataclass
+class AsyncAdminService:
+    """Headless admin ops over AsyncSession (list/get/create/update/delete)."""
+
+    resources: dict[str, ResourceConfig]
+    session: AsyncSession
+    authz: Authz = field(default_factory=AllowAll)
+    field_authz: FieldAuthz = field(default_factory=AllowAllFields)
+    audit: AuditLog | None = None
+    storage: Any | None = None
+
+    def get_resource(self, name: str) -> ResourceConfig:
+        if name not in self.resources:
+            raise NotFoundError(f"unknown resource {name}")
+        return self.resources[name]
+
+    def _where(
+        self,
+        res: ResourceConfig,
+        *,
+        search: str | None,
+        filters: dict[str, str] | None,
+    ) -> list[Any]:
+        """Same filter rules as sync AdminService (shared ``build_where``)."""
+        return build_where(res, search=search, filters=filters, hide_soft_deleted=True)
+
+    async def list(
+        self,
+        name: str,
+        *,
+        page: int = 1,
+        page_size: int = 50,
+        search: str | None = None,
+        filters: dict[str, str] | None = None,
+        cursor: str | None = None,
+        pagination: str = "keyset",
+        principal: Any | None = None,
+    ) -> ListResult:
+        """List records (mirrors sync AdminService pagination rules)."""
+        from phzyx.admin.service import _resolve_list_pagination
+
+        res = self.get_resource(name)
+        require_authz(self.authz, principal, "list", name)
+        page = max(1, page)
+        page_size = min(max(1, page_size), 200)
+        where = self._where(res, search=search, filters=filters)
+        order = order_from_columns(default_order_columns(res.model))
+        mode = _resolve_list_pagination(pagination, page=page, cursor=cursor)
+        total = await self.session.count(res.model, where=where)
+        if mode == "keyset":
+            page_data = await self.session.query_keyset(
+                res.model,
+                where=where,
+                order_by=order,
+                limit=page_size,
+                cursor=cursor,
+            )
+            items = [_serialize(res.model, r) for r in page_data.items]
+            return ListResult(
+                items=items,
+                total=total,
+                page=page,
+                page_size=page_size,
+                next_cursor=page_data.next_cursor,
+                prev_cursor=page_data.prev_cursor,
+                has_more=page_data.has_more,
+                pagination="keyset",
+            )
+        rows = await self.session.query(
+            res.model,
+            where=where,
+            order_by=order,
+            limit=page_size,
+            offset=(page - 1) * page_size,
+        )
+        items = [_serialize(res.model, r) for r in rows]
+        return ListResult(
+            items=items,
+            total=total,
+            page=page,
+            page_size=page_size,
+            has_more=(page * page_size) < total,
+            pagination="offset",
+        )
+
+    async def get(
+        self,
+        name: str,
+        identity: str,
+        *,
+        principal: Any | None = None,
+    ) -> dict[str, Any]:
+        res = self.get_resource(name)
+        require_authz(self.authz, principal, "get", name)
+        key = decode_identity(res.model, identity)
+        obj = await self.session.get(res.model, key)
+        if obj is None:
+            raise NotFoundError(f"{name} {identity} not found")
+        return _serialize(res.model, obj)
+
+    async def create(
+        self,
+        name: str,
+        data: dict[str, Any],
+        *,
+        principal: Any | None = None,
+    ) -> dict[str, Any]:
+        res = self.get_resource(name)
+        require_authz(self.authz, principal, "create", name)
+        if res.readonly:
+            raise ValidationAdminError("resource is readonly")
+        clean = assert_no_mass_assignment(res, data, partial=False)
+        ai_pks: set[str] = set()
+        for pk in res.primary_key:
+            col = res.column(pk)
+            if col and col.autoincrement and (pk not in clean or clean.get(pk) in (None, "")):
+                clean.pop(pk, None)
+                ai_pks.add(pk)
+        # Drop generated fields from client payload
+        for c in res.columns:
+            meta = get_table_info(res.model).columns.get(c.name)
+            if meta and meta.generated:
+                clean.pop(c.name, None)
+        try:
+            obj = res.model.model_validate(clean)
+        except Exception as exc:
+            missing = [
+                fname
+                for fname, finfo in res.model.model_fields.items()
+                if fname not in ai_pks and finfo.is_required() and fname not in clean
+            ]
+            if missing or not ai_pks:
+                raise _validation_error(exc) from exc
+            try:
+                obj = res.model.model_construct(**clean)
+            except Exception as exc2:
+                raise _validation_error(exc2) from exc2
+        await raise_if_unique_violations_async(
+            res.model,
+            clean,
+            query=lambda where: self.session.query(res.model, where=where, limit=5),
+        )
+        try:
+            obj = await self.session.add(obj)
+            await self.session.commit()
+        except Exception as exc:
+            await self.session.rollback()
+            msg = str(exc).lower()
+            if "unique" in msg or "duplicate" in msg or "integrity" in msg:
+                raise ValidationAdminError(
+                    "Validation failed",
+                    fields={"_": "unique constraint violated"},
+                ) from exc
+            raise
+        if self.audit:
+            pid = getattr(principal, "id", None) if principal else None
+            self.audit.record("create", name, principal_id=pid)
+        return _serialize(res.model, obj)
+
+    async def update(
+        self,
+        name: str,
+        identity: str,
+        data: dict[str, Any],
+        *,
+        principal: Any | None = None,
+    ) -> dict[str, Any]:
+        res = self.get_resource(name)
+        require_authz(self.authz, principal, "update", name)
+        if res.readonly:
+            raise ValidationAdminError("resource is readonly")
+        key = decode_identity(res.model, identity)
+        obj = await self.session.get(res.model, key)
+        if obj is None:
+            raise NotFoundError(f"{name} {identity} not found")
+        clean = assert_no_mass_assignment(res, data, partial=True)
+        for c in res.columns:
+            meta = get_table_info(res.model).columns.get(c.name)
+            if meta and meta.generated:
+                clean.pop(c.name, None)
+        merged = {**_serialize(res.model, obj), **clean}
+        merged.pop("_identity", None)
+        await raise_if_unique_violations_async(
+            res.model,
+            merged,
+            query=lambda where: self.session.query(res.model, where=where, limit=5),
+            exclude_key=key,
+        )
+        try:
+            updated = await self.session.update(obj, **clean)
+            await self.session.commit()
+        except OrmConflict as exc:
+            await self.session.rollback()
+            raise ConflictError(str(exc), resource=name, identity=identity) from exc
+        except Exception as exc:
+            await self.session.rollback()
+            raise _validation_error(exc) from exc
+        if self.audit:
+            pid = getattr(principal, "id", None) if principal else None
+            self.audit.record("update", name, principal_id=pid, identity=identity)
+        return _serialize(res.model, updated)
+
+    async def delete(
+        self,
+        name: str,
+        identity: str,
+        *,
+        principal: Any | None = None,
+        soft: bool | None = None,
+    ) -> None:
+        res = self.get_resource(name)
+        require_authz(self.authz, principal, "delete", name)
+        if res.readonly:
+            raise ValidationAdminError("resource is readonly")
+        key = decode_identity(res.model, identity)
+        obj = await self.session.get(res.model, key)
+        if obj is None:
+            raise NotFoundError(f"{name} {identity} not found")
+        use_soft = soft if soft is not None else ("deleted_at" in res.model.model_fields)
+        if use_soft and "deleted_at" in res.model.model_fields:
+            await self.session.update(obj, deleted_at=utcnow().isoformat())
+        else:
+            await self.session.delete(obj)
+        await self.session.commit()
+        if self.audit:
+            pid = getattr(principal, "id", None) if principal else None
+            self.audit.record("delete", name, principal_id=pid, identity=identity)