tigrbl-core 0.1.0__tar.gz

tigrbl_core-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: tigrbl-core
+Version: 0.1.0
+Summary: Core specifications and primitives for the Tigrbl framework.
+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.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)
+
+# tigrbl-core
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-core.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-core.svg) ![License](https://img.shields.io/pypi/l/tigrbl-core.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-core.svg)
+
+## Features
+
+- Core specification and primitive contracts for Tigrbl.
+- Operational implementations now live in `tigrbl-ops-oltp`.
+- Supports Python 3.10 through 3.12.
+
+## Installation
+
+### uv
+
+```bash
+uv add tigrbl-core
+```
+
+### pip
+
+```bash
+pip install tigrbl-core
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.
+

tigrbl_core-0.1.0/README.md

@@ -0,0 +1,29 @@
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-core
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-core.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-core.svg) ![License](https://img.shields.io/pypi/l/tigrbl-core.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-core.svg)
+
+## Features
+
+- Core specification and primitive contracts for Tigrbl.
+- Operational implementations now live in `tigrbl-ops-oltp`.
+- Supports Python 3.10 through 3.12.
+
+## Installation
+
+### uv
+
+```bash
+uv add tigrbl-core
+```
+
+### pip
+
+```bash
+pip install tigrbl-core
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.

tigrbl_core-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "tigrbl-core"
+version = "0.1.0"
+description = "Core specifications and primitives for the Tigrbl framework."
+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-typing",
+    "pydantic>=2.10,<3",
+    "pyyaml",
+    "tomli-w",
+    "tomli>=2.0.1; python_version < '3.11'",
+]
+keywords = ["tigrbl", "sdk", "standards", "framework"]
+
+[tool.uv.sources]
+"tigrbl-typing" = { workspace = true }
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry]
+packages = [
+    { include = "tigrbl_core" },
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.9",
+]

tigrbl_core-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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",
+]