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

tigrbl/system/diagnostics/router.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from .compat import Router
+from .healthz import build_healthz_endpoint
+from .methodz import build_methodz_endpoint
+from .hookz import build_hookz_endpoint
+from .kernelz import build_kernelz_endpoint
+
+
+def mount_diagnostics(
+    api: Any,
+    *,
+    get_db: Optional[Callable[..., Any]] = None,
+) -> Router:
+    """
+    Create & return a Router that exposes:
+      GET /healthz
+      GET /methodz
+      GET /hookz
+      GET /kernelz
+    """
+    router = Router()
+
+    dep = get_db
+
+    router.add_api_route(
+        "/healthz",
+        build_healthz_endpoint(dep),
+        methods=["GET"],
+        name="healthz",
+        tags=["system"],
+        summary="Health",
+        description="Database connectivity check.",
+    )
+    router.add_api_route(
+        "/methodz",
+        build_methodz_endpoint(api),
+        methods=["GET"],
+        name="methodz",
+        tags=["system"],
+        summary="Methods",
+        description="Ordered, canonical operation list.",
+    )
+    router.add_api_route(
+        "/hookz",
+        build_hookz_endpoint(api),
+        methods=["GET"],
+        name="hookz",
+        tags=["system"],
+        summary="Hooks",
+        description=(
+            "Expose hook execution order for each method.\n\n"
+            "Phases appear in runner order; error phases trail.\n"
+            "Within each phase, hooks are listed in execution order: "
+            "global (None) hooks, then method-specific hooks."
+        ),
+    )
+    router.add_api_route(
+        "/kernelz",
+        build_kernelz_endpoint(api),
+        methods=["GET"],
+        name="kernelz",
+        tags=["system"],
+        summary="Kernel Plan",
+        description="Phase-chain plan as built by the kernel per operation.",
+    )
+
+    return router
+
+
+__all__ = ["mount_diagnostics"]

tigrbl/system/diagnostics/utils.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import inspect
+from types import SimpleNamespace
+from typing import Any, Iterable
+
+from sqlalchemy import text
+
+
+def model_iter(api: Any) -> Iterable[type]:
+    models = getattr(api, "models", {}) or {}
+    return models.values()
+
+
+def opspecs(model: type):
+    return getattr(getattr(model, "opspecs", SimpleNamespace()), "all", ()) or ()
+
+
+def label_callable(fn: Any) -> str:
+    n = getattr(fn, "__qualname__", getattr(fn, "__name__", repr(fn)))
+    m = getattr(fn, "__module__", None)
+    return f"{m}.{n}" if m else n
+
+
+def label_hook(fn: Any, phase: str) -> str:
+    label = getattr(fn, "__tigrbl_label", None)
+    if isinstance(label, str):
+        return label
+    subj = label_callable(fn).replace(".", ":")
+    return f"hook:wire:{subj}@{phase}"
+
+
+async def maybe_execute(db: Any, stmt: str):
+    try:
+        rv = db.execute(text(stmt))  # type: ignore[attr-defined]
+        if inspect.isawaitable(rv):
+            return await rv
+        return rv
+    except Exception:
+        rv = db.execute(text("select 1"))  # type: ignore[attr-defined]
+        if inspect.isawaitable(rv):
+            return await rv
+        return rv

tigrbl/system/uvicorn.py

@@ -0,0 +1,60 @@
+"""Utilities for running uvicorn during tests or tooling."""
+
+from __future__ import annotations
+
+import asyncio
+
+import uvicorn
+
+
+async def _cancel_task(task: asyncio.Task) -> None:
+    if task.done():
+        return
+    task.cancel()
+    try:
+        await task
+    except asyncio.CancelledError:
+        return
+
+
+async def _close_servers(server: uvicorn.Server) -> None:
+    servers = []
+    primary = getattr(server, "server", None)
+    if primary is not None:
+        servers.append(primary)
+    extra = getattr(server, "servers", None)
+    if extra:
+        servers.extend(extra)
+    for srv in servers:
+        close = getattr(srv, "close", None)
+        if callable(close):
+            close()
+        wait_closed = getattr(srv, "wait_closed", None)
+        if callable(wait_closed):
+            await wait_closed()
+
+
+async def stop_uvicorn_server(
+    server: uvicorn.Server,
+    task: asyncio.Task,
+    *,
+    timeout: float = 5.0,
+) -> None:
+    """Request uvicorn shutdown and ensure the task exits."""
+    if task.done():
+        return
+
+    server.should_exit = True
+    try:
+        await asyncio.wait_for(task, timeout=timeout)
+        return
+    except asyncio.TimeoutError:
+        server.force_exit = True
+        shutdown = getattr(server, "shutdown", None)
+        if callable(shutdown):
+            try:
+                await asyncio.wait_for(shutdown(), timeout=timeout)
+            except asyncio.TimeoutError:
+                pass
+        await _close_servers(server)
+        await _cancel_task(task)

tigrbl/table/__init__.py

@@ -0,0 +1,9 @@
+"""Table module exposing Base and Table."""
+
+from __future__ import annotations
+
+from ._base import Base
+from ._table import Table
+from .table_spec import TableSpec
+
+__all__ = ["Base", "Table", "TableSpec"]

tigrbl/table/_base.py

@@ -0,0 +1,260 @@
+# tigrbl/tigrbl/v3/table/_base.py
+from __future__ import annotations
+
+from typing import Any, Optional, Union, get_args, get_origin
+from enum import Enum as PyEnum
+
+from sqlalchemy.orm import DeclarativeBase, declared_attr, mapped_column
+from sqlalchemy import CheckConstraint, ForeignKey, MetaData
+from sqlalchemy.types import Enum as SAEnum, String
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Helpers – type inference & SA type instantiation
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _unwrap_optional(t: Any) -> Any:
+    """Optional[T] / Union[T, None]  →  T"""
+    if get_origin(t) is Union:
+        args = [a for a in get_args(t) if a is not type(None)]
+        return args[0] if args else t
+    return t
+
+
+def _infer_py_type(cls, name: str, spec: Any) -> Optional[type]:
+    """
+    Prefer FieldSpec.py_type if provided; otherwise unwrap Mapped[...] / Optional[...]
+    from the class' annotation to get the real Python type for the column.
+    """
+    fld = getattr(spec, "field", None)
+    py = getattr(fld, "py_type", None)
+    if isinstance(py, type):
+        return py
+
+    ann = getattr(cls, "__annotations__", {}).get(name)
+    if ann is None:
+        return None
+
+    # Mapped[T] → T (then unwrap Optional)
+    try:
+        from ..types import Mapped
+
+        if get_origin(ann) is Mapped:
+            inner = get_args(ann)[0]
+            return _unwrap_optional(inner)
+    except Exception:
+        pass
+
+    # Optional[T]/Union[T, None] → T
+    return _unwrap_optional(ann)
+
+
+def _instantiate_dtype(
+    dtype: Any, py_type: Any, spec: Any, cls_name: str, col_name: str
+):
+    """
+    Create a SQLAlchemy TypeEngine instance from either a type CLASS or an instance.
+    - SAEnum: instantiate from the actual Enum class with a stable name
+    - String: honor FieldSpec.constraints['max_length'] if present
+    - UUID (PG): prefer as_uuid=True when available
+    """
+    # Already an instance? keep it.
+    try:
+        from sqlalchemy.sql.type_api import TypeEngine
+
+        if isinstance(dtype, TypeEngine):
+            return dtype
+    except Exception:
+        pass
+
+    # SAEnum from a Python Enum class
+    if dtype is SAEnum and isinstance(py_type, type) and issubclass(py_type, PyEnum):
+        enum_name = f"{cls_name.lower()}_{col_name.lower()}"
+        return SAEnum(py_type, name=enum_name, native_enum=True, validate_strings=True)
+
+    # String – pick up max_length from FieldSpec
+    if dtype is String:
+        max_len = getattr(getattr(spec, "field", None), "constraints", {}).get(
+            "max_length"
+        )
+        return String(max_len) if max_len else String()
+
+    # PostgreSQL UUID (or similar) – try as_uuid=True first
+    try:
+        return dtype(as_uuid=True)  # e.g., PG UUID
+    except TypeError:
+        try:
+            return dtype()
+        except TypeError:
+            # As a last resort, return the class; SQLA will raise clearly if unusable
+            return dtype
+
+
+def _materialize_colspecs_to_sqla(cls) -> None:
+    """
+    Replace ColumnSpec attributes with sqlalchemy.orm.mapped_column(...) BEFORE mapping.
+    Keep the original specs in __tigrbl_cols__ for downstream builders.
+    """
+    try:
+        from tigrbl.column.column_spec import ColumnSpec
+    except Exception:
+        return
+
+    # Prefer explicit registry if present; otherwise collect specs from the
+    # entire MRO so mixins contribute their ColumnSpec definitions.
+    specs: dict[str, ColumnSpec] = {}
+    for base in reversed(cls.__mro__):
+        base_specs = getattr(base, "__tigrbl_cols__", None)
+        if isinstance(base_specs, dict) and base_specs:
+            specs.update(base_specs)
+            continue
+        for name, attr in getattr(base, "__dict__", {}).items():
+            if isinstance(attr, ColumnSpec):
+                specs.setdefault(name, attr)
+
+    if not specs:
+        return
+
+    # Ensure downstream code can find the spec map
+    setattr(cls, "__tigrbl_cols__", dict(specs))
+
+    for name, spec in specs.items():
+        storage = getattr(spec, "storage", None)
+        if not storage:
+            # Virtual (wire-only) column – no DB column
+            continue
+
+        dtype = getattr(storage, "type_", None)
+        if not dtype:
+            # No SA dtype specified – cannot materialize
+            continue
+
+        py_type = _infer_py_type(cls, name, spec)
+        dtype_inst = _instantiate_dtype(dtype, py_type, spec, cls.__name__, name)
+
+        # Foreign key (if any)
+        fk = getattr(storage, "fk", None)
+        fk_arg = None
+        if fk is not None:
+            # ForeignKeySpec: target="table(col)", on_delete/on_update: "CASCADE"/...
+            fk_arg = ForeignKey(fk.target, ondelete=fk.on_delete, onupdate=fk.on_update)
+
+        check = getattr(storage, "check", None)
+        args: list[Any] = []
+        if fk_arg is not None:
+            args.append(fk_arg)
+        if check is not None:
+            cname = f"ck_{cls.__name__.lower()}_{name}"
+            args.append(CheckConstraint(check, name=cname))
+
+        # Build mapped_column from StorageSpec flags
+        mc = mapped_column(
+            dtype_inst,
+            *args,
+            primary_key=getattr(storage, "primary_key", False),
+            nullable=getattr(storage, "nullable", True),
+            unique=getattr(storage, "unique", False),
+            index=getattr(storage, "index", False),
+            default=getattr(storage, "default", None),
+            onupdate=getattr(storage, "onupdate", None),
+            server_default=getattr(storage, "server_default", None),
+            comment=getattr(storage, "comment", None),
+            autoincrement=getattr(storage, "autoincrement", None),
+        )
+
+        setattr(cls, name, mc)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Declarative Base
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+class Base(DeclarativeBase):
+    __allow_unmapped__ = True
+
+    def __init_subclass__(cls, **kw):
+        # 0) Remove any previously registered class with the same module path.
+        try:
+            reg = Base.registry._class_registry
+            key = f"{cls.__module__}.{cls.__name__}"
+            existing = reg.get(key)
+            if existing is not None:
+                try:
+                    Base.registry._dispose_cls(existing)
+                except Exception:
+                    pass
+                reg.pop(key, None)
+                if reg.get(cls.__name__) is existing:
+                    reg.pop(cls.__name__, None)
+        except Exception:
+            pass
+
+        # 0.5) If a table with the same name already exists, allow this class
+        # to extend it instead of raising duplicate-table errors.
+        try:
+            table_name = getattr(cls, "__tablename__", None)
+            if table_name and table_name in Base.metadata.tables:
+                table_args = getattr(cls, "__table_args__", None)
+                if table_args is None:
+                    cls.__table_args__ = {"extend_existing": True}
+                elif isinstance(table_args, dict):
+                    table_args = dict(table_args)
+                    table_args["extend_existing"] = True
+                    cls.__table_args__ = table_args
+                elif isinstance(table_args, tuple):
+                    if table_args and isinstance(table_args[-1], dict):
+                        table_dict = dict(table_args[-1])
+                        table_dict["extend_existing"] = True
+                        cls.__table_args__ = (*table_args[:-1], table_dict)
+                    else:
+                        cls.__table_args__ = (*table_args, {"extend_existing": True})
+        except Exception:
+            pass
+
+        # 1) BEFORE SQLAlchemy maps: turn ColumnSpecs into real mapped_column(...)
+        _materialize_colspecs_to_sqla(cls)
+
+        # 2) Let SQLAlchemy map the class (PK now exists)
+        super().__init_subclass__(**kw)
+
+        # 3) Seed model namespaces / index specs (ops/hooks/etc.) – idempotent
+        try:
+            from tigrbl.bindings import model as _model_bind
+
+            _model_bind.bind(cls)
+        except Exception:
+            pass
+
+        # 3) AUTO-BUILD CRUD schemas from ColumnSpecs so /docs has them
+        try:
+            from tigrbl.schema.build import build_for_model as _build_schemas
+
+            _build_schemas(
+                cls
+            )  # attaches request/response models to the model/registry
+        except Exception:
+            # Surface during development if needed:
+            # raise
+            pass
+
+    metadata = MetaData(
+        naming_convention={
+            "pk": "pk_%(table_name)s",
+            "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+            "ix": "ix_%(table_name)s_%(column_0_name)s",
+            "uq": "uq_%(table_name)s_%(column_0_name)s",
+            "ck": "ck_%(table_name)s_%(column_0_name)s_%(constraint_type)s",
+        }
+    )
+
+    @declared_attr.directive
+    def __tablename__(cls) -> str:  # noqa: N805
+        return cls.__name__.lower()
+
+    def __getitem__(self, key: str) -> Any:
+        """Allow dict-style access to model attributes."""
+        return getattr(self, key)
+
+
+__all__ = ["Base"]

tigrbl/table/_table.py

@@ -0,0 +1,54 @@
+# tigrbl/tigrbl/v3/table/_table.py
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any, Callable
+
+from ..engine._engine import AsyncSession, Session
+from ..engine import install_from_objects  # reuse the collector
+from ..engine import resolver as _resolver
+from ..ddl import initialize as _ddl_initialize
+from ._base import Base
+from .table_spec import TableSpec
+
+
+class Table(Base, TableSpec):
+    """Declarative ORM table base.
+
+    This class now integrates :class:`Base` so ORM models and tables share
+    the same type.  Column specifications are exposed via ``columns`` for
+    convenience.
+    """
+
+    __abstract__ = True
+    columns: SimpleNamespace = SimpleNamespace()
+
+    def __init__(self, **kw: Any) -> None:  # pragma: no cover - SQLA sets attrs
+        for k, v in kw.items():
+            setattr(self, k, v)
+
+    def __init_subclass__(cls, **kw: Any) -> None:  # noqa: D401
+        super().__init_subclass__(**kw)
+
+        # expose ColumnSpecs under `columns` namespace
+        specs = getattr(cls, "__tigrbl_cols__", {})
+        cls.columns = SimpleNamespace(**specs)
+
+        # auto-register table-level bindings if declared
+        try:
+            install_from_objects(models=[cls])
+        except Exception:  # pragma: no cover - best effort
+            pass
+
+    @classmethod
+    def install_engines(cls, *, api: Any | None = None) -> None:
+        install_from_objects(api=api, models=[cls])
+
+    @classmethod
+    def acquire(
+        cls, *, op_alias: str | None = None
+    ) -> tuple[Session | AsyncSession, Callable[[], None]]:
+        db, release = _resolver.acquire(model=cls, op_alias=op_alias)
+        return db, release
+
+    initialize = classmethod(_ddl_initialize)

tigrbl/table/mro_collect.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Any, Mapping, Tuple
+
+from .table_spec import TableSpec
+
+logger = logging.getLogger("uvicorn")
+
+
+def _merge_seq_attr(model: type, attr: str) -> Tuple[Any, ...]:
+    values: list[Any] = []
+    for base in model.__mro__:
+        seq = base.__dict__.get(attr, ()) or ()
+        try:
+            values.extend(seq)
+        except TypeError:  # pragma: no cover - non-iterable
+            values.append(seq)
+    return tuple(values)
+
+
+@lru_cache(maxsize=None)
+def mro_collect_table_spec(model: type) -> TableSpec:
+    """Collect TableSpec-like declarations across the model's MRO.
+
+    Merges common spec attributes (OPS, COLUMNS, SCHEMAS, HOOKS, SECURITY_DEPS,
+    DEPS) declared on the class or any mixins. Engine bindings declared via
+    ``table_config`` use the same precedence: later classes in the MRO override
+    earlier ones.
+    """
+
+    logger.info("Collecting table spec for %s", model.__name__)
+
+    engine: Any | None = None
+    for base in model.__mro__:
+        cfg = base.__dict__.get("table_config")
+        if isinstance(cfg, Mapping):
+            eng = (
+                cfg.get("engine")
+                or cfg.get("db")
+                or cfg.get("database")
+                or cfg.get("engine_provider")
+                or cfg.get("db_provider")
+            )
+            if eng is not None:
+                engine = eng
+
+    spec = TableSpec(
+        model=model,
+        engine=engine,
+        ops=_merge_seq_attr(model, "OPS"),
+        columns=_merge_seq_attr(model, "COLUMNS"),
+        schemas=_merge_seq_attr(model, "SCHEMAS"),
+        hooks=_merge_seq_attr(model, "HOOKS"),
+        security_deps=_merge_seq_attr(model, "SECURITY_DEPS"),
+        deps=_merge_seq_attr(model, "DEPS"),
+    )
+
+    logger.debug(
+        "Collected table spec for %s: %d ops, %d columns",
+        model.__name__,
+        len(spec.ops),
+        len(spec.columns),
+    )
+    return spec
+
+
+__all__ = ["mro_collect_table_spec"]

tigrbl/table/shortcuts.py

@@ -0,0 +1,57 @@
+# tigrbl/tigrbl/v3/table/shortcuts.py
+from __future__ import annotations
+
+from typing import Any, Sequence, Type
+
+from .table_spec import TableSpec
+from ._table import Table
+
+
+def defineTableSpec(
+    *,
+    # engine binding
+    engine: Any = None,
+    # composition
+    ops: Sequence[Any] = (),
+    columns: Sequence[Any] = (),
+    schemas: Sequence[Any] = (),
+    hooks: Sequence[Any] = (),
+    # dependency stacks
+    security_deps: Sequence[Any] = (),
+    deps: Sequence[Any] = (),
+) -> Type[TableSpec]:
+    """
+    Build a Table-spec class with class attributes only (no instances).
+    Use directly in your ORM class MRO:
+
+        class User(defineTableSpec(engine=..., ops=(...)), Base, Table):
+            __tablename__ = "users"
+
+    or pass it to `deriveTable(Model, ...)` to get a configured subclass.
+    """
+    attrs = {
+        # top-level mirrors read by collectors
+        "OPS": tuple(ops or ()),
+        "COLUMNS": tuple(columns or ()),
+        "SCHEMAS": tuple(schemas or ()),
+        "HOOKS": tuple(hooks or ()),
+        "SECURITY_DEPS": tuple(security_deps or ()),
+        "DEPS": tuple(deps or ()),
+    }
+
+    # Engine binding is conventionally stored under table_config["engine"]
+    # (and legacy "db" for backward compatibility) so collectors can find it.
+    if engine is not None:
+        attrs["table_config"] = {"engine": engine, "db": engine}
+
+    return type("TableSpec", (TableSpec,), attrs)
+
+
+def deriveTable(model: Type[Table], **kw: Any) -> Type[Table]:
+    """Produce a concrete ORM subclass that inherits the spec."""
+    Spec = defineTableSpec(**kw)
+    name = f"{model.__name__}WithSpec"
+    return type(name, (Spec, model), {})
+
+
+__all__ = ["defineTableSpec", "deriveTable"]

tigrbl/table/table_spec.py

@@ -0,0 +1,28 @@
+# tigrbl/tigrbl/v3/table/table_spec.py
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Sequence
+
+from ..engine.engine_spec import EngineCfg
+from ..response.types import ResponseSpec
+
+
+@dataclass
+class TableSpec:
+    """
+    Declarative enrichments for an ORM class (model == table).
+    This does not construct an instance; it decorates/produces a class.
+    """
+
+    model: Any  # ORM class
+    engine: Optional[EngineCfg] = None
+
+    # NEW
+    ops: Sequence[Any] = field(default_factory=tuple)  # OpSpec or shorthands
+    columns: Sequence[Any] = field(default_factory=tuple)  # ColumnSpec or shorthands
+    schemas: Sequence[Any] = field(default_factory=tuple)
+    hooks: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+    security_deps: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+    deps: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+
+    response: Optional[ResponseSpec] = None