tigrbl 0.3.0.dev4__py3-none-any.whl → 0.3.2__py3-none-any.whl

tigrbl/core/crud/helpers/db.py

@@ -7,7 +7,6 @@ import logging
 from . import AsyncSession, Session
 from .model import _model_columns, _single_pk_name
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 

tigrbl/core/crud/helpers/enum.py

@@ -6,7 +6,6 @@ import logging
 
 from . import SAEnum
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 

tigrbl/core/crud/helpers/filters.py

@@ -7,7 +7,6 @@ import logging
 from . import select, and_, asc, desc
 from .model import _model_columns, _colspecs
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 _CANON_OPS = {

tigrbl/core/crud/helpers/model.py

@@ -6,7 +6,6 @@ import logging
 
 from ....column.mro_collect import mro_collect_columns
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 

tigrbl/core/crud/helpers/normalize.py

@@ -6,7 +6,6 @@ import logging
 
 from . import AsyncSession, Session
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 

tigrbl/core/crud/ops.py

@@ -27,7 +27,6 @@ from .helpers import (
     _validate_enum_values,
 )
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 

tigrbl/docs/verbosity.md

@@ -0,0 +1,35 @@
+# Tigrbl verbosity and uvicorn logging
+
+Tigrbl logs through the `uvicorn` logger. This keeps its output aligned with the
+server's log configuration, so debug statements only appear when uvicorn is
+started in verbose mode.
+
+## Default behavior
+
+By default, uvicorn runs at `INFO` level and suppresses debug output. Tigrbl does
+not override that setting, so debug messages stay hidden unless you opt in.
+
+## Enabling verbose output
+
+Use uvicorn's log-level to opt into debug output:
+
+```bash
+uvicorn your_module:app --log-level debug
+```
+
+Or configure it programmatically:
+
+```python
+import uvicorn
+
+config = uvicorn.Config("your_module:app", log_level="debug")
+server = uvicorn.Server(config)
+```
+
+## Disabling verbose output
+
+Set the log level back to `info` (or higher) to suppress debug messages:
+
+```bash
+uvicorn your_module:app --log-level info
+```

tigrbl/engine/__init__.py

@@ -24,3 +24,22 @@ __all__ = [
     "Engine",
     "engine",
 ]
+
+
+# Optional engine plugin support
+from .plugins import load_engine_plugins
+from .registry import register_engine, known_engine_kinds, get_engine_registration
+
+# Load external engines automatically on import (idempotent)
+try:
+    load_engine_plugins()
+except Exception:
+    # Import-time plugin load should never fail the package import
+    pass
+
+__all__ += [
+    "load_engine_plugins",
+    "register_engine",
+    "known_engine_kinds",
+    "get_engine_registration",
+]

tigrbl/engine/_engine.py

@@ -27,6 +27,13 @@ if TYPE_CHECKING:  # pragma: no cover - for type checkers only
 
 @dataclass(frozen=True)
 class Provider:
+    # supports() exposes engine capabilities for compatibility checks
+    def supports(self) -> dict:
+        try:
+            return self.spec.supports()
+        except Exception:
+            return {"engine": self.spec.kind or "unknown"}
+
     """Lazily builds an engine + sessionmaker from an :class:`EngineSpec`."""
 
     spec: "EngineSpec"
@@ -87,6 +94,13 @@ class Provider:
 
 @dataclass
 class Engine:
+    # Delegate to provider/spec for capability reporting
+    def supports(self) -> dict:
+        try:
+            return self.provider.supports()
+        except Exception:
+            return {"engine": self.spec.kind or "unknown"}
+
     """Thin façade over an :class:`EngineSpec` with convenient (a)context managers."""
 
     spec: "EngineSpec"

tigrbl/engine/builders.py

@@ -9,7 +9,6 @@ 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")
 
 

tigrbl/engine/capabilities.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from typing import Any, Dict
+
+
+def sqlite_capabilities(*, async_: bool, memory: bool) -> Dict[str, Any]:
+    # SQLite supports transactional semantics; isolation semantics differ from server DBs.
+    # We expose a conservative set that higher layers can reason about.
+    return {
+        "transactional": True,
+        "async_native": async_,  # async layer is provided by aiosqlite/SQLAlchemy AsyncEngine
+        "isolation_levels": {"read_committed", "serializable"},
+        "read_only_enforced": False,  # app layer should enforce; file-open RO may be used externally
+        "supports_timeouts": True,
+        "supports_ddl": True,
+        "engine": "sqlite",
+        "memory": bool(memory),
+    }
+
+
+def postgres_capabilities(*, async_: bool) -> Dict[str, Any]:
+    return {
+        "transactional": True,
+        "async_native": async_,
+        "isolation_levels": {"read_committed", "repeatable_read", "serializable"},
+        "read_only_enforced": True,
+        "supports_timeouts": True,
+        "supports_ddl": True,
+        "engine": "postgres",
+    }

tigrbl/engine/decorators.py

@@ -56,7 +56,9 @@ def _normalize(ctx: Optional[EngineCfg] = None, **kw: Any) -> EngineCfg:
             if k in kw:
                 m[k] = kw[k]
     else:
-        raise ValueError("kind must be 'sqlite' or 'postgres'")
+        # Allow external engine kinds; pass mapping through unchanged.
+        # Keep provided keys as-is so external builders can interpret them.
+        m.update({k: v for k, v in kw.items() if k not in m})
 
     return m
 

tigrbl/engine/docs/PLUGINS.md

@@ -0,0 +1,49 @@
+
+# Tigrbl Engine Plugins
+
+Tigrbl supports external engine kinds via an entry-point group: `tigrbl.engine`.
+
+An external package registers itself by exposing a `register()` function and
+declaring an entry point:
+
+```toml
+[project.entry-points."tigrbl.engine"]
+duckdb = "tigrbl_engine_duckdb.plugin:register"
+```
+
+Inside `register()` call:
+
+```python
+from tigrbl.engine.registry import register_engine
+from .builder import duckdb_engine, duckdb_capabilities
+
+def register():
+    register_engine("duckdb", duckdb_engine, duckdb_capabilities)
+```
+
+At runtime, `EngineSpec(kind="duckdb")` will look up the registration and use
+the external builder or raise a helpful `RuntimeError` if the plugin is not
+installed.
+
+
+## Capabilities / supports()
+
+External engines should expose a capabilities callable when registering:
+
+```python
+from tigrbl.engine.registry import register_engine
+
+def my_engine_builder(...): ...
+def my_engine_capabilities(**kw):
+    # Return a dict describing what the engine supports
+    return {
+        "transactional": True,
+        "isolation_levels": {"read_committed","serializable"},
+        "read_only_enforced": True,
+        "async_native": False,
+        "engine": "myengine",
+    }
+
+def register():
+    register_engine("myengine", my_engine_builder, capabilities=my_engine_capabilities)
+```

tigrbl/engine/engine_spec.py

@@ -1,7 +1,7 @@
 # tigrbl/v3/engine/engine_spec.py
 from __future__ import annotations
 
-from dataclasses import dataclass, field, fields
+from dataclasses import dataclass, field
 from typing import Optional, Mapping, Union, Any, Tuple
 from urllib.parse import urlsplit, urlunsplit
 
@@ -14,7 +14,6 @@ from .builders import (
 )
 
 # The value stored by @engine_ctx on App/API/Table/Op.
-# Accept either a DSN string, structured mapping, or pre-built objects.
 EngineCfg = Union[str, Mapping[str, object], "EngineSpec", Provider, Engine]
 
 
@@ -31,28 +30,21 @@ class EngineSpec:
           "postgresql://user:pwd@host:5432/db" ,
           "postgresql+asyncpg://user:pwd@host:5432/db"
       • Mapping (recommended for clarity/portability):
-          {
-            "kind": "sqlite" | "postgres",
-            "async": bool,                 # default False
-            # sqlite:
-            "path": "./file.db",           # file-backed
-            "mode": "memory" | None,       # memory uses StaticPool
-            # postgres:
-            "user": "app", "pwd": "secret",
-            "host": "localhost", "port": 5432, "db": "app_db",
-            "pool_size": 10, "max": 20     # max_overflow (sync) or max_size (async)
-          }
-
-    This class *does not* open connections; call .to_provider() to obtain
-    a lazy Provider that builds (engine, sessionmaker) on first use.
+          {"kind":"sqlite","async":True,"path":"./file.db"}
+          {"kind":"postgres","async":True,"host":"db","db":"app_db",...}
+          {<external kind> ...}  # for plugin engines
     """
 
-    # normalized fields
-    kind: Optional[str] = None  # "sqlite" | "postgres"
+    # normalized
+    kind: Optional[str] = None  # "sqlite" | "postgres" | <external>
     async_: bool = False
 
+    # canonical DSN (optional) and raw mapping (for external engines)
+    dsn: Optional[str] = None
+    mapping: Optional[Mapping[str, object]] = None
+
     # sqlite
-    path: Optional[str] = None  # file path (None when memory=True)
+    path: Optional[str] = None  # file path (None → memory)
     memory: bool = False
 
     # postgres
@@ -64,44 +56,11 @@ class EngineSpec:
     pool_size: int = 10
     max: int = 20  # max_overflow (sync) or max_size (async)
 
-    # raw passthroughs (for diagnostics)
-    dsn: Optional[str] = None
-    mapping: Optional[Mapping[str, object]] = field(default=None, repr=False)
-
-    def __repr__(self) -> str:  # pragma: no cover - representation logic
-        parts = []
-        for f in fields(self):
-            if not f.repr:
-                continue
-            value = getattr(self, f.name)
-            if f.name == "dsn":
-                value = self._redact_dsn(value)
-            if value is not None:
-                parts.append(f"{f.name}={value!r}")
-        return f"EngineSpec({', '.join(parts)})"
-
-    @staticmethod
-    def _redact_dsn(dsn: Optional[str]) -> Optional[str]:
-        if not dsn:
-            return dsn
-        try:
-            parts = urlsplit(dsn)
-            if parts.password:
-                netloc = parts.netloc.replace(parts.password, "***")
-                return urlunsplit(
-                    (parts.scheme, netloc, parts.path, parts.query, parts.fragment)
-                )
-        except Exception:
-            pass
-        return dsn
-
-    # ---------- parsing / normalization ----------
+    # ---------- parsing ----------
 
     @staticmethod
     def from_any(x: EngineCfg | None) -> Optional["EngineSpec"]:
-        """
-        Parse a DSN or mapping (as attached by @engine_ctx) into an EngineSpec.
-        """
+        """Parse DSN/Mapping/Provider/Engine into an :class:`EngineSpec`."""
         if x is None:
             return None
 
@@ -114,39 +73,57 @@ class EngineSpec:
         if isinstance(x, Engine):
             return x.spec
 
-        # String DSN
+        # DSN string
         if isinstance(x, str):
             s = x.strip()
-            # sqlite memory
-            if s == "sqlite://:memory:" or s.startswith("sqlite+memory://"):
-                return EngineSpec(
-                    kind="sqlite",
-                    async_=s.startswith("sqlite+aiosqlite://"),
-                    memory=True,
-                    dsn=s,
-                )
-            # sqlite async file
-            if s.startswith("sqlite+aiosqlite:///"):
+            # sqlite async
+            if s.startswith("sqlite+aiosqlite://") or s.startswith("sqlite+aiosqlite:"):
+                path = urlsplit(s).path or ""
+                if s.startswith("sqlite+aiosqlite:////"):
+                    if path.startswith("//"):
+                        path = path[1:]
+                    path = path or None
+                else:
+                    path = path.lstrip("/") or None
+                mem = path in {None, ":memory:", "/:memory:"} or s.endswith(":memory:")
                 return EngineSpec(
-                    kind="sqlite", async_=True, path=s.split(":///")[1], dsn=s
+                    kind="sqlite", async_=True, path=path, memory=mem, dsn=s
                 )
-            # sqlite sync file
-            if s.startswith("sqlite:///"):
+            # sqlite sync
+            if s.startswith("sqlite://") or s.startswith("sqlite:"):
+                # handle sqlite://:memory: and sqlite:///file.db
+                if s.startswith("sqlite://:memory:") or s.endswith(":memory:"):
+                    return EngineSpec(
+                        kind="sqlite", async_=False, path=None, memory=True, dsn=s
+                    )
+                # Take the path part after scheme; urlsplit handles both sqlite:// and sqlite:/// forms
+                p = urlsplit(s).path or ""
+                if s.startswith("sqlite:////"):
+                    if p.startswith("//"):
+                        p = p[1:]
+                    p = p or None
+                else:
+                    p = p.lstrip("/") or None
+                mem = p is None
                 return EngineSpec(
-                    kind="sqlite", async_=False, path=s.split(":///")[1], dsn=s
+                    kind="sqlite", async_=False, path=p, memory=mem, dsn=s
                 )
+
             # postgres async
-            if s.startswith("postgresql+asyncpg://"):
+            if s.startswith("postgresql+asyncpg://") or s.startswith(
+                "postgres+asyncpg://"
+            ):
                 return EngineSpec(kind="postgres", async_=True, dsn=s)
             # postgres sync
-            if s.startswith("postgresql://"):
+            if s.startswith("postgresql://") or s.startswith("postgres://"):
                 return EngineSpec(kind="postgres", async_=False, dsn=s)
+
             raise ValueError(f"Unsupported DSN: {s}")
 
         # Mapping
         m = x  # type: ignore[assignment]
 
-        # allow a few common aliases for ergonomics
+        # Helpers
         def _get_bool(key: str, *aliases: str, default: bool = False) -> bool:
             for k in (key, *aliases):
                 if k in m:
@@ -166,14 +143,16 @@ class EngineSpec:
         ) -> Optional[int]:
             for k in (key, *aliases):
                 if k in m and m[k] is not None:
-                    return int(m[k])  # type: ignore[index]
+                    try:
+                        return int(m[k])  # type: ignore[index]
+                    except Exception:
+                        return default
             return default
 
         k = str(m.get("kind", m.get("engine", ""))).lower()  # type: ignore[index]
         if k == "sqlite":
             async_ = _get_bool("async", "async_", default=False)
             path = _get_str("path")
-            # support either {"mode": "memory"} or {"memory": True} or no path
             memory = (
                 _get_bool("memory", default=False)
                 or (str(m.get("mode", "")).lower() == "memory")
@@ -182,8 +161,9 @@ class EngineSpec:
             return EngineSpec(
                 kind="sqlite",
                 async_=async_,
-                path=None if memory else path,
+                path=path,
                 memory=memory,
+                dsn=_get_str("dsn", "url"),
                 mapping=m,
             )
 
@@ -199,10 +179,17 @@ class EngineSpec:
                 name=_get_str("db", "name"),
                 pool_size=_get_int("pool_size", default=10) or 10,
                 max=_get_int("max", "max_overflow", "max_size", default=20) or 20,
+                dsn=_get_str("dsn", "url"),
                 mapping=m,
             )
 
-        raise ValueError(f"Unsupported provider kind: {k!r}")
+        # External / unknown kinds – keep mapping and defer to registry at build()
+        return EngineSpec(
+            kind=k or None,
+            async_=_get_bool("async", "async_", default=False),
+            dsn=_get_str("dsn", "url"),
+            mapping=m,
+        )
 
     # ---------- realization ----------
 
@@ -222,40 +209,147 @@ class EngineSpec:
         if self.kind == "postgres":
             if self.dsn:
                 if self.async_:
-                    return async_postgres_engine(
-                        dsn=self.dsn,
-                        pool_size=self.pool_size,
-                        max_size=self.max,
-                    )
-                return blocking_postgres_engine(
-                    dsn=self.dsn,
-                    pool_size=self.pool_size,
-                    max_overflow=self.max,
-                )
-
-            kwargs = {
-                "pool_size": self.pool_size,
+                    return async_postgres_engine(dsn=self.dsn)
+                return blocking_postgres_engine(dsn=self.dsn)
+            # keyword build
+            kwargs: dict[str, Any] = {
+                "user": self.user or "app",
+                "host": self.host or "localhost",
+                "port": self.port or 5432,
+                "db": self.name or "app_db",
+                "pool_size": int(self.pool_size or 10),
             }
-            if self.async_:
-                kwargs["max_size"] = self.max
-            else:
-                kwargs["max_overflow"] = self.max
-            if self.user is not None:
-                kwargs["user"] = self.user
             if self.pwd is not None:
                 kwargs["pwd"] = self.pwd
-            if self.host is not None:
-                kwargs["host"] = self.host
-            if self.port is not None:
-                kwargs["port"] = self.port
-            if self.name is not None:
-                kwargs["db"] = self.name
             if self.async_:
+                kwargs["max_size"] = int(self.max or 20)
                 return async_postgres_engine(**kwargs)
-            return blocking_postgres_engine(**kwargs)
+            else:
+                kwargs["max_overflow"] = int(self.max or 20)
+                return blocking_postgres_engine(**kwargs)
+
+        # External/registered engines
+        try:
+            from .plugins import load_engine_plugins
+            from .registry import get_engine_registration, known_engine_kinds
+
+            load_engine_plugins()
+            reg = get_engine_registration(self.kind or "")
+        except Exception:
+            reg = None
+        if reg:
+            mapping = self.mapping or {}
+            return reg.build(mapping=mapping, spec=self, dsn=self.dsn)
+
+        # No registration found: helpful error
+        try:
+            from .registry import known_engine_kinds  # re-import defensive
+
+            kinds = ", ".join(known_engine_kinds()) or "(none)"
+        except Exception:
+            kinds = "(unknown)"
+        raise RuntimeError(
+            f"Unknown or unavailable engine kind '{self.kind}'. Installed engine kinds: {kinds}. "
+            f"If this is an optional extension, install its package (e.g., 'pip install tigrbl_engine_{self.kind}')."
+        )
+
+    def supports(self) -> dict[str, Any]:
+        """Return capability dictionary for this engine spec.
+        For external kinds, consult the plugin registry if available.
+        """
+        # Built-ins
+        if self.kind == "sqlite":
+            try:
+                from .capabilities import sqlite_capabilities
+
+                return sqlite_capabilities(async_=self.async_, memory=self.memory)
+            except Exception:
+                pass
+        if self.kind == "postgres":
+            try:
+                from .capabilities import postgres_capabilities
+
+                return postgres_capabilities(async_=self.async_)
+            except Exception:
+                pass
+        # External/registered engines
+        try:
+            from .plugins import load_engine_plugins
+            from .registry import get_engine_registration
 
-        raise ValueError("EngineSpec has no kind")
+            load_engine_plugins()
+            reg = get_engine_registration(self.kind or "")
+        except Exception:
+            reg = None
+        if reg and getattr(reg, "capabilities", None):
+            try:
+                # Try flexible signature: capabilities(spec=..., mapping=...)
+                return reg.capabilities(spec=self, mapping=self.mapping)
+            except TypeError:
+                try:
+                    return reg.capabilities()
+                except Exception:
+                    pass
+            except Exception:
+                pass
+        # Fallback minimal shape
+        return {
+            "transactional": False,
+            "async_native": bool(self.async_),
+            "isolation_levels": set(),
+            "read_only_enforced": False,
+            "engine": self.kind or "unknown",
+        }
 
     def to_provider(self) -> Provider:
         """Materialize a lazy :class:`Provider` for this spec."""
         return Provider(self)
+
+    def __repr__(self) -> str:  # pragma: no cover - deterministic output
+        def _redact_dsn(dsn: Optional[str]) -> Optional[str]:
+            if not dsn:
+                return dsn
+            try:
+                parts = urlsplit(dsn)
+            except Exception:
+                return dsn
+            if not parts.scheme or parts.password is None:
+                return dsn
+            user = parts.username or ""
+            userinfo = f"{user}:***" if user else "***"
+            host = parts.hostname or ""
+            netloc = f"{userinfo}@{host}" if host else userinfo
+            if parts.port is not None:
+                netloc = f"{netloc}:{parts.port}"
+            return urlunsplit(
+                (parts.scheme, netloc, parts.path, parts.query, parts.fragment)
+            )
+
+        def _redact_mapping(
+            mapping: Optional[Mapping[str, object]],
+        ) -> Optional[dict[str, object]]:
+            if mapping is None:
+                return None
+            redacted: dict[str, object] = {}
+            for key, value in mapping.items():
+                if str(key).lower() in {"pwd", "password", "pass", "secret"}:
+                    redacted[key] = "***"
+                else:
+                    redacted[key] = value
+            return redacted
+
+        fields = [
+            ("kind", self.kind),
+            ("async_", self.async_),
+            ("dsn", _redact_dsn(self.dsn)),
+            ("mapping", _redact_mapping(self.mapping)),
+            ("path", self.path),
+            ("memory", self.memory),
+            ("user", self.user),
+            ("host", self.host),
+            ("port", self.port),
+            ("name", self.name),
+            ("pool_size", self.pool_size),
+            ("max", self.max),
+        ]
+        return "EngineSpec(" + ", ".join(f"{k}={v!r}" for k, v in fields) + ")"