tigrbl 0.0.1.dev1__py3-none-any.whl → 0.3.0.dev3__py3-none-any.whl

tigrbl/schema/decorators.py

@@ -0,0 +1,68 @@
+# tigrbl/v3/schema/decorators.py
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from ..config.constants import TIGRBL_SCHEMA_DECLS_ATTR
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+
+
+@dataclass(frozen=True)
+class _SchemaDecl:
+    alias: str  # name under model.schemas.<alias>
+    kind: str  # "in" | "out"
+
+
+def _register_schema_decl(
+    target_model: type, alias: str, kind: str, schema_cls: type
+) -> None:
+    """Store schema declarations on the model for later binding."""
+    logger.debug(
+        "Registering schema decl for %s alias=%s kind=%s",
+        target_model.__name__,
+        alias,
+        kind,
+    )
+    if kind not in ("in", "out"):
+        logger.debug("Invalid kind '%s' for schema decl", kind)
+        raise ValueError("schema_ctx(kind=...) must be 'in' or 'out'")
+    mapping: Dict[str, Dict[str, type]] = (
+        getattr(target_model, TIGRBL_SCHEMA_DECLS_ATTR, None) or {}
+    )
+    bucket = dict(mapping.get(alias, {}))
+    bucket[kind] = schema_cls
+    mapping[alias] = bucket
+    setattr(target_model, TIGRBL_SCHEMA_DECLS_ATTR, mapping)
+    logger.debug("Registered schema %s for alias '%s'", schema_cls, alias)
+
+
+def schema_ctx(*, alias: str, kind: str = "out", for_: Optional[type] = None):
+    """Register a named schema for a model."""
+
+    def deco(schema_cls: type):
+        if not isinstance(schema_cls, type):
+            logger.debug("schema_ctx applied to non-class %r", schema_cls)
+            raise TypeError("@schema_ctx must decorate a class")
+        if for_ is not None:
+            logger.debug(
+                "Registering schema %s for model %s via decorator",
+                schema_cls,
+                for_.__name__,
+            )
+            _register_schema_decl(for_, alias, kind, schema_cls)
+        setattr(
+            schema_cls, "__tigrbl_schema_decl__", _SchemaDecl(alias=alias, kind=kind)
+        )
+        logger.debug(
+            "Attached schema decl to %s: alias=%s kind=%s", schema_cls, alias, kind
+        )
+        return schema_cls
+
+    return deco
+
+
+__all__ = ["schema_ctx"]

tigrbl/schema/get_schema.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import logging
+from typing import Literal, Optional, Type
+
+from pydantic import BaseModel
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+
+
+def get_schema(
+    orm_cls: type,
+    op: str,
+    *,
+    kind: Literal["in", "out"] = "out",
+) -> Optional[Type[BaseModel]]:
+    """Return the bound schema for ``orm_cls``.
+
+    Parameters
+    ----------
+    orm_cls:
+        ORM model that has been bound via :func:`tigrbl.bindings.build_schemas`.
+    op:
+        Operation alias whose schema should be returned.
+    kind:
+        Either ``"in"`` for request schemas or ``"out"`` for response schemas.
+
+    Returns
+    -------
+    Optional[Type[BaseModel]]
+        The requested schema class if available, otherwise ``None`` when the
+        operation uses raw payloads.
+
+    Raises
+    ------
+    KeyError
+        If the model has not been bound or the operation/kind is unknown.
+    """
+    logger.debug(
+        "Resolving schema for model=%s op=%s kind=%s", orm_cls.__name__, op, kind
+    )
+
+    ns = getattr(orm_cls, "schemas", None)
+    if ns is None:
+        logger.debug("Model %s has no schemas namespace", orm_cls.__name__)
+        raise KeyError(
+            f"{orm_cls.__name__} has no bound schemas; did you include the model?",
+        )
+    logger.debug("Found schemas namespace for model %s", orm_cls.__name__)
+
+    alias_ns = getattr(ns, op, None)
+    if alias_ns is None:
+        logger.debug("Unknown operation '%s' for model %s", op, orm_cls.__name__)
+        raise KeyError(f"Unknown op '{op}' for {orm_cls.__name__}")
+    logger.debug("Found operation '%s' for model %s", op, orm_cls.__name__)
+
+    kind = kind.lower()
+    if kind not in {"in", "out"}:
+        logger.debug("Invalid schema kind '%s' requested", kind)
+        raise ValueError("kind must be 'in' or 'out'")
+    logger.debug("Using schema kind '%s'", kind)
+
+    attr = "in_" if kind == "in" else "out"
+    if not hasattr(alias_ns, attr):
+        logger.debug(
+            "Schema kind '%s' not found for op '%s' on %s", kind, op, orm_cls.__name__
+        )
+        raise KeyError(
+            f"Schema kind '{kind}' not found for op '{op}' on {orm_cls.__name__}",
+        )
+    logger.debug(
+        "Found schema attribute '%s' for op '%s' on %s", attr, op, orm_cls.__name__
+    )
+    schema = getattr(alias_ns, attr)
+    logger.debug(
+        "Resolved schema %s for model %s op=%s kind=%s",
+        schema,
+        orm_cls.__name__,
+        op,
+        kind,
+    )
+    return schema
+
+
+__all__ = ["get_schema"]

tigrbl/schema/schema_spec.py

@@ -0,0 +1,20 @@
+# tigrbl/v3/schema/schema_spec.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .types import SchemaArg, SchemaKind
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaSpec:
+    """Declarative description of a schema for a model."""
+
+    alias: str
+    kind: SchemaKind = "out"
+    for_: Optional[type] = None
+    schema: SchemaArg | None = None
+
+
+__all__ = ["SchemaSpec"]

tigrbl/schema/shortcuts.py

@@ -0,0 +1,42 @@
+# tigrbl/v3/schema/shortcuts.py
+from __future__ import annotations
+
+from typing import Optional, Type
+
+try:  # pragma: no cover
+    from pydantic import BaseModel  # type: ignore
+except Exception:  # pragma: no cover
+
+    class BaseModel:  # minimal stub for typing only
+        pass
+
+
+from ._schema import Schema
+from .schema_spec import SchemaSpec
+from .types import SchemaArg, SchemaKind
+
+
+def schema_spec(
+    alias: str,
+    *,
+    kind: SchemaKind = "out",
+    for_: Optional[type] = None,
+    schema: SchemaArg | None = None,
+) -> SchemaSpec:
+    """Factory for :class:`SchemaSpec`."""
+
+    return SchemaSpec(alias=alias, kind=kind, for_=for_, schema=schema)
+
+
+def schema(
+    model: Type[BaseModel],
+    *,
+    kind: SchemaKind = "out",
+    alias: str | None = None,
+) -> Schema:
+    """Factory for :class:`Schema`."""
+
+    return Schema(model=model, kind=kind, alias=alias)
+
+
+__all__ = ["schema_spec", "schema"]

tigrbl/schema/types.py

@@ -0,0 +1,34 @@
+# tigrbl/v3/schema/types.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Type, Union, Literal
+
+try:  # pragma: no cover
+    from pydantic import BaseModel  # type: ignore
+except Exception:  # pragma: no cover
+
+    class BaseModel:  # minimal stub for typing only
+        pass
+
+
+SchemaKind = Literal["in", "out"]
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaRef:
+    """Lazy reference to ``model.schemas.<alias>.(in_|out)``."""
+
+    alias: str
+    kind: SchemaKind = "in"
+
+
+SchemaArg = Union[
+    Type[BaseModel],  # direct Pydantic model
+    SchemaRef,  # cross-op reference
+    str,  # "alias.in" | "alias.out"
+    Callable[[type], Type[BaseModel]],  # lambda cls: cls.schemas.create.in_
+]
+
+
+__all__ = ["SchemaKind", "SchemaRef", "SchemaArg"]

tigrbl/schema/utils.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Type
+
+from pydantic import BaseModel, ConfigDict, Field, RootModel, create_model
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+
+
+def namely_model(model: Type[BaseModel], *, name: str, doc: str) -> Type[BaseModel]:
+    """Assign a unique name and docstring to a Pydantic model class."""
+    logger.debug("Renaming model %s to %s", model.__name__, name)
+    model.__name__ = name
+    model.__qualname__ = name
+    model.__doc__ = doc
+
+    # Rebuild the model so Pydantic updates internal references (e.g., for OpenAPI titles).
+
+    model.model_rebuild(force=True)
+    logger.debug("Model %s rebuilt", name)
+    return model
+
+
+def _camel(s: str) -> str:
+    rv = "".join(p.capitalize() or "_" for p in s.split("_"))
+    logger.debug("Camel-cased '%s' → '%s'", s, rv)
+    return rv
+
+
+def _extract_example(schema: Type[BaseModel]) -> Dict[str, Any]:
+    """Build a simple example object from field examples if available."""
+    try:
+        js = schema.model_json_schema()
+    except Exception as exc:
+        logger.debug("Failed to build JSON schema for %s: %s", schema, exc)
+        return {}
+    out: Dict[str, Any] = {}
+    for name, prop in (js.get("properties") or {}).items():
+        examples = prop.get("examples")
+        if examples:
+            out[name] = examples[0]
+    logger.debug("Extracted example for %s: %s", schema, out)
+    return out
+
+
+def _make_bulk_rows_model(
+    model: type, verb: str, item_schema: Type[BaseModel]
+) -> Type[BaseModel]:
+    """Build a root model representing ``List[item_schema]``."""
+    name = f"{model.__name__}{_camel(verb)}Request"
+    example = _extract_example(item_schema)
+    examples = [[example]] if example else []
+
+    class _BulkModel(RootModel[List[item_schema]]):  # type: ignore[misc]
+        model_config = ConfigDict(json_schema_extra={"examples": examples})
+
+    logger.debug("Built bulk rows model %s with examples=%s", name, examples)
+    return namely_model(
+        _BulkModel,
+        name=name,
+        doc=f"{verb} request schema for {model.__name__}",
+    )
+
+
+def _make_bulk_rows_response_model(
+    model: type, verb: str, item_schema: Type[BaseModel]
+) -> Type[BaseModel]:
+    """Build a root model representing ``List[item_schema]`` for responses."""
+    name = f"{model.__name__}{_camel(verb)}Response"
+    example = _extract_example(item_schema)
+    examples = [[example]] if example else []
+
+    class _BulkModel(RootModel[List[item_schema]]):  # type: ignore[misc]
+        model_config = ConfigDict(json_schema_extra={"examples": examples})
+
+    logger.debug("Built bulk rows response model %s with examples=%s", name, examples)
+    return namely_model(
+        _BulkModel,
+        name=name,
+        doc=f"{verb} response schema for {model.__name__}",
+    )
+
+
+def _make_bulk_ids_model(
+    model: type, verb: str, pk_type: type | Any
+) -> Type[BaseModel]:
+    """Build a wrapper schema with an ``ids: List[pk_type]`` field."""
+    name = f"{model.__name__}{_camel(verb)}Request"
+    schema = create_model(  # type: ignore[call-arg]
+        name,
+        ids=(List[pk_type], Field(...)),  # type: ignore[name-defined]
+    )
+    logger.debug("Built bulk ids model %s", name)
+    return namely_model(
+        schema,
+        name=name,
+        doc=f"{verb} request schema for {model.__name__}",
+    )
+
+
+def _make_deleted_response_model(model: type, verb: str) -> Type[BaseModel]:
+    """Build a response schema with a ``deleted`` count."""
+    name = f"{model.__name__}{_camel(verb)}Response"
+    schema = create_model(  # type: ignore[call-arg]
+        name,
+        deleted=(int, Field(..., examples=[0])),
+        __config__=ConfigDict(json_schema_extra={"examples": [{"deleted": 0}]}),
+    )
+    logger.debug("Built deleted response model %s", name)
+    return namely_model(
+        schema,
+        name=name,
+        doc=f"{verb} response schema for {model.__name__}",
+    )
+
+
+def _make_pk_model(
+    model: type, verb: str, pk_name: str, pk_type: type | Any
+) -> Type[BaseModel]:
+    """Build a wrapper schema with a single primary-key field."""
+    name = f"{model.__name__}{_camel(verb)}Request"
+    schema = create_model(  # type: ignore[call-arg]
+        name,
+        **{pk_name: (pk_type, Field(...))},  # type: ignore[name-defined]
+    )
+    logger.debug("Built pk model %s for field %s", name, pk_name)
+    return namely_model(
+        schema,
+        name=name,
+        doc=f"{verb} request schema for {model.__name__}",
+    )
+
+
+__all__ = [
+    "namely_model",
+    "_make_bulk_rows_model",
+    "_make_bulk_rows_response_model",
+    "_make_bulk_ids_model",
+    "_make_deleted_response_model",
+    "_make_pk_model",
+]

tigrbl/shortcuts.py

@@ -0,0 +1,22 @@
+# tigrbl/tigrbl/v3/shortcuts.py
+from __future__ import annotations
+
+from .app import shortcuts as app_shortcuts
+from .api import shortcuts as api_shortcuts
+from .engine import shortcuts as engine_shortcuts
+from .specs import shortcuts as specs_shortcuts
+from .table import shortcuts as table_shortcuts
+
+from .app.shortcuts import *  # noqa: F401,F403
+from .api.shortcuts import *  # noqa: F401,F403
+from .engine.shortcuts import *  # noqa: F401,F403
+from .specs.shortcuts import *  # noqa: F401,F403
+from .table.shortcuts import *  # noqa: F401,F403
+
+__all__ = [
+    *app_shortcuts.__all__,
+    *api_shortcuts.__all__,
+    *engine_shortcuts.__all__,
+    *specs_shortcuts.__all__,
+    *table_shortcuts.__all__,
+]

tigrbl/specs.py

@@ -0,0 +1,44 @@
+# tigrbl/v3/specs.py
+"""Compatibility layer that re-exports column specs.
+
+Importing from ``tigrbl.specs`` remains supported but the
+implementation now lives under :mod:`tigrbl.column`.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .column import *  # noqa: F401,F403
+from .column import (
+    __all__ as _all,
+    column_spec as _column_spec,
+    field_spec as _field_spec,
+    infer as _infer,
+    io_spec as _io_spec,
+    shortcuts as _shortcuts,
+    storage_spec as _storage_spec,
+)
+
+__all__ = list(_all)
+
+# Allow submodule imports like ``tigrbl.specs.storage_spec``
+__path__: list[str] = []
+_mod = sys.modules[__name__]
+_mod.column_spec = _column_spec
+_mod.field_spec = _field_spec
+_mod.infer = _infer
+_mod.io_spec = _io_spec
+_mod.shortcuts = _shortcuts
+_mod.storage_spec = _storage_spec
+
+sys.modules[f"{__name__}.column_spec"] = _column_spec
+sys.modules[f"{__name__}.field_spec"] = _field_spec
+sys.modules[f"{__name__}.infer"] = _infer
+sys.modules[f"{__name__}.io_spec"] = _io_spec
+sys.modules[f"{__name__}.shortcuts"] = _shortcuts
+sys.modules[f"{__name__}.storage_spec"] = _storage_spec
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

tigrbl/system/__init__.py

@@ -0,0 +1,12 @@
+# tigrbl/v3/system/__init__.py
+"""
+Tigrbl v3 – System/Diagnostics helpers.
+
+- mount_diagnostics(api, *, get_db=None) -> Router
+"""
+
+from __future__ import annotations
+
+from .diagnostics import mount_diagnostics
+
+__all__ = ["mount_diagnostics"]

tigrbl/system/diagnostics/__init__.py

@@ -0,0 +1,24 @@
+from ...runtime.kernel import _default_kernel, build_phase_chains
+from .router import mount_diagnostics
+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
+from .utils import (
+    model_iter as _model_iter,
+    opspecs as _opspecs,
+    label_callable as _label_callable,
+    label_hook as _label_hook,
+)
+
+__all__ = [
+    "mount_diagnostics",
+    "_build_methodz_endpoint",
+    "_build_hookz_endpoint",
+    "_build_kernelz_endpoint",
+    "_model_iter",
+    "_opspecs",
+    "_label_callable",
+    "_label_hook",
+    "build_phase_chains",
+    "_default_kernel",
+]

tigrbl/system/diagnostics/compat.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Sequence
+from types import SimpleNamespace
+
+try:
+    from ...types import Router, Request, Depends
+    from fastapi.responses import JSONResponse
+except Exception:  # pragma: no cover
+
+    class Router:  # type: ignore
+        def __init__(self, *a, **kw):
+            self.routes = []
+
+        def add_api_route(
+            self, path: str, endpoint: Callable, methods: Sequence[str], **opts
+        ):
+            self.routes.append((path, methods, endpoint, opts))
+
+    class Request:  # type: ignore
+        def __init__(self, scope=None):
+            self.scope = scope or {}
+            self.state = SimpleNamespace()
+            self.query_params = {}
+
+    class JSONResponse(dict):  # type: ignore
+        def __init__(self, content: Any, status_code: int = 200):
+            super().__init__(content=content, status_code=status_code)
+
+    def Depends(fn: Callable[..., Any]):  # type: ignore
+        return fn

tigrbl/system/diagnostics/healthz.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional
+
+from .compat import Depends, JSONResponse, Request
+from .utils import maybe_execute
+
+logger = logging.getLogger(__name__)
+
+
+def build_healthz_endpoint(dep: Optional[Callable[..., Any]]):
+    """
+    Returns a FastAPI 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)):
+            try:
+                await maybe_execute(db, "SELECT 1")
+                return {"ok": True}
+            except Exception as e:  # pragma: no cover
+                logger.exception("/healthz failed")
+                return JSONResponse({"ok": False, "error": str(e)}, status_code=500)
+
+        return _healthz
+
+    async def _healthz(request: Request):
+        db = getattr(request.state, "db", None)
+        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.exception("/healthz failed")
+            return JSONResponse({"ok": False, "error": str(e)}, status_code=500)
+
+    return _healthz

tigrbl/system/diagnostics/hookz.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from types import SimpleNamespace
+
+from ...op.types import PHASES
+
+
+def build_hookz_endpoint(api: Any):
+    cache: Optional[Dict[str, Dict[str, Dict[str, List[str]]]]] = None
+
+    async def _hookz():
+        nonlocal cache
+        """
+        Expose hook execution order for each method.
+
+        Phases appear in runner order; error phases trail.
+        Within each phase, hooks are listed in execution order: global (None) hooks,
+        then method-specific hooks.
+        """
+        if cache is not None:
+            return cache
+
+        from . import _model_iter, _opspecs, _label_callable
+
+        out: Dict[str, Dict[str, Dict[str, List[str]]]] = {}
+        for model in _model_iter(api):
+            mname = getattr(model, "__name__", "Model")
+            hooks_root = getattr(model, "hooks", SimpleNamespace())
+            alias_sources = set()
+            rpc_ns = getattr(model, "rpc", SimpleNamespace())
+            alias_sources.update(getattr(rpc_ns, "__dict__", {}).keys())
+            for sp in _opspecs(model):
+                alias_sources.add(sp.alias)
+
+            model_map: Dict[str, Dict[str, List[str]]] = {}
+            for alias in sorted(alias_sources):
+                alias_ns = getattr(hooks_root, alias, None) or SimpleNamespace()
+                phase_map: Dict[str, List[str]] = {}
+                for ph in PHASES:
+                    steps = list(getattr(alias_ns, ph, []) or [])
+                    if steps:
+                        phase_map[ph] = [_label_callable(fn) for fn in steps]
+                if phase_map:
+                    model_map[alias] = phase_map
+            if model_map:
+                out[mname] = model_map
+        cache = out
+        return cache
+
+    return _hookz

tigrbl/system/diagnostics/kernelz.py

@@ -0,0 +1,20 @@
+"""Diagnostic endpoint exposing kernel phase plans."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...runtime.kernel import _default_kernel as K
+
+
+def build_kernelz_endpoint(api: Any):
+    """Return an async handler that serves the Kernel's cached plan."""
+
+    async def _kernelz():
+        K.ensure_primed(api)
+        return K.kernelz_payload(api)
+
+    return _kernelz
+
+
+__all__ = ["build_kernelz_endpoint"]