tigrbl-base 0.1.0.dev5__tar.gz

tigrbl_base-0.1.0.dev5/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: tigrbl-base
+Version: 0.1.0.dev5
+Summary: Abstract base interfaces for Tigrbl APIs and runtime components.
+License-Expression: Apache-2.0
+Keywords: tigrbl,sdk,standards,framework
+Author: Jacob Stewart
+Author-email: jacob@swarmauri.com
+Requires-Python: >=3.10,<3.13
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Development Status :: 1 - Planning
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Dist: pydantic (>=2.0)
+Requires-Dist: sqlalchemy (>=2.0)
+Requires-Dist: tigrbl-atoms
+Requires-Dist: tigrbl-core
+Description-Content-Type: text/markdown
+
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-base
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-base.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-base.svg) ![License](https://img.shields.io/pypi/l/tigrbl-base.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-base.svg)
+
+## Features
+
+- Modular package in the Tigrbl namespace.
+- Supports Python 3.10 through 3.12.
+- Distributed as part of the swarmauri-sdk workspace.
+
+## Installation
+
+### uv
+
+```bash
+uv add tigrbl-base
+```
+
+### pip
+
+```bash
+pip install tigrbl-base
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.
+

tigrbl_base-0.1.0.dev5/README.md

@@ -0,0 +1,29 @@
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-base
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-base.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-base.svg) ![License](https://img.shields.io/pypi/l/tigrbl-base.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-base.svg)
+
+## Features
+
+- Modular package in the Tigrbl namespace.
+- Supports Python 3.10 through 3.12.
+- Distributed as part of the swarmauri-sdk workspace.
+
+## Installation
+
+### uv
+
+```bash
+uv add tigrbl-base
+```
+
+### pip
+
+```bash
+pip install tigrbl-base
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.

tigrbl_base-0.1.0.dev5/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "tigrbl-base"
+version = "0.1.0.dev5"
+description = "Abstract base interfaces for Tigrbl APIs and runtime components."
+license = "Apache-2.0"
+readme = "README.md"
+repository = "http://github.com/swarmauri/swarmauri-sdk"
+requires-python = ">=3.10,<3.13"
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Development Status :: 1 - Planning",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
+dependencies = [
+    "tigrbl-core",
+    "tigrbl-atoms",
+    "sqlalchemy>=2.0",
+    "pydantic>=2.0",
+]
+keywords = ["tigrbl", "sdk", "standards", "framework"]
+
+[tool.uv.sources]
+"tigrbl-core" = { workspace = true }
+"tigrbl-atoms" = { workspace = true }
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry]
+packages = [
+    { include = "tigrbl_base" },
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-timeout>=2.3.1",
+    "ruff>=0.9",
+]

tigrbl_base-0.1.0.dev5/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-0.1.0.dev5/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-0.1.0.dev5/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-0.1.0.dev5/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-0.1.0.dev5/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-0.1.0.dev5/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-0.1.0.dev5/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-0.1.0.dev5/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-0.1.0.dev5/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-0.1.0.dev5/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-0.1.0.dev5/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"]