tigrbl-canon 0.1.0__tar.gz

tigrbl_canon-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: tigrbl-canon
+Version: 0.1.0
+Summary: Canonical mapping and routing resolution utilities for Tigrbl.
+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
+Requires-Dist: tigrbl-atoms
+Requires-Dist: tigrbl-base
+Requires-Dist: tigrbl-core
+Requires-Dist: tigrbl-ops-oltp
+Requires-Dist: tigrbl-runtime
+Description-Content-Type: text/markdown
+
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-canon
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-canon.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-canon.svg) ![License](https://img.shields.io/pypi/l/tigrbl-canon.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-canon.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-canon
+```
+
+### pip
+
+```bash
+pip install tigrbl-canon
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.
+

tigrbl_canon-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-canon
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-canon.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-canon.svg) ![License](https://img.shields.io/pypi/l/tigrbl-canon.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-canon.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-canon
+```
+
+### pip
+
+```bash
+pip install tigrbl-canon
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.

tigrbl_canon-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "tigrbl-canon"
+version = "0.1.0"
+description = "Canonical mapping and routing resolution utilities for Tigrbl."
+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-ops-oltp",
+    "tigrbl-base",
+    "tigrbl-core",
+    "tigrbl-runtime",
+    "tigrbl-atoms",
+    "tigrbl",
+]
+keywords = ["tigrbl", "sdk", "standards", "framework"]
+
+[tool.uv.sources]
+"tigrbl-ops-oltp" = { workspace = true }
+"tigrbl-base" = { workspace = true }
+"tigrbl-core" = { workspace = true }
+"tigrbl-runtime" = { workspace = true }
+"tigrbl-atoms" = { workspace = true }
+"tigrbl" = { workspace = true }
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry]
+packages = [
+    { include = "tigrbl_canon" },
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.9",
+]

tigrbl_canon-0.1.0/tigrbl_canon/__init__.py

@@ -0,0 +1,14 @@
+"""Tigrbl canon compatibility package."""
+
+from __future__ import annotations
+
+import warnings
+
+_DEPRECATION_MESSAGE = (
+    "tigrbl_canon is deprecated, not supported anymore, and likely to break. "
+    "Migrate away from tigrbl_canon imports as soon as possible."
+)
+
+warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
+
+__all__ = ["_DEPRECATION_MESSAGE"]

tigrbl_canon-0.1.0/tigrbl_canon/column/infer/__init__.py

@@ -0,0 +1,25 @@
+from .core import infer
+from .types import (
+    Email,
+    Phone,
+    DataKind,
+    PyTypeInfo,
+    SATypePlan,
+    JsonHint,
+    Inferred,
+    InferenceError,
+    UnsupportedType,
+)
+
+__all__ = [
+    "infer",
+    "Email",
+    "Phone",
+    "DataKind",
+    "PyTypeInfo",
+    "SATypePlan",
+    "JsonHint",
+    "Inferred",
+    "InferenceError",
+    "UnsupportedType",
+]

tigrbl_canon-0.1.0/tigrbl_canon/column/infer/core.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, get_origin
+
+from .types import DataKind, PyTypeInfo, Inferred
+from .utils import _strip_optional, _strip_annotated, _array_item, _is_enum
+from .planning import _plan_sa_type
+from .jsonhints import _json_hint
+
+
+def infer(
+    annotation: Any,
+    *,
+    prefer_dialect: Optional[str] = "postgresql",
+    max_length: Optional[int] = None,
+    decimal_precision: Optional[int] = None,
+    decimal_scale: Optional[int] = None,
+) -> Inferred:
+    """Bind-time inference from Python annotation to DataKind and hints."""
+    base, is_opt = _strip_optional(annotation)
+    base, meta = _strip_annotated(base)
+
+    enum_cls = _is_enum(base)
+    item_tp = _array_item(base)
+
+    array_item_info: Optional[PyTypeInfo] = None
+    if item_tp is not None:
+        nested = infer(
+            item_tp,
+            prefer_dialect=prefer_dialect,
+            max_length=max_length,
+            decimal_precision=decimal_precision,
+            decimal_scale=decimal_scale,
+        )
+        array_item_info = nested.py
+
+    py_info = PyTypeInfo(
+        base=base,
+        is_optional=is_opt,
+        enum_cls=enum_cls,
+        array_item=array_item_info,
+        annotated=meta,
+    )
+
+    import datetime as _dt
+    import decimal as _dc
+    import uuid as _uuid
+
+    origin = get_origin(base)
+
+    if enum_cls is not None:
+        kind = DataKind.ENUM
+    elif item_tp is not None:
+        kind = DataKind.ARRAY
+    elif base in (str,):
+        kind = DataKind.STRING
+    elif base in (bytes, bytearray, memoryview):
+        kind = DataKind.BYTES
+    elif base in (bool,):
+        kind = DataKind.BOOL
+    elif base in (int,):
+        kind = DataKind.INT
+    elif base in (float,):
+        kind = DataKind.FLOAT
+    elif base in (_dc.Decimal,):
+        kind = DataKind.DECIMAL
+    elif base in (_dt.datetime,):
+        kind = DataKind.DATETIME
+    elif base in (_dt.date,):
+        kind = DataKind.DATE
+    elif base in (_dt.time,):
+        kind = DataKind.TIME
+    elif base in (_uuid.UUID,):
+        kind = DataKind.UUID
+    else:
+        if origin in (dict, Dict):
+            kind = DataKind.JSON
+        else:
+            kind = DataKind.JSON
+
+    sa = _plan_sa_type(
+        kind,
+        py_info,
+        prefer_dialect=prefer_dialect,
+        max_length=max_length,
+        decimal_precision=decimal_precision,
+        decimal_scale=decimal_scale,
+    )
+
+    jh = _json_hint(kind, py_info, max_length=max_length)
+
+    return Inferred(kind=kind, py=py_info, sa=sa, json=jh, nullable=is_opt)

tigrbl_canon-0.1.0/tigrbl_canon/column/infer/jsonhints.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .types import DataKind, PyTypeInfo, JsonHint, Email, Phone
+from .planning import _nested_kind_from_py
+
+
+def _json_hint(
+    kind: DataKind, py: PyTypeInfo, *, max_length: Optional[int]
+) -> JsonHint:
+    if kind is DataKind.STRING:
+        fmt = None
+        if Email in py.annotated:
+            fmt = "email"
+        if Phone in py.annotated:
+            fmt = "phone"
+        return JsonHint(type="string", format=fmt, maxLength=max_length)
+    if kind is DataKind.BYTES:
+        return JsonHint(type="string", format="byte")
+    if kind is DataKind.BOOL:
+        return JsonHint(type="boolean")
+    if kind is DataKind.INT or kind is DataKind.BIGINT:
+        return JsonHint(type="integer")
+    if kind is DataKind.FLOAT or kind is DataKind.DECIMAL:
+        return JsonHint(type="number")
+    if kind is DataKind.DATE:
+        return JsonHint(type="string", format="date")
+    if kind is DataKind.TIME:
+        return JsonHint(type="string", format="time")
+    if kind is DataKind.DATETIME:
+        return JsonHint(type="string", format="date-time")
+    if kind is DataKind.UUID:
+        return JsonHint(type="string", format="uuid")
+    if kind is DataKind.JSON:
+        return JsonHint(type="object")
+    if kind is DataKind.ENUM and py.enum_cls:
+        return JsonHint(type="string", enum=[e.name for e in py.enum_cls])
+    if kind is DataKind.ARRAY and py.array_item:
+        elem_kind = _nested_kind_from_py(py.array_item)
+        return JsonHint(
+            type="array", items=_json_hint(elem_kind, py.array_item, max_length=None)
+        )
+    return JsonHint(type="string")

tigrbl_canon-0.1.0/tigrbl_canon/column/infer/planning.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .types import DataKind, PyTypeInfo, SATypePlan, InferenceError
+
+
+def _plan_sa_type(
+    kind: DataKind,
+    py: PyTypeInfo,
+    *,
+    prefer_dialect: Optional[str],
+    max_length: Optional[int],
+    decimal_precision: Optional[int],
+    decimal_scale: Optional[int],
+) -> SATypePlan:
+    d = prefer_dialect
+
+    if kind is DataKind.STRING:
+        if max_length and max_length > 0:
+            return SATypePlan(
+                name="String", args=(max_length,), kwargs={}, dialect=None
+            )
+        return SATypePlan(name="String", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.TEXT:
+        return SATypePlan(name="Text", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.BYTES:
+        return SATypePlan(name="LargeBinary", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.BOOL:
+        return SATypePlan(name="Boolean", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.INT:
+        return SATypePlan(name="Integer", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.BIGINT:
+        return SATypePlan(name="BigInteger", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.FLOAT:
+        return SATypePlan(name="Float", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.DECIMAL:
+        kwargs: Dict[str, Any] = {}
+        if decimal_precision is not None:
+            kwargs["precision"] = decimal_precision
+        if decimal_scale is not None:
+            kwargs["scale"] = decimal_scale
+        return SATypePlan(name="Numeric", args=(), kwargs=kwargs, dialect=None)
+
+    if kind is DataKind.DATE:
+        return SATypePlan(name="Date", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.TIME:
+        return SATypePlan(name="Time", args=(), kwargs={"timezone": True}, dialect=None)
+
+    if kind is DataKind.DATETIME:
+        return SATypePlan(
+            name="DateTime", args=(), kwargs={"timezone": True}, dialect=None
+        )
+
+    if kind is DataKind.UUID:
+        if d == "postgresql":
+            return SATypePlan(
+                name="UUID", args=(), kwargs={"as_uuid": True}, dialect="postgresql"
+            )
+        return SATypePlan(name="String", args=(36,), kwargs={}, dialect=None)
+
+    if kind is DataKind.JSON:
+        if d == "postgresql":
+            return SATypePlan(name="JSONB", args=(), kwargs={}, dialect="postgresql")
+        return SATypePlan(name="JSON", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.ENUM:
+        if not py.enum_cls:
+            raise InferenceError("ENUM kind requires enum_cls in PyTypeInfo")
+        return SATypePlan(
+            name="Enum", args=(py.enum_cls,), kwargs={"native_enum": True}, dialect=None
+        )
+
+    if kind is DataKind.ARRAY:
+        if not py.array_item:
+            raise InferenceError("ARRAY kind requires array_item in PyTypeInfo")
+        elem_plan = _plan_sa_type(
+            _nested_kind_from_py(py.array_item),
+            py.array_item,
+            prefer_dialect=prefer_dialect,
+            max_length=None,
+            decimal_precision=None,
+            decimal_scale=None,
+        )
+        if prefer_dialect == "postgresql":
+            return SATypePlan(
+                name="ARRAY",
+                args=(elem_plan.name,),
+                kwargs={},
+                dialect="postgresql",
+            )
+        return SATypePlan(name="JSON", args=(), kwargs={}, dialect=None)
+
+    raise InferenceError(f"Cannot plan SA type for kind={kind!r}")
+
+
+def _nested_kind_from_py(nested_py: PyTypeInfo) -> DataKind:
+    if nested_py.enum_cls is not None:
+        return DataKind.ENUM
+    b = nested_py.base
+    import datetime as _dt
+    import decimal as _dc
+    import uuid as _uuid
+
+    if b is str:
+        return DataKind.STRING
+    if b in (bytes, bytearray, memoryview):
+        return DataKind.BYTES
+    if b is bool:
+        return DataKind.BOOL
+    if b is int:
+        return DataKind.INT
+    if b is float:
+        return DataKind.FLOAT
+    if b is _dc.Decimal:
+        return DataKind.DECIMAL
+    if b is _dt.datetime:
+        return DataKind.DATETIME
+    if b is _dt.date:
+        return DataKind.DATE
+    if b is _dt.time:
+        return DataKind.TIME
+    if b is _uuid.UUID:
+        return DataKind.UUID
+    return DataKind.JSON

tigrbl_canon-0.1.0/tigrbl_canon/column/infer/types.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple, Type
+
+
+# ---------------------------------------------------------------------------
+# Public markers (wire/adapters provide validation/normalization at runtime)
+# ---------------------------------------------------------------------------
+
+
+class Email:
+    """Marker indicating email string semantics."""
+
+
+class Phone:
+    """Marker indicating E.164 phone string semantics."""
+
+
+# ---------------------------------------------------------------------------
+# Portable data-kind (DB- and adapter-agnostic)
+# ---------------------------------------------------------------------------
+
+
+class DataKind(str, Enum):
+    STRING = "string"
+    TEXT = "text"
+    BYTES = "bytes"
+    BOOL = "bool"
+    INT = "int"
+    BIGINT = "bigint"
+    FLOAT = "float"
+    DECIMAL = "decimal"
+    DATE = "date"
+    TIME = "time"
+    DATETIME = "datetime"
+    UUID = "uuid"
+    JSON = "json"
+    ENUM = "enum"
+    ARRAY = "array"
+
+
+# ---------------------------------------------------------------------------
+# Structured outputs
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PyTypeInfo:
+    """Normalized info about the Python-side type annotation."""
+
+    base: Any
+    is_optional: bool = False
+    enum_cls: Optional[Type[Enum]] = None
+    array_item: Optional["PyTypeInfo"] = None
+    annotated: Tuple[Any, ...] = ()
+
+
+@dataclass(frozen=True)
+class SATypePlan:
+    """Declarative plan for constructing an SA column type downstream."""
+
+    name: str  # e.g., "UUID", "String", "JSONB", "Enum", "ARRAY"
+    args: Tuple[Any, ...]  # positional args (e.g., (enum_cls,))
+    kwargs: Dict[str, Any]  # keyword args (e.g., {"as_uuid": True})
+    dialect: Optional[str] = None  # e.g., "postgresql" for JSONB/UUID/ARRAY
+
+
+@dataclass(frozen=True)
+class JsonHint:
+    """Minimal JSON Schema-ish hints for docs."""
+
+    type: str
+    format: Optional[str] = None
+    maxLength: Optional[int] = None
+    enum: Optional[List[str]] = None
+    items: Optional["JsonHint"] = None
+
+
+@dataclass(frozen=True)
+class Inferred:
+    """Primary product of inference."""
+
+    kind: DataKind
+    py: PyTypeInfo
+    sa: SATypePlan
+    json: JsonHint
+    nullable: bool
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class InferenceError(ValueError):
+    """Base class for inference-related errors."""
+
+
+class UnsupportedType(InferenceError):
+    """Raised when a type cannot be inferred."""

tigrbl_canon-0.1.0/tigrbl_canon/column/infer/utils.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import (
+    Any,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+    get_args,
+    get_origin,
+    Annotated,
+)
+
+
+def _strip_optional(tp: Any) -> Tuple[Any, bool]:
+    """Return (inner_type, is_optional) for Optional[T] / Union[T, None]."""
+    origin = get_origin(tp)
+    if origin is Union:
+        args = tuple(a for a in get_args(tp))
+        if len(args) == 2 and type(None) in args:
+            inner = args[0] if args[1] is type(None) else args[1]
+            return inner, True
+    return tp, False
+
+
+def _strip_annotated(tp: Any) -> Tuple[Any, Tuple[Any, ...]]:
+    """Return (base, metadata) for Annotated[base, *meta]; otherwise (tp, ())."""
+    origin = get_origin(tp)
+    if origin is Annotated:
+        args = get_args(tp)
+        if len(args) >= 1:
+            base, meta = args[0], tuple(args[1:])
+            return base, meta
+    return tp, ()
+
+
+def _array_item(tp: Any) -> Optional[Any]:
+    origin = get_origin(tp)
+    if origin in (list, List, tuple, Tuple, set, frozenset):
+        args = get_args(tp)
+        if not args:
+            return Any
+        if origin in (tuple, Tuple) and len(args) == 2 and args[1] is Ellipsis:
+            return args[0]
+        if len(args) == 1:
+            return args[0]
+        return Any
+    return None
+
+
+def _is_enum(tp: Any) -> Optional[Type[Enum]]:
+    try:
+        if isinstance(tp, type) and issubclass(tp, Enum):
+            return tp
+    except Exception:
+        pass
+    return None

tigrbl_canon-0.1.0/tigrbl_canon/mapping/__init__.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from importlib import import_module
+import warnings
+
+from tigrbl_canon import _DEPRECATION_MESSAGE
+
+warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
+
+__all__ = [
+    "bind",
+    "rebind",
+    "build_schemas",
+    "build_hooks",
+    "build_handlers",
+    "register_rpc",
+    "build_rest",
+    "bind_response",
+    "include_table",
+    "include_tables",
+    "rpc_call",
+    "MRO_COLLECTORS",
+    "RESOLVERS",
+    "INSTALLS",
+    "collect",
+    "install",
+    "collect_engine_bindings",
+    "install_engine_bindings",
+    "install_from_objects",
+]
+
+
+def __getattr__(name: str):
+    if name in {"bind", "rebind"}:
+        return getattr(import_module(".model", __name__), name)
+    if name == "build_schemas":
+        return import_module(".schemas", __name__).build_and_attach
+    if name == "build_hooks":
+        return import_module(".hooks", __name__).normalize_and_attach
+    if name == "build_handlers":
+        return import_module(".handlers", __name__).build_and_attach
+    if name == "register_rpc":
+        return import_module(".rpc", __name__).register_and_attach
+    if name == "build_rest":
+        return import_module(".rest", __name__).build_router_and_attach
+    if name == "bind_response":
+        return import_module(".responses_resolver", __name__).resolve_response_spec
+    if name in {"include_table", "include_tables"}:
+        return getattr(import_module(".router.include", __name__), name)
+    if name == "rpc_call":
+        # ``tigrbl.mapping.rpc_call`` should execute an RPC op end-to-end and
+        # return the serialized operation result.
+        return getattr(import_module(".router.rpc", __name__), name)
+    if name in {
+        "INSTALLS",
+        "MRO_COLLECTORS",
+        "RESOLVERS",
+        "collect",
+        "install",
+        "collect_engine_bindings",
+        "install_engine_bindings",
+        "install_from_objects",
+    }:
+        return getattr(import_module(".traversal", __name__), name)
+    raise AttributeError(name)

tigrbl_canon-0.1.0/tigrbl_canon/mapping/app_mro_collect.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from functools import lru_cache
+
+from tigrbl_core._spec.app_spec import AppSpec
+
+
+@lru_cache(maxsize=None)
+def mro_collect_app_spec(app: type) -> AppSpec:
+    """Collect AppSpec-like declarations across the app's MRO."""
+    return AppSpec.collect(app)
+
+
+__all__ = ["mro_collect_app_spec"]