tigrbl-typing 0.1.0.dev5__tar.gz

tigrbl_typing-0.1.0.dev5/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: tigrbl-typing
+Version: 0.1.0.dev5
+Summary: Typing protocols and shared type helpers 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)
+Description-Content-Type: text/markdown
+
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-typing
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-typing.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-typing.svg) ![License](https://img.shields.io/pypi/l/tigrbl-typing.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-typing.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-typing
+```
+
+### pip
+
+```bash
+pip install tigrbl-typing
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.
+

tigrbl_typing-0.1.0.dev5/README.md

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

tigrbl_typing-0.1.0.dev5/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "tigrbl-typing"
+version = "0.1.0.dev5"
+description = "Typing protocols and shared type helpers 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 = [
+    "pydantic>=2.10,<3",
+]
+keywords = ["tigrbl", "sdk", "standards", "framework"]
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry]
+packages = [
+    { include = "tigrbl_typing" },
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-timeout>=2.3.1",
+    "ruff>=0.9",
+]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/__init__.py

@@ -0,0 +1,5 @@
+"""Public exports for ``tigrbl_typing``."""
+
+from .types import PgUUID
+
+__all__ = ["PgUUID"]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/gw/__init__.py

@@ -0,0 +1,3 @@
+from .raw import GwRawEnvelope, GwRouteEnvelope
+
+__all__ = ["GwRawEnvelope", "GwRouteEnvelope"]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/gw/raw.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Literal, Mapping, Sequence
+
+
+@dataclass(slots=True)
+class GwRawEnvelope:
+    kind: Literal["asgi3"]
+    scope: dict[str, Any]
+    receive: Callable[[], Awaitable[dict[str, Any]]]
+    send: Callable[[dict[str, Any]], Awaitable[None]]
+
+
+@dataclass(frozen=True, slots=True)
+class GwRouteEnvelope:
+    transport: Literal["http", "ws", "sse", "stream", "http3"]
+    scheme: Literal["http", "https", "ws", "wss", "h3"]
+    kind: Literal["rest", "jsonrpc", "maybe-jsonrpc", "unknown"]
+    method: str | None
+    path: str | None
+    headers: Mapping[str, str]
+    query: Mapping[str, Sequence[str]]
+    body: bytes | None
+    ws_event: Any | None
+    rpc: Mapping[str, Any] | None

tigrbl_typing-0.1.0.dev5/tigrbl_typing/phases.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal, Tuple
+
+HookPhase = Literal[
+    "PRE_TX_BEGIN",
+    "START_TX",
+    "PRE_HANDLER",
+    "HANDLER",
+    "POST_HANDLER",
+    "PRE_COMMIT",
+    "END_TX",
+    "POST_COMMIT",
+    "POST_RESPONSE",
+    "ON_ERROR",
+    "ON_PRE_TX_BEGIN_ERROR",
+    "ON_START_TX_ERROR",
+    "ON_PRE_HANDLER_ERROR",
+    "ON_HANDLER_ERROR",
+    "ON_POST_HANDLER_ERROR",
+    "ON_PRE_COMMIT_ERROR",
+    "ON_END_TX_ERROR",
+    "ON_POST_COMMIT_ERROR",
+    "ON_POST_RESPONSE_ERROR",
+    "ON_ROLLBACK",
+]
+
+Phase = Literal[
+    "INGRESS_BEGIN",
+    "INGRESS_PARSE",
+    "INGRESS_ROUTE",
+    "PRE_TX_BEGIN",
+    "START_TX",
+    "PRE_HANDLER",
+    "HANDLER",
+    "POST_HANDLER",
+    "PRE_COMMIT",
+    "END_TX",
+    "POST_COMMIT",
+    "EGRESS_SHAPE",
+    "EGRESS_FINALIZE",
+    "POST_RESPONSE",
+    "ON_ERROR",
+    "ON_PRE_TX_BEGIN_ERROR",
+    "ON_START_TX_ERROR",
+    "ON_PRE_HANDLER_ERROR",
+    "ON_HANDLER_ERROR",
+    "ON_POST_HANDLER_ERROR",
+    "ON_PRE_COMMIT_ERROR",
+    "ON_END_TX_ERROR",
+    "ON_POST_COMMIT_ERROR",
+    "ON_POST_RESPONSE_ERROR",
+    "ON_ROLLBACK",
+]
+
+
+class PHASE(str, Enum):
+    PRE_TX_BEGIN = "PRE_TX_BEGIN"
+    START_TX = "START_TX"
+    PRE_HANDLER = "PRE_HANDLER"
+    HANDLER = "HANDLER"
+    POST_HANDLER = "POST_HANDLER"
+    PRE_COMMIT = "PRE_COMMIT"
+    END_TX = "END_TX"
+    POST_COMMIT = "POST_COMMIT"
+    POST_RESPONSE = "POST_RESPONSE"
+    ON_ERROR = "ON_ERROR"
+    ON_PRE_TX_BEGIN_ERROR = "ON_PRE_TX_BEGIN_ERROR"
+    ON_START_TX_ERROR = "ON_START_TX_ERROR"
+    ON_PRE_HANDLER_ERROR = "ON_PRE_HANDLER_ERROR"
+    ON_HANDLER_ERROR = "ON_HANDLER_ERROR"
+    ON_POST_HANDLER_ERROR = "ON_POST_HANDLER_ERROR"
+    ON_PRE_COMMIT_ERROR = "ON_PRE_COMMIT_ERROR"
+    ON_END_TX_ERROR = "ON_END_TX_ERROR"
+    ON_POST_COMMIT_ERROR = "ON_POST_COMMIT_ERROR"
+    ON_POST_RESPONSE_ERROR = "ON_POST_RESPONSE_ERROR"
+    ON_ROLLBACK = "ON_ROLLBACK"
+
+
+HOOK_PHASES: Tuple[HookPhase, ...] = tuple(p.value for p in PHASE)
+PHASES: Tuple[Phase, ...] = (
+    "INGRESS_BEGIN",
+    "INGRESS_PARSE",
+    "INGRESS_ROUTE",
+    "PRE_TX_BEGIN",
+    "START_TX",
+    "PRE_HANDLER",
+    "HANDLER",
+    "POST_HANDLER",
+    "PRE_COMMIT",
+    "END_TX",
+    "POST_COMMIT",
+    "EGRESS_SHAPE",
+    "EGRESS_FINALIZE",
+    "POST_RESPONSE",
+    "ON_ERROR",
+    "ON_PRE_TX_BEGIN_ERROR",
+    "ON_START_TX_ERROR",
+    "ON_PRE_HANDLER_ERROR",
+    "ON_HANDLER_ERROR",
+    "ON_POST_HANDLER_ERROR",
+    "ON_PRE_COMMIT_ERROR",
+    "ON_END_TX_ERROR",
+    "ON_POST_COMMIT_ERROR",
+    "ON_POST_RESPONSE_ERROR",
+    "ON_ROLLBACK",
+)
+
+__all__ = ["PHASE", "PHASES", "HOOK_PHASES", "Phase", "HookPhase"]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/protocols.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class RequestLike(Protocol):
+    query_params: dict[str, Any]
+    path_params: dict[str, Any]
+    headers: dict[str, Any]
+
+    def json_sync(self) -> Any: ...
+
+
+@runtime_checkable
+class DependencyLike(Protocol):
+    dependency: Any
+
+
+@runtime_checkable
+class ResponseLike(Protocol):
+    status_code: int
+    raw_headers: list[tuple[bytes, bytes]]
+    body: bytes | None
+
+
+def is_dependency_like(obj: Any) -> bool:
+    return isinstance(obj, DependencyLike) and callable(
+        getattr(obj, "dependency", None)
+    )
+
+
+def is_response_like(obj: Any) -> bool:
+    if not isinstance(obj, ResponseLike):
+        return False
+    return isinstance(getattr(obj, "raw_headers", None), list)
+
+
+__all__ = [
+    "RequestLike",
+    "DependencyLike",
+    "ResponseLike",
+    "is_dependency_like",
+    "is_response_like",
+]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/request.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class URL:
+    path: str
+    query: dict[str, list[str]]
+    script_name: str = ""
+
+    def __str__(self) -> str:
+        base = (self.script_name or "").rstrip("/")
+        query_string = "&".join(
+            f"{name}={value}" for name, values in self.query.items() for value in values
+        )
+        path = f"{base}{self.path}" if base else self.path
+        return f"{path}?{query_string}" if query_string else path
+
+
+@dataclass(frozen=True)
+class AwaitableValue:
+    value: Any
+
+    def __await__(self):
+        async def _value() -> Any:
+            return self.value
+
+        return _value().__await__()
+
+
+__all__ = ["URL", "AwaitableValue"]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/status/__init__.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from .exceptions import HTTPException, StatusDetailError
+from .mappings import (
+    status,
+    HTTP_ERROR_MESSAGES,
+    ERROR_MESSAGES,
+    _HTTP_TO_RPC,
+    _RPC_TO_HTTP,
+)
+from .converters import (
+    http_exc_to_rpc,
+    rpc_error_to_http,
+    _http_exc_to_rpc,
+    _rpc_error_to_http,
+    create_standardized_error,
+    create_standardized_error_from_status,
+    to_rpc_error_payload,
+)
+from .exceptions import (
+    TigrblError,
+    PlanningError,
+    LabelError,
+    ConfigError,
+    SystemStepError,
+    ValidationError,
+    TransformError,
+    DeriveError,
+    KernelAbort,
+    coerce_runtime_error,
+    raise_for_in_errors,
+)
+
+__all__ = [
+    "HTTPException",
+    "StatusDetailError",
+    "status",
+    # maps & messages
+    "HTTP_ERROR_MESSAGES",
+    "ERROR_MESSAGES",
+    "_HTTP_TO_RPC",
+    "_RPC_TO_HTTP",
+    # conversions
+    "http_exc_to_rpc",
+    "rpc_error_to_http",
+    "_http_exc_to_rpc",
+    "_rpc_error_to_http",
+    "create_standardized_error",
+    "create_standardized_error_from_status",
+    "to_rpc_error_payload",
+    # typed errors + helpers
+    "TigrblError",
+    "PlanningError",
+    "LabelError",
+    "ConfigError",
+    "SystemStepError",
+    "ValidationError",
+    "TransformError",
+    "DeriveError",
+    "KernelAbort",
+    "coerce_runtime_error",
+    "raise_for_in_errors",
+]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/status/converters.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from .utils import (
+    PydanticValidationError,
+    RequestValidationError,
+    IntegrityError,
+    DBAPIError,
+    OperationalError,
+    NoResultFound,
+    _is_asyncpg_constraint_error,
+    _stringify_exc,
+    _format_validation,
+)
+from .exceptions import HTTPException, TigrblError
+from .mappings import (
+    status,
+    _HTTP_TO_RPC,
+    _RPC_TO_HTTP,
+    ERROR_MESSAGES,
+    HTTP_ERROR_MESSAGES,
+)
+
+
+def http_exc_to_rpc(exc: HTTPException) -> tuple[int, str, Any | None]:
+    """Convert HTTPException → (rpc_code, message, data)."""
+    code = _HTTP_TO_RPC.get(exc.status_code, -32603)
+    detail = exc.detail
+    if isinstance(detail, (dict, list)):
+        return code, ERROR_MESSAGES.get(code, "Unknown error"), detail
+    msg = getattr(exc, "rpc_message", None) or (
+        detail if isinstance(detail, str) else None
+    )
+    if not msg:
+        msg = ERROR_MESSAGES.get(
+            code, HTTP_ERROR_MESSAGES.get(exc.status_code, "Unknown error")
+        )
+    data = getattr(exc, "rpc_data", None)
+    return code, msg, data
+
+
+def rpc_error_to_http(
+    rpc_code: int, message: str | None = None, data: Any | None = None
+) -> HTTPException:
+    """Convert JSON-RPC error code (and optional message/data) → HTTPException."""
+    http_status = _RPC_TO_HTTP.get(rpc_code, 500)
+    msg = (
+        message
+        or HTTP_ERROR_MESSAGES.get(http_status)
+        or ERROR_MESSAGES.get(rpc_code, "Unknown error")
+    )
+    http_exc = HTTPException(status_code=http_status, detail=msg)
+    setattr(http_exc, "rpc_code", rpc_code)
+    setattr(http_exc, "rpc_message", msg)
+    setattr(http_exc, "rpc_data", data)
+    return http_exc
+
+
+def _http_exc_to_rpc(exc: HTTPException) -> tuple[int, str, Any | None]:
+    """Alias for :func:`http_exc_to_rpc` to preserve older import paths."""
+    return http_exc_to_rpc(exc)
+
+
+def _rpc_error_to_http(
+    rpc_code: int, message: str | None = None, data: Any | None = None
+) -> HTTPException:
+    """Alias for :func:`rpc_error_to_http` to preserve older import paths."""
+    return rpc_error_to_http(rpc_code, message, data)
+
+
+def _classify_exception(
+    exc: BaseException,
+) -> Tuple[int, str | dict | list, Any | None]:
+    """
+    Return (http_status, detail_or_message, data) suitable for HTTPException and JSON-RPC mapping.
+    `detail_or_message` may be a string OR a structured dict/list (validation).
+    """
+    # 0) Typed Tigrbl errors
+    if isinstance(exc, TigrblError):
+        status_code = getattr(exc, "status", 400) or 400
+        details = getattr(exc, "details", None)
+        if isinstance(details, (dict, list)):
+            return status_code, details, details
+        return status_code, str(exc) or exc.code, None
+
+    # 1) Pass-through HTTPException preserving detail
+    if isinstance(exc, HTTPException):
+        return exc.status_code, exc.detail, getattr(exc, "rpc_data", None)
+
+    # 1b) Compatibility shim for framework-style exceptions that expose
+    # ``status_code`` and ``detail`` but are not our HTTPException type.
+    status_code = getattr(exc, "status_code", None)
+    if isinstance(status_code, int):
+        detail = getattr(exc, "detail", None)
+        if detail in (None, ""):
+            detail = _stringify_exc(exc)
+        return int(status_code), detail, None
+
+    # 2) Validation errors → 422 with structured data
+    if (PydanticValidationError is not None) and isinstance(
+        exc, PydanticValidationError
+    ):
+        return (
+            status.HTTP_422_UNPROCESSABLE_ENTITY,
+            HTTP_ERROR_MESSAGES.get(422, "Validation failed"),
+            _format_validation(exc),
+        )
+    if (RequestValidationError is not None) and isinstance(exc, RequestValidationError):
+        return (
+            status.HTTP_422_UNPROCESSABLE_ENTITY,
+            HTTP_ERROR_MESSAGES.get(422, "Validation failed"),
+            _format_validation(exc),
+        )
+
+    # 3) Common client errors
+    if isinstance(exc, (ValueError, TypeError, KeyError)):
+        return status.HTTP_400_BAD_REQUEST, _stringify_exc(exc), None
+    if isinstance(exc, PermissionError):
+        return status.HTTP_403_FORBIDDEN, _stringify_exc(exc), None
+    if isinstance(exc, NotImplementedError):
+        return status.HTTP_501_NOT_IMPLEMENTED, _stringify_exc(exc), None
+    if isinstance(exc, TimeoutError):
+        return status.HTTP_504_GATEWAY_TIMEOUT, _stringify_exc(exc), None
+
+    # 4) ORM/DB mapping
+    if (NoResultFound is not None) and isinstance(exc, NoResultFound):
+        return status.HTTP_404_NOT_FOUND, "Resource not found", None
+
+    if _is_asyncpg_constraint_error(exc):
+        return status.HTTP_409_CONFLICT, _stringify_exc(exc), None
+
+    if (IntegrityError is not None) and isinstance(exc, IntegrityError):
+        msg = _stringify_exc(exc)
+        lower_msg = msg.lower()
+        if "not null constraint" in lower_msg or "check constraint" in lower_msg:
+            return status.HTTP_422_UNPROCESSABLE_ENTITY, msg, None
+        return status.HTTP_409_CONFLICT, msg, None
+
+    if (OperationalError is not None) and isinstance(exc, OperationalError):
+        return status.HTTP_503_SERVICE_UNAVAILABLE, _stringify_exc(exc), None
+
+    if (DBAPIError is not None) and isinstance(exc, DBAPIError):
+        return status.HTTP_500_INTERNAL_SERVER_ERROR, _stringify_exc(exc), None
+
+    # 5) Fallback
+    return status.HTTP_500_INTERNAL_SERVER_ERROR, _stringify_exc(exc), None
+
+
+def create_standardized_error(exc: BaseException) -> HTTPException:
+    """
+    Normalize any exception → HTTPException with attached RPC context:
+      • .rpc_code
+      • .rpc_message
+      • .rpc_data
+    """
+    http_status, detail_or_message, data = _classify_exception(exc)
+    rpc_code = _HTTP_TO_RPC.get(http_status, -32603)
+    if isinstance(detail_or_message, (dict, list)):
+        http_detail = detail_or_message
+        rpc_message = ERROR_MESSAGES.get(
+            rpc_code, HTTP_ERROR_MESSAGES.get(http_status, "Unknown error")
+        )
+    else:
+        http_detail = detail_or_message
+        rpc_message = detail_or_message or ERROR_MESSAGES.get(
+            rpc_code, HTTP_ERROR_MESSAGES.get(http_status, "Unknown error")
+        )
+    http_exc = HTTPException(status_code=http_status, detail=http_detail)
+    setattr(http_exc, "rpc_code", rpc_code)
+    setattr(http_exc, "rpc_message", rpc_message)
+    setattr(http_exc, "rpc_data", data)
+    return http_exc
+
+
+def create_standardized_error_from_status(
+    http_status: int,
+    message: str | None = None,
+    *,
+    rpc_code: int | None = None,
+    data: Any | None = None,
+) -> tuple[HTTPException, int, str]:
+    """Explicit constructor used by code paths that already decided on an HTTP status."""
+    if rpc_code is None:
+        rpc_code = _HTTP_TO_RPC.get(http_status, -32603)
+    if message is None:
+        http_message = HTTP_ERROR_MESSAGES.get(http_status) or ERROR_MESSAGES.get(
+            rpc_code, "Unknown error"
+        )
+        rpc_message = ERROR_MESSAGES.get(rpc_code) or HTTP_ERROR_MESSAGES.get(
+            http_status, "Unknown error"
+        )
+    else:
+        http_message = rpc_message = message
+    http_exc = HTTPException(status_code=http_status, detail=http_message)
+    setattr(http_exc, "rpc_code", rpc_code)
+    setattr(http_exc, "rpc_message", rpc_message)
+    setattr(http_exc, "rpc_data", data)
+    return http_exc, rpc_code, rpc_message
+
+
+def to_rpc_error_payload(exc: HTTPException) -> dict:
+    """Produce a JSON-RPC error object from an HTTPException (with or without rpc_* attrs)."""
+    code, msg, data = http_exc_to_rpc(exc)
+    payload = {"code": code, "message": msg}
+    if data is not None:
+        payload["data"] = data
+    else:
+        if isinstance(exc.detail, (dict, list)):
+            payload["data"] = exc.detail
+    return payload
+
+
+__all__ = [
+    "http_exc_to_rpc",
+    "rpc_error_to_http",
+    "_http_exc_to_rpc",
+    "_rpc_error_to_http",
+    "create_standardized_error",
+    "create_standardized_error_from_status",
+    "to_rpc_error_payload",
+]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/status/exceptions.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from .utils import _read_in_errors, _has_in_errors
+
+
+class StatusDetailError(Exception):
+    def __init__(
+        self,
+        status_code: int,
+        detail: Any = "",
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        super().__init__(detail)
+        self.status_code = int(status_code)
+        self.detail = detail
+        self.headers = dict(headers or {})
+
+
+class HTTPException(StatusDetailError):
+    def __init__(
+        self,
+        status_code: int,
+        detail: Any = "",
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        super().__init__(status_code=status_code, detail=detail, headers=headers)
+
+
+class TigrblError(Exception):
+    """Base class for runtime errors in Tigrbl v3."""
+
+    code: str = "tigrbl_error"
+    status: int = 400
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        code: Optional[str] = None,
+        status: Optional[int] = None,
+        details: Any = None,
+        cause: Optional[BaseException] = None,
+    ):
+        super().__init__(message)
+        if cause is not None:
+            self.__cause__ = cause
+        if code is not None:
+            self.code = code
+        if status is not None:
+            self.status = status
+        self.details = details
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = {
+            "type": self.__class__.__name__,
+            "code": self.code,
+            "status": self.status,
+            "message": str(self),
+        }
+        if self.details is not None:
+            d["details"] = self.details
+        return d
+
+
+class PlanningError(TigrblError):
+    code = "planning_error"
+    status = 500
+
+
+class LabelError(TigrblError):
+    code = "label_error"
+    status = 400
+
+
+class ConfigError(TigrblError):
+    code = "config_error"
+    status = 400
+
+
+class SystemStepError(TigrblError):
+    code = "system_step_error"
+    status = 500
+
+
+class ValidationError(TigrblError):
+    code = "validation_error"
+    status = 422
+
+    @staticmethod
+    def from_ctx(
+        ctx: Any, message: str = "Input validation failed."
+    ) -> "ValidationError":
+        return ValidationError(message, status=422, details=_read_in_errors(ctx))
+
+
+class TransformError(TigrblError):
+    code = "transform_error"
+    status = 400
+
+
+class DeriveError(TigrblError):
+    code = "derive_error"
+    status = 400
+
+
+class KernelAbort(TigrblError):
+    code = "kernel_abort"
+    status = 403
+
+
+def coerce_runtime_error(exc: BaseException, ctx: Any | None = None) -> TigrblError:
+    """
+    Map arbitrary exceptions to a typed TigrblError for consistent kernel handling.
+    - Already TigrblError → return as-is
+    - ValueError + ctx.temp['in_errors'] → ValidationError
+    - Otherwise → generic TigrblError
+    """
+    if isinstance(exc, TigrblError):
+        return exc
+    if isinstance(exc, ValueError) and ctx is not None and _has_in_errors(ctx):
+        return ValidationError.from_ctx(
+            ctx, message=str(exc) or "Input validation failed."
+        )
+    return TigrblError(str(exc) or exc.__class__.__name__)
+
+
+def raise_for_in_errors(ctx: Any) -> None:
+    """Raise a typed ValidationError if ctx.temp['in_errors'] indicates invalid input."""
+    if _has_in_errors(ctx):
+        raise ValidationError.from_ctx(ctx)
+
+
+__all__ = [
+    "StatusDetailError",
+    "HTTPException",
+    "TigrblError",
+    "PlanningError",
+    "LabelError",
+    "ConfigError",
+    "SystemStepError",
+    "ValidationError",
+    "TransformError",
+    "DeriveError",
+    "KernelAbort",
+    "coerce_runtime_error",
+    "raise_for_in_errors",
+]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/status/mappings.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+
+class _Status:
+    HTTP_200_OK = 200
+    HTTP_201_CREATED = 201
+    HTTP_204_NO_CONTENT = 204
+    HTTP_400_BAD_REQUEST = 400
+    HTTP_401_UNAUTHORIZED = 401
+    HTTP_403_FORBIDDEN = 403
+    HTTP_404_NOT_FOUND = 404
+    HTTP_405_METHOD_NOT_ALLOWED = 405
+    HTTP_409_CONFLICT = 409
+    HTTP_422_UNPROCESSABLE_ENTITY = 422
+    HTTP_429_TOO_MANY_REQUESTS = 429
+    HTTP_500_INTERNAL_SERVER_ERROR = 500
+    HTTP_501_NOT_IMPLEMENTED = 501
+    HTTP_503_SERVICE_UNAVAILABLE = 503
+    HTTP_504_GATEWAY_TIMEOUT = 504
+
+
+status = _Status()
+
+# HTTP → JSON-RPC code map
+_HTTP_TO_RPC: dict[int, int] = {
+    400: -32602,
+    401: -32001,
+    403: -32002,
+    404: -32003,
+    409: -32004,
+    422: -32602,
+    500: -32603,
+    501: -32603,
+    503: -32603,
+    504: -32603,
+}
+
+# JSON-RPC → HTTP status map
+_RPC_TO_HTTP: dict[int, int] = {
+    -32700: 400,
+    -32600: 400,
+    -32601: 404,
+    -32602: 400,
+    -32603: 500,
+    -32001: 401,
+    -32002: 403,
+    -32003: 404,
+    -32004: 409,
+}
+
+# Standardized error messages
+ERROR_MESSAGES: dict[int, str] = {
+    -32700: "Parse error",
+    -32600: "Invalid Request",
+    -32601: "Method not found",
+    -32602: "Invalid params",
+    -32603: "Internal error",
+    -32001: "Authentication required",
+    -32002: "Insufficient permissions",
+    -32003: "Resource not found",
+    -32004: "Resource conflict",
+    -32000: "Server error",
+    -32099: "Duplicate key constraint violation",
+    -32098: "Data constraint violation",
+    -32097: "Foreign key constraint violation",
+    -32096: "Authentication required",
+    -32095: "Authorization failed",
+    -32094: "Resource not found",
+    -32093: "Validation error",
+    -32092: "Transaction failed",
+}
+
+# HTTP status code → standardized message
+HTTP_ERROR_MESSAGES: dict[int, str] = {
+    400: "Bad Request: malformed input",
+    401: "Unauthorized: authentication required",
+    403: "Forbidden: insufficient permissions",
+    404: "Not Found: resource does not exist",
+    409: "Conflict: duplicate key or constraint violation",
+    422: "Unprocessable Entity: validation failed",
+    500: "Internal Server Error: unexpected server error",
+    501: "Not Implemented",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+}
+
+__all__ = [
+    "_Status",
+    "status",
+    "_HTTP_TO_RPC",
+    "_RPC_TO_HTTP",
+    "ERROR_MESSAGES",
+    "HTTP_ERROR_MESSAGES",
+]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/status/utils.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Mapping
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Optional imports – code must run even if these packages aren’t installed.
+try:
+    from pydantic import ValidationError as PydanticValidationError  # v2
+except Exception:  # pragma: no cover
+    PydanticValidationError = None  # type: ignore
+
+try:
+    import importlib
+
+    _http_exc = importlib.import_module("fast" + "router.exceptions")
+    RequestValidationError = _http_exc.RequestValidationError
+except Exception:  # pragma: no cover
+    RequestValidationError = None  # type: ignore
+
+try:
+    # SQLAlchemy v1/v2 exception sets
+    from sqlalchemy.exc import IntegrityError, DBAPIError, OperationalError
+    from sqlalchemy.orm.exc import NoResultFound  # type: ignore
+except Exception:  # pragma: no cover
+    IntegrityError = DBAPIError = OperationalError = NoResultFound = None  # type: ignore
+
+
+# Detect asyncpg constraint errors without importing asyncpg (optional dep).
+_ASYNCPG_CONSTRAINT_NAMES = {
+    "UniqueViolationError",
+    "ForeignKeyViolationError",
+    "NotNullViolationError",
+    "CheckViolationError",
+    "ExclusionViolationError",
+}
+
+
+def _is_asyncpg_constraint_error(exc: BaseException) -> bool:
+    cls = type(exc)
+    return (cls.__module__ or "").startswith("asyncpg") and (
+        cls.__name__ in _ASYNCPG_CONSTRAINT_NAMES
+    )
+
+
+def _limit(s: str, n: int = 4000) -> str:
+    return s if len(s) <= n else s[: n - 3] + "..."
+
+
+def _stringify_exc(exc: BaseException) -> str:
+    detail = getattr(exc, "detail", None)
+    if detail:
+        return _limit(str(detail))
+    return _limit(f"{exc.__class__!r}: {str(exc) or repr(exc)}")
+
+
+def _format_validation(err: Any) -> Any:
+    try:
+        items = err.errors()  # pydantic / asgi RequestValidationError
+        if isinstance(items, Iterable):
+            return list(items)
+    except Exception:  # pragma: no cover
+        pass
+    return _limit(str(err))
+
+
+def _get_temp(ctx: Any) -> Mapping[str, Any]:
+    tmp = getattr(ctx, "temp", None)
+    return tmp if isinstance(tmp, Mapping) else {}
+
+
+def _has_in_errors(ctx: Any) -> bool:
+    tmp = _get_temp(ctx)
+    if tmp.get("in_invalid") is True:
+        return True
+    errs = tmp.get("in_errors")
+    return isinstance(errs, (list, tuple)) and len(errs) > 0
+
+
+def _read_in_errors(ctx: Any) -> List[Dict[str, Any]]:
+    tmp = _get_temp(ctx)
+    errs = tmp.get("in_errors")
+    if isinstance(errs, list):
+        norm: List[Dict[str, Any]] = []
+        for e in errs:
+            if isinstance(e, Mapping):
+                field = e.get("field")
+                code = e.get("code") or "invalid"
+                msg = e.get("message") or "Invalid value."
+                entry = {"field": field, "code": code, "message": msg}
+                for k, v in e.items():
+                    if k not in entry:
+                        entry[k] = v
+                norm.append(entry)
+        return norm
+    return []
+
+
+__all__ = [
+    "PydanticValidationError",
+    "RequestValidationError",
+    "IntegrityError",
+    "DBAPIError",
+    "OperationalError",
+    "NoResultFound",
+    "_is_asyncpg_constraint_error",
+    "_limit",
+    "_stringify_exc",
+    "_format_validation",
+    "_get_temp",
+    "_has_in_errors",
+    "_read_in_errors",
+]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/types/__init__.py

@@ -0,0 +1,129 @@
+# ── Standard Library ─────────────────────────────────────────────────────
+from types import MethodType, SimpleNamespace
+from uuid import uuid4, UUID
+
+# ── Third-party Dependencies (via deps module) ───────────────────────────
+from ..vendor.sqlalchemy import (
+    # Core SQLAlchemy
+    Boolean,
+    Column,
+    _DateTime,
+    SAEnum,
+    Text,
+    ForeignKey,
+    Index,
+    Integer,
+    JSON,
+    Numeric,
+    String,
+    LargeBinary,
+    UniqueConstraint,
+    CheckConstraint,
+    create_engine,
+    event,
+    # PostgreSQL dialect
+    ARRAY,
+    PgEnum,
+    JSONB,
+    TSVECTOR,
+    # ORM
+    Mapped,
+    declarative_mixin,
+    declared_attr,
+    foreign,
+    mapped_column,
+    relationship,
+    remote,
+    column_property,
+    Session,
+    sessionmaker,
+    InstrumentedAttribute,
+    # Extensions
+    MutableDict,
+    MutableList,
+    hybrid_property,
+    StaticPool,
+    TypeDecorator,
+)
+
+
+from ..vendor.pydantic import (
+    BaseModel,
+    Field,
+    ValidationError,
+)
+
+from ..status.exceptions import StatusDetailError
+
+# ── Local Package ─────────────────────────────────────────────────────────
+from .op import _Op, _SchemaVerb
+from .uuid import PgUUID, SqliteUUID
+from .authn_abc import AuthNProvider
+
+# ── Generics / Extensions ─────────────────────────────────────────────────
+DateTime = _DateTime(timezone=False)
+TZDateTime = _DateTime(timezone=True)
+
+
+# ── Public Re-exports (Backwards Compatibility) ──────────────────────────
+__all__: list[str] = [
+    # local
+    "_Op",
+    "_SchemaVerb",
+    "AuthNProvider",
+    # add ons
+    "SqliteUUID",
+    # builtin types
+    "MethodType",
+    "SimpleNamespace",
+    "uuid4",
+    "UUID",
+    # sqlalchemy core (from deps.sqlalchemy)
+    "Boolean",
+    "Column",
+    "DateTime",
+    "TZDateTime",
+    "Text",
+    "SAEnum",
+    "ForeignKey",
+    "Index",
+    "Integer",
+    "JSON",
+    "Numeric",
+    "String",
+    "LargeBinary",
+    "UniqueConstraint",
+    "CheckConstraint",
+    "create_engine",
+    "event",
+    # sqlalchemy.dialects.postgresql (from deps.sqlalchemy)
+    "ARRAY",
+    "PgEnum",
+    "JSONB",
+    "PgUUID",
+    "TSVECTOR",
+    # sqlalchemy.orm (from deps.sqlalchemy)
+    "Mapped",
+    "declarative_mixin",
+    "declared_attr",
+    "foreign",
+    "mapped_column",
+    "column_property",
+    "hybrid_property",
+    "relationship",
+    "remote",
+    "Session",
+    "sessionmaker",
+    "InstrumentedAttribute",
+    # sqlalchemy.ext.mutable (from deps.sqlalchemy)
+    "MutableDict",
+    "MutableList",
+    "StaticPool",
+    "TypeDecorator",
+    # pydantic schema support (from deps.pydantic)
+    "BaseModel",
+    "Field",
+    "ValidationError",
+    # status
+    "StatusDetailError",
+]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/types/authn_abc.py

@@ -0,0 +1,33 @@
+# tigrbl/types/authn_abc.py
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tigrbl import Request
+
+
+class AuthNProvider(ABC):
+    """
+    Marker‑interface that any AuthN extension must implement
+    so that Tigrbl can plug itself in at run‑time.
+    """
+
+    # ---------- ASGI dependency ----------
+    @abstractmethod
+    async def get_principal(self, request: "Request"):  # -> dict[str, str]
+        """Return {"sub": user_id, "tid": tenant_id, ...} or raise HTTP 401."""
+
+
+__all__ = ["AuthNProvider"]
+
+
+for _name in list(globals()):
+    if _name not in __all__ and not _name.startswith("__"):
+        del globals()[_name]
+
+
+def __dir__():
+    """Tighten ``dir()`` output for interactive sessions."""
+
+    return sorted(__all__)

tigrbl_typing-0.1.0.dev5/tigrbl_typing/types/op.py

@@ -0,0 +1,35 @@
+"""
+tigrbl/types/op.py
+Pure structural helpers."""
+
+from typing import Any, Callable, NamedTuple, Type, Literal, TypeAlias
+
+_SchemaVerb: TypeAlias = Literal[
+    "create",
+    "read",
+    "update",
+    "replace",
+    "merge",
+    "delete",
+    "list",
+    "clear",
+]
+
+# need to add clear
+# need to add support for bulk create, update, delete
+
+
+class _Op(NamedTuple):
+    """
+    Metadata for one REST/RPC operation registered by Tigrbl.
+    """
+
+    verb: str  # e.g. "create", "list"
+    http: str  # "POST" | "GET" | "PATCH" | …
+    path: str  # URL suffix, e.g. "/{item_id}"
+    In: Type | None  # Pydantic input model (or None)
+    Out: Type  # Pydantic output model
+    core: Callable[..., Any]  # The actual implementation
+
+
+__all__ = ["_Op", "_SchemaVerb"]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/types/uuid.py

@@ -0,0 +1,55 @@
+# ── Standard Library ─────────────────────────────────────────────────────
+from __future__ import annotations
+
+from typing import Any
+import uuid
+
+# ── Third-party Dependencies ────────────────────────────────────────────
+from sqlalchemy.types import TypeDecorator
+
+# ── Local Package ───────────────────────────────────────────────────────
+from ..vendor.sqlalchemy import String, _PgUUID
+
+
+class PgUUID(_PgUUID):
+    @property
+    def hex(self):
+        return self.as_uuid.hex
+
+
+class SqliteUUID(TypeDecorator):
+    """UUID type that stores hyphenated strings on SQLite to avoid numeric coercion."""
+
+    impl = String(36)
+    cache_ok = True
+
+    def __init__(self, as_uuid: bool = True):
+        super().__init__()
+        self.as_uuid = as_uuid
+
+    @property
+    def python_type(self) -> type:
+        return uuid.UUID if self.as_uuid else str
+
+    def load_dialect_impl(self, dialect) -> Any:
+        if dialect.name == "postgresql":
+            return dialect.type_descriptor(PgUUID(as_uuid=self.as_uuid))
+        return dialect.type_descriptor(String(36))
+
+    def process_bind_param(self, value: Any, dialect) -> Any:
+        if value is None:
+            return None
+        if self.as_uuid:
+            if not isinstance(value, uuid.UUID):
+                value = uuid.UUID(str(value))
+            return value if dialect.name == "postgresql" else str(value)
+        return str(value)
+
+    def process_result_value(self, value: Any, dialect) -> Any:
+        if value is None:
+            return None
+        if self.as_uuid:
+            if isinstance(value, uuid.UUID):
+                return value
+            return uuid.UUID(str(value))
+        return str(value)

tigrbl_typing-0.1.0.dev5/tigrbl_typing/vendor/__init__.py

@@ -0,0 +1 @@
+"""Vendor dependency re-export namespace."""

tigrbl_typing-0.1.0.dev5/tigrbl_typing/vendor/pydantic.py

@@ -0,0 +1,5 @@
+"""Pydantic symbols re-exported for typing compatibility."""
+
+from pydantic import BaseModel, Field, ValidationError
+
+__all__ = ["BaseModel", "Field", "ValidationError"]

tigrbl_typing-0.1.0.dev5/tigrbl_typing/vendor/sqlalchemy.py

@@ -0,0 +1,84 @@
+"""SQLAlchemy symbols re-exported for typing compatibility."""
+
+from sqlalchemy import (
+    Boolean,
+    CheckConstraint,
+    Column,
+    DateTime as _DateTime,
+    Enum as SAEnum,
+    ForeignKey,
+    Index,
+    Integer,
+    JSON,
+    LargeBinary,
+    Numeric,
+    String,
+    Text,
+    TypeDecorator,
+    UniqueConstraint,
+    create_engine,
+    event,
+)
+from sqlalchemy.dialects.postgresql import (
+    ARRAY,
+    ENUM as PgEnum,
+    JSONB,
+    TSVECTOR,
+    UUID as _PgUUID,
+)
+from sqlalchemy.ext.hybrid import hybrid_property
+from sqlalchemy.ext.mutable import MutableDict, MutableList
+from sqlalchemy.orm import (
+    InstrumentedAttribute,
+    Mapped,
+    Session,
+    column_property,
+    declarative_mixin,
+    declared_attr,
+    foreign,
+    mapped_column,
+    relationship,
+    remote,
+    sessionmaker,
+)
+from sqlalchemy.pool import StaticPool
+
+__all__ = [
+    "Boolean",
+    "Column",
+    "_DateTime",
+    "SAEnum",
+    "Text",
+    "ForeignKey",
+    "Index",
+    "Integer",
+    "JSON",
+    "Numeric",
+    "String",
+    "LargeBinary",
+    "UniqueConstraint",
+    "CheckConstraint",
+    "create_engine",
+    "event",
+    "ARRAY",
+    "PgEnum",
+    "JSONB",
+    "TSVECTOR",
+    "_PgUUID",
+    "Mapped",
+    "declarative_mixin",
+    "declared_attr",
+    "foreign",
+    "mapped_column",
+    "relationship",
+    "remote",
+    "column_property",
+    "Session",
+    "sessionmaker",
+    "InstrumentedAttribute",
+    "MutableDict",
+    "MutableList",
+    "hybrid_property",
+    "StaticPool",
+    "TypeDecorator",
+]