tigrbl-tests 0.3.2.dev1__tar.gz → 0.3.3.dev1__tar.gz

{tigrbl_tests-0.3.2.dev1 → tigrbl_tests-0.3.3.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrbl-tests
-Version: 0.3.2.dev1
+Version: 0.3.3.dev1
 Summary: Test suite and fixtures for the Tigrbl framework.
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -30,6 +30,7 @@ Requires-Dist: python-dotenv
 Requires-Dist: requests (>=2.32.3)
 Requires-Dist: ruff (>=0.9.9)
 Requires-Dist: tigrbl
+Requires-Dist: tigrbl_client
 Description-Content-Type: text/markdown
 
 ![Tigrbl Logo](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
@@ -100,4 +101,18 @@ Use pytest selectors to focus on specific suites:
 pytest standards/tigrbl_tests/tests/unit
 ```
 
+## Examples Curriculum 📚
+
+The `examples/` directory contains downstream-facing pytest lessons that
+demonstrate how to implement Tigrbl in real applications. These lessons are
+organized as a multi-module curriculum with uvicorn-backed usage examples and
+system diagnostics validation. See the full curriculum plan for the learning
+sequence and module descriptions.[^tigrbl-examples]
+Run the examples from the `pkgs` directory:
+
+```bash
+uv run --package tigrbl-tests --directory standards/tigrbl_tests pytest examples
+```
+
+[^tigrbl-examples]: examples/README.md
 

{tigrbl_tests-0.3.2.dev1 → tigrbl_tests-0.3.3.dev1}/README.md

@@ -66,3 +66,17 @@ Use pytest selectors to focus on specific suites:
 pytest standards/tigrbl_tests/tests/unit
 ```
 
+## Examples Curriculum 📚
+
+The `examples/` directory contains downstream-facing pytest lessons that
+demonstrate how to implement Tigrbl in real applications. These lessons are
+organized as a multi-module curriculum with uvicorn-backed usage examples and
+system diagnostics validation. See the full curriculum plan for the learning
+sequence and module descriptions.[^tigrbl-examples]
+Run the examples from the `pkgs` directory:
+
+```bash
+uv run --package tigrbl-tests --directory standards/tigrbl_tests pytest examples
+```
+
+[^tigrbl-examples]: examples/README.md

{tigrbl_tests-0.3.2.dev1 → tigrbl_tests-0.3.3.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tigrbl-tests"
-version = "0.3.2.dev1"
+version = "0.3.3.dev1"
 description = "Test suite and fixtures for the Tigrbl framework."
 license = "Apache-2.0"
 readme = "README.md"
@@ -20,6 +20,7 @@ classifiers = [
 authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
 dependencies = [
     "tigrbl",
+    "tigrbl_client",
     "psycopg2-binary>=2.9.9",
     "asyncpg>=0.30.0",
     "pytest>=8.0",
@@ -46,6 +47,7 @@ keywords = [
 
 [tool.uv.sources]
 tigrbl = { workspace = true }
+tigrbl-client = { workspace = true }
 
 [tool.pytest.ini_options]
 norecursedirs = ["combined", "scripts"]

tigrbl_tests-0.3.3.dev1/tests/i9n/test_tigrbl_api_app_usage_uvicorn.py

@@ -0,0 +1,98 @@
+import httpx
+import pytest
+import pytest_asyncio
+from fastapi import Security
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from tigrbl import Base, TigrblApi, TigrblApp
+from tigrbl.engine.shortcuts import mem
+from tigrbl.orm.mixins import GUIDPk
+from tigrbl.specs import F, IO, S, acol
+from tigrbl.types import Mapped, String
+
+from .uvicorn_utils import run_uvicorn_in_task, stop_uvicorn_server
+
+
+bearer = HTTPBearer()
+
+
+def auth_dependency(
+    credentials: HTTPAuthorizationCredentials = Security(bearer),
+) -> HTTPAuthorizationCredentials:
+    return credentials
+
+
+class Kappa(Base, GUIDPk):
+    __tablename__ = "kappa_api_app_usage"
+    __allow_unmapped__ = True
+
+    name: Mapped[str] = acol(
+        storage=S(type_=String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+    __tigrbl_cols__ = {"id": GUIDPk.id, "name": name}
+
+
+class KappaApi(TigrblApi):
+    MODELS = (Kappa,)
+
+
+@pytest_asyncio.fixture()
+async def running_api_app():
+    api = KappaApi(engine=mem(async_=False))
+    api.set_auth(authn=auth_dependency, allow_anon=False)
+    api.include_models([Kappa])
+    api.initialize()
+
+    class KappaApp(TigrblApp):
+        APIS = (api,)
+
+    app = KappaApp(engine=mem(async_=False))
+    app.include_router(api)
+
+    base_url, server, task = await run_uvicorn_in_task(app)
+    try:
+        yield base_url
+    finally:
+        await stop_uvicorn_server(server, task)
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_api_app_deploys_and_serves_openapi(running_api_app) -> None:
+    base_url = running_api_app
+
+    async with httpx.AsyncClient() as client:
+        openapi_resp = await client.get(f"{base_url}/openapi.json")
+
+    assert openapi_resp.status_code == 200
+    openapi = openapi_resp.json()
+    paths = openapi["paths"]
+
+    assert "/kappa" in paths
+    assert "/kappa/{item_id}" in paths
+    assert {"get", "post", "delete"}.issubset(paths["/kappa"])
+    assert {"get", "patch", "put", "delete"}.issubset(paths["/kappa/{item_id}"])
+
+    security_schemes = openapi.get("components", {}).get("securitySchemes", {})
+    assert "HTTPBearer" in security_schemes
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_api_app_handles_authenticated_request(running_api_app) -> None:
+    base_url = running_api_app
+    headers = {"Authorization": "Bearer demo"}
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{base_url}/kappa",
+            json={"name": "Kappa"},
+            headers=headers,
+        )
+
+    assert resp.status_code == 201
+    payload = resp.json()
+    assert payload["name"] == "Kappa"

tigrbl_tests-0.3.3.dev1/tests/i9n/test_tigrbl_api_usage_uvicorn.py

@@ -0,0 +1,105 @@
+import httpx
+import pytest
+import pytest_asyncio
+from fastapi import Security
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from tigrbl import Base, TigrblApi
+from tigrbl.engine.shortcuts import mem
+from tigrbl.orm.mixins import GUIDPk
+from tigrbl.specs import F, IO, S, acol
+from tigrbl.types import App, Mapped, String
+
+from .uvicorn_utils import run_uvicorn_in_task, stop_uvicorn_server
+
+
+bearer = HTTPBearer()
+
+
+def auth_dependency(
+    credentials: HTTPAuthorizationCredentials = Security(bearer),
+) -> HTTPAuthorizationCredentials:
+    return credentials
+
+
+class Alpha(Base, GUIDPk):
+    __tablename__ = "alpha_api_usage"
+    __allow_unmapped__ = True
+
+    name: Mapped[str] = acol(
+        storage=S(type_=String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+    __tigrbl_cols__ = {"id": GUIDPk.id, "name": name}
+
+
+class Beta(Base, GUIDPk):
+    __tablename__ = "beta_api_usage"
+    __allow_unmapped__ = True
+
+    name: Mapped[str] = acol(
+        storage=S(type_=String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+    __tigrbl_cols__ = {"id": GUIDPk.id, "name": name}
+
+
+@pytest_asyncio.fixture()
+async def running_api():
+    app = App()
+    api = TigrblApi(engine=mem(async_=False))
+    api.set_auth(authn=auth_dependency, allow_anon=False)
+    api.include_models([Alpha, Beta])
+    api.initialize()
+    app.include_router(api)
+
+    base_url, server, task = await run_uvicorn_in_task(app)
+    try:
+        yield base_url
+    finally:
+        await stop_uvicorn_server(server, task)
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_api_deploys_and_serves_openapi(running_api) -> None:
+    base_url = running_api
+
+    async with httpx.AsyncClient() as client:
+        openapi_resp = await client.get(f"{base_url}/openapi.json")
+
+    assert openapi_resp.status_code == 200
+    openapi = openapi_resp.json()
+    paths = openapi["paths"]
+
+    assert "/alpha" in paths
+    assert "/alpha/{item_id}" in paths
+    assert "/beta" in paths
+    assert "/beta/{item_id}" in paths
+    assert {"get", "post", "delete"}.issubset(paths["/alpha"])
+    assert {"get", "patch", "put", "delete"}.issubset(paths["/alpha/{item_id}"])
+
+    security_schemes = openapi.get("components", {}).get("securitySchemes", {})
+    assert "HTTPBearer" in security_schemes
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_api_handles_authenticated_request(running_api) -> None:
+    base_url = running_api
+    headers = {"Authorization": "Bearer demo"}
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{base_url}/alpha",
+            json={"name": "Alpha"},
+            headers=headers,
+        )
+
+    assert resp.status_code == 201
+    payload = resp.json()
+    assert payload["name"] == "Alpha"

tigrbl_tests-0.3.3.dev1/tests/i9n/test_tigrbl_api_uvicorn.py

@@ -0,0 +1,67 @@
+import httpx
+import pytest
+import pytest_asyncio
+
+from tigrbl import Base, TigrblApi
+from tigrbl.engine.shortcuts import mem
+from tigrbl.orm.mixins import GUIDPk
+from tigrbl.specs import F, IO, S, acol
+from tigrbl.types import App, Mapped, String
+
+from .uvicorn_utils import run_uvicorn_in_task, stop_uvicorn_server
+
+
+class Gadget(Base, GUIDPk):
+    __tablename__ = "gadgets_api"
+    __resource__ = "gadget"
+
+    name: Mapped[str] = acol(
+        storage=S(String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+
+@pytest_asyncio.fixture()
+async def running_api_app():
+    api = TigrblApi(
+        engine=mem(async_=False),
+        models=[Gadget],
+        prefix="/gadgets",
+        system_prefix="/diagnostics",
+    )
+    await api.initialize()
+
+    app = App()
+    app.include_router(api.router)
+    api.attach_diagnostics(app=app)
+
+    base_url, server, task = await run_uvicorn_in_task(app)
+    try:
+        yield base_url
+    finally:
+        await stop_uvicorn_server(server, task)
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_api_create_gadget(running_api_app):
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"{running_api_app}/gadgets/gadget", json={"name": "gyro"}
+        )
+
+    assert response.status_code == 201
+    payload = response.json()
+    assert payload["name"] == "gyro"
+    assert "id" in payload
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_api_healthz(running_api_app):
+    async with httpx.AsyncClient() as client:
+        response = await client.get(f"{running_api_app}/diagnostics/healthz")
+
+    assert response.status_code == 200
+    assert response.json()["ok"] is True

tigrbl_tests-0.3.3.dev1/tests/i9n/test_tigrbl_app_include_api_uvicorn.py

@@ -0,0 +1,149 @@
+import httpx
+import pytest
+import pytest_asyncio
+
+from tigrbl import Base, TigrblApi, TigrblApp
+from tigrbl.engine.shortcuts import mem
+from tigrbl.orm.mixins import GUIDPk
+from tigrbl.specs import F, IO, S, acol
+from tigrbl.types import Mapped, String
+
+from .uvicorn_utils import run_uvicorn_in_task, stop_uvicorn_server
+
+
+class AlphaWidget(Base, GUIDPk):
+    __tablename__ = "alpha_widgets_alt"
+    __resource__ = "alpha-widget"
+
+    name: Mapped[str] = acol(
+        storage=S(String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+
+class BetaWidget(Base, GUIDPk):
+    __tablename__ = "beta_widgets_alt"
+    __resource__ = "beta-widget"
+
+    name: Mapped[str] = acol(
+        storage=S(String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+
+class ZetaWidget(Base, GUIDPk):
+    __tablename__ = "zeta_widgets_alt"
+    __resource__ = "zeta-widget"
+
+    name: Mapped[str] = acol(
+        storage=S(String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+
+@pytest_asyncio.fixture()
+async def running_app_with_apis():
+    engine = mem(async_=False)
+    alpha_api = TigrblApi(engine=engine, models=[AlphaWidget], prefix="/alpha")
+    beta_api = TigrblApi(engine=engine)
+    beta_api.include_model(BetaWidget)
+    zeta_api = TigrblApi(engine=engine)
+    zeta_api.include_model(ZetaWidget)
+
+    app = TigrblApp(engine=engine, apis=[alpha_api, (zeta_api, "/zeta")])
+    app.include_api(beta_api, prefix="/beta")
+    await app.initialize()
+
+    base_url, server, task = await run_uvicorn_in_task(app)
+    try:
+        yield base_url
+    finally:
+        await stop_uvicorn_server(server, task)
+
+
+@pytest_asyncio.fixture()
+async def running_app_with_api_router():
+    engine = mem(async_=False)
+    alpha_api = TigrblApi(engine=engine)
+    alpha_api.include_model(AlphaWidget)
+    beta_api = TigrblApi(engine=engine)
+    beta_api.include_model(BetaWidget)
+
+    app = TigrblApp(engine=engine, apis=[alpha_api])
+    app.include_api(beta_api, prefix="/beta")
+    app.include_api(alpha_api.router, prefix="/alpha")
+    await app.initialize()
+
+    base_url, server, task = await run_uvicorn_in_task(app)
+    try:
+        yield base_url
+    finally:
+        await stop_uvicorn_server(server, task)
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_app_api_list_alpha(running_app_with_apis):
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"{running_app_with_apis}/alpha/alpha-widget", json={"name": "ace"}
+        )
+
+    assert response.status_code == 201
+    payload = response.json()
+    assert payload["name"] == "ace"
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_app_include_api_beta(running_app_with_apis):
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"{running_app_with_apis}/beta/beta-widget", json={"name": "bolt"}
+        )
+
+    assert response.status_code == 201
+    payload = response.json()
+    assert payload["name"] == "bolt"
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_app_api_list_zeta(running_app_with_apis):
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"{running_app_with_apis}/zeta/zeta-widget", json={"name": "zen"}
+        )
+
+    assert response.status_code == 201
+    payload = response.json()
+    assert payload["name"] == "zen"
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_app_include_api_router_alpha(running_app_with_api_router):
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"{running_app_with_api_router}/alpha/alpha-widget", json={"name": "ace"}
+        )
+
+    assert response.status_code == 201
+    payload = response.json()
+    assert payload["name"] == "ace"
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_app_include_api_router_beta(running_app_with_api_router):
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"{running_app_with_api_router}/beta/beta-widget", json={"name": "bolt"}
+        )
+
+    assert response.status_code == 201
+    payload = response.json()
+    assert payload["name"] == "bolt"

tigrbl_tests-0.3.3.dev1/tests/i9n/test_tigrbl_app_multi_api_uvicorn.py

@@ -0,0 +1,80 @@
+import httpx
+import pytest
+import pytest_asyncio
+
+from tigrbl import Base, TigrblApi, TigrblApp
+from tigrbl.engine.shortcuts import mem
+from tigrbl.orm.mixins import GUIDPk
+from tigrbl.specs import F, IO, S, acol
+from tigrbl.types import Mapped, String
+
+from .uvicorn_utils import run_uvicorn_in_task, stop_uvicorn_server
+
+
+class AlphaWidget(Base, GUIDPk):
+    __tablename__ = "alpha_widgets"
+    __resource__ = "alpha-widget"
+
+    name: Mapped[str] = acol(
+        storage=S(String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+
+class BetaWidget(Base, GUIDPk):
+    __tablename__ = "beta_widgets"
+    __resource__ = "beta-widget"
+
+    name: Mapped[str] = acol(
+        storage=S(String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+
+@pytest_asyncio.fixture()
+async def running_multi_api_app():
+    engine = mem(async_=False)
+    alpha_api = TigrblApi(engine=engine)
+    alpha_api.include_model(AlphaWidget)
+
+    beta_api = TigrblApi(engine=engine)
+    beta_api.include_model(BetaWidget)
+
+    app = TigrblApp(engine=engine, apis=[alpha_api])
+    app.include_router(beta_api, prefix="/beta")
+    app.include_router(alpha_api.router, prefix="/alpha")
+    await app.initialize()
+
+    base_url, server, task = await run_uvicorn_in_task(app)
+    try:
+        yield base_url
+    finally:
+        await stop_uvicorn_server(server, task)
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_app_routes_alpha_api(running_multi_api_app):
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"{running_multi_api_app}/alpha/alpha-widget", json={"name": "ace"}
+        )
+
+    assert response.status_code == 201
+    payload = response.json()
+    assert payload["name"] == "ace"
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_app_routes_beta_api(running_multi_api_app):
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            f"{running_multi_api_app}/beta/beta-widget", json={"name": "bolt"}
+        )
+
+    assert response.status_code == 201
+    payload = response.json()
+    assert payload["name"] == "bolt"

tigrbl_tests-0.3.3.dev1/tests/i9n/test_tigrbl_app_usage_uvicorn.py

@@ -0,0 +1,103 @@
+import httpx
+import pytest
+import pytest_asyncio
+from fastapi import Security
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from tigrbl import Base, TigrblApp
+from tigrbl.engine.shortcuts import mem
+from tigrbl.orm.mixins import GUIDPk
+from tigrbl.specs import F, IO, S, acol
+from tigrbl.types import Mapped, String
+
+from .uvicorn_utils import run_uvicorn_in_task, stop_uvicorn_server
+
+
+bearer = HTTPBearer()
+
+
+def auth_dependency(
+    credentials: HTTPAuthorizationCredentials = Security(bearer),
+) -> HTTPAuthorizationCredentials:
+    return credentials
+
+
+class Gamma(Base, GUIDPk):
+    __tablename__ = "gamma_app_usage"
+    __allow_unmapped__ = True
+
+    name: Mapped[str] = acol(
+        storage=S(type_=String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+    __tigrbl_cols__ = {"id": GUIDPk.id, "name": name}
+
+
+class Delta(Base, GUIDPk):
+    __tablename__ = "delta_app_usage"
+    __allow_unmapped__ = True
+
+    name: Mapped[str] = acol(
+        storage=S(type_=String, nullable=False),
+        field=F(py_type=str),
+        io=IO(in_verbs=("create",), out_verbs=("create", "read", "list")),
+    )
+
+    __tigrbl_cols__ = {"id": GUIDPk.id, "name": name}
+
+
+@pytest_asyncio.fixture()
+async def running_app():
+    app = TigrblApp(engine=mem(async_=False))
+    app.set_auth(authn=auth_dependency, allow_anon=False)
+    app.include_models([Gamma, Delta])
+    app.initialize()
+
+    base_url, server, task = await run_uvicorn_in_task(app)
+    try:
+        yield base_url
+    finally:
+        await stop_uvicorn_server(server, task)
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_app_deploys_and_serves_openapi(running_app) -> None:
+    base_url = running_app
+
+    async with httpx.AsyncClient() as client:
+        openapi_resp = await client.get(f"{base_url}/openapi.json")
+
+    assert openapi_resp.status_code == 200
+    openapi = openapi_resp.json()
+    paths = openapi["paths"]
+
+    assert "/gamma" in paths
+    assert "/gamma/{item_id}" in paths
+    assert "/delta" in paths
+    assert "/delta/{item_id}" in paths
+    assert {"get", "post", "delete"}.issubset(paths["/gamma"])
+    assert {"get", "patch", "put", "delete"}.issubset(paths["/gamma/{item_id}"])
+
+    security_schemes = openapi.get("components", {}).get("securitySchemes", {})
+    assert "HTTPBearer" in security_schemes
+
+
+@pytest.mark.i9n
+@pytest.mark.asyncio
+async def test_tigrbl_app_handles_authenticated_request(running_app) -> None:
+    base_url = running_app
+    headers = {"Authorization": "Bearer demo"}
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{base_url}/gamma",
+            json={"name": "Gamma"},
+            headers=headers,
+        )
+
+    assert resp.status_code == 201
+    payload = resp.json()
+    assert payload["name"] == "Gamma"