tigrbl-base 0.1.0.dev1__py3-none-any.whl

tigrbl_base/_base/__init__.py

@@ -0,0 +1,24 @@
+"""Base class implementations for tigrbl internals."""
+
+from ._hook_base import HookBase
+from ._storage import ForeignKeyBase
+from ._op_base import OpBase
+from ._request_base import RequestBase
+from ._schema_base import SchemaBase
+from ._session_abc import SessionABC
+from ._session_base import TigrblSessionBase
+from ._table_base import TableBase
+from ._table_registry_base import TableRegistryBase
+
+
+__all__ = [
+    "HookBase",
+    "ForeignKeyBase",
+    "OpBase",
+    "RequestBase",
+    "SchemaBase",
+    "SessionABC",
+    "TigrblSessionBase",
+    "TableBase",
+    "TableRegistryBase",
+]

tigrbl_base/_base/_hook_base.py

@@ -0,0 +1,25 @@
+"""Base runtime hook wrapper for Tigrbl v3."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Optional, Union
+
+from tigrbl_core._spec.hook_spec import HookSpec
+from tigrbl_runtime.runtime.hook_types import HookPhase, StepFn
+
+
+@dataclass(frozen=True, slots=True)
+class HookBase(HookSpec):
+    """Base hook bound to a phase and one or more ops."""
+
+    phase: HookPhase
+    fn: StepFn
+    ops: Union[str, Iterable[str]] = "*"
+    order: int = 0
+    when: Optional[object] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+
+
+__all__ = ["HookBase"]

tigrbl_base/_base/_middleware_base.py

@@ -0,0 +1,146 @@
+"""Request/response middleware base with ``dispatch`` + ``call_next`` semantics."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlencode
+
+from tigrbl_concrete._concrete._request import Request
+from tigrbl_concrete._concrete._request_adapters import request_from_asgi
+from tigrbl_concrete._concrete._response import Response
+from tigrbl_atoms.atoms.egress.asgi_send import finalize_transport_response
+
+from tigrbl_core._spec.middleware_spec import (
+    ASGIReceive,
+    ASGISend,
+    Message,
+    MiddlewareSpec,
+)
+
+
+class MiddlewareBase(MiddlewareSpec):
+    """Base middleware for intercepting HTTP requests in ASGI mode."""
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Any,
+    ) -> Response:
+        """Process the request and optionally delegate to downstream middleware/app."""
+
+        return await call_next(request)
+
+    @staticmethod
+    def _scope_from_request(scope: dict[str, Any], request: Request) -> dict[str, Any]:
+        query_string = urlencode(
+            [
+                (name, value)
+                for name, values in request.query.items()
+                for value in values
+            ],
+            doseq=True,
+        ).encode("latin-1")
+        return {
+            **scope,
+            "method": request.method,
+            "path": request.path,
+            "query_string": query_string,
+            "headers": [
+                (key.encode("latin-1"), value.encode("latin-1"))
+                for key, value in request.headers.items()
+            ],
+            "root_path": request.script_name,
+        }
+
+    async def asgi(
+        self,
+        scope: dict[str, Any],
+        receive: ASGIReceive,
+        send: ASGISend,
+    ) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request_body = b""
+        more_body = True
+        while more_body:
+            message = await receive()
+            request_body += message.get("body", b"")
+            more_body = message.get("more_body", False)
+
+        request = request_from_asgi(None, scope, request_body)
+
+        async def call_next(forward_request: Request | None = None) -> Response:
+            target_request = forward_request or request
+            target_scope = self._scope_from_request(scope, target_request)
+
+            messages: list[Message] = []
+            body_sent = False
+
+            async def receive_for_app() -> Message:
+                nonlocal body_sent
+                if body_sent:
+                    return {"type": "http.request", "body": b"", "more_body": False}
+                body_sent = True
+                return {
+                    "type": "http.request",
+                    "body": target_request.body,
+                    "more_body": False,
+                }
+
+            async def send_from_app(message: Message) -> None:
+                messages.append(message)
+
+            await self.app(target_scope, receive_for_app, send_from_app)
+
+            start = next(
+                message
+                for message in messages
+                if message.get("type") == "http.response.start"
+            )
+            raw_headers = list(start.get("headers", []))
+            body = b"".join(
+                message.get("body", b"")
+                for message in messages
+                if message.get("type") == "http.response.body"
+            )
+            headers, finalized_body = finalize_transport_response(
+                target_scope,
+                int(start.get("status", 200)),
+                raw_headers,
+                body,
+            )
+            return Response(
+                status_code=int(start.get("status", 200)),
+                headers=[
+                    (key.decode("latin-1"), value.decode("latin-1"))
+                    for key, value in headers
+                ],
+                body=finalized_body,
+            )
+
+        response = await self.dispatch(request, call_next)
+        headers, finalized_body = finalize_transport_response(
+            scope,
+            response.status_code,
+            response.raw_headers,
+            response.body,
+        )
+        await send(
+            {
+                "type": "http.response.start",
+                "status": response.status_code,
+                "headers": headers,
+            }
+        )
+        await send(
+            {
+                "type": "http.response.body",
+                "body": finalized_body,
+                "more_body": False,
+            }
+        )
+
+
+__all__ = ["MiddlewareBase"]

tigrbl_base/_base/_op_base.py

@@ -0,0 +1,12 @@
+"""Base operation descriptor implementation for Tigrbl."""
+
+from __future__ import annotations
+
+from tigrbl_core._spec.op_spec import OpSpec
+
+
+class OpBase(OpSpec):
+    """Base operation descriptor type."""
+
+
+__all__ = ["OpBase"]

tigrbl_base/_base/_request_base.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any
+
+from tigrbl_core._spec.request_spec import RequestSpec
+
+
+class RequestBase(RequestSpec):
+    """Base request model behavior shared by concrete request implementations."""
+
+    @classmethod
+    def from_scope(
+        cls,
+        scope: dict[str, Any],
+        receive: Any | None = None,
+        *,
+        app: Any | None = None,
+        state: Any | None = None,
+    ) -> "RequestBase":
+        """Construct a request from an ASGI scope.
+
+        Middleware/tests may resolve ``Request`` through base/spec surfaces during
+        import cycles. Delegate to the concrete request model to keep
+        ``Request.from_scope(...)`` consistently available.
+        """
+
+        from tigrbl_concrete._concrete._request import Request
+
+        return Request.from_scope(scope, receive, app=app, state=state)
+
+
+__all__ = ["RequestBase"]

tigrbl_base/_base/_response_base.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import json as json_module
+from dataclasses import dataclass
+from http.cookies import SimpleCookie
+from typing import Any, Mapping
+
+from tigrbl_concrete._concrete._headers import HeaderCookies, Headers
+
+from tigrbl_core._spec.response_spec import ResponseSpec, TemplateSpec
+
+
+class _JSONDualMethod:
+    def __get__(
+        self,
+        obj: "ResponseBase" | None,
+        owner: type["ResponseBase"],
+    ):
+        if obj is None:
+
+            def _factory(
+                data: Any,
+                status_code: int = 200,
+                headers: Mapping[str, str] | None = None,
+            ) -> "ResponseBase":
+                return owner.from_json(data, status_code=status_code, headers=headers)
+
+            return _factory
+
+        def _instance_json() -> Any:
+            return obj.json_body()
+
+        return _instance_json
+
+
+class ResponseBase(ResponseSpec):
+    """Concrete HTTP response object that also implements ``ResponseSpec``."""
+
+    json = _JSONDualMethod()
+
+    def __init__(
+        self,
+        *,
+        status_code: int = 200,
+        headers: Mapping[str, str] | list[tuple[str, str]] | None = None,
+        body: bytes | None = None,
+        content: bytes | None = None,
+        media_type: str | None = None,
+        kind: str = "auto",
+        envelope: bool | None = None,
+        template: TemplateSpec | None = None,
+        filename: str | None = None,
+        download: bool | None = None,
+        etag: str | None = None,
+        cache_control: str | None = None,
+        redirect_to: str | None = None,
+    ) -> None:
+        if body is not None and content is not None:
+            raise TypeError(
+                "ResponseBase: provide either 'body' or 'content', not both"
+            )
+
+        payload = (
+            body if body is not None else (content if content is not None else b"")
+        )
+
+        super().__init__(
+            kind=kind,
+            media_type=media_type,
+            status_code=status_code,
+            headers={
+                k: v
+                for k, v in (
+                    headers.items() if hasattr(headers, "items") else (headers or [])
+                )
+            },
+            envelope=envelope,
+            template=template,
+            filename=filename,
+            download=download,
+            etag=etag,
+            cache_control=cache_control,
+            redirect_to=redirect_to,
+        )
+        self.status_code = status_code
+        self.headers = Headers(headers or {})
+        self.body = payload
+        self.media_type = media_type
+        self._headers = self.headers
+
+    @staticmethod
+    def _status_text(code: int) -> str:
+        return {
+            200: "OK",
+            201: "Created",
+            205: "Reset Content",
+            204: "No Content",
+            301: "Moved Permanently",
+            302: "Found",
+            307: "Temporary Redirect",
+            308: "Permanent Redirect",
+            400: "Bad Request",
+            401: "Unauthorized",
+            403: "Forbidden",
+            404: "Not Found",
+            405: "Method Not Allowed",
+            422: "Unprocessable Entity",
+            500: "Internal Server Error",
+        }.get(code, "OK")
+
+    def status_line(self) -> str:
+        return f"{self.status_code} {self._status_text(self.status_code)}"
+
+    @property
+    def raw_headers(self) -> list[tuple[bytes, bytes]]:
+        return [
+            (k.encode("latin-1"), v.encode("latin-1")) for k, v in self.headers.items()
+        ]
+
+    @property
+    def headers_map(self) -> Headers:
+        return self.headers
+
+    @property
+    def body_text(self) -> str:
+        return self.body.decode("utf-8")
+
+    def json_body(self) -> Any:
+        if not self.body:
+            return None
+        return json_module.loads(self.body.decode("utf-8"))
+
+    @property
+    def cookies(self) -> HeaderCookies:
+        cookie = SimpleCookie()
+        for name, value in self.headers.items():
+            if name == "set-cookie":
+                cookie.load(value)
+        return HeaderCookies({name: morsel.value for name, morsel in cookie.items()})
+
+    def set_cookie(
+        self,
+        key: str,
+        value: str,
+        *,
+        path: str = "/",
+        domain: str | None = None,
+        secure: bool = False,
+        httponly: bool = False,
+        samesite: str | None = None,
+        max_age: int | None = None,
+        expires: str | None = None,
+    ) -> None:
+        cookie = SimpleCookie()
+        cookie[key] = value
+        morsel = cookie[key]
+        morsel["path"] = path
+        if domain is not None:
+            morsel["domain"] = domain
+        if secure:
+            morsel["secure"] = True
+        if httponly:
+            morsel["httponly"] = True
+        if samesite is not None:
+            morsel["samesite"] = samesite
+        if max_age is not None:
+            morsel["max-age"] = str(max_age)
+        if expires is not None:
+            morsel["expires"] = expires
+        self.headers["set-cookie"] = cookie.output(header="").strip()
+
+    @classmethod
+    def from_json(
+        cls,
+        data: Any,
+        status_code: int = 200,
+        headers: Mapping[str, str] | None = None,
+    ) -> "ResponseBase":
+        payload = json_module.dumps(
+            data, ensure_ascii=False, separators=(",", ":"), default=str
+        ).encode("utf-8")
+        hdrs = [("content-type", "application/json; charset=utf-8")]
+        for k, v in (headers or {}).items():
+            hdrs.append((k.lower(), v))
+        return cls(
+            status_code=status_code,
+            headers=hdrs,
+            body=payload,
+            media_type="application/json",
+        )
+
+    @classmethod
+    def html(
+        cls,
+        html: str,
+        status_code: int = 200,
+        headers: Mapping[str, str] | None = None,
+    ) -> "ResponseBase":
+        payload = html.encode("utf-8")
+        hdrs = [("content-type", "text/html; charset=utf-8")]
+        for k, v in (headers or {}).items():
+            hdrs.append((k.lower(), v))
+        return cls(
+            status_code=status_code,
+            headers=hdrs,
+            body=payload,
+            media_type="text/html",
+        )
+
+    @classmethod
+    def text(
+        cls,
+        text: str,
+        status_code: int = 200,
+        headers: Mapping[str, str] | None = None,
+    ) -> "ResponseBase":
+        payload = text.encode("utf-8")
+        hdrs = [("content-type", "text/plain; charset=utf-8")]
+        for k, v in (headers or {}).items():
+            hdrs.append((k.lower(), v))
+        return cls(
+            status_code=status_code,
+            headers=hdrs,
+            body=payload,
+            media_type="text/plain",
+        )
+
+
+@dataclass
+class TemplateBase(TemplateSpec):
+    """Concrete template configuration used at runtime."""

tigrbl_base/_base/_schema_base.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+
+class SchemaBase:
+    """Shared schema helpers used by concrete schema wrappers."""
+
+    @classmethod
+    def collect(cls, model: type) -> dict[str, dict[str, type]]:
+        from tigrbl_canon.mapping.collect_decorated_schemas import (
+            collect_decorated_schemas,
+        )
+
+        return collect_decorated_schemas(model)
+
+
+__all__ = ["SchemaBase"]

tigrbl_base/_base/_security_base.py

@@ -0,0 +1,69 @@
+"""Core OpenAPI security scheme primitives."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+_VALID_SECURITY_SCHEME_TYPES = {
+    "http",
+    "apiKey",
+    "oauth2",
+    "openIdConnect",
+    "mutualTLS",
+}
+
+
+class OpenAPISecurityDependency:
+    """Base security dependency with OpenAPI document metadata."""
+
+    def __init__(
+        self,
+        *,
+        scheme_name: str,
+        scheme: Mapping[str, Any],
+        scopes: Sequence[str] | None = None,
+        auto_error: bool = True,
+    ) -> None:
+        self.scheme_name = scheme_name
+        self.auto_error = auto_error
+        self._scheme = dict(scheme)
+        self._scopes = list(scopes or [])
+        validate_openapi_security_scheme(self._scheme)
+
+    def openapi_security_scheme(self) -> dict[str, Any]:
+        return dict(self._scheme)
+
+    def openapi_security_requirement(self) -> dict[str, list[str]]:
+        return {self.scheme_name: list(self._scopes)}
+
+    def __call__(self, request: Any) -> Any | None:
+        return None
+
+
+def validate_openapi_security_scheme(scheme: Mapping[str, Any]) -> None:
+    scheme_type = scheme.get("type")
+    if scheme_type not in _VALID_SECURITY_SCHEME_TYPES:
+        raise ValueError(
+            "OpenAPI security scheme 'type' must be one of: "
+            f"{sorted(_VALID_SECURITY_SCHEME_TYPES)}"
+        )
+
+    if "scheme" in scheme and scheme_type != "http":
+        raise ValueError("OpenAPI 'scheme' is only valid when type is 'http'.")
+
+    if scheme_type == "http" and not scheme.get("scheme"):
+        raise ValueError("OpenAPI type='http' requires a non-empty 'scheme'.")
+
+    if scheme_type == "apiKey":
+        if scheme.get("in") not in {"header", "query", "cookie"}:
+            raise ValueError(
+                "OpenAPI type='apiKey' requires 'in' to be header/query/cookie."
+            )
+        if not scheme.get("name"):
+            raise ValueError("OpenAPI type='apiKey' requires 'name'.")
+
+    if scheme_type == "oauth2" and not isinstance(scheme.get("flows"), Mapping):
+        raise ValueError("OpenAPI type='oauth2' requires a 'flows' object.")
+
+    if scheme_type == "openIdConnect" and not scheme.get("openIdConnectUrl"):
+        raise ValueError("OpenAPI type='openIdConnect' requires 'openIdConnectUrl'.")

tigrbl_base/_base/_session_abc.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+
+class SessionABC(ABC):
+    """Authoritative Tigrbl session interface."""
+
+    @abstractmethod
+    async def begin(self) -> None: ...
+
+    @abstractmethod
+    async def commit(self) -> None: ...
+
+    @abstractmethod
+    async def rollback(self) -> None: ...
+
+    @abstractmethod
+    def in_transaction(self) -> bool: ...
+
+    @abstractmethod
+    async def get(self, model: type, ident: Any) -> Any | None: ...
+
+    @abstractmethod
+    def add(self, obj: Any) -> None: ...
+
+    @abstractmethod
+    async def delete(self, obj: Any) -> None: ...
+
+    @abstractmethod
+    async def flush(self) -> None: ...
+
+    @abstractmethod
+    async def refresh(self, obj: Any) -> None: ...
+
+    @abstractmethod
+    async def execute(self, stmt: Any) -> Any: ...
+
+    @abstractmethod
+    async def close(self) -> None: ...
+
+    @abstractmethod
+    async def run_sync(self, fn: Callable[[Any], Any]) -> Any: ...
+
+
+__all__ = ["SessionABC"]

tigrbl_base/_base/_session_base.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Callable, List, Optional
+
+from ._session_abc import SessionABC
+from tigrbl_core._spec.session_spec import SessionSpec
+
+
+@dataclass
+class TigrblSessionBase(SessionABC):
+    _spec: Optional[SessionSpec] = None
+    _open: bool = field(default=False, init=False)
+    _dirty: bool = field(default=False, init=False)
+    _pending: List[asyncio.Task] = field(default_factory=list, init=False)
+
+    def apply_spec(self, spec: SessionSpec | None) -> None:
+        self._spec = spec
+
+    async def run_sync(self, fn: Callable[[Any], Any]) -> Any:
+        rv = fn(self)
+        if inspect.isawaitable(rv):
+            return await rv
+        return rv
+
+    async def begin(self) -> None:
+        await self._tx_begin_impl()
+        self._open = True
+
+    async def commit(self) -> None:
+        if self._spec and self._spec.read_only and self._dirty:
+            raise RuntimeError("read-only session: writes detected before commit")
+        await self.flush()
+        await self._tx_commit_impl()
+        self._open = False
+        self._dirty = False
+
+    async def rollback(self) -> None:
+        for t in self._pending:
+            try:
+                t.cancel()
+            except Exception:
+                pass
+        self._pending.clear()
+        await self._tx_rollback_impl()
+        self._open = False
+        self._dirty = False
+
+    def in_transaction(self) -> bool:
+        return bool(self._open)
+
+    def add(self, obj: Any) -> None:
+        if self._spec and self._spec.read_only:
+            raise RuntimeError("write attempted in read-only session (add)")
+        self._dirty = True
+        rv = self._add_impl(obj)
+        if inspect.isawaitable(rv):
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                asyncio.run(rv)
+            else:
+                self._pending.append(loop.create_task(rv))
+
+    async def delete(self, obj: Any) -> None:
+        if self._spec and self._spec.read_only:
+            raise RuntimeError("write attempted in read-only session (delete)")
+        self._dirty = True
+        await self._delete_impl(obj)
+
+    async def flush(self) -> None:
+        if self._pending:
+            done, _ = await asyncio.wait(
+                self._pending, return_when=asyncio.ALL_COMPLETED
+            )
+            self._pending = []
+            for t in done:
+                _ = t.result()
+        await self._flush_impl()
+
+    async def refresh(self, obj: Any) -> None:
+        await self._refresh_impl(obj)
+
+    async def get(self, model: type, ident: Any) -> Any | None:
+        return await self._get_impl(model, ident)
+
+    async def execute(self, stmt: Any) -> Any:
+        return await self._execute_impl(stmt)
+
+    async def close(self) -> None:
+        for t in self._pending:
+            try:
+                t.cancel()
+            except Exception:
+                pass
+        self._pending = []
+        await self._close_impl()
+
+    async def _tx_begin_impl(self) -> None:
+        raise NotImplementedError
+
+    async def _tx_commit_impl(self) -> None:
+        raise NotImplementedError
+
+    async def _tx_rollback_impl(self) -> None:
+        raise NotImplementedError
+
+    def _add_impl(self, obj: Any) -> Any:
+        raise NotImplementedError
+
+    async def _delete_impl(self, obj: Any) -> None:
+        raise NotImplementedError
+
+    async def _flush_impl(self) -> None:
+        return
+
+    async def _refresh_impl(self, obj: Any) -> None:
+        return
+
+    async def _get_impl(self, model: type, ident: Any) -> Any | None:
+        raise NotImplementedError
+
+    async def _execute_impl(self, stmt: Any) -> Any:
+        raise NotImplementedError
+
+    async def _close_impl(self) -> None:
+        return
+
+
+__all__ = ["TigrblSessionBase"]

tigrbl_base/_base/_storage.py

@@ -0,0 +1,13 @@
+"""Base storage-layer primitives."""
+
+from dataclasses import dataclass
+
+from tigrbl_core._spec.storage_spec import ForeignKeySpec
+
+
+@dataclass(frozen=True)
+class ForeignKeyBase(ForeignKeySpec):
+    """Base foreign-key configuration shared by concrete implementations."""
+
+
+__all__ = ["ForeignKeyBase"]

tigrbl_base/_base/_table_base.py

@@ -0,0 +1,435 @@
+# tigrbl/tigrbl/table/_base.py
+from __future__ import annotations
+
+from typing import Any, Optional, Union, get_args, get_origin
+from enum import Enum as PyEnum
+
+from sqlalchemy.orm import DeclarativeBase, declared_attr, mapped_column
+from sqlalchemy import CheckConstraint, ForeignKey, MetaData
+from sqlalchemy.types import Enum as SAEnum, String
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Helpers – type inference & SA type instantiation
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _unwrap_optional(t: Any) -> Any:
+    """Optional[T] / Union[T, None]  →  T"""
+    if get_origin(t) is Union:
+        args = [a for a in get_args(t) if a is not type(None)]
+        return args[0] if args else t
+    return t
+
+
+def _infer_py_type(cls, name: str, spec: Any) -> Optional[type]:
+    """
+    Prefer FieldSpec.py_type if provided; otherwise unwrap Mapped[...] / Optional[...]
+    from the class' annotation to get the real Python type for the column.
+    """
+    fld = getattr(spec, "field", None)
+    py = getattr(fld, "py_type", None)
+    if isinstance(py, type):
+        return py
+
+    ann = getattr(cls, "__annotations__", {}).get(name)
+    if ann is None:
+        return None
+
+    # Mapped[T] → T (then unwrap Optional)
+    try:
+        from sqlalchemy.orm import Mapped
+
+        if get_origin(ann) is Mapped:
+            inner = get_args(ann)[0]
+            return _unwrap_optional(inner)
+    except Exception:
+        pass
+
+    # Optional[T]/Union[T, None] → T
+    return _unwrap_optional(ann)
+
+
+def _instantiate_dtype(
+    dtype: Any, py_type: Any, spec: Any, cls_name: str, col_name: str
+):
+    """
+    Create a SQLAlchemy TypeEngine instance from either a type CLASS or an instance.
+    - SAEnum: instantiate from the actual Enum class with a stable name
+    - String: honor FieldSpec.constraints['max_length'] if present
+    - UUID (PG): prefer as_uuid=True when available
+    """
+    # Already an instance? keep it.
+    try:
+        from sqlalchemy.sql.type_api import TypeEngine
+
+        if isinstance(dtype, TypeEngine):
+            return dtype
+    except Exception:
+        pass
+
+    # SAEnum from a Python Enum class
+    if dtype is SAEnum and isinstance(py_type, type) and issubclass(py_type, PyEnum):
+        enum_name = f"{cls_name.lower()}_{col_name.lower()}"
+        return SAEnum(py_type, name=enum_name, native_enum=True, validate_strings=True)
+
+    # String – pick up max_length from FieldSpec
+    if dtype is String:
+        max_len = getattr(getattr(spec, "field", None), "constraints", {}).get(
+            "max_length"
+        )
+        return String(max_len) if max_len else String()
+
+    # PostgreSQL UUID (or similar) – try as_uuid=True first
+    try:
+        return dtype(as_uuid=True)  # e.g., PG UUID
+    except TypeError:
+        try:
+            return dtype()
+        except TypeError:
+            # As a last resort, return the class; SQLA will raise clearly if unusable
+            return dtype
+
+
+def _materialize_colspecs_to_sqla(cls, *, map_columns: bool = True) -> None:
+    """
+    Replace ColumnSpec attributes with sqlalchemy.orm.mapped_column(...) BEFORE mapping.
+    Keep the original specs in __tigrbl_cols__ for downstream builders.
+    """
+    try:
+        from tigrbl_core._spec.column_spec import ColumnSpec
+    except Exception:
+        return
+    try:
+        from sqlalchemy.orm import InstrumentedAttribute, MappedColumn
+    except Exception:  # pragma: no cover - defensive for minimal SQLA envs
+        InstrumentedAttribute = None
+        MappedColumn = None
+
+    # Prefer explicit registry if present; otherwise collect specs from the
+    # entire MRO so mixins contribute their ColumnSpec definitions.
+    specs: dict[str, ColumnSpec] = {}
+    for base in reversed(cls.__mro__):
+        base_specs = getattr(base, "__tigrbl_cols__", None)
+        if isinstance(base_specs, dict) and base_specs:
+            specs.update(base_specs)
+            continue
+        for name, attr in getattr(base, "__dict__", {}).items():
+            if isinstance(attr, ColumnSpec):
+                specs.setdefault(name, attr)
+
+    if not specs:
+        return
+
+    if map_columns:
+        for name, spec in specs.items():
+            storage = getattr(spec, "storage", None)
+            if not storage:
+                # Virtual (wire-only) column – ensure SQLAlchemy ignores it.
+                if MappedColumn is not None and isinstance(spec, MappedColumn):
+                    annotations = getattr(cls, "__annotations__", {}) or {}
+                    if name not in annotations:
+                        replacement = ColumnSpec(
+                            storage=None,
+                            field=getattr(spec, "field", None),
+                            io=getattr(spec, "io", None),
+                            default_factory=getattr(spec, "default_factory", None),
+                            read_producer=getattr(spec, "read_producer", None),
+                        )
+                        setattr(cls, name, replacement)
+                        specs[name] = replacement
+                continue
+            existing_attr = getattr(cls, name, None)
+            if InstrumentedAttribute is not None and isinstance(
+                existing_attr, InstrumentedAttribute
+            ):
+                # Column already mapped on a base class; avoid duplicating columns
+                # that trigger SQLAlchemy implicit combination warnings.
+                continue
+
+            dtype = getattr(storage, "type_", None)
+            if not dtype:
+                # No SA dtype specified – cannot materialize
+                continue
+
+            py_type = _infer_py_type(cls, name, spec)
+            dtype_inst = _instantiate_dtype(dtype, py_type, spec, cls.__name__, name)
+
+            # Foreign key (if any)
+            fk = getattr(storage, "fk", None)
+            fk_arg = None
+            if fk is not None:
+                # ForeignKeySpec: target="table(col)", on_delete/on_update: "CASCADE"/...
+                fk_arg = ForeignKey(
+                    fk.target, ondelete=fk.on_delete, onupdate=fk.on_update
+                )
+
+            check = getattr(storage, "check", None)
+            args: list[Any] = []
+            if fk_arg is not None:
+                args.append(fk_arg)
+            if check is not None:
+                cname = f"ck_{cls.__name__.lower()}_{name}"
+                args.append(CheckConstraint(check, name=cname))
+
+            # Build mapped_column from StorageSpec flags
+            mc = mapped_column(
+                dtype_inst,
+                *args,
+                primary_key=getattr(storage, "primary_key", False),
+                nullable=getattr(storage, "nullable", True),
+                unique=getattr(storage, "unique", False),
+                index=getattr(storage, "index", False),
+                default=getattr(storage, "default", None),
+                onupdate=getattr(storage, "onupdate", None),
+                server_default=getattr(storage, "server_default", None),
+                comment=getattr(storage, "comment", None),
+                autoincrement=getattr(storage, "autoincrement", None),
+            )
+
+            setattr(cls, name, mc)
+
+    # Ensure downstream code can find the spec map
+    setattr(cls, "__tigrbl_cols__", dict(specs))
+
+
+def _ensure_instrumented_attr_accessors() -> None:
+    """Expose ColumnSpec metadata on SQLAlchemy InstrumentedAttribute objects."""
+    try:
+        from sqlalchemy.orm.attributes import InstrumentedAttribute
+    except Exception:  # pragma: no cover - defensive for minimal SQLA envs
+        return
+
+    if not hasattr(InstrumentedAttribute, "storage"):
+
+        def _storage(self):  # type: ignore[no-untyped-def]
+            spec = getattr(self.class_, "__tigrbl_cols__", {}).get(self.key)
+            return getattr(spec, "storage", None)
+
+        InstrumentedAttribute.storage = property(_storage)  # type: ignore[attr-defined]
+
+    if not hasattr(InstrumentedAttribute, "field"):
+
+        def _field(self):  # type: ignore[no-untyped-def]
+            spec = getattr(self.class_, "__tigrbl_cols__", {}).get(self.key)
+            return getattr(spec, "field", None)
+
+        InstrumentedAttribute.field = property(_field)  # type: ignore[attr-defined]
+
+    if not hasattr(InstrumentedAttribute, "io"):
+
+        def _io(self):  # type: ignore[no-untyped-def]
+            spec = getattr(self.class_, "__tigrbl_cols__", {}).get(self.key)
+            return getattr(spec, "io", None)
+
+        InstrumentedAttribute.io = property(_io)  # type: ignore[attr-defined]
+
+    if not hasattr(InstrumentedAttribute, "default_factory"):
+
+        def _default_factory(self):  # type: ignore[no-untyped-def]
+            spec = getattr(self.class_, "__tigrbl_cols__", {}).get(self.key)
+            return getattr(spec, "default_factory", None)
+
+        InstrumentedAttribute.default_factory = property(_default_factory)  # type: ignore[attr-defined]
+
+    if not hasattr(InstrumentedAttribute, "read_producer"):
+
+        def _read_producer(self):  # type: ignore[no-untyped-def]
+            spec = getattr(self.class_, "__tigrbl_cols__", {}).get(self.key)
+            return getattr(spec, "read_producer", None)
+
+        InstrumentedAttribute.read_producer = property(_read_producer)  # type: ignore[attr-defined]
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Declarative Base
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+class TableBase(DeclarativeBase):
+    __allow_unmapped__ = True
+
+    def __init_subclass__(cls, **kw):
+        # 0) Remove any previously registered class with the same module path.
+        try:
+            reg = TableBase.registry._class_registry
+            name = cls.__name__
+            existing = reg.get(name)
+            if existing is not None:
+                try:
+                    TableBase.registry._dispose_cls(existing)
+                except Exception:
+                    pass
+                reg.pop(name, None)
+            module_reg = reg.get("_sa_module_registry")
+            if module_reg is not None:
+                marker = module_reg
+                for part in cls.__module__.split("."):
+                    contents = getattr(marker, "contents", None)
+                    if not isinstance(contents, dict) or part not in contents:
+                        marker = None
+                        break
+                    marker = contents.get(part)
+                if marker is not None and isinstance(
+                    getattr(marker, "contents", None), dict
+                ):
+                    marker.contents.pop(name, None)
+        except Exception:
+            pass
+
+        # 0.5) If a table with the same name already exists, allow this class
+        # to extend it instead of raising duplicate-table errors.
+        try:
+            table_name = getattr(cls, "__tablename__", None)
+            if table_name and table_name in TableBase.metadata.tables:
+                table_args = getattr(cls, "__table_args__", None)
+                if table_args is None:
+                    cls.__table_args__ = {"extend_existing": True}
+                elif isinstance(table_args, dict):
+                    table_args = dict(table_args)
+                    table_args["extend_existing"] = True
+                    cls.__table_args__ = table_args
+                elif isinstance(table_args, tuple):
+                    if table_args and isinstance(table_args[-1], dict):
+                        table_dict = dict(table_args[-1])
+                        table_dict["extend_existing"] = True
+                        cls.__table_args__ = (*table_args[:-1], table_dict)
+                    else:
+                        cls.__table_args__ = (*table_args, {"extend_existing": True})
+        except Exception:
+            pass
+
+        # 1) Determine whether this class should be mapped.
+        try:
+            from sqlalchemy import Column as _SAColumn
+            from sqlalchemy.orm import MappedColumn as _MappedColumn
+        except Exception:  # pragma: no cover - defensive
+            _SAColumn = None
+            _MappedColumn = None
+
+        def _has_mappable_columns() -> bool:
+            for base in cls.__mro__:
+                for attr in getattr(base, "__dict__", {}).values():
+                    if _SAColumn is not None and isinstance(attr, _SAColumn):
+                        return True
+                    if _MappedColumn is not None and isinstance(attr, _MappedColumn):
+                        return True
+                    storage = getattr(attr, "storage", None)
+                    if storage is not None:
+                        return True
+                mapping = getattr(base, "__tigrbl_cols__", None)
+                if isinstance(mapping, dict):
+                    for spec in mapping.values():
+                        if _MappedColumn is not None and isinstance(
+                            spec, _MappedColumn
+                        ):
+                            return True
+                        storage = getattr(spec, "storage", None)
+                        if storage is not None:
+                            return True
+            return False
+
+        def _has_primary_key() -> bool:
+            mapper_args = getattr(cls, "__mapper_args__", None)
+            if isinstance(mapper_args, dict) and mapper_args.get("primary_key"):
+                return True
+            for base in cls.__mro__:
+                for attr in getattr(base, "__dict__", {}).values():
+                    if _SAColumn is not None and isinstance(attr, _SAColumn):
+                        if getattr(attr, "primary_key", False):
+                            return True
+                    if _MappedColumn is not None and isinstance(attr, _MappedColumn):
+                        if getattr(attr, "primary_key", False):
+                            return True
+                    storage = getattr(attr, "storage", None)
+                    if storage is not None and getattr(storage, "primary_key", False):
+                        return True
+                mapping = getattr(base, "__tigrbl_cols__", None)
+                if isinstance(mapping, dict):
+                    for spec in mapping.values():
+                        storage = getattr(spec, "storage", None)
+                        if storage is not None and getattr(
+                            storage, "primary_key", False
+                        ):
+                            return True
+            return False
+
+        explicit_abstract = "__abstract__" in cls.__dict__
+        if not explicit_abstract:
+            if not _has_mappable_columns() or not _has_primary_key():
+                cls.__abstract__ = True
+            else:
+                cls.__abstract__ = False
+
+        should_map = not getattr(cls, "__abstract__", False)
+
+        # 1.5) BEFORE SQLAlchemy maps: turn ColumnSpecs into real mapped_column(...)
+        _materialize_colspecs_to_sqla(cls, map_columns=should_map)
+        _ensure_instrumented_attr_accessors()
+
+        # 2) Let SQLAlchemy map the class (PK now exists)
+        super().__init_subclass__(**kw)
+
+        # 2.5) Surface ctx-only op declarations for lightweight introspection.
+        if not hasattr(cls, "__tigrbl_ops__"):
+            for attr in cls.__dict__.values():
+                target = getattr(attr, "__func__", attr)
+                if getattr(target, "__tigrbl_op_spec__", None) is not None:
+                    cls.__tigrbl_ops__ = tuple()
+                    break
+
+        # 2.6) Collect response specs declared via @response_ctx.
+        responses = {}
+        for name, obj in cls.__dict__.items():
+            spec = getattr(obj, "__tigrbl_response_spec__", None)
+            if spec is None:
+                continue
+            alias = getattr(obj, "__tigrbl_response_alias__", None) or name
+            responses[alias] = spec
+        if responses:
+            cls.responses = responses
+            cls.response = next(iter(responses.values()))
+
+        # 3) Seed model namespaces / index specs (ops/hooks/etc.) – idempotent
+        try:
+            from tigrbl_canon.mapping import model as _model_bind
+
+            _model_bind.bind(cls)
+        except Exception:
+            pass
+
+        # 3) AUTO-BUILD CRUD schemas from ColumnSpecs so /docs has them
+        try:
+            from tigrbl_canon.mapping import build_schemas as _build_schemas
+
+            _build_schemas(
+                cls
+            )  # attaches request/response models to the model/registry
+        except Exception:
+            # Surface during development if needed:
+            # raise
+            pass
+
+    metadata = MetaData(
+        naming_convention={
+            "pk": "pk_%(table_name)s",
+            "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+            "ix": "ix_%(table_name)s_%(column_0_name)s",
+            "uq": "uq_%(table_name)s_%(column_0_name)s",
+            "ck": "ck_%(table_name)s_%(column_0_name)s_%(constraint_type)s",
+        }
+    )
+
+    @declared_attr.directive
+    def __tablename__(cls) -> str:  # noqa: N805
+        return cls.__name__.lower()
+
+    @declared_attr.directive
+    def resource_name(cls):  # noqa: N805
+        return getattr(cls, "__resource__", cls.__name__.lower())
+
+    def __getitem__(self, key: str) -> Any:
+        """Allow dict-style access to model attributes."""
+        return getattr(self, key)
+
+
+__all__ = ["TableBase"]

tigrbl_base/_base/_table_registry_base.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+
+class TableRegistryBase(dict[str, Any]):
+    """Dict-like registry used for table/model lookups."""
+
+    def __init__(self, tables: Iterable[Any] = ()) -> None:
+        resolved_tables = tuple(tables or ())
+        dict.__init__(self)
+        self.tables = resolved_tables
+        self.register_many(resolved_tables)
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            value = self[name]
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+        # Preserve historic table-registry attribute behavior where
+        # ``registry.Widget`` surfaced SQLAlchemy table metadata while key-based
+        # lookup remains model-centric for runtime mapping.
+        if isinstance(value, type):
+            table = getattr(value, "__table__", None)
+            if table is not None:
+                return table
+        return value
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name == "tables" or name.startswith("_"):
+            super().__setattr__(name, value)
+            return
+        self[name] = value
+
+    def register(self, entry: Any) -> None:
+        if isinstance(entry, tuple) and len(entry) == 2 and isinstance(entry[0], str):
+            alias, model = entry
+            self[alias] = model
+            model_name = getattr(model, "__name__", alias)
+            self.setdefault(model_name, model)
+            return
+
+        model = entry
+        model_name = getattr(model, "__name__", None)
+        if model_name is None:
+            model_name = str(model)
+        self[model_name] = model
+
+    def register_many(self, tables: Iterable[Any]) -> None:
+        for entry in tables:
+            self.register(entry)
+
+
+__all__ = ["TableRegistryBase"]

tigrbl_base-0.1.0.dev1.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: tigrbl-base
+Version: 0.1.0.dev1
+Summary: Abstract base interfaces for Tigrbl APIs and runtime components.
+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-atoms
+Requires-Dist: tigrbl-canon
+Requires-Dist: tigrbl-concrete
+Requires-Dist: tigrbl-core
+Requires-Dist: tigrbl-runtime
+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-base
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-base.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-base.svg) ![License](https://img.shields.io/pypi/l/tigrbl-base.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-base.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-base
+```
+
+### pip
+
+```bash
+pip install tigrbl-base
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.
+

tigrbl_base-0.1.0.dev1.dist-info/RECORD

@@ -0,0 +1,16 @@
+tigrbl_base/_base/__init__.py,sha256=ozQWEKKarRB6CgjRAwuVADq9dxKPd8QUblW6Ptq1FQ4,590
+tigrbl_base/_base/_hook_base.py,sha256=bFcG4ghm6oU3LoVGjgXxaD_ngyf-6GZSGBl9RJQvhXo,624
+tigrbl_base/_base/_middleware_base.py,sha256=lv2W9kXUEb0k3-YuFkFEh4sYfNm2lu4xNzFTXTjaxu4,4598
+tigrbl_base/_base/_op_base.py,sha256=4kejZkpj6tTcIfF2JAFNxh49z3lgIhvxn9NBw-pUyhc,230
+tigrbl_base/_base/_request_base.py,sha256=pHHd9IiIG2SkJTTaJHm_66EjvYMPyCukBS8F9-ePM1E,892
+tigrbl_base/_base/_response_base.py,sha256=1u1xla8l9BBTHitR0t9BypYQDpWJ82fLCzTezUk-Tt4,6818
+tigrbl_base/_base/_schema_base.py,sha256=R1Y117j8ZtDmyrJ5GZHKtv2HjAxLvVByM8k_mUDblrk,398
+tigrbl_base/_base/_security_base.py,sha256=LTv3TYeW6WX60KixLsEtIPta5ap4lmqDiSfBB1MP2YE,2284
+tigrbl_base/_base/_session_abc.py,sha256=GxJBBcSXDgE7P_XGouZmMEnezD7fmd9MWU6KK8Qw24g,1028
+tigrbl_base/_base/_session_base.py,sha256=D4HapOTe_mMIp7Z-O8ARWHEbmy1mFgzwhlFA6khBnMM,3879
+tigrbl_base/_base/_storage.py,sha256=Pw8QYjZxL1Sg9IGRTIr6Hn2J9Caz4v-lsQAU0_MyFnw,303
+tigrbl_base/_base/_table_base.py,sha256=zveQbRB1j-nRNGkZc3NOlnZ7u6hD5bzl3tJQLHTTwT0,18134
+tigrbl_base/_base/_table_registry_base.py,sha256=0bkl0g6JFonzaaDiP5dVPxJ8g2LVqq25vyu9JniY1zM,1801
+tigrbl_base-0.1.0.dev1.dist-info/METADATA,sha256=dfBp0JliSd6rJmMSocAm8MC82W6Nfm8QL_KNyqxcWdo,1755
+tigrbl_base-0.1.0.dev1.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+tigrbl_base-0.1.0.dev1.dist-info/RECORD,,

tigrbl_base-0.1.0.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.1
+Root-Is-Purelib: true
+Tag: py3-none-any