tigrbl 0.3.4.dev2__tar.gz → 0.3.5.dev5__tar.gz

{tigrbl-0.3.4.dev2 → tigrbl-0.3.5.dev5}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: tigrbl
-Version: 0.3.4.dev2
-Summary: Automatic API generation tools by Swarmauri.
+Version: 0.3.5.dev5
+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
-Keywords: tigrbl,sdk,standards
-Author: Swarmauri Team
-Author-email: team@swarmauri.com
+Keywords: tigrbl,sdk,standards,asgi,rest,rpc
+Author: Jacob Stewart
+Author-email: jacob@swarmauri.com
 Requires-Python: >=3.10,<3.13
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Development Status :: 3 - Alpha
@@ -21,16 +21,12 @@ Provides-Extra: templates
 Provides-Extra: tests
 Requires-Dist: aiosqlite (>=0.19.0)
 Requires-Dist: asyncpg (>=0.30.0) ; extra == "postgres"
-Requires-Dist: fastapi (>=0.100.0)
 Requires-Dist: greenlet (>=3.2.3)
 Requires-Dist: httpx (>=0.27.0)
 Requires-Dist: jinja2 (>=3.1.4) ; extra == "templates"
 Requires-Dist: psycopg2-binary (>=2.9.9) ; extra == "postgres"
 Requires-Dist: pydantic (>=2.0.0)
 Requires-Dist: sqlalchemy (>=2.0)
-Requires-Dist: swarmauri_base
-Requires-Dist: swarmauri_core
-Requires-Dist: swarmauri_standard
 Requires-Dist: tigrbl-tests ; extra == "tests"
 Requires-Dist: uvicorn
 Description-Content-Type: text/markdown
@@ -53,7 +49,7 @@ Description-Content-Type: text/markdown
 ---
 
 # Tigrbl 🐅🐂
-A high-leverage meta-framework that turns plain SQLAlchemy models into a fully-featured REST+RPC surface with near-zero boilerplate. 🚀
+A high-leverage ASGI meta-framework that turns plain SQLAlchemy models into a fully-featured REST+RPC surface with near-zero boilerplate. 🚀
 
 ## Features ✨
 
@@ -61,7 +57,7 @@ A high-leverage meta-framework that turns plain SQLAlchemy models into a fully-f
 - 🔌 Unified REST and RPC endpoints from a single definition
 - 🪝 Hookable phase system for deep customization
 - 🧩 Pluggable engine and provider abstractions
-- 🚀 Built on FastAPI and Pydantic for modern Python web apps
+- 🚀 Built as an ASGI-native framework with Pydantic-powered schema generation
 
 ## Terminology 📚
 
@@ -402,7 +398,232 @@ control headers, status codes, and optional template rendering. See
 
 * SQLAlchemy for ORM integration.
 * Pydantic for schema generation.
-* FastAPI for routing and dependency injection.
+* ASGI-native routing and dependency injection.
+
+## Best Design Practices ✅
+
+The following practices are the canonical, production-ready patterns for
+building on Tigrbl. Each rule is explained and demonstrated with
+approved usage. These are not optional—adhering to them keeps the runtime
+predictable, preserves hook lifecycle guarantees, and ensures schema
+consistency across REST and RPC surfaces.
+
+### 1) Never import SQLAlchemy directly or bypass Tigrbl APIs
+
+**Why:** Direct imports bypass Tigrbl's compatibility layer and make it
+harder to evolve internal dependencies. Use the Tigrbl exports so your
+code stays aligned with the framework’s versioned ASGI API.
+
+✅ **Preferred:**
+```python
+from tigrbl import Base, TigrblApp, TigrblApi
+from tigrbl.types import Integer, String, Mapped
+from tigrbl.types import Depends, HTTPException, Request
+```
+
+🚫 **Avoid:**
+```python
+from sqlalchemy import Integer, String
+from some_framework import Depends
+```
+
+### 2) Do not coerce UUIDs manually
+
+**Why:** Tigrbl schemas and types already normalize UUIDs. Manual coercion
+creates inconsistent behavior across engines and breaks schema-level
+validation.
+
+✅ **Preferred:**
+```python
+from tigrbl.types import PgUUID, uuid4, Mapped
+
+class Item(Table):
+    __tablename__ = "items"
+    id: Mapped[PgUUID] = acol(primary_key=True, default=uuid4)
+```
+
+🚫 **Avoid:**
+```python
+from uuid import UUID
+
+item_id = UUID(str(payload["id"]))
+```
+
+### 3) Use engine specs for persistence, not ad-hoc engines
+
+**Why:** Engine specs make persistence declarative, testable, and
+compatible with engine resolution across app, API, table, and op scopes.
+
+✅ **Preferred:**
+```python
+from tigrbl.engine.shortcuts import engine_spec
+from tigrbl.engine.decorators import engine_ctx
+
+spec = engine_spec(kind="postgres", async_=True, host="db", name="app_db")
+
+@engine_ctx(spec)
+class App:
+    ...
+```
+
+🚫 **Avoid:**
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+
+engine = create_async_engine("postgresql+asyncpg://...")
+```
+
+### 4) Never call DB session methods directly
+
+**Why:** Direct calls bypass the hook lifecycle and the database guards.
+Use model handlers or `app.<Model>.handlers.<op>` so hooks, policies, and
+schema enforcement run consistently.
+
+✅ **Preferred:**
+```python
+result = await Item.handlers.create(payload, ctx=request_ctx)
+# or from a Tigrbl app instance:
+result = await app.Item.handlers.create(payload, ctx=request_ctx)
+```
+
+🚫 **Avoid:**
+```python
+db.add(item)
+await db.execute(statement)
+```
+
+### 5) Always use encapsulated payloads as inputs and outputs
+
+**Why:** Tigrbl expects request/response envelopes to preserve metadata,
+support policy enforcement, and keep REST/RPC in lockstep.
+
+✅ **Preferred:**
+```python
+from tigrbl import get_schema
+
+CreateIn = get_schema(Item, "create", "in")
+CreateOut = get_schema(Item, "create", "out")
+
+payload = CreateIn(name="Widget")
+result = await Item.handlers.create(payload, ctx=request_ctx)
+response = CreateOut(result=result)
+```
+
+🚫 **Avoid:**
+```python
+payload = {"name": "Widget"}
+result = await Item.handlers.create(payload)
+```
+
+### 6) Encapsulation must use `get_schema(...)`
+
+**Why:** `get_schema` guarantees the envelope is aligned to the configured
+schema and respects schema overrides, request extras, and response extras.
+
+✅ **Preferred:**
+```python
+ListIn = get_schema(Item, "list", "in")
+ListOut = get_schema(Item, "list", "out")
+```
+
+🚫 **Avoid:**
+```python
+from pydantic import BaseModel
+
+class ListIn(BaseModel):
+    payload: dict
+```
+
+### 7) `Table` must be the first inherited class for all models
+
+**Why:** Tigrbl inspects base classes for lifecycle and configuration.
+Putting `Table` first preserves deterministic MRO behavior.
+
+✅ **Preferred:**
+```python
+from tigrbl.orm.tables import Table
+from tigrbl.orm.mixins import Timestamped
+
+class Item(Table, Timestamped):
+    __tablename__ = "items"
+```
+
+🚫 **Avoid:**
+```python
+class Item(Timestamped, Table):
+    __tablename__ = "items"
+```
+
+### 8) Never call `db.flush()` or `db.commit()`
+
+**Why:** The hook lifecycle owns transactional boundaries. Manual flush or
+commit short-circuits phase guards and can corrupt the request lifecycle.
+
+✅ **Preferred:**
+```python
+@hook_ctx(ops="create", phase="HANDLER")
+async def handler(ctx):
+    await Item.handlers.create(ctx["request"].payload, ctx=ctx)
+```
+
+🚫 **Avoid:**
+```python
+db.flush()
+db.commit()
+```
+
+### 9) Use ops for new REST/RPC methods—never add ad-hoc framework routes
+
+**Why:** Ops keep routing, schemas, hooks, and policies unified. Custom
+custom framework routes bypass these guarantees.
+
+✅ **Preferred:**
+```python
+from tigrbl import op_ctx
+
+@op_ctx(name="rotate_keys", method="POST", path="/keys/rotate")
+async def rotate_keys(payload, *, ctx):
+    return await Key.handlers.rotate(payload, ctx=ctx)
+```
+
+🚫 **Avoid:**
+```python
+from some_framework import APIRouter
+
+router = APIRouter()
+
+@router.post("/keys/rotate")
+async def rotate_keys(payload):
+    ...
+```
+
+### 10) Use context decorators where appropriate
+
+**Why:** Context decorators (`engine_ctx`, `schema_ctx`, `op_ctx`,
+`hook_ctx`) provide explicit, declarative binding of behavior and are
+resolved deterministically by the runtime.
+
+✅ **Preferred:**
+```python
+from tigrbl import hook_ctx, op_ctx, schema_ctx
+from tigrbl.engine.decorators import engine_ctx
+
+@engine_ctx(kind="sqlite", mode="memory")
+class Item(Table):
+    __tablename__ = "items"
+
+@schema_ctx(ops="create", cfg={"exclude": {"id"}})
+class ItemCreateSchema:
+    model = Item
+
+@op_ctx(name="export", method="GET", path="/items/export")
+async def export_items(payload, *, ctx):
+    return await Item.handlers.list(payload, ctx=ctx)
+
+@hook_ctx(ops="create", phase="PRE_HANDLER")
+async def validate(ctx):
+    ...
+```
 
 ### Engine & Provider examples 🛠️
 
@@ -512,5 +733,3 @@ async def decorated_create(payload, *, db=None):
 9. Core
 10. Core\_Raw
 
-
-

{tigrbl-0.3.4.dev2 → tigrbl-0.3.5.dev5}/README.md

@@ -16,7 +16,7 @@
 ---
 
 # Tigrbl 🐅🐂
-A high-leverage meta-framework that turns plain SQLAlchemy models into a fully-featured REST+RPC surface with near-zero boilerplate. 🚀
+A high-leverage ASGI meta-framework that turns plain SQLAlchemy models into a fully-featured REST+RPC surface with near-zero boilerplate. 🚀
 
 ## Features ✨
 
@@ -24,7 +24,7 @@ A high-leverage meta-framework that turns plain SQLAlchemy models into a fully-f
 - 🔌 Unified REST and RPC endpoints from a single definition
 - 🪝 Hookable phase system for deep customization
 - 🧩 Pluggable engine and provider abstractions
-- 🚀 Built on FastAPI and Pydantic for modern Python web apps
+- 🚀 Built as an ASGI-native framework with Pydantic-powered schema generation
 
 ## Terminology 📚
 
@@ -365,7 +365,232 @@ control headers, status codes, and optional template rendering. See
 
 * SQLAlchemy for ORM integration.
 * Pydantic for schema generation.
-* FastAPI for routing and dependency injection.
+* ASGI-native routing and dependency injection.
+
+## Best Design Practices ✅
+
+The following practices are the canonical, production-ready patterns for
+building on Tigrbl. Each rule is explained and demonstrated with
+approved usage. These are not optional—adhering to them keeps the runtime
+predictable, preserves hook lifecycle guarantees, and ensures schema
+consistency across REST and RPC surfaces.
+
+### 1) Never import SQLAlchemy directly or bypass Tigrbl APIs
+
+**Why:** Direct imports bypass Tigrbl's compatibility layer and make it
+harder to evolve internal dependencies. Use the Tigrbl exports so your
+code stays aligned with the framework’s versioned ASGI API.
+
+✅ **Preferred:**
+```python
+from tigrbl import Base, TigrblApp, TigrblApi
+from tigrbl.types import Integer, String, Mapped
+from tigrbl.types import Depends, HTTPException, Request
+```
+
+🚫 **Avoid:**
+```python
+from sqlalchemy import Integer, String
+from some_framework import Depends
+```
+
+### 2) Do not coerce UUIDs manually
+
+**Why:** Tigrbl schemas and types already normalize UUIDs. Manual coercion
+creates inconsistent behavior across engines and breaks schema-level
+validation.
+
+✅ **Preferred:**
+```python
+from tigrbl.types import PgUUID, uuid4, Mapped
+
+class Item(Table):
+    __tablename__ = "items"
+    id: Mapped[PgUUID] = acol(primary_key=True, default=uuid4)
+```
+
+🚫 **Avoid:**
+```python
+from uuid import UUID
+
+item_id = UUID(str(payload["id"]))
+```
+
+### 3) Use engine specs for persistence, not ad-hoc engines
+
+**Why:** Engine specs make persistence declarative, testable, and
+compatible with engine resolution across app, API, table, and op scopes.
+
+✅ **Preferred:**
+```python
+from tigrbl.engine.shortcuts import engine_spec
+from tigrbl.engine.decorators import engine_ctx
+
+spec = engine_spec(kind="postgres", async_=True, host="db", name="app_db")
+
+@engine_ctx(spec)
+class App:
+    ...
+```
+
+🚫 **Avoid:**
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+
+engine = create_async_engine("postgresql+asyncpg://...")
+```
+
+### 4) Never call DB session methods directly
+
+**Why:** Direct calls bypass the hook lifecycle and the database guards.
+Use model handlers or `app.<Model>.handlers.<op>` so hooks, policies, and
+schema enforcement run consistently.
+
+✅ **Preferred:**
+```python
+result = await Item.handlers.create(payload, ctx=request_ctx)
+# or from a Tigrbl app instance:
+result = await app.Item.handlers.create(payload, ctx=request_ctx)
+```
+
+🚫 **Avoid:**
+```python
+db.add(item)
+await db.execute(statement)
+```
+
+### 5) Always use encapsulated payloads as inputs and outputs
+
+**Why:** Tigrbl expects request/response envelopes to preserve metadata,
+support policy enforcement, and keep REST/RPC in lockstep.
+
+✅ **Preferred:**
+```python
+from tigrbl import get_schema
+
+CreateIn = get_schema(Item, "create", "in")
+CreateOut = get_schema(Item, "create", "out")
+
+payload = CreateIn(name="Widget")
+result = await Item.handlers.create(payload, ctx=request_ctx)
+response = CreateOut(result=result)
+```
+
+🚫 **Avoid:**
+```python
+payload = {"name": "Widget"}
+result = await Item.handlers.create(payload)
+```
+
+### 6) Encapsulation must use `get_schema(...)`
+
+**Why:** `get_schema` guarantees the envelope is aligned to the configured
+schema and respects schema overrides, request extras, and response extras.
+
+✅ **Preferred:**
+```python
+ListIn = get_schema(Item, "list", "in")
+ListOut = get_schema(Item, "list", "out")
+```
+
+🚫 **Avoid:**
+```python
+from pydantic import BaseModel
+
+class ListIn(BaseModel):
+    payload: dict
+```
+
+### 7) `Table` must be the first inherited class for all models
+
+**Why:** Tigrbl inspects base classes for lifecycle and configuration.
+Putting `Table` first preserves deterministic MRO behavior.
+
+✅ **Preferred:**
+```python
+from tigrbl.orm.tables import Table
+from tigrbl.orm.mixins import Timestamped
+
+class Item(Table, Timestamped):
+    __tablename__ = "items"
+```
+
+🚫 **Avoid:**
+```python
+class Item(Timestamped, Table):
+    __tablename__ = "items"
+```
+
+### 8) Never call `db.flush()` or `db.commit()`
+
+**Why:** The hook lifecycle owns transactional boundaries. Manual flush or
+commit short-circuits phase guards and can corrupt the request lifecycle.
+
+✅ **Preferred:**
+```python
+@hook_ctx(ops="create", phase="HANDLER")
+async def handler(ctx):
+    await Item.handlers.create(ctx["request"].payload, ctx=ctx)
+```
+
+🚫 **Avoid:**
+```python
+db.flush()
+db.commit()
+```
+
+### 9) Use ops for new REST/RPC methods—never add ad-hoc framework routes
+
+**Why:** Ops keep routing, schemas, hooks, and policies unified. Custom
+custom framework routes bypass these guarantees.
+
+✅ **Preferred:**
+```python
+from tigrbl import op_ctx
+
+@op_ctx(name="rotate_keys", method="POST", path="/keys/rotate")
+async def rotate_keys(payload, *, ctx):
+    return await Key.handlers.rotate(payload, ctx=ctx)
+```
+
+🚫 **Avoid:**
+```python
+from some_framework import APIRouter
+
+router = APIRouter()
+
+@router.post("/keys/rotate")
+async def rotate_keys(payload):
+    ...
+```
+
+### 10) Use context decorators where appropriate
+
+**Why:** Context decorators (`engine_ctx`, `schema_ctx`, `op_ctx`,
+`hook_ctx`) provide explicit, declarative binding of behavior and are
+resolved deterministically by the runtime.
+
+✅ **Preferred:**
+```python
+from tigrbl import hook_ctx, op_ctx, schema_ctx
+from tigrbl.engine.decorators import engine_ctx
+
+@engine_ctx(kind="sqlite", mode="memory")
+class Item(Table):
+    __tablename__ = "items"
+
+@schema_ctx(ops="create", cfg={"exclude": {"id"}})
+class ItemCreateSchema:
+    model = Item
+
+@op_ctx(name="export", method="GET", path="/items/export")
+async def export_items(payload, *, ctx):
+    return await Item.handlers.list(payload, ctx=ctx)
+
+@hook_ctx(ops="create", phase="PRE_HANDLER")
+async def validate(ctx):
+    ...
+```
 
 ### Engine & Provider examples 🛠️
 
@@ -474,5 +699,3 @@ async def decorated_create(payload, *, db=None):
 8. Default Flush
 9. Core
 10. Core\_Raw
-
-

{tigrbl-0.3.4.dev2 → tigrbl-0.3.5.dev5}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "tigrbl"
-version = "0.3.4.dev2"
-description = "Automatic API generation tools by Swarmauri."
+version = "0.3.5.dev5"
+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"
 repository = "http://github.com/swarmauri/swarmauri-sdk"
@@ -16,12 +16,8 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
 ]
-authors = [{ name = "Swarmauri Team", email = "team@swarmauri.com" }]
+authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
 dependencies = [
-    "swarmauri_core",
-    "swarmauri_base",
-    "swarmauri_standard",
-    "fastapi>=0.100.0",
     "pydantic>=2.0.0",
     "sqlalchemy>=2.0",
     "aiosqlite>=0.19.0",
@@ -33,6 +29,9 @@ keywords = [
     'tigrbl',
     'sdk',
     'standards',
+    'asgi',
+    'rest',
+    'rpc',
 ]
 
 [project.optional-dependencies]
@@ -48,9 +47,6 @@ tests = [
 ]
 
 [tool.uv.sources]
-swarmauri_core = { workspace = true }
-swarmauri_base = { workspace = true }
-swarmauri_standard = { workspace = true }
 tigrbl-tests = { workspace = true }
 
 [tool.pytest.ini_options]

{tigrbl-0.3.4.dev2 → tigrbl-0.3.5.dev5}/tigrbl/__init__.py

@@ -9,7 +9,7 @@ Quick start:
     from tigrbl import include_model, build_jsonrpc_router, mount_diagnostics
     from tigrbl import OpSpec, hook_ctx, op_ctx, alias_ctx, schema_ctx, SchemaRef
 
-    include_model(api, User, app=fastapi_app)
+    include_model(api, User, app=asgi_app)
     app.include_router(build_jsonrpc_router(api), prefix="/rpc")
     app.include_router(mount_diagnostics(api), prefix="/system")
 
@@ -80,12 +80,23 @@ from .api import Api, TigrblApi
 
 from .table import Base
 from .op import Op
-from .app._app import App
+from .security import APIKey, HTTPBearer, MutualTLS, OAuth2, OpenIdConnect
 
 
 __all__: list[str] = []
 
-__all__ += ["TigrblApp", "TigrblApi", "Api", "Base", "App", "Op"]
+__all__ += [
+    "TigrblApp",
+    "TigrblApi",
+    "Api",
+    "Base",
+    "Op",
+    "HTTPBearer",
+    "APIKey",
+    "OAuth2",
+    "OpenIdConnect",
+    "MutualTLS",
+]
 
 __all__ += [
     # OpSpec core

tigrbl-0.3.5.dev5/tigrbl/api/__init__.py

@@ -0,0 +1,19 @@
+"""Core API surfaces for the Tigrbl package."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["Api", "TigrblApi"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "Api":
+        from ._api import Api
+
+        return Api
+    if name == "TigrblApi":
+        from .tigrbl_api import TigrblApi
+
+        return TigrblApi
+    raise AttributeError(name)