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

tigrbl/engine/_engine.py

@@ -0,0 +1,130 @@
+# tigrbl/tigrbl/v3/engine/_engine.py
+from __future__ import annotations
+
+from contextlib import contextmanager, asynccontextmanager
+from dataclasses import dataclass, field
+import asyncio
+import inspect
+from typing import Any, Callable, Optional, Tuple, Union, Protocol, TYPE_CHECKING
+
+try:
+    from sqlalchemy.orm import Session
+    from sqlalchemy.ext.asyncio import AsyncSession
+except Exception:  # pragma: no cover
+    Session = object  # type: ignore
+    AsyncSession = object  # type: ignore
+
+
+class SessionFactory(Protocol):
+    def __call__(self) -> Union[Session, AsyncSession]: ...
+
+
+Builder = Callable[[], Tuple[Any, SessionFactory]]  # returns (engine, sessionmaker)
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers only
+    from .engine_spec import EngineSpec
+
+
+@dataclass(frozen=True)
+class Provider:
+    """Lazily builds an engine + sessionmaker from an :class:`EngineSpec`."""
+
+    spec: "EngineSpec"
+    _engine: Any = None
+    _maker: Optional[SessionFactory] = None
+    get_db: Callable[..., Any] = field(init=False)
+
+    @property
+    def kind(self) -> str:
+        return "async" if self.spec.async_ else "sync"
+
+    def ensure(self) -> Tuple[Any, SessionFactory]:
+        if self._maker is None:
+            eng, mk = self.spec.build()
+            object.__setattr__(self, "_engine", eng)
+            object.__setattr__(self, "_maker", mk)
+        return self._engine, self._maker  # type: ignore[return-value]
+
+    def session(self) -> Union[Session, AsyncSession]:
+        _, mk = self.ensure()
+        return mk()  # type: ignore[misc]
+
+    def __post_init__(self) -> None:
+        if self.spec.async_:
+
+            async def _get_db() -> Any:
+                db = self.session()
+                try:
+                    yield db  # type: ignore[misc]
+                finally:
+                    close = getattr(db, "close", None)
+                    if callable(close):
+                        rv = close()
+                        if inspect.isawaitable(rv):
+                            await rv
+
+            object.__setattr__(self, "get_db", _get_db)
+        else:
+
+            def _get_db() -> Any:
+                db = self.session()
+                try:
+                    yield db  # type: ignore[misc]
+                finally:
+                    close = getattr(db, "close", None)
+                    if callable(close):
+                        rv = close()
+                        if inspect.isawaitable(rv):
+                            try:
+                                loop = asyncio.get_running_loop()
+                            except RuntimeError:
+                                asyncio.run(rv)
+                            else:
+                                loop.create_task(rv)
+
+            object.__setattr__(self, "get_db", _get_db)
+
+
+@dataclass
+class Engine:
+    """Thin façade over an :class:`EngineSpec` with convenient (a)context managers."""
+
+    spec: "EngineSpec"
+    provider: Provider = field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "provider", Provider(self.spec))
+
+    @property
+    def is_async(self) -> bool:
+        return self.provider.kind == "async"
+
+    def raw(self) -> Tuple[Any, SessionFactory]:
+        return self.provider.ensure()
+
+    @property
+    def get_db(self) -> Callable[..., Any]:
+        return self.provider.get_db
+
+    @contextmanager
+    def session(self) -> Session:
+        db = self.provider.session()
+        try:
+            yield db  # type: ignore[return-value]
+        finally:
+            close = getattr(db, "close", None)
+            if callable(close):
+                close()
+
+    @asynccontextmanager
+    async def asession(self) -> AsyncSession:
+        db = self.provider.session()
+        try:
+            yield db  # type: ignore[return-value]
+        finally:
+            close = getattr(db, "close", None)
+            if callable(close):
+                # AsyncSession.close() is sync; close() may exist as async in some impls
+                res = close()
+                if hasattr(res, "__await__"):
+                    await res

tigrbl/engine/bind.py

@@ -0,0 +1,33 @@
+"""Bind collected engine configuration to the resolver."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable
+
+from .resolver import register_api, register_op, register_table, set_default
+
+
+def bind(collected: Dict[str, Any]) -> None:
+    """Bind a collected configuration mapping into the resolver."""
+    default_db = collected.get("default")
+    if default_db is not None:
+        set_default(default_db)
+
+    for api_obj, db in collected.get("api", {}).items():
+        register_api(api_obj, db)
+
+    for table_obj, db in collected.get("tables", {}).items():
+        register_table(table_obj, db)
+
+    for (model, alias), db in collected.get("ops", {}).items():
+        register_op(model, alias, db)
+
+
+def install_from_objects(
+    *, app: Any | None = None, api: Any | None = None, models: Iterable[Any] = ()
+) -> None:
+    """Collect engine config from objects and bind them to the resolver."""
+    from .collect import collect_engine_config
+
+    collected = collect_engine_config(app=app, api=api, models=models)
+    bind(collected)

tigrbl/engine/builders.py

@@ -0,0 +1,236 @@
+"""SQLAlchemy engine and sessionmaker builders."""
+
+import logging
+import os
+from sqlalchemy import create_engine, event
+from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.pool import StaticPool  # only for SQLite
+from sqlalchemy.orm import sessionmaker
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+
+
+# ---------------------------------------------------------------------
+# 1. BLOCKING  •  SQLite
+# ---------------------------------------------------------------------
+def blocking_sqlite_engine(path: str | None = None):
+    """
+    Parameters
+    ----------
+    path : str | None
+        • None  → single shared in-memory DB (thread-safe).
+        • "./db.sqlite3" etc. → file-backed database.
+    """
+    logger.debug("blocking_sqlite_engine called with path=%r", path)
+    if path is None:
+        logger.debug("blocking_sqlite_engine: creating shared in-memory SQLite engine")
+        url = "sqlite+pysqlite://"
+        kwargs = dict(
+            connect_args={"check_same_thread": False},
+            poolclass=StaticPool,  # same connection everywhere
+            echo=False,
+            future=True,
+        )
+    else:
+        logger.debug(
+            "blocking_sqlite_engine: creating file-backed SQLite engine at %s",
+            path,
+        )
+        url = f"sqlite+pysqlite:///{path}"
+        kwargs = dict(echo=False, future=True)
+
+    eng = create_engine(url, **kwargs)
+
+    def _fk_pragma(dbapi_conn, _):
+        try:
+            dbapi_conn.execute("PRAGMA foreign_keys=ON")
+        except Exception:
+            pass
+
+    event.listen(eng, "connect", _fk_pragma)
+    logger.debug("blocking_sqlite_engine: created engine %r", eng)
+    return eng, sessionmaker(bind=eng, expire_on_commit=False)
+
+
+# ---------------------------------------------------------------------
+# 3. BLOCKING  •  PostgreSQL  (psycopg2)
+# ---------------------------------------------------------------------
+def blocking_postgres_engine(
+    dsn: str | None = None,
+    user: str = "app",
+    pwd: str | None = None,
+    host: str = "localhost",
+    port: int = 5432,
+    db: str = "app_db",
+    pool_size: int = 10,
+    max_overflow: int = 20,
+):
+    logger.debug(
+        "blocking_postgres_engine called with dsn=%r user=%r host=%r port=%r db=%r",
+        dsn,
+        user,
+        host,
+        port,
+        db,
+    )
+    if dsn:
+        logger.debug("blocking_postgres_engine: using provided DSN")
+        url = dsn
+    else:
+        logger.debug("blocking_postgres_engine: constructing DSN from parameters")
+        user = os.getenv("PGUSER", user)
+        pwd = os.getenv("PGPASSWORD", pwd or "secret")
+        host = os.getenv("PGHOST", host)
+        port = int(os.getenv("PGPORT", port))
+        db = os.getenv("PGDATABASE", db)
+        url = f"postgresql+psycopg2://{user}:{pwd}@{host}:{port}/{db}"
+    eng = create_engine(
+        url,
+        pool_size=pool_size,
+        max_overflow=max_overflow,
+        pool_pre_ping=True,  # drops stale connections
+        echo=False,
+        future=True,
+    )
+    logger.debug("blocking_postgres_engine: created engine %r", eng)
+    return eng, sessionmaker(bind=eng, expire_on_commit=False)
+
+
+# ───────────────────────────────────────────────────────────────────────
+# HybridSession: async under the hood, classic Session façade on top
+# ───────────────────────────────────────────────────────────────────────
+class HybridSession(AsyncSession):
+    """
+    An AsyncSession that ALSO behaves like a synchronous Session for the
+    handful of blocking helpers Tigrbl’s CRUD cores expect (`query`,
+    `commit`, `flush`, `refresh`, `get`, `delete`).
+    """
+
+    # ---- synchronous wrappers (delegate to the sync mirror) ------------
+    # NOTE: self.sync_session is provided by SQLAlchemy ≥1.4
+    def query(self, *e, **k):
+        logger.debug("HybridSession.query called with args=%r kwargs=%r", e, k)
+        return self.sync_session.query(*e, **k)
+
+    def add(self, *a, **k):
+        logger.debug("HybridSession.add called with args=%r kwargs=%r", a, k)
+        return self.sync_session.add(*a, **k)
+
+    async def get(self, *a, **k):
+        logger.debug("HybridSession.get called with args=%r kwargs=%r", a, k)
+        return await super().get(*a, **k)
+
+    async def flush(self, *a, **k):
+        logger.debug("HybridSession.flush called with args=%r kwargs=%r", a, k)
+        return await super().flush(*a, **k)
+
+    async def commit(self, *a, **k):
+        logger.debug("HybridSession.commit called with args=%r kwargs=%r", a, k)
+        return await super().commit(*a, **k)
+
+    async def refresh(self, *a, **k):
+        logger.debug("HybridSession.refresh called with args=%r kwargs=%r", a, k)
+        return await super().refresh(*a, **k)
+
+    async def delete(self, *a, **k):
+        logger.debug("HybridSession.delete called with args=%r kwargs=%r", a, k)
+        return await super().delete(*a, **k)
+
+    # ---- DDL helper used at Tigrbl bootstrap --------------------------
+    async def run_sync(self, fn, *a, **kw):
+        logger.debug(
+            "HybridSession.run_sync called with fn=%r args=%r kwargs=%r", fn, a, kw
+        )
+        try:
+            rv = await super().run_sync(fn, *a, **kw)
+            logger.debug("HybridSession.run_sync succeeded with result=%r", rv)
+            return rv
+        except (OSError, SQLAlchemyError) as exc:
+            url = getattr(self.bind, "url", "unknown")
+            logger.debug(
+                "HybridSession.run_sync failed for url %s with exc=%r", url, exc
+            )
+            await self.bind.dispose()
+            raise RuntimeError(
+                f"Failed to connect to database at '{url}'. "
+                "Ensure the database is reachable and credentials are correct."
+            ) from exc
+
+
+# ----------------------------------------------------------------------
+# 2. ASYNC  •  SQLite  (aiosqlite driver)
+# ----------------------------------------------------------------------
+def async_sqlite_engine(path: str | None = None):
+    logger.debug("async_sqlite_engine called with path=%r", path)
+    url = "sqlite+aiosqlite://" + (f"/{path}" if path else "")
+    logger.debug("async_sqlite_engine: using url=%s", url)
+    eng = create_async_engine(
+        url,
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+        echo=False,
+    )
+
+    def _fk_pragma(dbapi_conn, _):
+        try:
+            dbapi_conn.execute("PRAGMA foreign_keys=ON")
+        except Exception:
+            pass
+
+    event.listen(eng.sync_engine, "connect", _fk_pragma)
+    logger.debug("async_sqlite_engine: created engine %r", eng)
+    return eng, async_sessionmaker(
+        eng,
+        expire_on_commit=False,
+        class_=HybridSession,  # CHANGED ←
+    )
+
+
+# ----------------------------------------------------------------------
+# 4. ASYNC  •  PostgreSQL  (asyncpg)
+# ----------------------------------------------------------------------
+def async_postgres_engine(
+    dsn: str | None = None,
+    user: str = "app",
+    pwd: str | None = None,
+    host: str = "localhost",
+    port: int = 5432,
+    db: str = "app_db",
+    pool_size: int = 10,
+    max_size: int = 20,
+):
+    logger.debug(
+        "async_postgres_engine called with dsn=%r user=%r host=%r port=%r db=%r",
+        dsn,
+        user,
+        host,
+        port,
+        db,
+    )
+    if dsn:
+        logger.debug("async_postgres_engine: using provided DSN")
+        url = dsn
+    else:
+        logger.debug("async_postgres_engine: constructing DSN from parameters")
+        user = os.getenv("PGUSER", user)
+        pwd = os.getenv("PGPASSWORD", pwd or "secret")
+        host = os.getenv("PGHOST", host)
+        port = int(os.getenv("PGPORT", port))
+        db = os.getenv("PGDATABASE", db)
+        url = f"postgresql+asyncpg://{user}:{pwd}@{host}:{port}/{db}"
+    eng = create_async_engine(
+        url,
+        pool_size=pool_size,
+        max_overflow=max_size - pool_size,
+        pool_pre_ping=True,
+        echo=False,
+    )
+    logger.debug("async_postgres_engine: created engine %r", eng)
+    return eng, async_sessionmaker(
+        eng,
+        expire_on_commit=False,
+        class_=HybridSession,  # CHANGED ←
+    )

tigrbl/engine/collect.py

@@ -0,0 +1,111 @@
+"""Functions for inspecting objects for engine configuration."""
+
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+from typing import Any, Dict, Iterable, Mapping, Tuple
+
+
+logger = logging.getLogger("uvicorn")
+
+
+def _read_engine_attr(obj: Any):
+    for k in ("engine", "db", "database", "engine_provider", "db_provider"):
+        if hasattr(obj, k):
+            return getattr(obj, k)
+    for k in (
+        "tigrbl_engine",
+        "tigrbl_db",
+        "get_engine",
+    ):
+        fn = getattr(obj, k, None)
+        if callable(fn):
+            return fn()
+    return None
+
+
+def _iter_op_decorators(model: Any) -> Dict[Tuple[Any, str], Mapping[str, Any]]:
+    out: Dict[Tuple[Any, str], Mapping[str, Any]] = {}
+    handlers = getattr(model, "handlers", None)
+    if handlers:
+        for alias in dir(handlers):
+            h = getattr(handlers, alias, None)
+            if h is None:
+                continue
+            for slot in ("handler", "core"):
+                fn = getattr(h, slot, None)
+                if callable(fn) and (
+                    hasattr(fn, "__tigrbl_engine_ctx__") or hasattr(fn, "__tigrbl_db__")
+                ):
+                    spec = getattr(fn, "__tigrbl_engine_ctx__", None)
+                    if spec is None:
+                        spec = getattr(fn, "__tigrbl_db__")
+                    out[(model, alias)] = {"engine": spec}
+                    break
+    rpcns = getattr(model, "rpc", SimpleNamespace())
+    for alias in dir(rpcns):
+        if alias.startswith("_"):
+            continue
+        fn = getattr(rpcns, alias, None)
+        if callable(fn) and (
+            hasattr(fn, "__tigrbl_engine_ctx__") or hasattr(fn, "__tigrbl_db__")
+        ):
+            spec = getattr(fn, "__tigrbl_engine_ctx__", None)
+            if spec is None:
+                spec = getattr(fn, "__tigrbl_db__")
+            out[(model, alias)] = {"engine": spec}
+    return out
+
+
+def _iter_declared_ops(model: Any) -> Dict[Tuple[Any, str], Mapping[str, Any]]:
+    out: Dict[Tuple[Any, str], Mapping[str, Any]] = {}
+    for spec in getattr(model, "__tigrbl_ops__", ()) or ():
+        eng = getattr(spec, "engine", None)
+        alias = getattr(spec, "alias", None)
+        if eng is not None and alias:
+            out[(model, alias)] = {"engine": eng}
+    return out
+
+
+def collect_engine_config(
+    *, app: Any | None = None, api: Any | None = None, models: Iterable[Any] = ()
+) -> Dict[str, Any]:
+    """Collect engine configuration from objects without binding them."""
+    logger.info("Collecting engine configuration")
+    app_engine = _read_engine_attr(app) if app is not None else None
+    api_engine = _read_engine_attr(api) if api is not None else None
+
+    tables: Dict[Any, Any] = {}
+    ops: Dict[Tuple[Any, str], Any] = {}
+
+    for m in models:
+        cfg = getattr(m, "table_config", None)
+        t_engine = None
+        if isinstance(cfg, Mapping):
+            for k in ("engine", "db", "database", "engine_provider", "db_provider"):
+                if k in cfg:
+                    t_engine = cfg[k]
+                    break
+        if t_engine is None:
+            t_engine = _read_engine_attr(m)
+        if t_engine is not None:
+            tables[m] = t_engine
+
+        for (model, alias), ocfg in _iter_op_decorators(m).items():
+            ops[(model, alias)] = ocfg.get("engine")
+        for (model, alias), ocfg in _iter_declared_ops(m).items():
+            ops[(model, alias)] = ocfg.get("engine")
+
+    api_map = {api: api_engine} if api_engine is not None and api is not None else {}
+
+    logger.debug("Collected engine config for %d models", len(models))
+    return {
+        "default": app_engine,
+        "api": api_map,
+        "tables": tables,
+        "ops": ops,
+    }
+
+
+__all__ = ["collect_engine_config"]

tigrbl/engine/decorators.py

@@ -0,0 +1,108 @@
+# tigrbl/tigrbl/v3/engine/decorators.py
+from __future__ import annotations
+
+import inspect
+from typing import Any, Optional
+
+# EngineSpec provides the canonical parsing; EngineCfg is the accepted input type
+# (DSN string or mapping) attached by @engine_ctx.
+from .engine_spec import EngineCfg
+
+
+def _normalize(ctx: Optional[EngineCfg] = None, **kw: Any) -> EngineCfg:
+    """
+    Accept either:
+      • ctx: a DSN string (e.g., "sqlite:///file.db", "postgresql+asyncpg://…")
+      • ctx: a mapping like {"kind":"sqlite","async":True,"mode":"memory"} or
+             {"kind":"postgres","async":True,"host":"db","db":"app_db",...}
+      • **kw: keyword form that will be converted to the mapping shape
+
+    Returns an EngineCfg (string or mapping) suitable for EngineSpec.from_any(...).
+    """
+    if ctx is not None:
+        return ctx
+
+    kind = kw.get("kind")
+    if not kind:
+        dsn = kw.get("dsn")
+        if not dsn:
+            raise ValueError(
+                "Provide engine_ctx=<DSN|mapping> or kind=sqlite|postgres (with fields)"
+            )
+        return str(dsn)
+
+    async_kw = kw.get("async_")
+    if async_kw is None:
+        async_kw = kw.get("async")
+
+    m: dict[str, Any] = {"kind": kind}
+
+    if kind == "sqlite":
+        path = kw.get("path")
+        mode = kw.get("mode")
+        memory_flag = kw.get("memory")
+        # memory modes: mode="memory" OR memory=True OR no path supplied
+        memory = (mode == "memory") or memory_flag or not path
+        async_default = True if async_kw is None and memory else False
+        m["async"] = bool(async_kw) if async_kw is not None else async_default
+        if memory:
+            m["mode"] = "memory"
+        else:
+            m["path"] = path
+
+    elif kind == "postgres":
+        m["async"] = bool(async_kw) if async_kw is not None else False
+        for k in ("user", "pwd", "host", "port", "db", "pool_size", "max"):
+            if k in kw:
+                m[k] = kw[k]
+    else:
+        raise ValueError("kind must be 'sqlite' or 'postgres'")
+
+    return m
+
+
+def engine_ctx(ctx: Optional[EngineCfg] = None, **kw: Any):
+    """
+    Object-agnostic decorator to attach engine configuration to:
+      - App classes/instances     (app-level default)
+      - API classes/instances     (api-level default)
+      - ORM model classes         (table-level)
+      - Op callables              (op-level)
+
+    What it stores:
+      • For ops (functions/methods): sets __tigrbl_engine_ctx__ (and legacy __tigrbl_db__).
+      • For ORM table classes: injects mapping under model.table_config["engine"] (and legacy "db").
+      • For App/API classes or instances: sets attribute .engine = EngineCfg (and legacy .db).
+
+    Downstream:
+      • engine.install_from_objects(...) discovers these and registers
+        Providers with resolver precedence: op > table(model) > api > app.
+    """
+    spec = _normalize(ctx, **kw)
+
+    def _decorate(obj: Any):
+        # Op-level: functions or methods
+        if inspect.isfunction(obj) or inspect.ismethod(obj):
+            # New attribute name for clarity
+            setattr(obj, "__tigrbl_engine_ctx__", spec)
+            # Back-compat: some collectors still look for __tigrbl_db__
+            setattr(obj, "__tigrbl_db__", spec)
+            return obj
+
+        # ORM model class?
+        if inspect.isclass(obj) and hasattr(obj, "__tablename__"):
+            cfg = dict(getattr(obj, "table_config", {}) or {})
+            cfg["engine"] = spec
+            cfg["db"] = spec  # legacy key for backward compatibility
+            setattr(obj, "table_config", cfg)
+            return obj
+
+        # API/App classes or instances: keep a simple attribute
+        setattr(obj, "engine", spec)
+        setattr(obj, "db", spec)  # legacy attribute
+        return obj
+
+    return _decorate
+
+
+__all__ = ["engine_ctx"]