tigrbl 0.3.29.dev2__tar.gz → 0.4.0.dev2__tar.gz

{tigrbl-0.3.29.dev2 → tigrbl-0.4.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrbl
-Version: 0.3.29.dev2
+Version: 0.4.0.dev2
 Summary: A modern pure ASGI/WSGI Python framework for building schema-first REST and JSON-RPC APIs with SQLAlchemy models, typed validation, lifecycle hooks, and engine extension support.
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -40,6 +40,11 @@ Requires-Dist: tigrbl-orm
 Requires-Dist: tigrbl-runtime
 Requires-Dist: tigrbl-tests ; extra == "tests"
 Requires-Dist: uvicorn
+Project-URL: Discord, https://discord.gg/K4YTAPapjR
+Project-URL: Homepage, https://github.com/tigrbl/tigrbl
+Project-URL: Issues, https://github.com/tigrbl/tigrbl/issues
+Project-URL: Organization, https://github.com/tigrbl
+Project-URL: Repository, https://github.com/tigrbl/tigrbl
 Description-Content-Type: text/markdown
 
 # tigrbl
@@ -60,6 +65,10 @@ It is not the authoritative location for repository governance, current target s
 
 ## Package identity
 
+- canonical repository: `https://github.com/tigrbl/tigrbl`
+- organization: `https://github.com/tigrbl`
+- social: `https://discord.gg/K4YTAPapjR`
+- package path: `https://github.com/tigrbl/tigrbl/tree/master/pkgs/core/tigrbl`
 - workspace path: `pkgs/core/tigrbl`
 - workspace class: core Python package
 - implementation layout: `tigrbl/`

{tigrbl-0.3.29.dev2 → tigrbl-0.4.0.dev2}/README.md

@@ -16,6 +16,10 @@ It is not the authoritative location for repository governance, current target s
 
 ## Package identity
 
+- canonical repository: `https://github.com/tigrbl/tigrbl`
+- organization: `https://github.com/tigrbl`
+- social: `https://discord.gg/K4YTAPapjR`
+- package path: `https://github.com/tigrbl/tigrbl/tree/master/pkgs/core/tigrbl`
 - workspace path: `pkgs/core/tigrbl`
 - workspace class: core Python package
 - implementation layout: `tigrbl/`

{tigrbl-0.3.29.dev2 → tigrbl-0.4.0.dev2}/pyproject.toml

@@ -1,10 +1,9 @@
 [project]
 name = "tigrbl"
-version = "0.3.29.dev2"
+version = "0.4.0.dev2"
 description = "A modern pure ASGI/WSGI Python framework for building schema-first REST and JSON-RPC APIs with SQLAlchemy models, typed validation, lifecycle hooks, and engine extension support."
 license = "Apache-2.0"
 readme = "README.md"
-repository = "http://github.com/swarmauri/swarmauri-sdk"
 requires-python = ">=3.10,<3.14"
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -17,6 +16,7 @@ classifiers = [
     "Programming Language :: Python :: 3 :: Only",
 ]
 authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
+
 dependencies = [
     "tigrbl-core",
     "tigrbl-base",
@@ -36,6 +36,14 @@ dependencies = [
 ]
 
 
+
+[project.urls]
+Organization = "https://github.com/tigrbl"
+Discord = "https://discord.gg/K4YTAPapjR"
+Homepage = "https://github.com/tigrbl/tigrbl"
+Repository = "https://github.com/tigrbl/tigrbl"
+Issues = "https://github.com/tigrbl/tigrbl/issues"
+
 [project.scripts]
 tigrbl = "tigrbl.cli:console_main"
 

{tigrbl-0.3.29.dev2 → tigrbl-0.4.0.dev2}/tigrbl/__init__.py

@@ -101,6 +101,7 @@ from tigrbl_concrete._concrete import (  # noqa: E402
     PlainTextResponse,
     RedirectResponse,
     Request,
+    TransportResponse,
     UploadedFile,
     WebSocket,
     Response,
@@ -148,6 +149,8 @@ from tigrbl.ddl import bootstrap_dbschema, ensure_schemas, register_sqlite_attac
 
 from tigrbl_base._base import (  # noqa: E402
     AppBase,
+    EngineBase,
+    EngineProviderBase,
     ForeignKeyBase,
     HookBase,
     RouterBase,
@@ -161,6 +164,7 @@ from tigrbl_core._spec import (  # noqa: E402
     BindingSpec,
     ColumnSpec,
     EngineSpec,
+    EngineRegistry,
     Exchange,
     FieldSpec,
     Framing,
@@ -182,12 +186,18 @@ from tigrbl_core._spec import (  # noqa: E402
     SchemaRef,
     SchemaSpec,
     SessionSpec,
+    readonly,
+    session_spec,
     StorageSpec,
     StorageTransformSpec,
+    StorageTypeRef,
     TableRegistrySpec,
     TableSpec,
     TargetOp,
     TemplateSpec,
+    tx_read_committed,
+    tx_repeatable_read,
+    tx_serializable,
     TxScope,
     WebTransportBindingSpec,
     WsBindingSpec,
@@ -246,12 +256,47 @@ def include_tables(*args, **kwargs):
     )
 
 
+def include_model(*args, **kwargs):
+    if len(args) == 1 and isinstance(args[0], type) and not kwargs:
+        return args[0], None
+    return import_module("tigrbl_concrete._mapping.router.include").include_model(
+        *args, **kwargs
+    )
+
+
+def include_table(*args, **kwargs):
+    return import_module("tigrbl_concrete._mapping.router.include").include_table(
+        *args, **kwargs
+    )
+
+
+def include_models(*args, **kwargs):
+    return import_module("tigrbl_concrete._mapping.router.include").include_models(
+        *args, **kwargs
+    )
+
+
 async def rpc_call(*args, **kwargs):
     return await import_module("tigrbl_concrete._mapping.router.rpc").rpc_call(
         *args, **kwargs
     )
 
 
+from tigrbl_core._spec.session_spec import (  # noqa: E402
+    readonly as _readonly_fn,
+    session_spec as _session_spec_fn,
+    tx_read_committed as _tx_read_committed_fn,
+    tx_repeatable_read as _tx_repeatable_read_fn,
+    tx_serializable as _tx_serializable_fn,
+)
+
+readonly = _readonly_fn
+session_spec = _session_spec_fn
+tx_read_committed = _tx_read_committed_fn
+tx_repeatable_read = _tx_repeatable_read_fn
+tx_serializable = _tx_serializable_fn
+
+
 __all__ = [
     "specs",
     "base",
@@ -324,6 +369,9 @@ __all__ = [
     "build_handlers",
     "register_rpc",
     "build_rest",
+    "include_model",
+    "include_table",
+    "include_models",
     "include_tables",
     "rpc_call",
     "_invoke",
@@ -339,6 +387,7 @@ __all__ = [
     "UploadedFile",
     "WebSocket",
     "Response",
+    "TransportResponse",
     "JSONResponse",
     "BackgroundTask",
     "resolver",
@@ -355,11 +404,20 @@ __all__ = [
     "StorageTransform",
     "Middleware",
     "StorageTransformSpec",
+    "StorageTypeRef",
     "ForeignKeySpec",
     "RequestSpec",
     "SchemaSpec",
     "SessionSpec",
+    "session_spec",
+    "tx_read_committed",
+    "tx_repeatable_read",
+    "tx_serializable",
+    "readonly",
     "EngineSpec",
+    "EngineRegistry",
+    "EngineBase",
+    "EngineProviderBase",
     "TemplateSpec",
     "ForeignKeyBase",
     "HookBase",

tigrbl-0.4.0.dev2/tigrbl/canonical_json.py

@@ -0,0 +1,7 @@
+"""Compatibility export for core-owned canonical JSON helpers."""
+
+from __future__ import annotations
+
+from tigrbl_core.canonical_json import canonical_json_bytes, canonicalize
+
+__all__ = ["canonical_json_bytes", "canonicalize"]

tigrbl-0.4.0.dev2/tigrbl/session/__init__.py

@@ -0,0 +1,8 @@
+"""Compatibility exports for legacy ``tigrbl.session`` imports."""
+
+from __future__ import annotations
+
+from tigrbl_base._base import TigrblSessionBase
+from tigrbl_core._spec.session_spec import SessionSpec
+
+__all__ = ["SessionSpec", "TigrblSessionBase"]

tigrbl-0.4.0.dev2/tigrbl/session/base.py

@@ -0,0 +1,7 @@
+"""Compatibility module for ``tigrbl.session.base``."""
+
+from __future__ import annotations
+
+from tigrbl_base._base import TigrblSessionBase
+
+__all__ = ["TigrblSessionBase"]

tigrbl-0.4.0.dev2/tigrbl/session/spec.py

@@ -0,0 +1,7 @@
+"""Compatibility module for ``tigrbl.session.spec``."""
+
+from __future__ import annotations
+
+from tigrbl_core._spec.session_spec import SessionSpec
+
+__all__ = ["SessionSpec"]

{tigrbl-0.3.29.dev2 → tigrbl-0.4.0.dev2}/tigrbl/system/diagnostics/__init__.py

@@ -1,5 +1,9 @@
 from ...runtime.kernel import _default_kernel, build_phase_chains
 from .router import mount_diagnostics
+from .healthz import build_healthz_endpoint, build_healthz_html, mount_healthz_uix
+from .methodz import build_methodz_endpoint
+from .hookz import build_hookz_endpoint
+from .kernelz import build_kernelz_endpoint
 from .methodz import build_methodz_endpoint as _build_methodz_endpoint
 from .hookz import build_hookz_endpoint as _build_hookz_endpoint
 from .kernelz import build_kernelz_endpoint as _build_kernelz_endpoint
@@ -13,6 +17,12 @@ from .utils import (
 
 __all__ = [
     "mount_diagnostics",
+    "build_healthz_endpoint",
+    "build_healthz_html",
+    "mount_healthz_uix",
+    "build_methodz_endpoint",
+    "build_hookz_endpoint",
+    "build_kernelz_endpoint",
     "_build_methodz_endpoint",
     "_build_hookz_endpoint",
     "_build_kernelz_endpoint",

tigrbl-0.4.0.dev2/tigrbl/system/diagnostics/healthz.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Iterable, Mapping
+from typing import Any, Callable, Optional
+
+from ... import Depends, Request
+from ..._concrete import JSONResponse
+from ..._concrete._response import Response
+from .utils import maybe_execute
+
+logger = logging.getLogger(__name__)
+
+_NO_DB_WARNING = "db-not-configured"
+_UNAVAILABLE_WARNING = "db-unavailable"
+
+
+def _resolve_db(candidate: Any) -> Any:
+    """Resolve a DB-like object from either a DB handle or a Request object."""
+    if hasattr(candidate, "execute"):
+        return candidate
+
+    state = getattr(candidate, "state", None)
+    db = getattr(state, "db", None)
+    if db is not None:
+        return db
+    return None
+
+
+def _has_execute(candidate: Any) -> bool:
+    return callable(getattr(candidate, "execute", None))
+
+
+def _query_value(request: Any, name: str, default: str | None = None) -> str | None:
+    getter = getattr(request, "query_param", None)
+    if callable(getter):
+        return getter(name, default)
+    query = getattr(request, "query", None) or {}
+    values = query.get(name)
+    if isinstance(values, (list, tuple)) and values:
+        return str(values[0])
+    if values is not None:
+        return str(values)
+    return default
+
+
+def _query_flag(request: Any, name: str) -> bool:
+    value = _query_value(request, name)
+    if value is None:
+        return False
+    return str(value).strip().lower() in {"1", "true", "yes", "on", "warn"}
+
+
+def _wants_all_dbs(request: Any) -> bool:
+    value = _query_value(request, "dbs") or _query_value(request, "detail")
+    return str(value or "").strip().lower() in {"all", "full", "verbose"}
+
+
+def _iter_db_entries(candidate: Any) -> list[tuple[str, Any]]:
+    if candidate is None:
+        return []
+    if _has_execute(candidate):
+        return [("default", candidate)]
+    if isinstance(candidate, Mapping):
+        return [
+            (str(name), db)
+            for name, db in candidate.items()
+            if _has_execute(db)
+        ]
+    if isinstance(candidate, Iterable) and not isinstance(
+        candidate, (str, bytes, bytearray)
+    ):
+        return [
+            (str(index), db)
+            for index, db in enumerate(candidate)
+            if _has_execute(db)
+        ]
+    return []
+
+
+def _resolve_db_entries(candidate: Any, *sources: Any) -> list[tuple[str, Any]]:
+    entries = _iter_db_entries(candidate)
+    if entries:
+        return entries
+
+    state = getattr(candidate, "state", None)
+    app = getattr(candidate, "app", None)
+    for source in (state, app, *sources):
+        if source is None:
+            continue
+        for attr in ("dbs", "databases", "engines", "db"):
+            entries = _iter_db_entries(getattr(source, attr, None))
+            if entries:
+                return entries
+    return []
+
+
+async def _check_db(name: str, db: Any) -> dict[str, Any]:
+    try:
+        await maybe_execute(db, "SELECT 1")
+        return {"name": name, "ok": True}
+    except Exception as exc:  # pragma: no cover - covered by fixture fakes
+        logger.warning("/healthz degraded for %s: %s", name, exc)
+        return {
+            "name": name,
+            "ok": False,
+            "warning": _UNAVAILABLE_WARNING,
+            "error": str(exc),
+        }
+
+
+def _multi_db_payload(results: list[dict[str, Any]], *, include_all: bool) -> dict[str, Any]:
+    total = len(results)
+    healthy = sum(1 for item in results if item["ok"])
+    payload: dict[str, Any] = {
+        "ok": healthy == total,
+        "dbs": {
+            "ok": healthy,
+            "total": total,
+            "failed": total - healthy,
+        },
+    }
+    if healthy != total:
+        payload["warning"] = _UNAVAILABLE_WARNING
+    if include_all:
+        payload["databases"] = results
+    return payload
+
+
+def build_healthz_endpoint(
+    dep: Optional[Callable[..., Any]],
+    *,
+    router: Any | None = None,
+    warn_no_db: bool = False,
+):
+    """
+    Returns a ASGI endpoint function for /healthz.
+    If `dep` is provided, it's used as a dependency to supply `db`.
+    Otherwise, we try request.state.db.
+    """
+    if dep is not None:
+
+        async def _healthz(db: Any = Depends(dep)):
+            if hasattr(db, "dependency") and callable(getattr(db, "dependency", None)):
+                resolved = db.dependency()
+                if inspect.isawaitable(resolved):
+                    resolved = await resolved
+                db = resolved
+            entries = _resolve_db_entries(db, router)
+            if not entries:
+                if warn_no_db:
+                    return {"ok": True, "warning": _NO_DB_WARNING}
+                return {"ok": True}
+            if len(entries) == 1:
+                result = await _check_db(*entries[0])
+                if result["ok"]:
+                    return {"ok": True}
+                return JSONResponse(
+                    {
+                        "ok": False,
+                        "warning": result["warning"],
+                        "error": result["error"],
+                    },
+                    status_code=200,
+                )
+            results = [await _check_db(name, db) for name, db in entries]
+            return _multi_db_payload(results, include_all=False)
+
+        return _healthz
+
+    async def _healthz(request: Request):
+        entries = _resolve_db_entries(request, router)
+        if not entries:
+            if warn_no_db or _query_flag(request, "warn_no_db"):
+                return {"ok": True, "warning": _NO_DB_WARNING}
+            return {"ok": True}
+        if len(entries) == 1:
+            result = await _check_db(*entries[0])
+            if result["ok"]:
+                return {"ok": True}
+            return JSONResponse(
+                {
+                    "ok": False,
+                    "warning": result["warning"],
+                    "error": result["error"],
+                },
+                status_code=200,
+            )
+        results = [await _check_db(name, db) for name, db in entries]
+        return _multi_db_payload(results, include_all=_wants_all_dbs(request))
+
+    return _healthz
+
+
+def _with_leading_slash(path: str) -> str:
+    return path if path.startswith("/") else f"/{path}"
+
+
+def build_healthz_html(router: Any, request: Any, *, healthz_path: str | None = None) -> str:
+    """Return a small operator-facing HTML page for the JSON health endpoint."""
+
+    base = (getattr(request, "script_name", "") or "").rstrip("/")
+    configured = healthz_path or f"{getattr(router, 'system_prefix', '/system')}/healthz"
+    payload_url = f"{base}{_with_leading_slash(configured)}"
+    title = getattr(router, "title", "API")
+    return f"""<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title} health</title>
+    <style>
+      body {{
+        margin: 0;
+        min-height: 100vh;
+        font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        color: #111827;
+        background: #f8fafc;
+      }}
+      main {{
+        width: min(720px, calc(100% - 32px));
+        margin: 0 auto;
+        padding: 48px 0;
+      }}
+      h1 {{
+        font-size: 24px;
+        font-weight: 650;
+        margin: 0 0 16px;
+      }}
+      pre {{
+        overflow: auto;
+        padding: 16px;
+        background: #111827;
+        color: #e5e7eb;
+        border-radius: 6px;
+      }}
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Health</h1>
+      <pre id="payload">Loading {payload_url}</pre>
+    </main>
+    <script>
+      const payload = document.getElementById("payload");
+      fetch("{payload_url}", {{ headers: {{ "accept": "application/json" }} }})
+        .then((response) => response.json())
+        .then((data) => {{
+          payload.textContent = JSON.stringify(data, null, 2);
+          payload.dataset.ok = String(data.ok === true);
+        }})
+        .catch((error) => {{
+          payload.textContent = JSON.stringify({{ ok: false, error: String(error) }}, null, 2);
+          payload.dataset.ok = "false";
+        }});
+    </script>
+  </body>
+</html>
+"""
+
+
+def mount_healthz_uix(
+    router: Any,
+    *,
+    path: str = "/healthz",
+    name: str = "__healthz_uix__",
+    healthz_path: str | None = None,
+) -> Any:
+    """Mount a human-viewable health page that reads the JSON health endpoint."""
+
+    def _healthz_uix_handler(request: Any) -> Response:
+        return Response.html(
+            build_healthz_html(router, request, healthz_path=healthz_path)
+        )
+
+    router.add_route(
+        path,
+        _healthz_uix_handler,
+        methods=["GET"],
+        name=name,
+        include_in_schema=False,
+        inherit_owner_dependencies=False,
+    )
+    return router

{tigrbl-0.3.29.dev2 → tigrbl-0.4.0.dev2}/tigrbl/types/__init__.py

@@ -8,16 +8,6 @@ from tigrbl_concrete.decorators import allow_anon
 from tigrbl_typing import types as _typing_types
 from tigrbl_typing.types import __all__ as _typing_all
 
-_DEPRECATED_NAMES = {
-    "Router": "tigrbl",
-    "Request": "tigrbl",
-    "Body": "tigrbl.core.crud",
-    "Depends": "tigrbl.security",
-    "HTTPException": "tigrbl.runtime.status",
-    "Response": "tigrbl",
-}
-
-
 for _name in _typing_all:
     globals()[_name] = getattr(_typing_types, _name)
 
@@ -26,11 +16,5 @@ __all__ = [*_typing_all, "F", "IO", "S", "acol", "allow_anon"]
 
 
 def __getattr__(name: str):
-    if name in _DEPRECATED_NAMES:
-        module = _DEPRECATED_NAMES[name]
-        raise AttributeError(
-            f"tigrbl.types no longer exports '{name}'. "
-            f"Import it from '{module}' instead."
-        )
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 

tigrbl-0.3.29.dev2/tigrbl/system/diagnostics/healthz.py

@@ -1,69 +0,0 @@
-from __future__ import annotations
-
-import inspect
-import logging
-from typing import Any, Callable, Optional
-
-from ... import Depends, Request
-from ..._concrete import JSONResponse
-from .utils import maybe_execute
-
-logger = logging.getLogger(__name__)
-
-
-def _resolve_db(candidate: Any) -> Any:
-    """Resolve a DB-like object from either a DB handle or a Request object."""
-    if hasattr(candidate, "execute"):
-        return candidate
-
-    state = getattr(candidate, "state", None)
-    db = getattr(state, "db", None)
-    if db is not None:
-        return db
-    return None
-
-
-def build_healthz_endpoint(dep: Optional[Callable[..., Any]]):
-    """
-    Returns a ASGI endpoint function for /healthz.
-    If `dep` is provided, it's used as a dependency to supply `db`.
-    Otherwise, we try request.state.db.
-    """
-    if dep is not None:
-
-        async def _healthz(db: Any = Depends(dep)):
-            if hasattr(db, "dependency") and callable(getattr(db, "dependency", None)):
-                resolved = db.dependency()
-                if inspect.isawaitable(resolved):
-                    resolved = await resolved
-                db = resolved
-            db = _resolve_db(db)
-            if db is None:
-                return {"ok": True, "warning": "no-db"}
-            try:
-                await maybe_execute(db, "SELECT 1")
-                return {"ok": True}
-            except Exception as e:  # pragma: no cover
-                logger.warning("/healthz degraded: %s", e)
-                return JSONResponse(
-                    {"ok": False, "warning": "db-unavailable", "error": str(e)},
-                    status_code=200,
-                )
-
-        return _healthz
-
-    async def _healthz(request: Request):
-        db = _resolve_db(request)
-        if db is None:
-            return {"ok": True, "warning": "no-db"}
-        try:
-            await maybe_execute(db, "SELECT 1")
-            return {"ok": True}
-        except Exception as e:  # pragma: no cover
-            logger.warning("/healthz degraded: %s", e)
-            return JSONResponse(
-                {"ok": False, "warning": "db-unavailable", "error": str(e)},
-                status_code=200,
-            )
-
-    return _healthz