tigrbl-base 0.1.0__py3-none-any.whl

tigrbl_base/_base/__init__.py

@@ -0,0 +1,40 @@
+"""Base class implementations for tigrbl internals."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+_EXPORTS = {
+    "AppBase": "_app_base",
+    "BindingBase": "_binding_base",
+    "BindingRegistryBase": "_binding_base",
+    "ColumnBase": "_column_base",
+    "AliasBase": "_alias_base",
+    "EngineBase": "_engine_base",
+    "EngineProviderBase": "_engine_provider_base",
+    "HookBase": "_hook_base",
+    "RouterBase": "_router_base",
+    "ForeignKeyBase": "_storage",
+    "StorageTransformBase": "_storage",
+    "OpBase": "_op_base",
+    "RequestBase": "_request_base",
+    "SchemaBase": "_schema_base",
+    "SessionABC": "_session_abc",
+    "TigrblSessionBase": "_session_base",
+    "TableBase": "_table_base",
+    "TableRegistryBase": "_table_registry_base",
+    "AttrDict": "_mapping_access",
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(name)
+    module = import_module(f"{__name__}.{module_name}")
+    value = getattr(module, name)
+    globals()[name] = value
+    return value

tigrbl_base/_base/_alias_base.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Optional
+
+from tigrbl_core._spec.alias_spec import AliasSpec
+from tigrbl_core._spec.op_spec import Arity, PersistPolicy
+
+if TYPE_CHECKING:  # pragma: no cover
+    from tigrbl_core._spec.schema_spec import SchemaArg
+else:
+    SchemaArg = Any
+
+
+@dataclass(frozen=True)
+class AliasBase(AliasSpec):
+    """Base alias contract implementation shared by concrete aliases."""
+
+    _alias: str
+    _request_schema: Optional[SchemaArg] = None
+    _response_schema: Optional[SchemaArg] = None
+    _persist: Optional[PersistPolicy] = None
+    _arity: Optional[Arity] = None
+    _rest: Optional[bool] = None
+
+    @property
+    def alias(self) -> str:
+        return self._alias
+
+    @property
+    def request_schema(self) -> Optional[SchemaArg]:
+        return self._request_schema
+
+    @property
+    def response_schema(self) -> Optional[SchemaArg]:
+        return self._response_schema
+
+    @property
+    def persist(self) -> Optional[PersistPolicy]:
+        return self._persist
+
+    @property
+    def arity(self) -> Optional[Arity]:
+        return self._arity
+
+    @property
+    def rest(self) -> Optional[bool]:
+        return self._rest
+
+
+__all__ = ["AliasBase"]

tigrbl_base/_base/_app_base.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import inspect
+from typing import Any
+from typing import Callable, Optional, Sequence
+
+from tigrbl_core._spec.app_spec import AppSpec
+from tigrbl_core._spec.engine_spec import EngineCfg
+from tigrbl_core._spec.response_spec import ResponseSpec
+
+
+@dataclass(eq=False)
+class AppBase(AppSpec):
+    """Base app configuration helpers shared by concrete app implementations."""
+
+    title: str = "Tigrbl"
+    description: str | None = None
+    version: str = "0.1.0"
+    engine: Optional[EngineCfg] = None
+    routers: Sequence[Any] = ()
+    ops: Sequence[Any] = ()
+    tables: Sequence[Any] = ()
+    schemas: Sequence[Any] = ()
+    hooks: Sequence[Callable[..., Any]] = ()
+    security_deps: Sequence[Callable[..., Any]] = ()
+    deps: Sequence[Callable[..., Any]] = ()
+    response: Optional[ResponseSpec] = None
+    jsonrpc_prefix: str = "/rpc"
+    system_prefix: str = "/system"
+    middlewares: Sequence[Any] = ()
+    lifespan: Optional[Callable[..., Any]] = None
+
+    @staticmethod
+    def _is_bindable_child_class(candidate: Any) -> bool:
+        if not inspect.isclass(candidate):
+            return False
+
+        bindable_types: list[type[Any]] = []
+        for mod_name, type_name in (
+            ("._table_base", "TableBase"),
+            ("._op_base", "OpBase"),
+            ("._hook_base", "HookBase"),
+            ("._schema_base", "SchemaBase"),
+        ):
+            try:
+                module = __import__(
+                    f"tigrbl_base._base{mod_name}", fromlist=[type_name]
+                )
+                bindable = getattr(module, type_name, None)
+                if isinstance(bindable, type):
+                    bindable_types.append(bindable)
+            except Exception:
+                continue
+
+        if not bindable_types:
+            return False
+
+        try:
+            return issubclass(candidate, tuple(bindable_types))
+        except TypeError:
+            return False
+
+    @classmethod
+    def _bind_child_to_parent(cls, child: Any, *, parent: object | None) -> Any:
+        if parent is None:
+            return child
+
+        target = child
+        if cls._is_bindable_child_class(child):
+            try:
+                target = child()
+            except Exception:
+                target = child
+
+        for attr in ("app", "parent", "owner"):
+            if hasattr(target, attr):
+                try:
+                    setattr(target, attr, parent)
+                except Exception:
+                    pass
+
+        for attr in ("APP", "PARENT", "OWNER"):
+            if hasattr(target, attr):
+                try:
+                    setattr(target, attr, parent)
+                except Exception:
+                    pass
+
+        return target
+
+    @classmethod
+    def collect_spec(cls, app: type) -> AppSpec:
+        """Collect and normalize an ``AppSpec`` snapshot from an app type."""
+
+        spec = AppSpec.collect(app)
+        routers = tuple(dict.fromkeys(tuple(spec.routers or ())))
+        return AppSpec(
+            title=spec.title,
+            description=spec.description,
+            version=spec.version,
+            engine=spec.engine,
+            routers=routers,
+            ops=tuple(spec.ops or ()),
+            tables=tuple(spec.tables or ()),
+            schemas=tuple(spec.schemas or ()),
+            hooks=tuple(spec.hooks or ()),
+            security_deps=tuple(spec.security_deps or ()),
+            deps=tuple(spec.deps or ()),
+            response=spec.response,
+            jsonrpc_prefix=spec.jsonrpc_prefix,
+            system_prefix=spec.system_prefix,
+            middlewares=tuple(spec.middlewares or ()),
+            lifespan=spec.lifespan,
+        )
+
+    @classmethod
+    def _bind_mapped_children(
+        cls, children: Sequence[Any] | None, *, parent: object | None
+    ) -> tuple[Any, ...]:
+        return tuple(
+            cls._bind_child_to_parent(child, parent=parent)
+            for child in tuple(children or ())
+        )
+
+    @classmethod
+    def bind_spec(cls, spec: AppSpec, *, parent: object | None = None) -> AppSpec:
+        """Bind a collected AppSpec by attaching mapped children to the parent."""
+
+        return AppSpec(
+            title=str(spec.title or "Tigrbl"),
+            description=spec.description,
+            version=str(spec.version or "0.1.0"),
+            engine=spec.engine,
+            routers=cls._bind_mapped_children(spec.routers, parent=parent),
+            ops=cls._bind_mapped_children(spec.ops, parent=parent),
+            tables=cls._bind_mapped_children(spec.tables, parent=parent),
+            schemas=cls._bind_mapped_children(spec.schemas, parent=parent),
+            hooks=cls._bind_mapped_children(spec.hooks, parent=parent),
+            security_deps=tuple(spec.security_deps or ()),
+            deps=tuple(spec.deps or ()),
+            response=spec.response,
+            jsonrpc_prefix=str(spec.jsonrpc_prefix or "/rpc"),
+            system_prefix=str(spec.system_prefix or "/system"),
+            middlewares=tuple(spec.middlewares or ()),
+            lifespan=spec.lifespan,
+        )
+
+
+__all__ = ["AppBase"]

tigrbl_base/_base/_assembly.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from functools import singledispatch
+from typing import Any, Iterable
+
+
+_CHILD_ATTRS = ("routers", "tables", "ops", "hooks", "schemas", "columns")
+
+
+def iter_children(spec: Any) -> Iterable[tuple[str, str, Any]]:
+    for namespace in _CHILD_ATTRS:
+        children = getattr(spec, namespace, ()) or ()
+        if isinstance(children, dict):
+            for key, child in children.items():
+                yield namespace, str(key), child
+            continue
+        for child in tuple(children):
+            key = str(
+                getattr(child, "name", None)
+                or getattr(child, "alias", None)
+                or id(child)
+            )
+            yield namespace, key, child
+
+
+def bind_child(parent: Any, namespace: str, key: str, child: Any) -> Any:
+    slot = getattr(parent, namespace, None)
+    if hasattr(slot, "__setitem__"):
+        try:
+            slot[key] = child
+            return child
+        except Exception:
+            pass
+    for attr in ("app", "parent", "owner"):
+        if hasattr(child, attr):
+            try:
+                setattr(child, attr, parent)
+            except Exception:
+                pass
+    return child
+
+
+@singledispatch
+def maybe_convert(parent: Any, namespace: str, key: str, child: Any) -> Any:
+    return child
+
+
+def assemble(owner: Any) -> Any:
+    collector = getattr(type(owner), "collect", None)
+    spec = collector(owner) if callable(collector) else owner
+    for namespace, key, child in iter_children(spec):
+        assembled_child = assemble(child)
+        converted = maybe_convert(owner, namespace, key, assembled_child)
+        bind_child(owner, namespace, key, converted)
+    finalize = getattr(owner, "finalize", None)
+    if callable(finalize):
+        finalize(spec)
+    return owner

tigrbl_base/_base/_binding_base.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from tigrbl_core._spec.binding_spec import BindingRegistrySpec, BindingSpec
+
+
+class BindingBase(BindingSpec):
+    """Base named binding declaration."""
+
+
+class BindingRegistryBase(BindingRegistrySpec):
+    """Base named binding registry."""
+
+
+__all__ = ["BindingBase", "BindingRegistryBase"]

tigrbl_base/_base/_column_base.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import MappedColumn
+
+from tigrbl_core._spec.column_spec import ColumnSpec
+from tigrbl_core._spec.field_spec import FieldSpec as F
+from tigrbl_core._spec.io_spec import IOSpec as IO
+from tigrbl_core._spec.storage_spec import StorageSpec as S
+
+
+class ColumnBase(ColumnSpec, MappedColumn):
+    """Base SQLAlchemy column descriptor implementing :class:`ColumnSpec`."""
+
+    __slots__ = ()
+
+    def __init__(
+        self,
+        *,
+        spec: ColumnSpec | None = None,
+        storage: S | None = None,
+        field: F | None = None,
+        io: IO | None = None,
+        default_factory: Optional[Callable[[dict], Any]] = None,
+        read_producer: Optional[Callable[[object, dict], Any]] = None,
+        **kw: Any,
+    ) -> None:
+        if spec is not None and any(
+            x is not None for x in (storage, field, io, default_factory, read_producer)
+        ):
+            raise ValueError("Provide either spec or individual components, not both.")
+
+        if spec is None:
+            spec = ColumnSpec(
+                storage=storage,
+                field=field,
+                io=io,
+                default_factory=default_factory,
+                read_producer=read_producer,
+            )
+        else:
+            storage = spec.storage
+            field = spec.field
+            io = spec.io
+            default_factory = spec.default_factory
+            read_producer = spec.read_producer
+
+        s = storage
+        if s is not None:
+            args: list[Any] = [s.type_]
+            fk = getattr(s, "fk", None)
+            if fk is not None:
+                args.append(
+                    ForeignKey(
+                        fk.target,
+                        ondelete=fk.on_delete,
+                        onupdate=fk.on_update,
+                        deferrable=fk.deferrable,
+                        initially="DEFERRED" if fk.initially_deferred else "IMMEDIATE",
+                        match=fk.match,
+                    )
+                )
+            MappedColumn.__init__(
+                self,
+                *args,
+                primary_key=s.primary_key,
+                nullable=s.nullable,
+                unique=s.unique,
+                index=s.index,
+                default=s.default,
+                autoincrement=s.autoincrement,
+                server_default=s.server_default,
+                onupdate=s.onupdate,
+                comment=s.comment,
+                **kw,
+            )
+        else:
+            MappedColumn.__init__(self, **kw)
+
+        self.storage = s
+        self.field = field if field is not None else F()
+        self.io = io if io is not None else IO()
+        self.default_factory = default_factory
+        self.read_producer = read_producer
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        parent = getattr(super(), "__set_name__", None)
+        if parent:
+            parent(owner, name)
+
+        colspecs = owner.__dict__.get("__tigrbl_colspecs__")
+        if colspecs is None:
+            base_specs = getattr(owner, "__tigrbl_colspecs__", {})
+            colspecs = dict(base_specs)
+            setattr(owner, "__tigrbl_colspecs__", colspecs)
+        colspecs[name] = self
+
+
+__all__ = ["ColumnBase"]

tigrbl_base/_base/_engine_base.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class EngineBase:
+    """Base contract for concrete engine façade implementations."""
+
+    spec: Any
+
+    def to_provider(self) -> Any:  # pragma: no cover - interface contract
+        raise NotImplementedError
+
+
+__all__ = ["EngineBase"]

tigrbl_base/_base/_engine_provider_base.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class EngineProviderBase(Protocol):
+    """Provider-like runtime contract for engine provider objects."""
+
+    spec: Any
+
+    def to_provider(self) -> "EngineProviderBase": ...
+
+
+__all__ = ["EngineProviderBase"]

tigrbl_base/_base/_headers_base.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+
+class HeadersBase(dict[str, str]):
+    """Base header mapping type for response implementations."""
+
+
+class HeaderCookiesBase(dict[str, str]):
+    """Base cookie mapping type for response implementations."""
+
+
+__all__ = ["HeaderCookiesBase", "HeadersBase"]

tigrbl_base/_base/_hook_base.py

@@ -0,0 +1,25 @@
+"""Base runtime hook wrapper for Tigrbl v3."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Optional, Union
+
+from tigrbl_core._spec.hook_spec import HookSpec
+from tigrbl_atoms import HookPhase, StepFn
+
+
+@dataclass(frozen=True, slots=True)
+class HookBase(HookSpec):
+    """Base hook bound to a phase and one or more ops."""
+
+    phase: HookPhase
+    fn: StepFn
+    ops: Union[str, Iterable[str]] = "*"
+    order: int = 0
+    when: Optional[object] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+
+
+__all__ = ["HookBase"]

tigrbl_base/_base/_mapping_access.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class AttrDict(dict):
+    """Dictionary that also supports attribute-style access."""
+
+    def __getattr__(self, item: str) -> Any:  # pragma: no cover - trivial
+        try:
+            return self[item]
+        except KeyError as e:  # pragma: no cover - debug helper
+            raise AttributeError(item) from e
+
+    def __setattr__(self, key: str, value: Any) -> None:  # pragma: no cover - trivial
+        self[key] = value
+
+
+__all__ = ["AttrDict"]

tigrbl_base/_base/_middleware_base.py

@@ -0,0 +1,145 @@
+"""Request/response middleware base with ``dispatch`` + ``call_next`` semantics."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlencode
+
+from tigrbl_core._spec.middleware_spec import (
+    ASGIApp,
+    ASGIReceive,
+    ASGISend,
+    Message,
+    MiddlewareSpec,
+)
+
+from ._request_base import RequestBase
+from ._response_base import ResponseBase
+
+
+def finalize_transport_response(
+    scope: dict[str, Any],
+    status_code: int,
+    raw_headers: list[tuple[bytes, bytes]],
+    body: bytes,
+) -> tuple[list[tuple[bytes, bytes]], bytes]:
+    """Base transport finalization hook with pass-through defaults."""
+
+    del scope, status_code
+    return raw_headers, body
+
+
+class MiddlewareBase(MiddlewareSpec):
+    """Base middleware for intercepting HTTP requests in ASGI mode."""
+
+    def __init__(self, app: ASGIApp, **kwargs: Any) -> None:
+        self.app = app
+        self.kwargs = kwargs
+
+    async def dispatch(self, request: RequestBase, call_next: Any) -> ResponseBase:
+        return await call_next(request)
+
+    @staticmethod
+    def _scope_from_request(
+        scope: dict[str, Any], request: RequestBase
+    ) -> dict[str, Any]:
+        query_string = urlencode(
+            [
+                (name, value)
+                for name, values in request.query.items()
+                for value in values
+            ],
+            doseq=True,
+        ).encode("latin-1")
+        return {
+            **scope,
+            "method": request.method,
+            "path": request.path,
+            "query_string": query_string,
+            "headers": [
+                (key.encode("latin-1"), value.encode("latin-1"))
+                for key, value in request.headers.items()
+            ],
+            "root_path": request.script_name,
+        }
+
+    async def asgi(
+        self, scope: dict[str, Any], receive: ASGIReceive, send: ASGISend
+    ) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request_body = b""
+        more_body = True
+        while more_body:
+            message = await receive()
+            request_body += message.get("body", b"")
+            more_body = message.get("more_body", False)
+
+        request = RequestBase.from_scope(scope)
+        request.body = request_body
+
+        async def call_next(forward_request: RequestBase | None = None) -> ResponseBase:
+            target_request = forward_request or request
+            target_scope = self._scope_from_request(scope, target_request)
+
+            messages: list[Message] = []
+            body_sent = False
+
+            async def receive_for_app() -> Message:
+                nonlocal body_sent
+                if body_sent:
+                    return {"type": "http.request", "body": b"", "more_body": False}
+                body_sent = True
+                return {
+                    "type": "http.request",
+                    "body": target_request.body,
+                    "more_body": False,
+                }
+
+            async def send_from_app(message: Message) -> None:
+                messages.append(message)
+
+            await self.app(target_scope, receive_for_app, send_from_app)
+
+            start = next(m for m in messages if m.get("type") == "http.response.start")
+            raw_headers = list(start.get("headers", []))
+            body = b"".join(
+                m.get("body", b"")
+                for m in messages
+                if m.get("type") == "http.response.body"
+            )
+            headers, finalized_body = finalize_transport_response(
+                target_scope,
+                int(start.get("status", 200)),
+                raw_headers,
+                body,
+            )
+            return ResponseBase(
+                status_code=int(start.get("status", 200)),
+                headers=[
+                    (key.decode("latin-1"), value.decode("latin-1"))
+                    for key, value in headers
+                ],
+                body=finalized_body,
+            )
+
+        response = await self.dispatch(request, call_next)
+        headers, finalized_body = finalize_transport_response(
+            scope, response.status_code, response.raw_headers, response.body
+        )
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": response.status_code,
+                "headers": headers,
+            }
+        )
+        await send(
+            {"type": "http.response.body", "body": finalized_body, "more_body": False}
+        )
+
+
+__all__ = ["MiddlewareBase"]

tigrbl_base/_base/_op_base.py

@@ -0,0 +1,12 @@
+"""Base operation descriptor implementation for Tigrbl."""
+
+from __future__ import annotations
+
+from tigrbl_core._spec.op_spec import OpSpec
+
+
+class OpBase(OpSpec):
+    """Base operation descriptor type."""
+
+
+__all__ = ["OpBase"]