phzyx-forge 0.1.0__tar.gz

phzyx_forge-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: phzyx-forge
+Version: 0.1.0
+Summary: Phzyx Forge — schema, failsafe migrations, ORM, AdminBoard, CLI
+Project-URL: Homepage, https://phzyx.xyz
+Project-URL: Documentation, https://phzyx.xyz/docs
+Project-URL: Repository, https://github.com/phzyxyz/forge
+Project-URL: Issues, https://github.com/phzyxyz/forge/issues
+Author: Athul Nandaswaroop
+License-Expression: MIT
+Keywords: admin,fastapi,migrations,orm,phzyx,pydantic
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite
+Requires-Dist: fastapi>=0.115
+Requires-Dist: pydantic>=2
+Requires-Dist: python-multipart>=0.0.32
+Provides-Extra: auth
+Requires-Dist: phzyx-auth[fastapi]<0.2,>=0.1.0; extra == 'auth'
+Provides-Extra: cache
+Requires-Dist: phzyx-cache<0.2,>=0.1.0; extra == 'cache'
+Provides-Extra: full
+Requires-Dist: asyncpg; extra == 'full'
+Requires-Dist: litestar>=2.12; extra == 'full'
+Requires-Dist: phzyx-auth[fastapi]<0.2,>=0.1.0; extra == 'full'
+Requires-Dist: phzyx-cache<0.2,>=0.1.0; extra == 'full'
+Requires-Dist: psycopg[binary]>=3; extra == 'full'
+Requires-Dist: pymssql>=2.3; extra == 'full'
+Requires-Dist: pymysql; extra == 'full'
+Provides-Extra: litestar
+Requires-Dist: litestar>=2.12; extra == 'litestar'
+Provides-Extra: mssql
+Requires-Dist: pymssql>=2.3; extra == 'mssql'
+Provides-Extra: mysql
+Requires-Dist: pymysql; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: asyncpg; extra == 'postgres'
+Requires-Dist: psycopg[binary]>=3; extra == 'postgres'
+Provides-Extra: sqlite
+Description-Content-Type: text/markdown
+
+# phzyx-forge
+
+**Forge** — Phzyx data stack in one install: Pydantic schema, failsafe migrations,
+ORM, AdminBoard (FastAPI-first), and the `phzyx` CLI.
+
+```bash
+uv add phzyx-forge
+```
+
+```python
+from phzyx.schema.model import Model
+from phzyx.orm import Session
+from phzyx.admin.fastapi import AdminBoard
+```
+
+Optional batteries (separate packages):
+
+- `phzyx-auth` — identity / sessions / JWT / RBAC (`uv add 'phzyx-forge[auth]'`)
+- `phzyx-cache` — versioned resource cache
+
+Pre-1.0: APIs may change. Pin `==0.1.0` for apps.
+
+Homepage: https://phzyx.xyz · Source: https://github.com/phzyxyz/forge

phzyx_forge-0.1.0/README.md

@@ -0,0 +1,23 @@
+# phzyx-forge
+
+**Forge** — Phzyx data stack in one install: Pydantic schema, failsafe migrations,
+ORM, AdminBoard (FastAPI-first), and the `phzyx` CLI.
+
+```bash
+uv add phzyx-forge
+```
+
+```python
+from phzyx.schema.model import Model
+from phzyx.orm import Session
+from phzyx.admin.fastapi import AdminBoard
+```
+
+Optional batteries (separate packages):
+
+- `phzyx-auth` — identity / sessions / JWT / RBAC (`uv add 'phzyx-forge[auth]'`)
+- `phzyx-cache` — versioned resource cache
+
+Pre-1.0: APIs may change. Pin `==0.1.0` for apps.
+
+Homepage: https://phzyx.xyz · Source: https://github.com/phzyxyz/forge

phzyx_forge-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "phzyx-forge"
+version = "0.1.0"
+description = "Phzyx Forge — schema, failsafe migrations, ORM, AdminBoard, CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Athul Nandaswaroop" }]
+keywords = ["phzyx", "orm", "pydantic", "admin", "migrations", "fastapi"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Framework :: FastAPI",
+  "Topic :: Database",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pydantic>=2",
+  "fastapi>=0.115",
+  "python-multipart>=0.0.32",
+  "aiosqlite",  # default local stack; postgres/mysql/mssql stay extras
+]
+
+[project.optional-dependencies]
+# [sqlite] kept as no-op alias so old docs still resolve
+sqlite = []
+postgres = ["asyncpg", "psycopg[binary]>=3"]
+mysql = ["pymysql"]
+mssql = ["pymssql>=2.3"]
+auth = ["phzyx-auth[fastapi]>=0.1.0,<0.2"]
+cache = ["phzyx-cache>=0.1.0,<0.2"]
+litestar = ["litestar>=2.12"]
+# Literally full: every driver + batteries + Litestar (SQLite already in core).
+full = [
+  "asyncpg",
+  "psycopg[binary]>=3",
+  "pymysql",
+  "pymssql>=2.3",
+  "phzyx-auth[fastapi]>=0.1.0,<0.2",
+  "phzyx-cache>=0.1.0,<0.2",
+  "litestar>=2.12",
+]
+
+[project.scripts]
+phzyx = "phzyx.cli:main"
+
+[project.urls]
+Homepage = "https://phzyx.xyz"
+Documentation = "https://phzyx.xyz/docs"
+Repository = "https://github.com/phzyxyz/forge"
+Issues = "https://github.com/phzyxyz/forge/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/phzyx"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/phzyx", "README.md", "pyproject.toml"]

phzyx_forge-0.1.0/src/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_forge-0.1.0/src/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,
+    )