tigrbl-core 0.1.0.dev1__tar.gz → 0.1.0.dev6__tar.gz

{tigrbl_core-0.1.0.dev1 → tigrbl_core-0.1.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrbl-core
-Version: 0.1.0.dev1
+Version: 0.1.0.dev6
 Summary: Core specifications and primitives for the Tigrbl framework.
 License-Expression: Apache-2.0
 Keywords: tigrbl,sdk,standards,framework
@@ -15,7 +15,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.10,<3)
+Requires-Dist: pyyaml
 Requires-Dist: tigrbl-typing
+Requires-Dist: tomli (>=2.0.1) ; python_version < "3.11"
+Requires-Dist: tomli-w
 Description-Content-Type: text/markdown
 
 ![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
@@ -26,9 +30,9 @@ Description-Content-Type: text/markdown
 
 ## Features
 
-- Modular package in the Tigrbl namespace.
+- Core specification and primitive contracts for Tigrbl.
+- Operational implementations now live in `tigrbl-ops-oltp`.
 - Supports Python 3.10 through 3.12.
-- Distributed as part of the swarmauri-sdk workspace.
 
 ## Installation
 

{tigrbl_core-0.1.0.dev1 → tigrbl_core-0.1.0.dev6}/README.md

@@ -6,9 +6,9 @@
 
 ## Features
 
-- Modular package in the Tigrbl namespace.
+- Core specification and primitive contracts for Tigrbl.
+- Operational implementations now live in `tigrbl-ops-oltp`.
 - Supports Python 3.10 through 3.12.
-- Distributed as part of the swarmauri-sdk workspace.
 
 ## Installation
 

{tigrbl_core-0.1.0.dev1 → tigrbl_core-0.1.0.dev6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tigrbl-core"
-version = "0.1.0.dev1"
+version = "0.1.0.dev6"
 description = "Core specifications and primitives for the Tigrbl framework."
 license = "Apache-2.0"
 readme = "README.md"
@@ -19,6 +19,10 @@ classifiers = [
 authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
 dependencies = [
     "tigrbl-typing",
+    "pydantic>=2.10,<3",
+    "pyyaml",
+    "tomli-w",
+    "tomli>=2.0.1; python_version < '3.11'",
 ]
 keywords = ["tigrbl", "sdk", "standards", "framework"]
 

{tigrbl_core-0.1.0.dev1 → tigrbl_core-0.1.0.dev6}/tigrbl_core/_spec/__init__.py

@@ -11,53 +11,74 @@ from typing import Any
 _EXPORTS = {
     "AliasSpec": "alias_spec",
     "AppSpec": "app_spec",
-    "Binding": "binding_spec",
-    "BindingRegistry": "binding_spec",
     "BindingSpec": "binding_spec",
+    "BindingRegistrySpec": "binding_spec",
+    "TransportBindingSpec": "binding_spec",
     "HttpRestBindingSpec": "binding_spec",
     "HttpJsonRpcBindingSpec": "binding_spec",
     "WsBindingSpec": "binding_spec",
     "resolve_rest_nested_prefix": "binding_spec",
     "ColumnSpec": "column_spec",
     "EngineSpec": "engine_spec",
+    "EngineProviderSpec": "engine_spec",
     "FieldSpec": "field_spec",
+    "F": "field_spec",
     "HookSpec": "hook_spec",
     "IOSpec": "io_spec",
+    "IO": "io_spec",
     "MiddlewareSpec": "middleware_spec",
     "OpSpec": "op_spec",
+    "Arity": "op_spec",
+    "TargetOp": "op_spec",
+    "PersistPolicy": "op_spec",
     "PHASE": "op_spec",
     "PHASES": "op_spec",
+    "HookPhase": "hook_spec",
     "TemplateSpec": "response_spec",
     "ResponseSpec": "response_spec",
+    "resolve_response_spec": "response_resolver",
     "RequestSpec": "request_spec",
     "RouterSpec": "router_spec",
     "SchemaSpec": "schema_spec",
     "SchemaRef": "schema_spec",
+    "SchemaArg": "schema_spec",
     "SessionSpec": "session_spec",
     "session_spec": "session_spec",
     "tx_read_committed": "session_spec",
     "tx_repeatable_read": "session_spec",
     "tx_serializable": "session_spec",
     "readonly": "session_spec",
-    "wrap_sessionmaker": "session_spec",
     "StorageSpec": "storage_spec",
+    "S": "storage_spec",
+    "StorageTransformSpec": "storage_spec",
     "StorageTransform": "storage_spec",
     "ForeignKeySpec": "storage_spec",
     "TableSpec": "table_spec",
     "TableRegistrySpec": "table_registry_spec",
-    "F": "shortcuts_spec",
-    "IO": "shortcuts_spec",
-    "S": "shortcuts_spec",
-    "makeColumn": "shortcuts_spec",
-    "makeVirtualColumn": "shortcuts_spec",
-    "acol": "shortcuts_spec",
-    "vcol": "shortcuts_spec",
 }
 
 __all__ = list(_EXPORTS)
 
 
 def __getattr__(name: str) -> Any:
+    if name in {"PHASE", "PHASES"}:
+        from .hook_types import HookPhase, HookPhases
+
+        value = HookPhase if name == "PHASE" else HookPhases
+        globals()[name] = value
+        return value
+    if name in {"F", "IO", "S"}:
+        aliases = {
+            "F": ("field_spec", "FieldSpec"),
+            "IO": ("io_spec", "IOSpec"),
+            "S": ("storage_spec", "StorageSpec"),
+        }
+        module_name, attr = aliases[name]
+        module = import_module(f"{__name__}.{module_name}")
+        value = getattr(module, attr)
+        globals()[name] = value
+        return value
+
     module_name = _EXPORTS.get(name)
     if module_name is None:
         raise AttributeError(name)

{tigrbl_core-0.1.0.dev1 → tigrbl_core-0.1.0.dev6}/tigrbl_core/_spec/alias_spec.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Optional
 from .._spec.op_spec import Arity, PersistPolicy
 
 if TYPE_CHECKING:  # pragma: no cover
-    from ..schema.types import SchemaArg
+    from .schema_spec import SchemaArg
 
 
 class AliasSpec(ABC):

{tigrbl_core-0.1.0.dev1 → tigrbl_core-0.1.0.dev6}/tigrbl_core/_spec/app_spec.py

@@ -1,14 +1,91 @@
 # pkgs/standards/tigrbl_core/tigrbl/_spec/app_spec.py
 from __future__ import annotations
 from dataclasses import dataclass, field
-from typing import Any, Callable, Optional, Sequence
+from typing import Any, Callable, Iterable, Mapping, Optional, Sequence
 
 from .._spec.engine_spec import EngineCfg
 from .._spec.response_spec import ResponseSpec
+from .serde import SerdeMixin
+
+
+def _seqify(value: Any) -> tuple[Any, ...]:
+    """Normalize sequence-like inputs while treating scalars as a single item."""
+
+    if value is None:
+        return ()
+    if isinstance(value, tuple):
+        return value
+    if isinstance(value, (str, bytes, bytearray)):
+        return (value,)
+    if isinstance(value, Mapping):
+        return (value,)
+    if isinstance(value, Iterable):
+        return tuple(value)
+    return (value,)
+
+
+def merge_seq_attr(
+    owner: type,
+    attr: str,
+    *,
+    include_inherited: bool = False,
+    reverse: bool = False,
+    dedupe: bool = True,
+) -> tuple[Any, ...]:
+    """Merge sequence-like class attributes over the MRO."""
+
+    values: list[Any] = []
+    seen_hashable: set[Any] = set()
+    mro = reversed(owner.__mro__) if reverse else owner.__mro__
+    for base in mro:
+        if include_inherited:
+            if not hasattr(base, attr):
+                continue
+            seq = getattr(base, attr) or ()
+        else:
+            seq = base.__dict__.get(attr, ()) or ()
+        for item in _seqify(seq):
+            if dedupe:
+                try:
+                    if item in seen_hashable:
+                        continue
+                    seen_hashable.add(item)
+                except TypeError:
+                    if any(item == existing for existing in values):
+                        continue
+            values.append(item)
+    return tuple(values)
+
+
+def normalize_app_spec(spec: "AppSpec") -> "AppSpec":
+    """Return a normalized app spec snapshot with stable sequence fields."""
+
+    routers = _seqify(spec.routers)
+    tables = _seqify(spec.tables)
+    ops = _seqify(spec.ops)
+
+    return AppSpec(
+        title=str(spec.title or "Tigrbl"),
+        description=spec.description,
+        version=str(spec.version or "0.1.0"),
+        engine=spec.engine,
+        routers=routers,
+        ops=ops,
+        tables=tables,
+        schemas=_seqify(spec.schemas),
+        hooks=_seqify(spec.hooks),
+        security_deps=_seqify(spec.security_deps),
+        deps=_seqify(spec.deps),
+        middlewares=_seqify(spec.middlewares),
+        response=spec.response,
+        jsonrpc_prefix=str(spec.jsonrpc_prefix or "/rpc"),
+        system_prefix=str(spec.system_prefix or "/system"),
+        lifespan=spec.lifespan,
+    )
 
 
 @dataclass(eq=False)
-class AppSpec:
+class AppSpec(SerdeMixin):
     """
     Used to *produce an App subclass* via App.from_spec().
     """
@@ -43,9 +120,11 @@ class AppSpec:
     lifespan: Optional[Callable[..., Any]] = None
 
     @classmethod
-    def collect(cls, app: type) -> "AppSpec":
-        from ..mapping.spec_normalization import merge_seq_attr, normalize_app_spec
+    def from_dict(cls, payload: dict[str, Any]) -> "AppSpec":
+        return super().from_dict(payload)
 
+    @classmethod
+    def collect(cls, app: type) -> "AppSpec":
         sentinel = object()
         title: Any = sentinel
         version: Any = sentinel

{tigrbl_core-0.1.0.dev1 → tigrbl_core-0.1.0.dev6}/tigrbl_core/_spec/binding_spec.py

@@ -1,60 +1,60 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Literal, Optional, Type, Union
 
 from ..config.constants import TIGRBL_NESTED_PATHS_ATTR
+from .serde import SerdeMixin
 
 
 @dataclass(frozen=True, slots=True)
-class HttpRestBindingSpec:
+class HttpRestBindingSpec(SerdeMixin):
     proto: Literal["http.rest", "https.rest"]
     methods: tuple[str, ...]
     path: str
 
 
 @dataclass(frozen=True, slots=True)
-class HttpJsonRpcBindingSpec:
+class HttpJsonRpcBindingSpec(SerdeMixin):
     proto: Literal["http.jsonrpc", "https.jsonrpc"]
     rpc_method: str
 
 
 @dataclass(frozen=True, slots=True)
-class WsBindingSpec:
+class WsBindingSpec(SerdeMixin):
     proto: Literal["ws", "wss"]
     path: str
     subprotocols: tuple[str, ...] = ()
 
 
-BindingSpec = Union[HttpRestBindingSpec, HttpJsonRpcBindingSpec, WsBindingSpec]
+TransportBindingSpec = Union[
+    HttpRestBindingSpec,
+    HttpJsonRpcBindingSpec,
+    WsBindingSpec,
+]
 
 
 @dataclass(frozen=True, slots=True)
-class Binding:
+class BindingSpec(SerdeMixin):
     """Named binding declaration used for registry composition."""
 
-    """Named binding wrapper used by registries and planners."""
-
     name: str
-    spec: BindingSpec
+    spec: TransportBindingSpec
 
 
 @dataclass(slots=True)
-class BindingRegistry:
+class BindingRegistrySpec(SerdeMixin):
     """Simple in-memory registry for named transport bindings."""
 
-    _bindings: dict[str, Binding]
-
-    def __init__(self) -> None:
-        self._bindings = {}
+    _bindings: dict[str, BindingSpec] = field(default_factory=dict)
 
-    def register(self, binding: Binding) -> None:
+    def register(self, binding: BindingSpec) -> None:
         self._bindings[binding.name] = binding
 
-    def get(self, name: str) -> Optional[Binding]:
+    def get(self, name: str) -> Optional[BindingSpec]:
         return self._bindings.get(name)
 
-    def values(self) -> tuple[Binding, ...]:
+    def values(self) -> tuple[BindingSpec, ...]:
         return tuple(self._bindings.values())
 
 
@@ -68,11 +68,11 @@ def resolve_rest_nested_prefix(model: Type) -> Optional[str]:
 
 
 __all__ = [
-    "Binding",
-    "BindingRegistry",
     "BindingSpec",
+    "BindingRegistrySpec",
     "HttpJsonRpcBindingSpec",
     "HttpRestBindingSpec",
+    "TransportBindingSpec",
     "WsBindingSpec",
     "resolve_rest_nested_prefix",
 ]

tigrbl_core-0.1.0.dev6/tigrbl_core/_spec/column_spec.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from types import SimpleNamespace
+from typing import Any, Callable, Dict, Optional
+
+from .._spec.field_spec import FieldSpec as F
+from .._spec.io_spec import IOSpec as IO
+from .._spec.storage_spec import StorageSpec as S
+from .serde import SerdeMixin
+
+logger = logging.getLogger("uvicorn")
+
+
+class ColumnSpec(SerdeMixin):
+    """Aggregate configuration for a model attribute.
+
+    A :class:`ColumnSpec` brings together the three lower-level specs used by
+    Tigrbl's declarative column system:
+
+    - ``storage`` (:class:`~tigrbl._spec.storage_spec.StorageSpec`) controls
+      how the value is persisted in the database.
+    - ``field`` (:class:`~tigrbl._spec.field_spec.FieldSpec`) describes the
+      Python type and any schema metadata.
+    - ``io`` (:class:`~tigrbl._spec.io_spec.IOSpec`) governs inbound and
+      outbound API exposure.
+
+    Optional ``default_factory`` and ``read_producer`` callables allow for
+    programmatic defaults and virtual read-time values respectively.
+    """
+
+    def __init__(
+        self,
+        *,
+        storage: S | None,
+        field: F | None = None,
+        io: IO | None = None,
+        default_factory: Optional[Callable[[dict], Any]] = None,
+        read_producer: Optional[Callable[[object, dict], Any]] = None,
+    ) -> None:
+        self.storage = storage
+        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
+
+    # Default inbound/outbound verbs for columns lacking an explicit ColumnSpec.
+    #
+    # Without this, plain SQLAlchemy ``Column`` definitions are omitted from the
+    # collected spec map, causing downstream components to treat their values as
+    # unknown. By seeding such columns with a permissive IO spec we ensure they
+    # participate in canonical CRUD operations just like columns defined via
+    # ``acol``.
+    _DEFAULT_IO = IO(
+        in_verbs=("create", "update", "replace"),
+        out_verbs=("read", "list"),
+        mutable_verbs=("create", "update", "replace"),
+    )
+
+    @staticmethod
+    def _model_label(model: object) -> str:
+        return str(
+            getattr(model, "__name__", None)
+            or getattr(model, "name", None)
+            or type(model).__name__
+        )
+
+    @staticmethod
+    def _coerce_columns_iterable(columns: object) -> tuple[object, ...]:
+        """Normalize model/table column containers to an iterable tuple.
+
+        Some table classes expose ``columns`` as a ``SimpleNamespace`` of
+        ``ColumnSpec`` objects for convenience. Runtime collectors should treat
+        that namespace as a mapping and iterate over its values rather than
+        trying to iterate the namespace object directly.
+        """
+
+        if isinstance(columns, SimpleNamespace):
+            return tuple(columns.__dict__.values())
+        if isinstance(columns, dict):
+            return tuple(columns.values())
+        try:
+            return tuple(columns)  # type: ignore[arg-type]
+        except TypeError:
+            return ()
+
+    @staticmethod
+    @lru_cache(maxsize=None)
+    def _mro_collect_columns_cached(
+        model: object, _cache_bust: int
+    ) -> Dict[str, "ColumnSpec"]:
+        """Collect ColumnSpecs declared on *model* and all mixins.
+
+        Iterates across the model's MRO so that mixin-defined columns are
+        included in the resulting mapping. Later definitions take precedence
+        over earlier ones in the MRO. Any table-backed columns lacking a spec
+        are populated with a default ColumnSpec so they participate in opviews
+        and schema generation.
+        """
+        logger.debug("Collecting columns for %s", ColumnSpec._model_label(model))
+        out: Dict[str, ColumnSpec] = {}
+        mro = getattr(model, "__mro__", ()) or ()
+        for base in reversed(mro):
+            mapping = getattr(base, "__tigrbl_colspecs__", None)
+            if isinstance(mapping, dict):
+                out.update(mapping)
+            mapping = getattr(base, "__tigrbl_cols__", None)
+            if isinstance(mapping, dict):
+                out.update(mapping)
+
+        cols = None
+        table = getattr(model, "__table__", None)
+        if table is not None:
+            cols = getattr(table, "columns", None)
+        elif hasattr(model, "columns"):
+            cols = getattr(model, "columns", None)
+
+        if cols is not None:
+            for col in ColumnSpec._coerce_columns_iterable(cols):
+                name = getattr(col, "key", None) or getattr(col, "name", None)
+                if not isinstance(name, str):
+                    continue
+                out.setdefault(name, ColumnSpec(storage=S(), io=ColumnSpec._DEFAULT_IO))
+        else:
+            # Declarative models can be inspected before SQLAlchemy finishes
+            # materializing ``__table__``. In that transient state plain
+            # ``Column(...)`` declarations still exist on the class body and
+            # should participate in schema inference.
+            for base in reversed(mro):
+                for attr_name, value in vars(base).items():
+                    if attr_name.startswith("_") or attr_name in out:
+                        continue
+                    if hasattr(value, "type") and hasattr(value, "nullable"):
+                        out[attr_name] = ColumnSpec(
+                            storage=S(), io=ColumnSpec._DEFAULT_IO
+                        )
+
+        logger.debug(
+            "Collected %d columns for %s", len(out), ColumnSpec._model_label(model)
+        )
+        return out
+
+    @classmethod
+    def collect(
+        cls, model: object, *, _cache_bust: int | None = None
+    ) -> Dict[str, "ColumnSpec"]:
+        """Collect ColumnSpecs for *model* with topology-aware cache busting."""
+
+        if _cache_bust is None:
+            table = getattr(model, "__table__", None)
+            cols = getattr(table, "columns", None) if table is not None else None
+            col_count = (
+                len(cls._coerce_columns_iterable(cols)) if cols is not None else 0
+            )
+            _cache_bust = hash(
+                (
+                    id(getattr(model, "__tigrbl_colspecs__", None)),
+                    id(getattr(model, "__tigrbl_cols__", None)),
+                    id(table),
+                    col_count,
+                )
+            )
+        return cls._mro_collect_columns_cached(model, _cache_bust)
+
+    @classmethod
+    def mro_collect_columns(
+        cls, model: object, *, _cache_bust: int | None = None
+    ) -> Dict[str, "ColumnSpec"]:
+        """Backward-compatible alias for :meth:`collect`."""
+
+        return cls.collect(model, _cache_bust=_cache_bust)
+
+
+def mro_collect_columns(
+    model: object, *, _cache_bust: int | None = None
+) -> Dict[str, ColumnSpec]:
+    return ColumnSpec.collect(model, _cache_bust=_cache_bust)
+
+
+mro_collect_columns.cache_clear = ColumnSpec._mro_collect_columns_cached.cache_clear
+
+__all__ = ["ColumnSpec", "mro_collect_columns"]