python-neva 3.7.0__py3-none-any.whl → 4.0.0__py3-none-any.whl

neva/arch/__init__.py

@@ -5,6 +5,7 @@ and facade implementations.
 """
 
 from neva.arch.application import Application
+from neva.arch.config import AppConfig, ProviderConfig
 from neva.arch.facade import Facade
 from neva.arch.service_provider import (
     Bootable,
@@ -13,8 +14,10 @@ from neva.arch.service_provider import (
 
 
 __all__ = [
+    "AppConfig",
     "Application",
     "Bootable",
     "Facade",
+    "ProviderConfig",
     "ServiceProvider",
 ]

neva/arch/application.py

@@ -6,17 +6,16 @@ from collections.abc import AsyncGenerator, Sequence
 from contextlib import AsyncExitStack, asynccontextmanager
 from contextvars import ContextVar
 from pathlib import Path
-from typing import Any, Callable, Self
+from typing import Any, Self
 
 import dishka
 from dishka.provider import BaseProvider
-from typing_extensions import deprecated
 
 from neva.arch.facade import Facade
 from neva.arch.scopes import BaseScope, Scope
 from neva.arch.service_provider import Bootable, ServiceProvider
 from neva.config.loader import ConfigLoader
-from neva.support import Err, Ok, Result
+from neva.support import Err, Ok, Result, Some
 
 
 _current_container: ContextVar["dishka.AsyncContainer"] = ContextVar(
@@ -24,6 +23,26 @@ _current_container: ContextVar["dishka.AsyncContainer"] = ContextVar(
 )
 
 
+def _resolve_config_path(config_path: str | Path | None) -> Path:
+    """Resolve the directory config files are loaded from.
+
+    The config directory is a dedicated folder, never the project root: every
+    ``.py`` in it is imported to read its ``config`` dict, so pointing this at
+    a directory holding ordinary modules would execute them.
+
+    Returns:
+        The explicit argument, else $NEVA_CONFIG_PATH, else ./config.
+    """
+    if config_path is not None:
+        return Path(config_path)
+
+    env_path = os.getenv("NEVA_CONFIG_PATH")
+    if env_path:
+        return Path(env_path)
+
+    return Path.cwd() / "config"
+
+
 class Application:
     """Base application for DI and facade injection."""
 
@@ -31,8 +50,9 @@ class Application:
         """Initialize the application and its bindings.
 
         Args:
-            config_path: Path to the configuration directory. Defaults to "./config"
-                relative to the current working directory.
+            config_path: Path to the configuration directory. Defaults to
+                ``$NEVA_CONFIG_PATH``, else ``./config`` relative to the
+                current working directory.
 
         Raises:
             RuntimeError: If the application fails to initialize.
@@ -47,11 +67,7 @@ class Application:
         self._container: dishka.AsyncContainer | None = None
         self._booted: bool = False
 
-        configuration_path = (
-            config_path
-            if config_path is not None
-            else os.getenv("NEVA_CONFIG_PATH", default=Path.cwd())
-        )
+        configuration_path = _resolve_config_path(config_path)
         match ConfigLoader(configuration_path).load_all():
             case Err(e):
                 raise RuntimeError(f"Failed to register config: {e}")
@@ -150,21 +166,6 @@ class Application:
         for provider in providers:
             _ = self.register(provider)
 
-    @deprecated("Use the new bind() method directly with a Service Provider.")
-    def bind(
-        self,
-        source: type | Callable[..., Any],
-        *,
-        interface: type | None = None,
-        scope: BaseScope | None = None,
-    ) -> None:
-        """Binds a source to the container."""
-        _ = self.root_provider.provide(
-            source=source,
-            scope=scope,
-            provides=interface,
-        )
-
     @property
     def current_container(self) -> dishka.AsyncContainer:
         """The container backing resolution in the current context.
@@ -226,6 +227,11 @@ class Application:
     @asynccontextmanager
     async def lifespan(self) -> AsyncGenerator[None]:
         """Wire the facades and providers."""
+        # The facade root is a single process-global slot, so a short-lived
+        # application nested inside a longer-lived one must hand it back rather
+        # than clear it -- otherwise it disarms every facade for whatever the
+        # outer application still has to do.
+        previous_facade_application = Facade.get_facade_application()
         Facade.set_facade_application(self)
         self._booted = True
 
@@ -243,27 +249,50 @@ class Application:
             if self._container is not None:
                 await self._container.close()
             self._booted = False
-            Facade.reset_facade_application()
+            match previous_facade_application:
+                case Some(application):
+                    Facade.set_facade_application(application)
+                case _:
+                    Facade.reset_facade_application()
 
     def _bind_event_listeners(self) -> None:
         """Bind all listener classes declared in provider ``listen`` dicts."""
         for provider in self.providers.values():
             for listeners in provider.listen.values():
                 for listener_cls in listeners:
-                    # Straight onto the root provider: routing this through the
-                    # deprecated `bind` warned on every boot.
+                    # Straight onto the root provider: these listeners are not
+                    # a provider's own bindings, so they do not belong in one.
                     _ = self.root_provider.provide(listener_cls, scope=Scope.APP)
 
     async def _wire_event_listeners(self) -> None:
-        """Wire event-listener mappings from all providers onto the dispatcher."""
+        """Wire event-listener mappings from all providers onto the dispatcher.
+
+        Raises:
+            RuntimeError: If listeners are declared but the dispatcher cannot
+                be resolved. Booting on regardless would leave every one of
+                them unwired, so the events would simply never fire — with
+                nothing anywhere saying why.
+        """
         from neva.events.dispatcher import EventDispatcher
 
-        result = await self.make_async(EventDispatcher)
-        if result.is_err:
+        declared = [
+            (event_cls, listener_cls)
+            for provider in self.providers.values()
+            for event_cls, listeners in provider.listen.items()
+            for listener_cls in listeners
+        ]
+        if not declared:
             return
 
-        dispatcher = result.unwrap()
-        for provider in self.providers.values():
-            for event_cls, listeners in provider.listen.items():
-                for listener_cls in listeners:
+        match await self.make_async(EventDispatcher):
+            case Err(e):
+                msg = (
+                    f"Cannot wire {len(declared)} declared event listener(s): "
+                    f"the EventDispatcher could not be resolved ({e}). "
+                    "Register EventServiceProvider, or remove the 'listen' "
+                    "mappings that need it."
+                )
+                raise RuntimeError(msg)
+            case Ok(dispatcher):
+                for event_cls, listener_cls in declared:
                     dispatcher.listen(event_cls, listener_cls)

neva/arch/config.py

@@ -1,37 +1,49 @@
-"""Helper TypedDict for application configuration."""
+"""Config shapes for the namespaces the core itself reads.
+
+Annotate a config file with one of these to have a type checker catch typos
+and wrong value types before boot:
+
+```python
+# src/config/app.py
+from neva.arch import AppConfig
+
+config: AppConfig = {"providers": [MyProvider]}
+```
+
+Keys read by an integration package are declared by that package, not here —
+`neva-fastapi` owns the OpenAPI and title keys of the `app` namespace, for
+instance. The core only describes what the core consumes.
+"""
 
 from typing import NotRequired, TypedDict
 
-from neva.arch import ServiceProvider
+from neva.arch.service_provider import ServiceProvider
 
 
 class AppConfig(TypedDict):
-    """Main application config.
+    """The `app` namespace keys the core reads.
 
     Attributes:
-        title: The application title.
-        debug: Whether the application is in debug mode.
-        version: The application version.
-        openapi_url: The URL for the OpenAPI specification.
-        docs_url: The URL for the Swagger UI documentation.
-        redoc_url: The URL for the ReDoc documentation.
-        providers: List of service providers to register.
+        key: Base64-encoded 32-byte key for `Crypt`. Generate one with
+            `AesEncrypter.generate_key()`.
+        previous_keys: Superseded keys, still accepted when decrypting so a
+            key rotation does not orphan existing ciphertext.
+        providers: Service providers to register, appended after those from
+            the `providers` namespace.
     """
 
-    title: NotRequired[str]
-    debug: NotRequired[bool]
-    version: NotRequired[str]
-    openapi_url: NotRequired[str]
-    docs_url: NotRequired[str]
-    redoc_url: NotRequired[str]
+    key: NotRequired[str]
+    previous_keys: NotRequired[list[str]]
     providers: NotRequired[list[type[ServiceProvider]]]
 
 
 class ProviderConfig(TypedDict):
-    """Application service provider config.
+    """The `providers` namespace.
+
+    A dedicated namespace for the provider list, read before `app.providers`.
 
     Attributes:
-        providers: List of service providers to register.
+        providers: Service providers to register.
     """
 
     providers: NotRequired[list[type[ServiceProvider]]]

neva/arch/integrations/faststream.py

@@ -1,18 +1,23 @@
 """FastStream wrapper for Neva."""
 
-from collections.abc import AsyncGenerator, AsyncIterator
-from contextlib import asynccontextmanager
+from collections.abc import AsyncGenerator, AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from typing import Any
 
 import faststream
 from faststream._internal.broker import BrokerUsecase
 from faststream._internal.configs import BrokerConfig
-from starlette.types import StatelessLifespan
 
 from neva.arch import Application, ServiceProvider
 from neva.support import Result
 
 
+# Spelled out locally rather than borrowed from starlette.types: a messaging
+# app's lifespan is not a web concern, and the core must not import an ASGI
+# framework to describe one.
+type FastStreamLifespan = Callable[["FastStream"], AbstractAsyncContextManager[None]]
+
+
 class FastStream(faststream.FastStream):
     """FastStream wrapper for Neva."""
 
@@ -42,9 +47,7 @@ class FastStream(faststream.FastStream):
         async with self.application.lifespan():
             yield
 
-    def _create_lifespan(
-        self,
-    ) -> StatelessLifespan["FastStream"]:
+    def _create_lifespan(self) -> FastStreamLifespan:
         @asynccontextmanager
         async def composed_lifespan(_: faststream.FastStream) -> AsyncIterator[None]:
             async with self.lifespan():

neva/arch/service_provider.py

@@ -8,7 +8,6 @@ container and optionally managing their lifecycle.
 from __future__ import annotations
 
 import abc
-import warnings
 from contextlib import AbstractAsyncContextManager
 from typing import (
     TYPE_CHECKING,
@@ -115,9 +114,9 @@ class ServiceProvider(abc.ABC):
         `instance` — which say what they mean. Use `bind` directly only to
         reach a scope those do not cover, and then pass `scope` explicitly.
 
-        Calling this with neither `scope` nor `cache` is deprecated: the
-        resulting binding is a process-wide singleton, which is the opposite of
-        Laravel's transient `bind`, and nothing at the call site says so.
+        A lifetime is required. Without one the binding would be a
+        process-wide singleton — the opposite of Laravel's transient `bind` —
+        with nothing at the call site saying so.
 
         Args:
             source: The class or factory to bind.
@@ -125,16 +124,17 @@ class ServiceProvider(abc.ABC):
             scope: The dishka scope. Defaults to the provider's (APP).
             when: Marker gating this binding.
             cache: Whether to reuse one instance per scope. Defaults to True.
+
+        Raises:
+            TypeError: If neither `scope` nor `cache` is given.
         """
         if scope is None and cache is None:
-            warnings.warn(
-                "bind() without an explicit lifetime is deprecated and will "
-                "require one in 4.0. It currently creates a process-wide "
-                "singleton: use singleton() for that, or scoped() / "
-                "transient() / instance(), or pass scope= or cache= yourself.",
-                DeprecationWarning,
-                stacklevel=2,
+            msg = (
+                "bind() requires an explicit lifetime: use singleton() for a "
+                "process-wide instance, or scoped() / transient() / "
+                "instance(), or pass scope= or cache= yourself."
             )
+            raise TypeError(msg)
 
         _ = self.provider.provide(
             source=source,

neva/database/connection.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass, field
 from typing import final
 
 from sqlalchemy.ext import asyncio
+from structlog.stdlib import get_logger
 
 from neva.database.transaction import BoundTransaction, TransactionState
 from neva.obs import LogManager
@@ -147,9 +148,13 @@ class ConnectionManager:
             else await tx.execute_on_rollback_callbacks()
         )
         label = "commit" if committed else "rollback"
+        # A post-commit callback cannot un-commit the transaction, so its
+        # failure is reported rather than raised. It must never be lost: fall
+        # back to a module logger when the manager has none.
+        logger = self.logger if self.logger is not None else get_logger(__name__)
         for result in results:
-            if result.is_err and self.logger is not None:
-                self.logger.error(
+            if result.is_err:
+                logger.error(
                     f"{label} callback failed",
                     error=result.err().unwrap(),
                     connection=self.name,

neva/database/manager.py

@@ -5,7 +5,6 @@ from contextlib import asynccontextmanager
 from typing import final
 
 from sqlalchemy.ext import asyncio
-from typing_extensions import deprecated
 
 from neva.database.config import ConnectionConfig
 from neva.database.connection import ConnectionManager, TransactionContext
@@ -24,9 +23,14 @@ class DatabaseManager:
         self._logger = logger
         self._connections: dict[str, ConnectionManager] = {}
 
-    @deprecated("Please use DatabaseManager.register_connection instead.")
     def register_engine(self, name: str, engine: asyncio.AsyncEngine) -> None:
-        """Register an engine and create a session factory for a connection.
+        """Register a connection around an engine you already built.
+
+        Prefer `register_connection`, which builds the engine from config. Use
+        this when the caller must own the engine — a test that creates the
+        schema on an in-memory database has to hand over that exact engine,
+        since a second engine to `sqlite:///:memory:` is a second, empty
+        database.
 
         Args:
             name: The connection name.

neva/database/transaction.py

@@ -1,17 +1,41 @@
 """Transaction management systems."""
 
 import asyncio
-from collections.abc import Awaitable
+import inspect
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from enum import Enum, auto
-from typing import Callable, Self
+from typing import Self
 
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from neva.support import Err, Nothing, Option, Result, Some
+from neva.support import Err, Nothing, Ok, Option, Result, Some
 
 
-type TransactionCallback = Callable[[], Awaitable[Result[None, str]]]
+type TransactionOutcome = Result[None, str] | None
+type TransactionCallback = Callable[
+    [], TransactionOutcome | Awaitable[TransactionOutcome]
+]
+
+
+async def _run_callback(callback: TransactionCallback) -> Result[None, str]:
+    """Invoke a transaction callback, whether it is sync or async.
+
+    A callback may return a ``Result`` to report its own failure, or ``None``
+    to say "done, nothing to report" — which is what a bare side-effecting
+    lambda does.
+
+    Returns:
+        The callback's own Result, Ok(None) if it returned None, or Err if it
+        raised.
+    """
+    try:
+        outcome = callback()
+        if inspect.isawaitable(outcome):
+            outcome = await outcome
+    except Exception as e:
+        return Err(f"Callback raised: {e}")
+    return Ok(None) if outcome is None else outcome
 
 
 class TransactionState(Enum):
@@ -77,10 +101,7 @@ class Transaction:
         """
         results: list[Result[None, str]] = []
         for callback in self._on_commit:
-            try:
-                results.append(await callback())
-            except Exception as e:
-                results.append(Err(f"Callback raised: {e}"))
+            results.append(await _run_callback(callback))
         self._on_commit.clear()
         return results
 
@@ -92,10 +113,7 @@ class Transaction:
         """
         results: list[Result[None, str]] = []
         for callback in self._on_rollback:
-            try:
-                results.append(await callback())
-            except Exception as e:
-                results.append(Err(f"Callback raised: {e}"))
+            results.append(await _run_callback(callback))
         self._on_rollback.clear()
         return results
 

neva/obs/__init__.py

@@ -1,13 +1,9 @@
 """Observability tooling."""
 
 from neva.obs.logging import LogManager, LogServiceProvider
-from neva.obs.middleware.correlation import CorrelationMiddleware
-from neva.obs.middleware.profiler import ProfilerMiddleware
 
 
 __all__ = [
-    "CorrelationMiddleware",
     "LogManager",
     "LogServiceProvider",
-    "ProfilerMiddleware",
 ]

neva/security/tokens/generate_token.py

@@ -3,14 +3,16 @@
 import secrets
 
 
-def generate_token(length: int = 32) -> str:
-    """Generate a secure random token.
+def generate_token(nbytes: int = 32) -> str:
+    """Generate a secure random URL-safe token.
 
     Args:
-        length (int, optional): The length of the token. Defaults to 32.
+        nbytes: Bytes of entropy to draw. This is not the length of the
+            returned string: base64url encoding makes it roughly
+            ``4 * nbytes / 3`` characters, so the default 32 bytes yields a
+            43-character token.
 
     Returns:
-        str: The generated token.
+        A URL-safe token carrying `nbytes` bytes of entropy.
     """
-    token = secrets.token_urlsafe(length)
-    return token
+    return secrets.token_urlsafe(nbytes)

neva/testing/__init__.py

@@ -1,7 +1,7 @@
 """Testing utilities for Neva applications."""
 
 from neva.testing.fakes import EventFake
-from neva.testing.test_case import RefreshDatabase, TestCase
+from neva.testing.test_case import FreshApplication, RefreshDatabase, TestCase
 
 
-__all__ = ["EventFake", "RefreshDatabase", "TestCase"]
+__all__ = ["EventFake", "FreshApplication", "RefreshDatabase", "TestCase"]

neva/testing/test_case.py

@@ -1,9 +1,12 @@
 """Base test case class."""
 
+import inspect
 from collections.abc import AsyncIterator, Iterator
 from pathlib import Path
+from typing import override
 
 import pytest
+import pytest_asyncio
 
 from neva.arch import Application, Facade
 from neva.database.manager import DatabaseManager
@@ -15,17 +18,43 @@ class TestCase:
     Subclasses can override `create_config` to provide custom configuration
     for their tests. The application will be automatically created with this
     configuration and injected into `self.app`.
+
+    The application is built **once per class**, not once per test: construction
+    costs tens of milliseconds (config loading re-executes every module in the
+    config directory, then every provider registers and a DI container is built)
+    and nothing in it is per-test. `RefreshDatabase` isolates database state by
+    rolling the transaction back, and `_restore_facades` undoes fakes.
+
+    Per class rather than per session is deliberate. `create_config` is a
+    per-subclass override point, so one application for the whole session would
+    serve every subclass the config of whichever class happened to run first.
+
+    Two consequences for subclasses:
+
+    * State written onto `self.app` outlives the test that wrote it, for the rest
+      of its class. Database state does not -- that is what `RefreshDatabase` is
+      for.
+    * Every test in a class shares one event loop, which is what lets the
+      application's engines and connections outlive a single test.
+
+    A class that genuinely needs a fresh application per test -- one varying the
+    *shape* of its config rather than reading it -- inherits `FreshApplication`.
     """
 
+    pytestmark = pytest.mark.asyncio(loop_scope="class")
+
     app: Application
 
-    def create_config(self, tmp_path: Path) -> Path:
+    @classmethod
+    def create_config(cls, tmp_path: Path) -> Path:
         """Create the configuration directory for tests.
 
-        Override this method to provide custom configuration.
+        Override this method to provide custom configuration. It is a classmethod
+        because the fixture that calls it is class-scoped: no instance exists yet
+        when the application is built.
 
         Args:
-            tmp_path: Pytest's temporary directory fixture.
+            tmp_path: A temporary directory belonging to this class.
 
         Returns:
             Path to the configuration directory.
@@ -38,20 +67,48 @@ class TestCase:
         _ = (config_dir / "providers.py").write_text("""config = { "providers": []}""")
         return config_dir
 
-    @pytest.fixture
-    def _test_case_config(self, tmp_path: Path) -> Path:
+    @pytest.fixture(scope="class")
+    @classmethod
+    def _test_case_config(cls, tmp_path_factory: pytest.TempPathFactory) -> Path:
         """Config fixture that uses the create_config method.
 
         Returns:
             Path to the configuration directory.
         """
-        return self.create_config(tmp_path)
+        return cls._build_config(tmp_path_factory.mktemp("neva"))
+
+    @classmethod
+    def _build_config(cls, tmp_path: Path) -> Path:
+        """Call `create_config`, rejecting an override left as an instance method.
 
-    @pytest.fixture
+        `create_config` became a classmethod when the application fixture became
+        class-scoped. An override still declared as `def create_config(self, ...)`
+        would otherwise fail with a bare "missing 1 required positional
+        argument", which says nothing about what to change.
+
+        Returns:
+            Path to the configuration directory.
+
+        Raises:
+            TypeError: If the override is an instance method.
+        """
+        create_config = inspect.getattr_static(cls, "create_config")
+        if isinstance(create_config, classmethod):
+            return cls.create_config(tmp_path)
+
+        msg = (
+            f"{cls.__name__}.create_config is an instance method. The application"
+            " fixture is class-scoped, so create_config must be a @classmethod"
+            " taking (cls, tmp_path)."
+        )
+        raise TypeError(msg)
+
+    @pytest_asyncio.fixture(scope="class", loop_scope="class")
+    @classmethod
     async def _test_case_application(
-        self, _test_case_config: Path
+        cls, _test_case_config: Path
     ) -> AsyncIterator[Application]:
-        """Application fixture for TestCase subclasses.
+        """Application fixture for TestCase subclasses, built once per class.
 
         Yields:
             Application instance with lifespan managed.
@@ -65,6 +122,17 @@ class TestCase:
         """Auto-inject app fixture into self.app."""
         self.app = _test_case_application
 
+    @pytest.fixture(autouse=True)
+    def _own_the_facade(self, _test_case_application: Application) -> None:
+        """Point the facade root at this class's application, for every test.
+
+        `Application.lifespan` already does this on entry, but the root is a single
+        process-global slot: another application booting and tearing down inside a
+        test would leave it pointing elsewhere. Re-asserting it per test costs one
+        attribute write and makes the ordering of unrelated tests irrelevant.
+        """
+        Facade.set_facade_application(_test_case_application)
+
     @pytest.fixture(autouse=True)
     def _restore_facades(self) -> Iterator[None]:
         """Restore all faked facades after each test."""
@@ -72,6 +140,45 @@ class TestCase:
         Facade.restore_all()
 
 
+class FreshApplication(TestCase):
+    """Opt-out base: build a new application for every test.
+
+    `TestCase` shares one application per class. Subclass this instead when a class
+    needs a genuinely fresh application per test -- typically because its tests vary
+    the *shape* of the configuration, so the application under test differs from one
+    test to the next rather than merely being read differently.
+
+    It pays the full construction cost per test, so reach for it only when the
+    shared application is actually wrong::
+
+        class TestConfigVariations(FreshApplication):
+            ...
+
+    It composes with `RefreshDatabase` the same way `TestCase` does::
+
+        class TestConfigVariations(FreshApplication, RefreshDatabase):
+            ...
+    """
+
+    # A fixture override cannot keep its parent's signature here: the shared
+    # application is class-scoped and therefore a classmethod, while a per-test one
+    # needs the instance. Overriding a fixture by name is the pytest-sanctioned way
+    # to do this, and no type checker can model it.
+    @pytest_asyncio.fixture(loop_scope="class")
+    @override
+    async def _test_case_application(  # pyrefly: ignore[bad-override]
+        self, tmp_path: Path
+    ) -> AsyncIterator[Application]:
+        """Override `TestCase`'s class-scoped application with a per-test one.
+
+        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():
+            yield app
+
+
 class RefreshDatabase(TestCase):
     """Mixin for TestCase that wraps each test in a transaction and rolls it back.
 
@@ -80,7 +187,7 @@ class RefreshDatabase(TestCase):
     before the rollback transaction opens.
     """
 
-    @pytest.fixture
+    @pytest_asyncio.fixture(loop_scope="class")
     async def _setup_database_engine(self) -> AsyncIterator[None]:
         """Hook for registering DB engines before the rollback transaction opens.
 
@@ -88,7 +195,7 @@ class RefreshDatabase(TestCase):
         """
         yield
 
-    @pytest.fixture(autouse=True)
+    @pytest_asyncio.fixture(autouse=True, loop_scope="class")
     async def _rollback_database(
         self,
         _setup_database_engine: None,  # ordering dependency: runs after engine setup

{python_neva-3.7.0.dist-info → python_neva-4.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 3.7.0
+Version: 4.0.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
@@ -12,9 +12,10 @@ Requires-Dist: pwdlib[argon2,bcrypt]>=0.3.0
 Requires-Dist: pydantic>=2.7
 Requires-Dist: pyinstrument>=5.1.1
 Requires-Dist: sqlalchemy[asyncio]>=2.0.0
-Requires-Dist: starlette>=0.41
 Requires-Dist: structlog>=25.5.0
 Requires-Dist: typing-extensions>=4.13
+Provides-Extra: asgi
+Requires-Dist: neva-asgi>=0.1.1; extra == 'asgi'
 Provides-Extra: fastapi
 Requires-Dist: neva-fastapi>=1.1.1; extra == 'fastapi'
 Provides-Extra: faststream
@@ -48,6 +49,7 @@ independent repo, independently versioned and published.
 | ----------------- | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------- |
 | `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, observability, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
 | `neva-fastapi`    | `neva-fastapi/`    | FastAPI integration — `App` extends `FastAPI` and wires dishka into routes. Pulled in via the `python-neva[fastapi]` extra. | published ([PyPI](https://pypi.org/project/neva-fastapi/)) |
+| `neva-asgi`       | `neva-asgi/`       | **ASGI middleware** — correlation IDs and per-request profiling. Pure ASGI, so both the HTTP and messaging integrations can consume it. Pulled in via the `python-neva[asgi]` extra. | published ([PyPI](https://pypi.org/project/neva-asgi/)) |
 | `neva-faststream` | `neva-faststream/` | FastStream (messaging) integration.                                                   | scaffolded, early placeholder   |
 | `neva-auth`       | `neva-auth/`       | Authentication & identity toolkit — token-issuance engine, OAuth2 grants, guards, pluggable formats/backends. | core complete, OAuth-server slice in progress |
 | `neva-example`    | `neva-example/`    | Reference application consuming `python-neva[fastapi]`. Not published; demonstration + integration test bed. | unpublished                     |

{python_neva-3.7.0.dist-info → python_neva-4.0.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
-neva/arch/__init__.py,sha256=1ukTl5Ynz5PrGa5e-tFSMaNgVkfhQRrYQGPUqUeXMMg,429
-neva/arch/application.py,sha256=PQ5Zb29kwt6srDArnDrxwOjc62MYutQTmhlUCQ5wSlQ,9968
-neva/arch/config.py,sha256=k8Nf5kBfw0We-gFxPqDEi78T8eFHBhZe1qTpCi2Q0kA,1054
+neva/arch/__init__.py,sha256=S9I9HUL9G-ylfzMdIfhLS8ux1heyFSti1auXpKvZrEY,523
+neva/arch/application.py,sha256=saXl8KdCp_EEwi0tgXqI_iuEzqtrw_CXixjkqSLlhNo,11401
+neva/arch/config.py,sha256=F_4TNIYJpqnAbQrfeYsKKHK9Py6L0ew1UkW0P9YkFro,1478
 neva/arch/facade.py,sha256=1kYVhyYto8zSyOZV6sAYJ3xWzQDJRzoVV-e_EarTp0Q,7927
 neva/arch/markers.py,sha256=STdhmW88qV8uogIa9kSD9gs-uMRaglZI8HOw3PrhX1Q,103
 neva/arch/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/arch/scopes.py,sha256=9sc1nIVeODQzAtNwvSUWiij6IIssNyOaKW2CNknBgTo,86
-neva/arch/service_provider.py,sha256=BRHMHuG3SRbVzQUipNaKgNQmn9GVUk5VO3Nart1JmnI,8630
+neva/arch/service_provider.py,sha256=eA6ZGYOYnZTgfQu-ry5qTmViX7B-KJFjC6NXTSxlbaE,8537
 neva/arch/integrations/__init__.py,sha256=cXuqC4JfZdGYLlh6POgYUVXUT2NQ84276eC-RYTyFxk,75
-neva/arch/integrations/faststream.py,sha256=AOwfpfdL3O5HLAx80SwUGQb_hKEeAkFOUyIXtjODaHM,1696
+neva/arch/integrations/faststream.py,sha256=_SnOg8Z-v_XqX_ReeLLTyz-oPm4-9tj9SblX6sDIZao,1931
 neva/config/__init__.py,sha256=Ygfnh-MRRKYDdf54_LeMSHwmck5VpNHTdnnMtGEFLtU,121
 neva/config/base_providers.py,sha256=vXv3kGWnrWQGBMo4WvEmYnryCKLkOdFFTjrDFDnhXFI,909
 neva/config/loader.py,sha256=E81a6nEboRNNMBEFU26UvEgvAjPIN3Aqn6mmVpa5cf4,4534
@@ -15,11 +15,11 @@ neva/config/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/config/repository.py,sha256=p8PjTfjV23ioy_iyb5b6oYPnYq1bVe6q6gVRSegJr7Q,5505
 neva/database/__init__.py,sha256=3yYnEe8HQM86tURyAhTbMtE7AXubIEMN3GuwxkkT-bk,508
 neva/database/config.py,sha256=bVKUqlrYDFrURqg_FbntPXyVkbOUPSVXQJTKjyucjL0,451
-neva/database/connection.py,sha256=pBv29IygCnRGex4hiUx5TSb3TtmPHNBhOS4VTNUfQNc,6972
-neva/database/manager.py,sha256=yPbDMcVlsn5_8ISPVhyajAM42i34r2gJgI9o-TVp59c,4617
+neva/database/connection.py,sha256=PkpC--RyLh0K2AR26a1ZlpHN0p4uFFlcbwSpPdSj8Y8,7274
+neva/database/manager.py,sha256=uZkCSvOgzjdQbuw4YKsNbA4T97nmbksKuAlp0yktAUE,4817
 neva/database/provider.py,sha256=XCi8-mfJ5KDVpVO10YlNX4jt0a9ESSeTyn8o3ohOe9c,1701
 neva/database/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-neva/database/transaction.py,sha256=hhEZg34RsITM-MJHQEcWEgArG8AOYr16p1WjldVVpQ0,5140
+neva/database/transaction.py,sha256=wC0BW44c16wxiFBXvLC921lXQ7ESxV-rZCpqTPx8Kvs,5703
 neva/events/__init__.py,sha256=Gpi5q-pNlIi-q23U2ZOsNf8Y9rB6AQtsBbbBFU0tkFc,776
 neva/events/dispatcher.py,sha256=O_sDpbQBRMFg34hoXEtIfWhYVX-_QUjYB0Nk4QXOGsM,4453
 neva/events/event.py,sha256=q-KyyxNkU3AN2YSaujuNPIoXQMXhGOwClTap5y8fU5I,282
@@ -33,16 +33,13 @@ neva/events/contracts/dispatcher.py,sha256=pzCv_ZLS5ju2IKVMxL5f-fFipEqQZc6zPiIVt
 neva/events/contracts/event.py,sha256=kUUECex_AlmaPJ-fXRg32eMkiqNS75CHldOr7bbpFqo,89
 neva/events/contracts/handler.py,sha256=SwLuuRtXhCzGkcBBLdH3MjUAkjEr0_rhqgE6dkWVJxI,327
 neva/events/contracts/listener.py,sha256=0xwPrjprkMzXu9vY1Z-EjSLFdvOUpomiE65hH16nfxA,465
-neva/obs/__init__.py,sha256=dVzgljk9Hvo44LI34RcwbDyT42_z4nSnFVmL4GLbKD0,331
+neva/obs/__init__.py,sha256=uVD8uKaRTLviBNQ681lG6mVgVynQ47-qwzehbTNUPpE,150
 neva/obs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/obs/instrumentation/__init__.py,sha256=SfIAvuCs-L0kEzOxUJ4aOIkhbydCe7qBwWtGeDELVA0,36
 neva/obs/instrumentation/sqlalchemy.py,sha256=kwk43NthFi4mPMhDJI55rxt9YPOY_mwOkr2E-cD64ZY,497
 neva/obs/logging/__init__.py,sha256=gIYBAzMK7-wPGEpA_kYKvJPT3hYN99OcCc9UuHFeiHk,251
 neva/obs/logging/manager.py,sha256=ktd3muBGU3e1KuBK6tSU5faRJRliPwmknuqJ2EYeFBk,2422
 neva/obs/logging/provider.py,sha256=-AIZb60PmTpvO9PtsJwZ5FJeTC_Yn6ik8DdJCHULpV0,651
-neva/obs/middleware/__init__.py,sha256=WbZ-Pr_fVl6T8LfQRyC_YXMlN7WaQKEwX8KUvGiLOBc,182
-neva/obs/middleware/correlation.py,sha256=x_3HtlBV1Qe8JRgGpEwSTXvKkeCgWal15b0hrFjNAJs,2034
-neva/obs/middleware/profiler.py,sha256=ovx3s-39WpNtu2KhzVMWyIJa6OLrSVDuL56xyDA-vQ4,1942
 neva/polyfactory/__init__.py,sha256=t7uAXaleAyshSyBdGXNzvgY0nNpb5AqFU4zjE8lyKyk,153
 neva/polyfactory/factories.py,sha256=8VoZJlY0-_ZOM8rmfUcvEbt-KOZsaDj8f6R5EQF62u8,600
 neva/polyfactory/persistence.py,sha256=1qBg8L_xkiRFq6J2XoZFez43oxNWDaUM8SrlNAeOkQA,605
@@ -61,7 +58,7 @@ neva/security/hashing/hashers/argon2.py,sha256=pJqTl3_oCJCjJarnQwNSFRznlaijjbjdD
 neva/security/hashing/hashers/bcrypt.py,sha256=-VsCtbQvEFDoKnwQxUwYFGSI_1qyWfP3R5TAhNvZW0Q,1083
 neva/security/hashing/hashers/protocol.py,sha256=aVGMO2q3H-u8uyGPt6mIy1Dq7pW0k4WjtHi0nnKsgCQ,611
 neva/security/tokens/__init__.py,sha256=H1SWLWa4btJqc0wBUFTdKUYmBgXYZYnCitG1BsbLtqI,235
-neva/security/tokens/generate_token.py,sha256=xqlC80IfCvkwmQR_TAHmEntiJdEV2yEPHX6qBnv5cBg,334
+neva/security/tokens/generate_token.py,sha256=K3Wy7DGVlBvPflDh6C8-FWZWCSPc3Fwmw9LqJdIViN4,524
 neva/security/tokens/hash_token.py,sha256=KMzYXNqi6SbmgNqntGnsE9FMIoDIEVEsCumLYzkQssc,351
 neva/security/tokens/verify_token.py,sha256=kPs3HQwu0N8Syp7V_hY_YmOWfmq-Cd9ACUWsxwjniZk,460
 neva/support/__init__.py,sha256=EOdAwB2qA_CwPnoace-Q1CEOvp0B4PdlPxRUGsWABD4,447
@@ -86,11 +83,11 @@ neva/support/facade/hash.py,sha256=tGhsvfGovt-mcRXSjDKf4jt1n7ib0eDPXFvRUfVxLUc,2
 neva/support/facade/hash.pyi,sha256=Uy0CkV67MImPjHc6BmmLQPd7qF1QNDtO1oDFyyRr-1A,2950
 neva/support/facade/log.py,sha256=_uLoHB9tkpHkiqEJXazbaqfiKUOtv3NS71ZCZAprzOI,347
 neva/support/facade/log.pyi,sha256=Xi7gIzw9qRqmD4D3PcW06_HUtgLWEOdsHqs1B0jh1-k,1647
-neva/testing/__init__.py,sha256=vt5zxG1N84vn_YwP44jhYPWYnyb02-cha3m-1l-qoEw,207
+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=zJBZJeKI-sv-EOaXNuSJ0V2Zp_6hdk64W4dOh0eP8RI,3290
-python_neva-3.7.0.dist-info/METADATA,sha256=FShZGkR90WatQd_me7ozxBOpKNKUg5RVVe-owWdELqo,5198
-python_neva-3.7.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-python_neva-3.7.0.dist-info/RECORD,,
+neva/testing/test_case.py,sha256=quVjECLWw5ZOnf7kwvtRsyD-_mkyxv5yRuvNSOAJYUI,8145
+python_neva-4.0.0.dist-info/METADATA,sha256=ILm9awKSo2HaeSc5IgvKFCDl2SPBd9Yd3zEmTnRrG9I,5523
+python_neva-4.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+python_neva-4.0.0.dist-info/RECORD,,

neva/obs/middleware/__init__.py

@@ -1,7 +0,0 @@
-"""Observability middlewares."""
-
-from .correlation import CorrelationMiddleware
-from .profiler import ProfilerMiddleware
-
-
-__all__ = ["CorrelationMiddleware", "ProfilerMiddleware"]

neva/obs/middleware/correlation.py

@@ -1,68 +0,0 @@
-"""Correlation middleware."""
-
-import uuid
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from typing import Literal
-
-from starlette.datastructures import MutableHeaders
-from starlette.types import ASGIApp, Message, Receive, Scope, Send
-
-
-def is_valid_uuid(uuid_: str, version: Literal[1, 2, 3, 4] = 4) -> bool:
-    """Check if a string is a valid UUID.
-
-    Args:
-        uuid_: The string to check.
-        version: The UUID version to check.
-
-    Returns:
-        True if the string is a valid UUID, False otherwise.
-    """
-    try:
-        return uuid.UUID(uuid_).version == version
-    except ValueError:
-        return False
-
-
-CorrelationHeader = Literal["X-Request-ID", "X-Correlation-ID"]
-
-
-@dataclass
-class CorrelationMiddleware:
-    """Middleware to add a correlation ID to outgoing requests."""
-
-    app: ASGIApp
-
-    header_name: CorrelationHeader = "X-Request-ID"
-    generator: Callable[[], str] = field(default=lambda: uuid.uuid4().hex)
-    validator: Callable[[str], bool] = field(default=is_valid_uuid)
-
-    async def __call__(
-        self,
-        scope: Scope,
-        receive: Receive,
-        send: Send,
-    ) -> None:
-        """Middleware entry point."""
-        if scope["type"] not in ("http", "websocket"):
-            await self.app(scope, receive, send)
-            return
-
-        headers = MutableHeaders(scope=scope)
-        header_value = headers.get("X-Request-ID".lower()) or headers.get(
-            "X-Correlation-ID".lower()
-        )
-        if header_value is None or not self.validator(header_value):
-            header_value = self.generator()
-
-        scope["state"]["correlation_id"] = header_value
-
-        async def handle_outgoing_request(message: Message) -> None:
-            if message["type"] == "http.response.start":
-                headers = MutableHeaders(scope=message)
-                headers.append(self.header_name, header_value)
-            await send(message)
-
-        await self.app(scope, receive, handle_outgoing_request)
-        return

neva/obs/middleware/profiler.py

@@ -1,68 +0,0 @@
-"""Profiler middleware.
-
-This module provides the ProfilerMiddleware class, which wraps an ASGI
-application and profiles its execution. It generates a HTML report of the
-profiling data and writes it to a file.
-
-Uses the Pyinstrument library for profiling.
-"""
-
-from dataclasses import dataclass
-
-from pyinstrument import Profiler
-from pyinstrument.profiler import AsyncMode
-from starlette.types import ASGIApp, Receive, Scope, Send
-
-from neva.support import time
-
-
-@dataclass
-class ProfilerMiddleware:
-    """Middleware for profiling ASGI applications.
-
-    This middleware wraps an ASGI application and profiles its execution.
-    It generates a HTML report of the profiling data and writes it to a file.
-    """
-
-    app: ASGIApp
-
-    interval: float = 0.001
-    async_mode: AsyncMode = "enabled"
-    use_timing_thread: bool = False
-    path: str = "./profiles"
-
-    async def __call__(
-        self,
-        scope: Scope,
-        receive: Receive,
-        send: Send,
-    ) -> None:
-        """Wrap the application with profiling.
-
-        Args:
-            scope: The ASGI scope.
-            receive: The ASGI receive function.
-            send: The ASGI send function.
-        """
-        if scope["type"] != "http":
-            await self.app(scope, receive, send)
-            return
-        correlation_id = scope["state"].get("correlation_id", None)
-        filename = (
-            f"profile_{correlation_id}"
-            if correlation_id is not None
-            else f"profile_{time.utcnow_ts()}"
-        )
-        self.profiler = Profiler(
-            interval=self.interval,
-            async_mode=self.async_mode,
-            use_timing_thread=self.use_timing_thread,
-        )
-
-        self.profiler.start()
-        try:
-            await self.app(scope, receive, send)
-        finally:
-            _ = self.profiler.stop()
-            file_path = f"{self.path}/{filename}.html"
-            self.profiler.write_html(file_path)