tigrbl-core 0.1.0.dev1__tar.gz

tigrbl_core-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: tigrbl-core
+Version: 0.1.0.dev1
+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: tigrbl-typing
+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
+
+- 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-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.dev1/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
+
+- 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-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.dev1/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "tigrbl-core"
+version = "0.1.0.dev1"
+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",
+]
+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.dev1/tigrbl_core/_spec/__init__.py

@@ -0,0 +1,67 @@
+"""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",
+    "Binding": "binding_spec",
+    "BindingRegistry": "binding_spec",
+    "BindingSpec": "binding_spec",
+    "HttpRestBindingSpec": "binding_spec",
+    "HttpJsonRpcBindingSpec": "binding_spec",
+    "WsBindingSpec": "binding_spec",
+    "resolve_rest_nested_prefix": "binding_spec",
+    "ColumnSpec": "column_spec",
+    "EngineSpec": "engine_spec",
+    "FieldSpec": "field_spec",
+    "HookSpec": "hook_spec",
+    "IOSpec": "io_spec",
+    "MiddlewareSpec": "middleware_spec",
+    "OpSpec": "op_spec",
+    "PHASE": "op_spec",
+    "PHASES": "op_spec",
+    "TemplateSpec": "response_spec",
+    "ResponseSpec": "response_spec",
+    "RequestSpec": "request_spec",
+    "RouterSpec": "router_spec",
+    "SchemaSpec": "schema_spec",
+    "SchemaRef": "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",
+    "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:
+    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.dev1/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.types 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.dev1/tigrbl_core/_spec/app_spec.py

@@ -0,0 +1,137 @@
+# 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 .._spec.engine_spec import EngineCfg
+from .._spec.response_spec import ResponseSpec
+
+
+@dataclass(eq=False)
+class AppSpec:
+    """
+    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 collect(cls, app: type) -> "AppSpec":
+        from ..mapping.spec_normalization import merge_seq_attr, normalize_app_spec
+
+        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.dev1/tigrbl_core/_spec/binding_spec.py

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

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

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any, Callable, 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
+
+
+class ColumnSpec:
+    """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