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

tigrbl/transport/rest/aggregator.py

@@ -0,0 +1,132 @@
+# tigrbl/v3/transport/rest/aggregator.py
+"""
+Aggregates per-model REST routers into a single Router.
+
+This does not build endpoints by itself — it simply collects the routers that
+`tigrbl.bindings.rest` attached to each model at `model.rest.router`.
+
+Recommended workflow:
+  1) Include models with `mount_router=False` so you don't double-mount:
+        api.include_model(User, mount_router=False)
+        api.include_model(Team, mount_router=False)
+  2) Aggregate and mount once:
+        app.include_router(build_rest_router(api, base_prefix="/api"))
+     or:
+        mount_rest(api, app, base_prefix="/api")
+
+Notes:
+  • Router paths already include `/{resource}`; we only add `base_prefix`.
+  • Model-level auth/db deps and extra REST deps are already attached to each
+    model router by `bindings.rest`; this wrapper can add *additional* top-level
+    dependencies if you pass them in.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Sequence
+
+try:
+    from ...types import Router, Depends
+except Exception:  # pragma: no cover
+    # Minimal shim to keep importable without FastAPI
+    class Router:  # type: ignore
+        def __init__(self, *a, dependencies: Optional[Sequence[Any]] = None, **kw):
+            self.routes = []
+            self.includes = []
+            self.dependencies = list(dependencies or [])
+
+        def add_api_route(self, path: str, endpoint, methods: Sequence[str], **opts):
+            self.routes.append((path, methods, endpoint, opts))
+
+        def include_router(self, router: "Router", *, prefix: str = "", **opts):
+            self.includes.append((router, prefix, opts))
+
+    def Depends(fn):  # type: ignore
+        return fn
+
+
+def _norm_prefix(p: Optional[str]) -> str:
+    if not p:
+        return ""
+    if not p.startswith("/"):
+        p = "/" + p
+    # Avoid double trailing slashes; FastAPI is lenient but keep it clean
+    return p.rstrip("/")
+
+
+def _normalize_deps(deps: Optional[Sequence[Any]]) -> list:
+    """Accept either Depends(...) objects or plain callables."""
+    out = []
+    for d in deps or ():
+        try:
+            is_dep_obj = hasattr(d, "dependency")
+        except Exception:
+            is_dep_obj = False
+        out.append(d if is_dep_obj else Depends(d))
+    return out
+
+
+def _iter_models(api: Any, only: Optional[Sequence[type]] = None) -> Sequence[type]:
+    if only:
+        return list(only)
+    models: Mapping[str, type] = getattr(api, "models", {}) or {}
+    # deterministic iteration
+    return [models[k] for k in sorted(models.keys())]
+
+
+def build_rest_router(
+    api: Any,
+    *,
+    models: Optional[Sequence[type]] = None,
+    base_prefix: str = "",
+    dependencies: Optional[Sequence[Any]] = None,
+) -> Router:
+    """
+    Build a top-level Router that includes each model's router under `base_prefix`.
+
+    Args:
+        api: your Tigrbl facade (or any object with `.models` dict).
+        models: optional subset of models to include; defaults to all bound models.
+        base_prefix: prefix applied once for all included routers (e.g., "/api").
+        dependencies: additional router-level dependencies (Depends(...) or callables).
+
+    Returns:
+        Router ready to be mounted on your FastAPI app.
+    """
+    root = Router(dependencies=_normalize_deps(dependencies))
+    prefix = _norm_prefix(base_prefix)
+
+    for model in _iter_models(api, models):
+        rest_ns = getattr(model, "rest", None)
+        router = getattr(rest_ns, "router", None) if rest_ns is not None else None
+        if router is None:
+            # Nothing to include for this model (not bound or no routes)
+            continue
+        # Include with only the base prefix; the model router already has /{resource} in its paths
+        root.include_router(router, prefix=prefix or "")
+    return root
+
+
+def mount_rest(
+    api: Any,
+    app: Any,
+    *,
+    models: Optional[Sequence[type]] = None,
+    base_prefix: str = "",
+    dependencies: Optional[Sequence[Any]] = None,
+) -> Router:
+    """
+    Convenience helper: build the aggregated router and include it on `app`.
+
+    Returns the created router so you can keep a reference if desired.
+    """
+    router = build_rest_router(
+        api, models=models, base_prefix=base_prefix, dependencies=dependencies
+    )
+    include = getattr(app, "include_router", None)
+    if callable(include):
+        include(router)
+    return router
+
+
+__all__ = ["build_rest_router", "mount_rest"]

tigrbl/types/__init__.py

@@ -0,0 +1,170 @@
+# ── Standard Library ─────────────────────────────────────────────────────
+from types import MethodType, SimpleNamespace
+from uuid import uuid4, UUID
+
+# ── Third-party Dependencies (via deps module) ───────────────────────────
+from ..deps.sqlalchemy import (
+    # Core SQLAlchemy
+    Boolean,
+    Column,
+    _DateTime,
+    SAEnum,
+    Text,
+    ForeignKey,
+    Index,
+    Integer,
+    JSON,
+    Numeric,
+    String,
+    LargeBinary,
+    UniqueConstraint,
+    CheckConstraint,
+    create_engine,
+    event,
+    # PostgreSQL dialect
+    ARRAY,
+    PgEnum,
+    JSONB,
+    TSVECTOR,
+    # ORM
+    Mapped,
+    declarative_mixin,
+    declared_attr,
+    foreign,
+    mapped_column,
+    relationship,
+    remote,
+    column_property,
+    Session,
+    sessionmaker,
+    InstrumentedAttribute,
+    # Extensions
+    MutableDict,
+    MutableList,
+    hybrid_property,
+    StaticPool,
+)
+
+from ..deps.pydantic import (
+    BaseModel,
+    Field,
+    ValidationError,
+)
+
+from ..deps.fastapi import (
+    APIRouter,
+    Router,
+    Security,
+    Depends,
+    Request,
+    Response,
+    Path,
+    Body,
+    HTTPException,
+    App,
+)
+
+# ── Local Package ─────────────────────────────────────────────────────────
+from .op import _Op, _SchemaVerb
+from .uuid import PgUUID, SqliteUUID
+from .authn_abc import AuthNProvider
+from .table_config_provider import TableConfigProvider
+from .nested_path_provider import NestedPathProvider
+from .allow_anon_provider import AllowAnonProvider
+from .request_extras_provider import (
+    RequestExtrasProvider,
+    list_request_extras_providers,
+)
+from .response_extras_provider import (
+    ResponseExtrasProvider,
+    list_response_extras_providers,
+)
+
+from .op_verb_alias_provider import OpVerbAliasProvider, list_verb_alias_providers
+from .op_config_provider import OpConfigProvider
+
+# ── Generics / Extensions ─────────────────────────────────────────────────
+DateTime = _DateTime(timezone=False)
+TZDateTime = _DateTime(timezone=True)
+
+
+# ── Public Re-exports (Backwards Compatibility) ──────────────────────────
+__all__: list[str] = [
+    # local
+    "_Op",
+    "_SchemaVerb",
+    "AuthNProvider",
+    "TableConfigProvider",
+    "NestedPathProvider",
+    "AllowAnonProvider",
+    "RequestExtrasProvider",
+    "ResponseExtrasProvider",
+    "OpVerbAliasProvider",
+    "list_verb_alias_providers",
+    "list_request_extras_providers",
+    "list_response_extras_providers",
+    "OpConfigProvider",
+    # add ons
+    "SqliteUUID",
+    # builtin types
+    "MethodType",
+    "SimpleNamespace",
+    "uuid4",
+    "UUID",
+    # sqlalchemy core (from deps.sqlalchemy)
+    "Boolean",
+    "Column",
+    "DateTime",
+    "TZDateTime",
+    "Text",
+    "SAEnum",
+    "ForeignKey",
+    "Index",
+    "Integer",
+    "JSON",
+    "Numeric",
+    "String",
+    "LargeBinary",
+    "UniqueConstraint",
+    "CheckConstraint",
+    "create_engine",
+    "event",
+    # sqlalchemy.dialects.postgresql (from deps.sqlalchemy)
+    "ARRAY",
+    "PgEnum",
+    "JSONB",
+    "PgUUID",
+    "TSVECTOR",
+    # sqlalchemy.orm (from deps.sqlalchemy)
+    "Mapped",
+    "declarative_mixin",
+    "declared_attr",
+    "foreign",
+    "mapped_column",
+    "column_property",
+    "hybrid_property",
+    "relationship",
+    "remote",
+    "Session",
+    "sessionmaker",
+    "InstrumentedAttribute",
+    # sqlalchemy.ext.mutable (from deps.sqlalchemy)
+    "MutableDict",
+    "MutableList",
+    "StaticPool",
+    # pydantic schema support (from deps.pydantic)
+    "BaseModel",
+    "Field",
+    "ValidationError",
+    # fastapi support (from deps.fastapi)
+    "Request",
+    "Response",
+    "APIRouter",
+    "Router",
+    "App",
+    "Security",
+    "Depends",
+    "Path",
+    "Body",
+    "HTTPException",
+]

tigrbl/types/allow_anon_provider.py

@@ -0,0 +1,19 @@
+from typing import Callable, ClassVar, Iterable
+
+from .table_config_provider import TableConfigProvider
+
+_ALLOW_ANON_PROVIDERS: set[type] = set()
+
+
+class AllowAnonProvider(TableConfigProvider):
+    """Models that expose operations without authentication."""
+
+    __tigrbl_allow_anon__: ClassVar[Iterable[str] | Callable[[], Iterable[str]]] = ()
+
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        _ALLOW_ANON_PROVIDERS.add(cls)
+
+
+def list_allow_anon_providers():
+    return sorted(_ALLOW_ANON_PROVIDERS, key=lambda c: c.__name__)

tigrbl/types/authn_abc.py

@@ -0,0 +1,30 @@
+# tigrbl/v3/types/authn_abc.py
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from fastapi import Request
+
+
+class AuthNProvider(ABC):
+    """
+    Marker‑interface that any AuthN extension must implement
+    so that Tigrbl can plug itself in at run‑time.
+    """
+
+    # ---------- FastAPI dependency ----------
+    @abstractmethod
+    async def get_principal(self, request: Request):  # -> dict[str, str]
+        """Return {"sub": user_id, "tid": tenant_id, ...} or raise HTTP 401."""
+
+
+__all__ = ["AuthNProvider"]
+
+
+for _name in list(globals()):
+    if _name not in __all__ and not _name.startswith("__"):
+        del globals()[_name]
+
+
+def __dir__():
+    """Tighten ``dir()`` output for interactive sessions."""
+
+    return sorted(__all__)

tigrbl/types/nested_path_provider.py

@@ -0,0 +1,22 @@
+from abc import abstractmethod
+
+from .table_config_provider import TableConfigProvider
+
+_NESTED_PATH_PROVIDERS: set[type] = set()
+
+
+class NestedPathProvider(TableConfigProvider):
+    """Models that supply nested route prefixes."""
+
+    @classmethod
+    @abstractmethod
+    def __tigrbl_nested_paths__(cls) -> str | None:
+        """Return hierarchical path prefix for nested routes."""
+
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        _NESTED_PATH_PROVIDERS.add(cls)
+
+
+def list_nested_path_providers():
+    return sorted(_NESTED_PATH_PROVIDERS, key=lambda c: c.__name__)

tigrbl/types/op.py

@@ -0,0 +1,35 @@
+"""
+tigrbl/v3/types/_op.py
+Pure structural helpers"""
+
+from typing import Any, Callable, NamedTuple, Type, Literal, TypeAlias
+
+_SchemaVerb: TypeAlias = Literal[
+    "create",
+    "read",
+    "update",
+    "replace",
+    "merge",
+    "delete",
+    "list",
+    "clear",
+]
+
+# need to add clear
+# need to add support for bulk create, update, delete
+
+
+class _Op(NamedTuple):
+    """
+    Metadata for one REST/RPC operation registered by Tigrbl.
+    """
+
+    verb: str  # e.g. "create", "list"
+    http: str  # "POST" | "GET" | "PATCH" | …
+    path: str  # URL suffix, e.g. "/{item_id}"
+    In: Type | None  # Pydantic input model (or None)
+    Out: Type  # Pydantic output model
+    core: Callable[..., Any]  # The actual implementation
+
+
+__all__ = ["_Op", "_SchemaVerb"]

tigrbl/types/op_config_provider.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+from typing import Iterable, Literal
+from .table_config_provider import TableConfigProvider
+from ..op import OpSpec
+from ..op.canonical import (  # noqa: F401
+    DEFAULT_CANON_VERBS,
+    should_wire_canonical,
+)
+
+
+class OpConfigProvider(TableConfigProvider):
+    __tigrbl_ops__: Iterable[OpSpec] = ()
+
+    # Default canonical verbs wiring policy
+    __tigrbl_defaults_mode__: Literal["all", "none", "some"] = "all"
+    __tigrbl_defaults_include__: set[str] = set()
+    __tigrbl_defaults_exclude__: set[str] = set()

tigrbl/types/op_verb_alias_provider.py

@@ -0,0 +1,33 @@
+from typing import Callable, ClassVar, Mapping, Literal
+
+from .table_config_provider import TableConfigProvider
+
+_VERB_ALIAS_PROVIDERS: set[type] = set()
+
+
+class OpVerbAliasProvider(TableConfigProvider):
+    """
+    Table-level config provider to rename operation verbs for RPC exposure.
+    Does not change REST routes or internal canonical semantics.
+    """
+
+    # Map canonical → alias (e.g., {"create": "register"})
+    __tigrbl_verb_aliases__: ClassVar[
+        Mapping[str, str] | Callable[[], Mapping[str, str]]
+    ] = {}
+
+    # How to expose names:
+    #  - "both" (default): expose canonical & alias
+    #  - "alias_only": expose alias only
+    #  - "canonical_only": ignore aliases, keep canonical only
+    __tigrbl_verb_alias_policy__: ClassVar[
+        Literal["both", "alias_only", "canonical_only"]
+    ] = "both"
+
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        _VERB_ALIAS_PROVIDERS.add(cls)
+
+
+def list_verb_alias_providers():
+    return sorted(_VERB_ALIAS_PROVIDERS, key=lambda c: c.__name__)

tigrbl/types/request_extras_provider.py

@@ -0,0 +1,22 @@
+from typing import Callable, ClassVar, Mapping
+
+from .table_config_provider import TableConfigProvider
+
+_REQUEST_EXTRAS_PROVIDERS: set[type] = set()
+
+
+class RequestExtrasProvider(TableConfigProvider):
+    """Models that expose request-only virtual fields."""
+
+    __tigrbl_request_extras__: ClassVar[
+        Mapping[str, Mapping[str, object]]
+        | Callable[[], Mapping[str, Mapping[str, object]]]
+    ] = {}
+
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        _REQUEST_EXTRAS_PROVIDERS.add(cls)
+
+
+def list_request_extras_providers():
+    return sorted(_REQUEST_EXTRAS_PROVIDERS, key=lambda c: c.__name__)

tigrbl/types/response_extras_provider.py

@@ -0,0 +1,22 @@
+from typing import Callable, ClassVar, Mapping
+
+from .table_config_provider import TableConfigProvider
+
+_RESPONSE_EXTRAS_PROVIDERS: set[type] = set()
+
+
+class ResponseExtrasProvider(TableConfigProvider):
+    """Models that expose response-only virtual fields."""
+
+    __tigrbl_response_extras__: ClassVar[
+        Mapping[str, Mapping[str, object]]
+        | Callable[[], Mapping[str, Mapping[str, object]]]
+    ] = {}
+
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        _RESPONSE_EXTRAS_PROVIDERS.add(cls)
+
+
+def list_response_extras_providers():
+    return sorted(_RESPONSE_EXTRAS_PROVIDERS, key=lambda c: c.__name__)

tigrbl/types/table_config_provider.py

@@ -0,0 +1,13 @@
+_TABLE_CONFIG_PROVIDERS: set[type] = set()
+
+
+class TableConfigProvider:
+    """Marker base for table-level configuration providers."""
+
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        _TABLE_CONFIG_PROVIDERS.add(cls)
+
+
+def list_table_config_providers():
+    return sorted(_TABLE_CONFIG_PROVIDERS, key=lambda c: c.__name__)

tigrbl/types/uuid.py

@@ -0,0 +1,55 @@
+# ── Standard Library ─────────────────────────────────────────────────────
+from __future__ import annotations
+
+from typing import Any
+import uuid
+
+# ── Third-party Dependencies ────────────────────────────────────────────
+from sqlalchemy.types import TypeDecorator
+
+# ── Local Package ───────────────────────────────────────────────────────
+from ..deps.sqlalchemy import String, _PgUUID
+
+
+class PgUUID(_PgUUID):
+    @property
+    def hex(self):
+        return self.as_uuid.hex
+
+
+class SqliteUUID(TypeDecorator):
+    """UUID type that stores hyphenated strings on SQLite to avoid numeric coercion."""
+
+    impl = String(36)
+    cache_ok = True
+
+    def __init__(self, as_uuid: bool = True):
+        super().__init__()
+        self.as_uuid = as_uuid
+
+    @property
+    def python_type(self) -> type:
+        return uuid.UUID if self.as_uuid else str
+
+    def load_dialect_impl(self, dialect) -> Any:
+        if dialect.name == "postgresql":
+            return dialect.type_descriptor(PgUUID(as_uuid=self.as_uuid))
+        return dialect.type_descriptor(String(36))
+
+    def process_bind_param(self, value: Any, dialect) -> Any:
+        if value is None:
+            return None
+        if self.as_uuid:
+            if not isinstance(value, uuid.UUID):
+                value = uuid.UUID(str(value))
+            return value if dialect.name == "postgresql" else str(value)
+        return str(value)
+
+    def process_result_value(self, value: Any, dialect) -> Any:
+        if value is None:
+            return None
+        if self.as_uuid:
+            if isinstance(value, uuid.UUID):
+                return value
+            return uuid.UUID(str(value))
+        return str(value)