python-neva 5.1.0__tar.gz → 5.3.0__tar.gz

{python_neva-5.1.0 → python_neva-5.3.0}/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 5.3.0 (2026-09-02)
+
+### ✨ Features
+
+- **testing**: promote the application hook TestCase builds through
+
+### 📝💡 Documentation
+
+- **guidelines**: say which of register's two checks is read first
+
+## 5.2.0 (2026-09-02)
+
+### ✨ Features
+
+- **testing**: promote the application hook TestCase builds through
+
 ## 5.1.0 (2026-09-02)
 
 ### ✨ Features

{python_neva-5.1.0 → python_neva-5.3.0}/PKG-INFO

@@ -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 → python_neva-5.3.0}/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
 

{python_neva-5.1.0 → python_neva-5.3.0}/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.

{python_neva-5.1.0 → python_neva-5.3.0}/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 → python_neva-5.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-neva"
-version = "5.1.0"
+version = "5.3.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12"

python_neva-5.3.0/tests/testing/test_boot_application.py

@@ -0,0 +1,85 @@
+"""`boot_application` is the public seam for the application a class tests.
+
+`create_config` already lets a subclass decide the configuration. It could not decide
+the *application*: `TestCase` built an `Application` itself and entered
+`Application.lifespan()`, so a class testing something that merely **owns** an
+application -- an HTTP app, whose own lifespan is the one that seeds its per-request
+state -- had no way in but to override `_test_case_application`, a private fixture,
+from another distribution.
+
+The hook is a context manager rather than a factory precisely so the lifespan is the
+subclass's to choose; the wrapper assertions below are what pins that down.
+"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import ClassVar, override
+
+from neva.arch import Application, Facade
+from neva.testing import FreshApplication, TestCase
+
+
+class Owner:
+    """Stands in for an object that owns an Application and wraps its lifespan."""
+
+    def __init__(self, config_path: Path) -> None:
+        self.application: Application = Application(config_path=config_path)
+        self.wrapper_entered: bool = False
+        self.wrapper_exited: bool = False
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        async with self.application.lifespan():
+            self.wrapper_entered = True
+            try:
+                yield
+            finally:
+                self.wrapper_exited = True
+
+
+class TestAnOverrideOwnsTheApplicationAndItsLifespan(TestCase):
+    owner: Owner
+
+    @override
+    @classmethod
+    @asynccontextmanager
+    async def boot_application(cls, config_path: Path) -> AsyncIterator[Application]:
+        cls.owner = Owner(config_path)
+        async with cls.owner.lifespan():
+            yield cls.owner.application
+
+    async def test_self_app_is_the_application_the_override_yielded(self) -> None:
+        assert self.app is type(self).owner.application
+
+    async def test_the_overrides_own_lifespan_wraps_the_test(self) -> None:
+        assert type(self).owner.wrapper_entered
+        assert not type(self).owner.wrapper_exited
+
+    async def test_the_facade_root_points_at_the_yielded_application(self) -> None:
+        assert Facade.get_facade_application().unwrap() is self.app
+
+
+class TestFreshApplicationRoutesThroughTheSameHook(FreshApplication):
+    """The per-test opt-out must honour the override too, not bypass it."""
+
+    owners: ClassVar[list[Owner]] = []
+
+    @override
+    @classmethod
+    @asynccontextmanager
+    async def boot_application(cls, config_path: Path) -> AsyncIterator[Application]:
+        owner = Owner(config_path)
+        cls.owners.append(owner)
+        async with owner.lifespan():
+            yield owner.application
+
+    async def test_a_builds_through_the_override(self) -> None:
+        assert self.app is type(self).owners[-1].application
+
+    async def test_b_built_a_second_one_and_closed_the_first(self) -> None:
+        owners = type(self).owners
+
+        assert len(owners) == 2, "FreshApplication must re-enter the hook per test"
+        assert owners[0].wrapper_exited, "the previous test's lifespan must be closed"
+        assert self.app is owners[-1].application

{python_neva-5.1.0 → python_neva-5.3.0}/uv.lock

@@ -1539,7 +1539,7 @@ wheels = [
 
 [[package]]
 name = "python-neva"
-version = "5.1.0"
+version = "5.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },