tigrbl-core 0.1.0.dev5__py3-none-any.whl

tigrbl_core/_spec/__init__.py

@@ -0,0 +1,88 @@
+"""Canonical spec package.
+
+Keep this module import-light to avoid circular imports during package startup.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+_EXPORTS = {
+    "AliasSpec": "alias_spec",
+    "AppSpec": "app_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",
+    "StorageSpec": "storage_spec",
+    "S": "storage_spec",
+    "StorageTransformSpec": "storage_spec",
+    "StorageTransform": "storage_spec",
+    "ForeignKeySpec": "storage_spec",
+    "TableSpec": "table_spec",
+    "TableRegistrySpec": "table_registry_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)
+    module = import_module(f"{__name__}.{module_name}")
+    value = getattr(module, name)
+    globals()[name] = value
+    return value

tigrbl_core/_spec/alias_spec.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Optional
+
+from .._spec.op_spec import Arity, PersistPolicy
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .schema_spec import SchemaArg
+
+
+class AliasSpec(ABC):
+    @property
+    @abstractmethod
+    def alias(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def request_schema(self) -> Optional[SchemaArg]: ...
+
+    @property
+    @abstractmethod
+    def response_schema(self) -> Optional[SchemaArg]: ...
+
+    @property
+    @abstractmethod
+    def persist(self) -> Optional[PersistPolicy]: ...
+
+    @property
+    @abstractmethod
+    def arity(self) -> Optional[Arity]: ...
+
+    @property
+    @abstractmethod
+    def rest(self) -> Optional[bool]: ...

tigrbl_core/_spec/app_spec.py

@@ -0,0 +1,216 @@
+# pkgs/standards/tigrbl_core/tigrbl/_spec/app_spec.py
+from __future__ import annotations
+from dataclasses import dataclass, field
+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(SerdeMixin):
+    """
+    Used to *produce an App subclass* via App.from_spec().
+    """
+
+    title: str = "Tigrbl"
+    description: str | None = None
+    version: str = "0.1.0"
+    engine: Optional[EngineCfg] = None
+
+    # NEW: multi-Router composition (store Router classes or instances)
+    routers: Sequence[Any] = field(default_factory=tuple)
+
+    # NEW: orchestration/topology knobs
+    ops: Sequence[Any] = field(default_factory=tuple)  # op descriptors or specs
+    tables: Sequence[Any] = field(default_factory=tuple)  # table refs owned by app
+    schemas: Sequence[Any] = field(default_factory=tuple)  # schema classes/defs
+    hooks: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+
+    # security/dep stacks (ASGI dependencies or callables)
+    security_deps: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+    deps: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+
+    # response defaults
+    response: Optional[ResponseSpec] = None
+
+    # system routing prefixes (REST/JSON-RPC namespaces)
+    jsonrpc_prefix: str = "/rpc"
+    system_prefix: str = "/system"
+
+    # optional framework bits
+    middlewares: Sequence[Any] = field(default_factory=tuple)
+    lifespan: Optional[Callable[..., Any]] = None
+
+    @classmethod
+    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
+        engine: Any | None = sentinel  # type: ignore[assignment]
+        response: Any = sentinel
+        jsonrpc_prefix: Any = sentinel
+        system_prefix: Any = sentinel
+        lifespan: Any = sentinel
+
+        for base in app.__mro__:
+            if "TITLE" in base.__dict__ and title is sentinel:
+                title = base.__dict__["TITLE"]
+            if "VERSION" in base.__dict__ and version is sentinel:
+                version = base.__dict__["VERSION"]
+            if "ENGINE" in base.__dict__ and engine is sentinel:
+                engine = base.__dict__["ENGINE"]
+            if "RESPONSE" in base.__dict__ and response is sentinel:
+                response = base.__dict__["RESPONSE"]
+            if "JSONRPC_PREFIX" in base.__dict__ and jsonrpc_prefix is sentinel:
+                jsonrpc_prefix = base.__dict__["JSONRPC_PREFIX"]
+            if "SYSTEM_PREFIX" in base.__dict__ and system_prefix is sentinel:
+                system_prefix = base.__dict__["SYSTEM_PREFIX"]
+            if "LIFESPAN" in base.__dict__ and lifespan is sentinel:
+                lifespan = base.__dict__["LIFESPAN"]
+
+        if title is sentinel:
+            title = "Tigrbl"
+        if version is sentinel:
+            version = "0.1.0"
+        if engine is sentinel:
+            engine = None
+        if response is sentinel:
+            response = None
+        if jsonrpc_prefix is sentinel:
+            jsonrpc_prefix = "/rpc"
+        if system_prefix is sentinel:
+            system_prefix = "/system"
+        if lifespan is sentinel:
+            lifespan = None
+
+        description = getattr(app, "DESCRIPTION", None)
+        include_inherited_routers = "ROUTERS" not in app.__dict__
+        spec = cls(
+            title=title,
+            description=description,
+            version=version,
+            engine=engine,
+            routers=tuple(
+                merge_seq_attr(
+                    app,
+                    "ROUTERS",
+                    include_inherited=include_inherited_routers,
+                    reverse=include_inherited_routers,
+                    dedupe=False,
+                )
+                or ()
+            ),
+            ops=tuple(merge_seq_attr(app, "OPS") or ()),
+            tables=tuple(merge_seq_attr(app, "TABLES") or ()),
+            schemas=tuple(merge_seq_attr(app, "SCHEMAS") or ()),
+            hooks=tuple(merge_seq_attr(app, "HOOKS") or ()),
+            security_deps=tuple(merge_seq_attr(app, "SECURITY_DEPS") or ()),
+            deps=tuple(merge_seq_attr(app, "DEPS") or ()),
+            response=response,
+            jsonrpc_prefix=(jsonrpc_prefix or "/rpc"),
+            system_prefix=(system_prefix or "/system"),
+            middlewares=tuple(merge_seq_attr(app, "MIDDLEWARES") or ()),
+            lifespan=lifespan,
+        )
+        return normalize_app_spec(
+            cls(
+                title=spec.title,
+                description=spec.description,
+                version=spec.version,
+                engine=spec.engine,
+                routers=tuple(spec.routers or ()),
+                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 or "/rpc"),
+                system_prefix=(spec.system_prefix or "/system"),
+                middlewares=tuple(spec.middlewares or ()),
+                lifespan=spec.lifespan,
+            )
+        )

tigrbl_core/_spec/binding_spec.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+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(SerdeMixin):
+    proto: Literal["http.rest", "https.rest"]
+    methods: tuple[str, ...]
+    path: str
+
+
+@dataclass(frozen=True, slots=True)
+class HttpJsonRpcBindingSpec(SerdeMixin):
+    proto: Literal["http.jsonrpc", "https.jsonrpc"]
+    rpc_method: str
+
+
+@dataclass(frozen=True, slots=True)
+class WsBindingSpec(SerdeMixin):
+    proto: Literal["ws", "wss"]
+    path: str
+    subprotocols: tuple[str, ...] = ()
+
+
+TransportBindingSpec = Union[
+    HttpRestBindingSpec,
+    HttpJsonRpcBindingSpec,
+    WsBindingSpec,
+]
+
+
+@dataclass(frozen=True, slots=True)
+class BindingSpec(SerdeMixin):
+    """Named binding declaration used for registry composition."""
+
+    name: str
+    spec: TransportBindingSpec
+
+
+@dataclass(slots=True)
+class BindingRegistrySpec(SerdeMixin):
+    """Simple in-memory registry for named transport bindings."""
+
+    _bindings: dict[str, BindingSpec] = field(default_factory=dict)
+
+    def register(self, binding: BindingSpec) -> None:
+        self._bindings[binding.name] = binding
+
+    def get(self, name: str) -> Optional[BindingSpec]:
+        return self._bindings.get(name)
+
+    def values(self) -> tuple[BindingSpec, ...]:
+        return tuple(self._bindings.values())
+
+
+def resolve_rest_nested_prefix(model: Type) -> Optional[str]:
+    """Return the configured nested REST prefix for ``model`` if present."""
+
+    cb = getattr(model, TIGRBL_NESTED_PATHS_ATTR, None)
+    if callable(cb):
+        return cb()
+    return getattr(model, "_nested_path", None)
+
+
+__all__ = [
+    "BindingSpec",
+    "BindingRegistrySpec",
+    "HttpJsonRpcBindingSpec",
+    "HttpRestBindingSpec",
+    "TransportBindingSpec",
+    "WsBindingSpec",
+    "resolve_rest_nested_prefix",
+]

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"]