tigrbl 0.3.16.dev5__tar.gz → 0.3.17.dev2__tar.gz

{tigrbl-0.3.16.dev5 → tigrbl-0.3.17.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrbl
-Version: 0.3.16.dev5
+Version: 0.3.17.dev2
 Summary: A modern pure ASGI/WSGI Python framework for building schema-first REST and JSON-RPC APIs with SQLAlchemy models, typed validation, lifecycle hooks, and engine extension support.
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -59,6 +59,11 @@ A high-leverage ASGI meta-framework that turns plain SQLAlchemy models into a fu
 - 🧩 Pluggable engine and provider abstractions
 - 🚀 Built as an ASGI-native framework with Pydantic-powered schema generation
 
+## Runtime-owned Routing Contract
+
+For the kernel-first flow that avoids pre-runtime REST/RPC dispatching, see
+[`RUNTIME_OWNED_ROUTING.md`](./RUNTIME_OWNED_ROUTING.md).
+
 ## Terminology 📚
 
 - **Tenant** 🏢 – a namespace used to group related resources.
@@ -457,7 +462,7 @@ compatible with engine resolution across app, router, table, and op scopes.
 ✅ **Preferred:**
 ```python
 from tigrbl.engine.shortcuts import engine_spec
-from tigrbl.engine.decorators import engine_ctx
+from tigrbl.decorators.engine import engine_ctx
 
 spec = engine_spec(kind="postgres", async_=True, host="db", name="app_db")
 
@@ -606,7 +611,7 @@ resolved deterministically by the runtime.
 ✅ **Preferred:**
 ```python
 from tigrbl import hook_ctx, op_ctx, schema_ctx
-from tigrbl.engine.decorators import engine_ctx
+from tigrbl.decorators.engine import engine_ctx
 
 @engine_ctx(kind="sqlite", mode="memory")
 class Item(Table):
@@ -629,7 +634,7 @@ async def validate(ctx):
 
 ```python
 from tigrbl.engine.shortcuts import engine_spec, prov
-from tigrbl.engine._engine import Engine, Provider
+from tigrbl._concrete._engine import Engine, Provider
 
 # Build an EngineSpec from a DSN string
 spec = engine_spec("sqlite://:memory:")
@@ -656,7 +661,7 @@ provider_pg = Provider(spec_pg)
 `engine_ctx` binds database configuration to different layers. It accepts a
 DSN string, a mapping, an `EngineSpec`, a `Provider`, or an `Engine`. The
 resolver chooses the most specific binding in the order
-`op > table > api > app`.
+`op > table > router > app`.
 
 #### Engine precedence 🥇
 
@@ -700,7 +705,7 @@ create.__tigrbl_engine_ctx__ = {
 #### Decorative bindings 🎛️
 
 ```python
-from tigrbl.engine.decorators import engine_ctx
+from tigrbl.decorators.engine import engine_ctx
 from tigrbl.engine.shortcuts import prov, engine
 
 @engine_ctx(prov(kind="sqlite", mode="memory"))

{tigrbl-0.3.16.dev5 → tigrbl-0.3.17.dev2}/README.md

@@ -26,6 +26,11 @@ A high-leverage ASGI meta-framework that turns plain SQLAlchemy models into a fu
 - 🧩 Pluggable engine and provider abstractions
 - 🚀 Built as an ASGI-native framework with Pydantic-powered schema generation
 
+## Runtime-owned Routing Contract
+
+For the kernel-first flow that avoids pre-runtime REST/RPC dispatching, see
+[`RUNTIME_OWNED_ROUTING.md`](./RUNTIME_OWNED_ROUTING.md).
+
 ## Terminology 📚
 
 - **Tenant** 🏢 – a namespace used to group related resources.
@@ -424,7 +429,7 @@ compatible with engine resolution across app, router, table, and op scopes.
 ✅ **Preferred:**
 ```python
 from tigrbl.engine.shortcuts import engine_spec
-from tigrbl.engine.decorators import engine_ctx
+from tigrbl.decorators.engine import engine_ctx
 
 spec = engine_spec(kind="postgres", async_=True, host="db", name="app_db")
 
@@ -573,7 +578,7 @@ resolved deterministically by the runtime.
 ✅ **Preferred:**
 ```python
 from tigrbl import hook_ctx, op_ctx, schema_ctx
-from tigrbl.engine.decorators import engine_ctx
+from tigrbl.decorators.engine import engine_ctx
 
 @engine_ctx(kind="sqlite", mode="memory")
 class Item(Table):
@@ -596,7 +601,7 @@ async def validate(ctx):
 
 ```python
 from tigrbl.engine.shortcuts import engine_spec, prov
-from tigrbl.engine._engine import Engine, Provider
+from tigrbl._concrete._engine import Engine, Provider
 
 # Build an EngineSpec from a DSN string
 spec = engine_spec("sqlite://:memory:")
@@ -623,7 +628,7 @@ provider_pg = Provider(spec_pg)
 `engine_ctx` binds database configuration to different layers. It accepts a
 DSN string, a mapping, an `EngineSpec`, a `Provider`, or an `Engine`. The
 resolver chooses the most specific binding in the order
-`op > table > api > app`.
+`op > table > router > app`.
 
 #### Engine precedence 🥇
 
@@ -667,7 +672,7 @@ create.__tigrbl_engine_ctx__ = {
 #### Decorative bindings 🎛️
 
 ```python
-from tigrbl.engine.decorators import engine_ctx
+from tigrbl.decorators.engine import engine_ctx
 from tigrbl.engine.shortcuts import prov, engine
 
 @engine_ctx(prov(kind="sqlite", mode="memory"))

{tigrbl-0.3.16.dev5 → tigrbl-0.3.17.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tigrbl"
-version = "0.3.16.dev5"
+version = "0.3.17.dev2"
 description = "A modern pure ASGI/WSGI Python framework for building schema-first REST and JSON-RPC APIs with SQLAlchemy models, typed validation, lifecycle hooks, and engine extension support."
 license = "Apache-2.0"
 readme = "README.md"
@@ -48,6 +48,7 @@ tests = [
 
 [tool.uv.sources]
 tigrbl-tests = { workspace = true }
+tigrbl_client = { workspace = true }
 
 [tool.pytest.ini_options]
 norecursedirs = ["combined", "scripts"]
@@ -81,6 +82,7 @@ packages = [
 
 [dependency-groups]
 dev = [
+    "tigrbl_client",
     "pytest>=8.0",
     "pytest-asyncio>=0.24.0",
     "pytest-xdist>=3.6.1",

{tigrbl-0.3.16.dev5 → tigrbl-0.3.17.dev2}/tigrbl/README.md

@@ -86,7 +86,7 @@ Some objects also expose optional helpers:
 | Column | `column_spec.py` | `_column.py` | — | `shortcuts.py` | `collect.py` | — | — |
 | Engine | `engine_spec.py` | `_engine.py` | `decorators.py` | `shortcuts.py` | `collect.py` | `resolver.py` | `builders.py` |
 | Op | `types.py` | `_op.py` | `decorators.py` | — | `collect.py` | — | — |
-| Router | `router_spec.py` | `_router.py` | — | `shortcuts.py` | — | — | — |
+| API | `router_spec.py` | `_api.py` | — | `shortcuts.py` | — | — | — |
 | App | `app_spec.py` | `_app.py` | — | `shortcuts.py` | — | — | — |
 | Table | `table_spec.py` | `_table.py` | — | `shortcuts.py` | — | — | — |
 

{tigrbl-0.3.16.dev5 → tigrbl-0.3.17.dev2}/tigrbl/__init__.py

@@ -9,6 +9,8 @@ register RPC & REST, and (optionally) mount JSON-RPC and diagnostics.
 
 from __future__ import annotations
 
+from ._concrete import Router
+
 # ── OpSpec (source of truth) ───────────────────────────────────────────────────
 from .op import (
     OpSpec,
@@ -26,14 +28,13 @@ from .schema.types import SchemaRef, SchemaArg
 # ── Ctx-only decorators (new surface; replaces legacy ops.decorators) ─────────
 
 from .op import alias_ctx, op_ctx, alias, op_alias
-from .hook import hook_ctx
-from .engine.decorators import engine_ctx
-from .schema.decorators import schema_ctx
-from .responses.decorators import response_ctx
-from .responses.types import ResponseSpec
+from .decorators.hook import hook_ctx
+from .decorators.engine import engine_ctx
+from .decorators.schema import schema_ctx
+from .decorators.response import response_ctx
 
 # ── Bindings (model + Router orchestration) ───────────────────────────────────────
-from .bindings import (
+from .mapping import (
     bind,
     rebind,
     build_schemas,
@@ -53,7 +54,10 @@ from .runtime.executor import _invoke
 from .schema import _build_schema, _build_list_params, get_schema
 
 # ── Transport & Diagnostics (optional) ─────────────────────────────────────────
-from .transport.jsonrpc import build_jsonrpc_router
+from ._concrete._request import Request
+from .security import Depends
+from ._concrete._json_response import JSONResponse
+from ._concrete._response import Response
 from .system import mount_diagnostics
 
 # ── DB/bootstrap helpers (infra; optional) ─────────────────────────────────────
@@ -61,13 +65,50 @@ from .ddl import ensure_schemas, register_sqlite_attach, bootstrap_dbschema
 
 # ── Config constants (defaults used by REST) ───────────────────────────────────
 from .config.constants import DEFAULT_HTTP_METHODS
-from .app.tigrbl_app import TigrblApp
-from .router import Router, TigrblRouter, route_ctx
-
-
-from .table import Base
+from ._concrete.tigrbl_app import TigrblApp
+from ._concrete.tigrbl_router import TigrblRouter
+from .decorators.router import route_ctx
+from .orm.tables import TableBase
 from .op import Op
-from .security import APIKey, HTTPBearer, MutualTLS, OAuth2, OpenIdConnect
+from .shortcuts.op import op
+from .engine import resolver
+from ._concrete._security.api_key import APIKey
+from ._concrete._security.http_bearer import HTTPBearer
+from ._concrete._security.mutual_tls import MutualTLS
+from ._concrete._security.oauth2 import OAuth2
+from ._concrete._security.openid_connect import OpenIdConnect
+from .runtime.status.exceptions import HTTPException
+from ._spec import (
+    AppSpec,
+    ColumnSpec,
+    EngineSpec,
+    FieldSpec,
+    ForeignKeySpec,
+    IOSpec,
+    RequestSpec,
+    ResponseSpec,
+    RouterSpec,
+    SchemaSpec,
+    SessionSpec,
+    StorageSpec,
+    StorageTransform,
+    TableRegistrySpec,
+    TableSpec,
+    TemplateSpec,
+)
+from ._base import ForeignKeyBase, HookBase, TableRegistryBase
+from ._concrete import (
+    App,
+    Column,
+    ForeignKey,
+    Hook,
+    Route,
+    Schema,
+    Table,
+    TableRegistry,
+)
+from .decorators import HOOK_DECLS_ATTR, middleware, middlewares
+
 
 __all__: list[str] = []
 
@@ -75,8 +116,11 @@ __all__ += [
     "TigrblApp",
     "TigrblRouter",
     "Router",
-    "Base",
+    "Depends",
+    "HTTPException",
+    "TableBase",
     "Op",
+    "op",
     "HTTPBearer",
     "APIKey",
     "OAuth2",
@@ -126,7 +170,6 @@ __all__ += [
     "_build_list_params",
     "get_schema",
     # Transport / Diagnostics
-    "build_jsonrpc_router",
     "mount_diagnostics",
     # DB/infra
     "ensure_schemas",
@@ -134,4 +177,40 @@ __all__ += [
     "bootstrap_dbschema",
     # Config
     "DEFAULT_HTTP_METHODS",
+    "Request",
+    "Depends",
+    "Response",
+    "JSONResponse",
+    "resolver",
+]
+__all__ += [
+    "AppSpec",
+    "RouterSpec",
+    "TableSpec",
+    "TableRegistrySpec",
+    "ColumnSpec",
+    "FieldSpec",
+    "IOSpec",
+    "StorageSpec",
+    "StorageTransform",
+    "ForeignKeySpec",
+    "RequestSpec",
+    "SchemaSpec",
+    "SessionSpec",
+    "EngineSpec",
+    "TemplateSpec",
+    "ForeignKeyBase",
+    "HookBase",
+    "TableRegistryBase",
+    "App",
+    "Table",
+    "Column",
+    "Route",
+    "Schema",
+    "Hook",
+    "ForeignKey",
+    "TableRegistry",
+    "HOOK_DECLS_ATTR",
+    "middleware",
+    "middlewares",
 ]

tigrbl-0.3.17.dev2/tigrbl/_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-0.3.17.dev2/tigrbl/_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 ..hook.types import HookPhase, StepFn
+from .._spec.hook_spec import HookSpec
+
+
+@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-0.3.16.dev5/tigrbl/middlewares/base.py → tigrbl-0.3.17.dev2/tigrbl/_base/_middleware_base.py

@@ -5,16 +5,15 @@ from __future__ import annotations
 from typing import Any
 from urllib.parse import urlencode
 
-from tigrbl.requests import Request
-from tigrbl.requests.adapters import request_from_asgi
-from tigrbl.responses import Response
-from tigrbl.responses._transport import finalize_transport_response
+from tigrbl._concrete._request import Request
+from tigrbl._concrete._request_adapters import request_from_asgi
+from tigrbl._concrete._response import Response
+from tigrbl.runtime.atoms.egress.asgi_send import finalize_transport_response
 
-from .middleware import Middleware
-from .spec import ASGIReceive, ASGISend, Message
+from .._spec.middleware_spec import MiddlewareSpec, ASGIReceive, ASGISend, Message
 
 
-class BaseHTTPMiddleware(Middleware):
+class MiddlewareBase(MiddlewareSpec):
     """Base middleware for intercepting HTTP requests in ASGI mode."""
 
     async def dispatch(
@@ -139,4 +138,4 @@ class BaseHTTPMiddleware(Middleware):
         )
 
 
-__all__ = ["BaseHTTPMiddleware"]
+__all__ = ["MiddlewareBase"]

tigrbl-0.3.17.dev2/tigrbl/_base/_op_base.py

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

tigrbl-0.3.17.dev2/tigrbl/_base/_request_base.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._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._request import Request
+
+        return Request.from_scope(scope, receive, app=app, state=state)
+
+
+__all__ = ["RequestBase"]

tigrbl-0.3.16.dev5/tigrbl/responses/_response.py → tigrbl-0.3.17.dev2/tigrbl/_base/_response_base.py

@@ -1,26 +1,28 @@
-"""StdAPI response primitives."""
-
 from __future__ import annotations
 
 import json as json_module
-import mimetypes
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from http.cookies import SimpleCookie
-from pathlib import Path
-from typing import Any, AsyncIterator, Iterable, Mapping
+from typing import Any, Mapping
+
+from tigrbl._concrete._headers import HeaderCookies, Headers
 
-from tigrbl.headers import HeaderCookies, Headers
+from .._spec.response_spec import ResponseSpec, TemplateSpec
 
 
 class _JSONDualMethod:
-    def __get__(self, obj: "Response" | None, owner: type["Response"]):
+    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,
-            ) -> "Response":
+            ) -> "ResponseBase":
                 return owner.from_json(data, status_code=status_code, headers=headers)
 
             return _factory
@@ -31,18 +33,59 @@ class _JSONDualMethod:
         return _instance_json
 
 
-@dataclass
-class Response:
-    status_code: int = 200
-    headers: Headers = field(default_factory=Headers)
-    body: bytes = b""
-    media_type: str | None = None
-    _headers: Headers = field(init=False, repr=False)
+class ResponseBase(ResponseSpec):
+    """Concrete HTTP response object that also implements ``ResponseSpec``."""
 
     json = _JSONDualMethod()
 
-    def __post_init__(self) -> None:
-        self.headers = Headers(self.headers)
+    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
@@ -132,7 +175,7 @@ class Response:
         data: Any,
         status_code: int = 200,
         headers: Mapping[str, str] | None = None,
-    ) -> "Response":
+    ) -> "ResponseBase":
         payload = json_module.dumps(
             data, ensure_ascii=False, separators=(",", ":"), default=str
         ).encode("utf-8")
@@ -152,7 +195,7 @@ class Response:
         html: str,
         status_code: int = 200,
         headers: Mapping[str, str] | None = None,
-    ) -> "Response":
+    ) -> "ResponseBase":
         payload = html.encode("utf-8")
         hdrs = [("content-type", "text/html; charset=utf-8")]
         for k, v in (headers or {}).items():
@@ -170,7 +213,7 @@ class Response:
         text: str,
         status_code: int = 200,
         headers: Mapping[str, str] | None = None,
-    ) -> "Response":
+    ) -> "ResponseBase":
         payload = text.encode("utf-8")
         hdrs = [("content-type", "text/plain; charset=utf-8")]
         for k, v in (headers or {}).items():
@@ -183,96 +226,6 @@ class Response:
         )
 
 
-class JSONResponse(Response):
-    def __init__(self, content: Any, status_code: int = 200) -> None:
-        payload = json_module.dumps(
-            content, ensure_ascii=False, separators=(",", ":"), default=str
-        ).encode("utf-8")
-        super().__init__(
-            status_code=status_code,
-            headers=[("content-type", "application/json; charset=utf-8")],
-            body=payload,
-            media_type="application/json",
-        )
-
-
-class HTMLResponse(Response):
-    def __init__(self, content: str, status_code: int = 200) -> None:
-        super().__init__(
-            status_code=status_code,
-            headers=[("content-type", "text/html; charset=utf-8")],
-            body=content.encode("utf-8"),
-            media_type="text/html",
-        )
-
-
-class PlainTextResponse(Response):
-    def __init__(self, content: str, status_code: int = 200) -> None:
-        super().__init__(
-            status_code=status_code,
-            headers=[("content-type", "text/plain; charset=utf-8")],
-            body=content.encode("utf-8"),
-            media_type="text/plain",
-        )
-
-
-class StreamingResponse(Response):
-    def __init__(
-        self,
-        content: Iterable[bytes] | bytes,
-        status_code: int = 200,
-        media_type: str = "application/octet-stream",
-    ) -> None:
-        chunks = [content] if isinstance(content, bytes) else list(content)
-        super().__init__(
-            status_code=status_code,
-            headers=[("content-type", media_type)],
-            body=b"".join(chunks),
-            media_type=media_type,
-        )
-        self._chunks = [bytes(chunk) for chunk in chunks]
-
-    @property
-    def body_iterator(self) -> AsyncIterator[bytes]:
-        async def _iter() -> AsyncIterator[bytes]:
-            for chunk in self._chunks:
-                yield chunk
-
-        return _iter()
-
-
-class FileResponse(Response):
-    def __init__(self, path: str, media_type: str | None = None) -> None:
-        payload = Path(path).read_bytes()
-        content_type = (
-            media_type or mimetypes.guess_type(path)[0] or "application/octet-stream"
-        )
-        super().__init__(
-            status_code=200,
-            headers=[("content-type", content_type)],
-            body=payload,
-            media_type=content_type,
-        )
-        self.path = str(path)
-
-
-class RedirectResponse(Response):
-    def __init__(self, url: str, status_code: int = 307) -> None:
-        super().__init__(
-            status_code=status_code,
-            headers=[("location", url)],
-            body=b"",
-            media_type=None,
-        )
-        self.url = url
-
-
-__all__ = [
-    "Response",
-    "JSONResponse",
-    "HTMLResponse",
-    "PlainTextResponse",
-    "StreamingResponse",
-    "FileResponse",
-    "RedirectResponse",
-]
+@dataclass
+class TemplateBase(TemplateSpec):
+    """Concrete template configuration used at runtime."""

tigrbl-0.3.17.dev2/tigrbl/_base/_schema_base.py

@@ -0,0 +1,14 @@
+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 ..mapping.collect_decorated_schemas import collect_decorated_schemas
+
+        return collect_decorated_schemas(model)
+
+
+__all__ = ["SchemaBase"]