python-neva 5.1.0__py3-none-any.whl → 5.3.0__py3-none-any.whl

neva/guidelines/fragments/service-providers.md

@@ -152,10 +152,15 @@ request-scoped container to another framework wants that, not `container`.
 
 ## Registration is closed after boot
 
-`register()` is idempotent for an already-registered class, but **returns `Err` once the
-application has booted**: dishka validates the graph at build time, and the booted container
-holds APP-scoped instances a rebuild would orphan. Declare providers in config, or register
-before entering `lifespan()`.
+`register()` **returns `Err` once the application has booted**: dishka validates the graph at
+build time, and the booted container holds APP-scoped instances a rebuild would orphan. Declare
+providers in config, or register before entering `lifespan()`.
+
+One case slips past that, and the order is what makes it: the already-registered check is read
+**first**, so re-registering a class the application already holds returns `Ok(existing)` even
+booted. Nothing is rebuilt, so nothing is at risk. It does mean a test asserting the refusal
+must pass a provider the application never registered: hand it one the config or the setup
+already installed and the assertion comes back `Ok`, proving nothing.
 
 ## Typed config shapes
 

neva/guidelines/fragments/testing.md

@@ -1,10 +1,10 @@
 ---
 id: testing
 title: Testing
-requires: python-neva>=4.0
-triggers: [writing a test, TestCase, RefreshDatabase, faking a facade, database isolation in tests, create_config]
+requires: python-neva>=5.2
+triggers: [writing a test, TestCase, RefreshDatabase, faking a facade, database isolation in tests, create_config, boot_application]
 priority: 60
-verified_by: [tests/testing/test_test_case.py, tests/testing/test_application_reuse.py, tests/testing/test_create_config_migration.py, tests/testing/test_refresh_database.py, tests/testing/test_facade_restore.py, tests/testing/test_event_fake.py, tests/testing/test_fixtures.py]
+verified_by: [tests/testing/test_test_case.py, tests/testing/test_boot_application.py, tests/testing/test_application_reuse.py, tests/testing/test_create_config_migration.py, tests/testing/test_refresh_database.py, tests/testing/test_facade_restore.py, tests/testing/test_event_fake.py, tests/testing/test_fixtures.py]
 ---
 
 # Testing
@@ -66,6 +66,33 @@ naming the fix. There is no instance-method fallback and no deprecation path —
 Omit the override entirely and the default writes a minimal `app.py` / `providers.py` into
 `tmp_path`.
 
+## boot_application picks the application, not just its config
+
+`create_config` says what configuration the class runs on; `boot_application` says what
+application runs over it, and which lifespan holds it open. Override it when the thing under
+test **owns** an `Application` instead of being one — an HTTP app, whose own lifespan is what
+seeds its per-request state — so entering `Application.lifespan()` would boot the container and
+skip everything wrapped around it.
+
+```python
+class HttpTestCase(TestCase):
+    @override
+    @classmethod
+    @asynccontextmanager
+    async def boot_application(cls, config_path: Path) -> AsyncIterator[Application]:
+        webapp = App(config_path=config_path)
+        async with webapp.router.lifespan_context(webapp):
+            yield webapp.application
+```
+
+Yield the application `self.app` and the facade root must point at. It is a **context manager**,
+so `@classmethod` and `@asynccontextmanager` both belong on the override — a factory returning
+an application would hand the lifespan back to `TestCase`. `FreshApplication` routes through the
+same hook, once per test.
+
+Registration order still holds: register providers and include routers *before* entering the
+lifespan. `Application.register` returns `Err` once booted.
+
 ## RefreshDatabase
 
 Mix it in **alongside** `TestCase`; it cannot boot an application alone.

neva/testing/test_case.py

@@ -2,6 +2,7 @@
 
 import inspect
 from collections.abc import AsyncIterator, Iterator
+from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import override
 
@@ -39,6 +40,10 @@ class TestCase:
 
     A class that genuinely needs a fresh application per test -- one varying the
     *shape* of its config rather than reading it -- inherits `FreshApplication`.
+
+    Two public override points: `create_config` for the configuration, and
+    `boot_application` for the application built over it and the lifespan it is
+    held open by.
     """
 
     pytestmark = pytest.mark.asyncio(loop_scope="class")
@@ -103,6 +108,39 @@ class TestCase:
         )
         raise TypeError(msg)
 
+    @classmethod
+    @asynccontextmanager
+    async def boot_application(cls, config_path: Path) -> AsyncIterator[Application]:
+        """Build the application under test and hold it booted.
+
+        The public override point for *what* a class tests and *how* it starts.
+        `create_config` decides the configuration; this decides the application.
+        Overriding it is how a downstream package tests something that owns an
+        `Application` rather than being one -- an HTTP app whose own lifespan has
+        to be the one entered, because that is what seeds its per-request state.
+
+        An override yields the `Application` the facades and `self.app` must point
+        at, from inside whatever lifespan it needs::
+
+            @classmethod
+            @asynccontextmanager
+            async def boot_application(cls, config_path):
+                webapp = App(config_path=config_path)
+                async with webapp.router.lifespan_context(webapp):
+                    yield webapp.application
+
+        It is a context manager rather than a factory so that the lifespan stays
+        the subclass's to choose. A factory would leave `TestCase` entering
+        `Application.lifespan()` itself, which boots the container but skips any
+        lifespan wrapped around it.
+
+        Yields:
+            The booted application under test.
+        """
+        app = Application(config_path=config_path)
+        async with app.lifespan():
+            yield app
+
     @pytest_asyncio.fixture(scope="class", loop_scope="class")
     @classmethod
     async def _test_case_application(
@@ -113,8 +151,7 @@ class TestCase:
         Yields:
             Application instance with lifespan managed.
         """
-        app = Application(config_path=_test_case_config)
-        async with app.lifespan():
+        async with cls.boot_application(_test_case_config) as app:
             yield app
 
     @pytest.fixture(autouse=True)
@@ -174,8 +211,7 @@ class FreshApplication(TestCase):
         Yields:
             A freshly built Application, torn down at the end of the test.
         """
-        app = Application(config_path=self._build_config(tmp_path))
-        async with app.lifespan():
+        async with self.boot_application(self._build_config(tmp_path)) as app:
             yield app
 
 

{python_neva-5.1.0.dist-info → python_neva-5.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 5.1.0
+Version: 5.3.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0

{python_neva-5.1.0.dist-info → python_neva-5.3.0.dist-info}/RECORD

@@ -44,8 +44,8 @@ neva/guidelines/fragments/factories.md,sha256=4ajYgtN1z4Fwb55FnXw7ROGQUrhqE4N9sg
 neva/guidelines/fragments/observability.md,sha256=RjX73YXulr30v-SCw1J3NHN_f6CGLCKUHQPS-rFeOLE,5760
 neva/guidelines/fragments/result-option.md,sha256=fGyuGwJmSIqb7gWjecbQXiKBdstJ7p5_k82j8KLOzcc,2809
 neva/guidelines/fragments/security.md,sha256=Pz9OHB7o7qVE-Pc3JpSNfMwPqov0ZxLlaIxMmsYfxbQ,5994
-neva/guidelines/fragments/service-providers.md,sha256=Jdzz4J28PkziEdkVoF3sx_qVUJVBrocVQm8E5mL2tyA,8051
-neva/guidelines/fragments/testing.md,sha256=0HZEdv1RmKbdVnzVVEe5ug4AD73gJoD6r74WC9WT5kI,5659
+neva/guidelines/fragments/service-providers.md,sha256=NAJfbChBUq9JC5GyWH7eZbUg55lvVi0tOGnxbvkbQtI,8445
+neva/guidelines/fragments/testing.md,sha256=cFOwNHjjyorpooUyEwsSk3O8XynAlkyk3_AzlQUO_K0,6993
 neva/obs/__init__.py,sha256=SShyp-wlNt6USx7Eus8_Csy0miEHXOS2YnVbP2EARjs,490
 neva/obs/config.py,sha256=cFDverbec3QSpLn0txcXnBnMvnUV7dGRTEdVERhl9L4,1026
 neva/obs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -102,8 +102,8 @@ neva/testing/__init__.py,sha256=QW9inJP1lC_HeoJbKjD_kyHCy4cFV6qt9Rp-EjsKmOY,245
 neva/testing/fakes.py,sha256=w2dnFaO6x14l0_si7iBNELMCxaFi8VsVOSQ6PmTlclE,2936
 neva/testing/fixtures.py,sha256=oiPa5ntUkW-SbySDvwEHXtti8NqSwI-R0CT1_ezTx_Y,1445
 neva/testing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-neva/testing/test_case.py,sha256=quVjECLWw5ZOnf7kwvtRsyD-_mkyxv5yRuvNSOAJYUI,8145
-python_neva-5.1.0.dist-info/METADATA,sha256=M7wOZqbMQilm0N-giNwTqL6JupSTdDzmZIDmkov4IC0,7352
-python_neva-5.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-python_neva-5.1.0.dist-info/entry_points.txt,sha256=DmWZ-qNgvl4eUAXxwX4iLgb38e6X-zU8JDx_brlmkyk,45
-python_neva-5.1.0.dist-info/RECORD,,
+neva/testing/test_case.py,sha256=GdIKrHz9ZuirJybUuaXbW8o-PhOzkvg-pJwe8PAwFD4,9789
+python_neva-5.3.0.dist-info/METADATA,sha256=oGUx6-CaM5vaFk2bx2Jq8anhB-ZETQCktJrh3XwTJl4,7352
+python_neva-5.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+python_neva-5.3.0.dist-info/entry_points.txt,sha256=DmWZ-qNgvl4eUAXxwX4iLgb38e6X-zU8JDx_brlmkyk,45
+python_neva-5.3.0.dist-info/RECORD,,