python-neva 3.5.1__tar.gz → 3.6.0__tar.gz

python_neva-3.6.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pyrefly
+        name: Pyrefly (type checking)
+        entry: uv run pyrefly check
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: false
+        require_serial: true

{python_neva-3.5.1 → python_neva-3.6.0}/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 3.6.0 (2026-08-28)
+
+### ✨ Features
+
+- **arch**: name the binding lifetimes, deprecate the implicit one
+- **security**: add make_async and check_async
+- **arch**: expose the container backing the current scope
+
+### 🐛🚑️ Fixes
+
+- **events**: dispatch once per registration, and defer to the outermost transaction
+- **config**: make freeze() actually freeze and merge() recursive
+- **config**: stop config files from displacing real modules
+- **arch**: run lifespan teardown even when the body raises
+- **security**: stop requiring the optional hasher tuning config
+- **arch**: make register() bind, or say why it cannot
+- **database**: keep the transaction when the registry contextvar is unset
+
+### 📝💡 Documentation
+
+- **general**: correct the Config stub, a lying docstring and a wrong annotation
+
+### 🔧🔨📦️ Configuration, Scripts, Packages
+
+- **tooling**: replace mypy with pyrefly at strict
+
 ## 3.5.1 (2026-08-24)
 
 ### 🐛🚑️ Fixes

{python_neva-3.5.1 → python_neva-3.6.0}/CLAUDE.md

@@ -18,7 +18,7 @@ ecosystem is listed in `README.md`.
 
 **Python Version:** 3.12+
 **Build System:** uv + hatchling
-**Type checker:** mypy (with the `pydantic.mypy` plugin and the `TypeForm` incomplete feature)
+**Type checker:** pyrefly (`preset = "strict"`, configured in `[tool.pyrefly]`)
 
 ## Commands
 
@@ -26,7 +26,7 @@ ecosystem is listed in `README.md`.
 # Development (poe task aliases)
 poe lint              # ruff check
 poe fmt               # ruff format
-poe tc                # mypy .
+poe tc                # pyrefly check
 poe test              # pytest
 poe test-cov          # tests with coverage (--cov-report=term-missing)
 poe test-full         # coverage over the neva package
@@ -72,11 +72,14 @@ config = Config.get("app.name").unwrap_or("MyApp")
 await Event.dispatch(UserCreated(event_id=1, user_id=42))
 ```
 
-**Service Providers** - Register services with lifecycle hooks:
+**Service Providers** - Register services with lifecycle hooks. Bindings
+declare a lifetime by name — `singleton` (one per process), `scoped` (one per
+REQUEST scope), `transient` (one per resolution), `instance` (an object you
+already have). Bare `bind` without an explicit `scope`/`cache` is deprecated:
 ```python
 class MyProvider(ServiceProvider):
     def register(self) -> Result[Self, str]:
-        self.bind(MyService)
+        _ = self.singleton(MyService)
         return Ok(self)
 
     @asynccontextmanager

{python_neva-3.5.1 → python_neva-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 3.5.1
+Version: 3.6.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
@@ -58,7 +58,7 @@ independent repo, independently versioned and published.
 uv sync          # install/refresh deps from uv.lock
 poe lint         # ruff check
 poe fmt          # ruff format
-poe tc           # type-check (mypy)
+poe tc           # type-check (pyrefly)
 poe test         # pytest
 poe test-cov     # tests with coverage
 

{python_neva-3.5.1 → python_neva-3.6.0}/README.md

@@ -34,7 +34,7 @@ independent repo, independently versioned and published.
 uv sync          # install/refresh deps from uv.lock
 poe lint         # ruff check
 poe fmt          # ruff format
-poe tc           # type-check (mypy)
+poe tc           # type-check (pyrefly)
 poe test         # pytest
 poe test-cov     # tests with coverage
 

{python_neva-3.5.1 → python_neva-3.6.0}/neva/arch/application.py

@@ -43,6 +43,9 @@ class Application:
         self.config: ConfigRepository = ConfigRepository()
         self.providers: OrderedDict[type, ServiceProvider] = OrderedDict()
         self.root_provider: dishka.Provider = dishka.Provider(scope=Scope.APP)
+        self._extra_providers: list[BaseProvider] = []
+        self._container: dishka.AsyncContainer | None = None
+        self._booted: bool = False
 
         configuration_path = (
             config_path
@@ -77,30 +80,70 @@ class Application:
         _ = self.root_provider.provide(source=lambda: self, provides=Application)
         self.register_providers(providers)
         self._bind_event_listeners()
-        self.build_container(self.root_provider)
+        self.build_container()
 
-    def build_container(self, *providers: BaseProvider) -> None:
-        """Build the application container."""
-        self.container: dishka.AsyncContainer = dishka.make_async_container(
+    @property
+    def container(self) -> dishka.AsyncContainer:
+        """The application container, built on first access.
+
+        Registering a provider discards the built container so the next access
+        rebuilds the graph with that provider's bindings in it.
+
+        Returns:
+            The application container.
+        """
+        if self._container is not None:
+            return self._container
+        return self.build_container()
+
+    def build_container(self, *providers: BaseProvider) -> dishka.AsyncContainer:
+        """Build the application container.
+
+        Args:
+            providers: Extra dishka providers to compose into the graph. They
+                are remembered, so a later rebuild keeps them.
+
+        Returns:
+            The freshly built container.
+        """
+        self._extra_providers.extend(providers)
+        self._container = dishka.make_async_container(
             self.root_provider,
             *[p.provider for p in self.providers.values()],
-            *providers,
+            *self._extra_providers,
         )
+        return self._container
 
     def register(self, provider: type[ServiceProvider]) -> Result[ServiceProvider, str]:
         """Registers a service provider with the application.
 
+        Providers must be registered before the application boots: dishka
+        validates the dependency graph when the container is built, and the
+        booted container already holds APP-scoped instances that a rebuild
+        would orphan. Registering after boot is an error rather than a
+        silently ignored call.
+
         Returns:
             Result containing the registered provider instance or an error message.
         """
         if provider in self.providers:
             return Ok(self.providers[provider])
 
-        return (
+        if self._booted:
+            return Err(
+                f"Cannot register '{provider.__name__}': the application is "
+                "already booted. Register providers before entering lifespan(), "
+                "or declare them in the 'providers' config namespace."
+            )
+
+        registered = (
             provider(self)
             .register()
             .map(lambda p: self.providers.setdefault(provider, p))
         )
+        if registered.is_ok:
+            self._container = None
+        return registered
 
     def register_providers(self, providers: Sequence[type[ServiceProvider]]) -> None:
         """Registers a set of providers."""
@@ -122,15 +165,28 @@ class Application:
             provides=interface,
         )
 
+    @property
+    def current_container(self) -> dishka.AsyncContainer:
+        """The container backing resolution in the current context.
+
+        Inside ``scope()`` this is the child container for that scope; outside
+        it, the application container. Integrations that hand a container to
+        another framework — a request-scoped container to a route layer, say —
+        want this one, not ``container``.
+
+        Returns:
+            The innermost container entered in this context.
+        """
+        return _current_container.get(self.container)
+
     async def make_async[T](self, interface: type[T]) -> Result[T, str]:
         """Resolve and instanciate a type from the container.
 
         Returns:
             Result containing the resolved type instance or an error message.
         """
-        container = _current_container.get(self.container)
         try:
-            return Ok(await container.get(interface))
+            return Ok(await self.current_container.get(interface))
         except Exception as e:
             return Err(f"Failed to resolve service '{interface.__name__}': {e}")
 
@@ -140,7 +196,7 @@ class Application:
         Returns:
             Result containing the resolved type instance or an error message.
         """
-        container = _current_container.get(self.container)
+        container = self.current_container
         try:
             return Ok(container.get_sync(interface))
         except Exception as e:
@@ -154,11 +210,13 @@ class Application:
     ) -> AsyncGenerator[Self]:
         """Enter a new scope.
 
+        The application is yielded, not the child container; read
+        ``current_container`` inside the block to reach it.
+
         Yields:
             The application instance with the new scope.
         """
-        parent = _current_container.get(self.container)
-        async with parent(scope=scope, context=context) as container:
+        async with self.current_container(scope=scope, context=context) as container:
             token = _current_container.set(container)
             try:
                 yield self
@@ -169,24 +227,32 @@ class Application:
     async def lifespan(self) -> AsyncGenerator[None]:
         """Wire the facades and providers."""
         Facade.set_facade_application(self)
+        self._booted = True
 
-        async with AsyncExitStack() as stack:
-            for provider in self.providers.values():
-                if isinstance(provider, Bootable):
-                    await stack.enter_async_context(provider.lifespan())
-
-            await self._wire_event_listeners()
-            yield
-
-        await self.container.close()
-        Facade.reset_facade_application()
+        try:
+            async with AsyncExitStack() as stack:
+                for provider in self.providers.values():
+                    if isinstance(provider, Bootable):
+                        await stack.enter_async_context(provider.lifespan())
+
+                await self._wire_event_listeners()
+                yield
+        finally:
+            # Read `_container` rather than the property: the container may
+            # never have been built, and closing is no reason to build one.
+            if self._container is not None:
+                await self._container.close()
+            self._booted = False
+            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:
-                    self.bind(listener_cls)
+                    # Straight onto the root provider: routing this through the
+                    # deprecated `bind` warned on every boot.
+                    _ = 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."""

{python_neva-3.5.1 → python_neva-3.6.0}/neva/arch/config.py

@@ -24,7 +24,7 @@ class AppConfig(TypedDict):
     openapi_url: NotRequired[str]
     docs_url: NotRequired[str]
     redoc_url: NotRequired[str]
-    providers: NotRequired[list[ServiceProvider]]
+    providers: NotRequired[list[type[ServiceProvider]]]
 
 
 class ProviderConfig(TypedDict):
@@ -34,4 +34,4 @@ class ProviderConfig(TypedDict):
         providers: List of service providers to register.
     """
 
-    providers: NotRequired[list[ServiceProvider]]
+    providers: NotRequired[list[type[ServiceProvider]]]

{python_neva-3.5.1 → python_neva-3.6.0}/neva/arch/scopes.py

@@ -2,4 +2,3 @@ from dishka.entities.scope import BaseScope, Scope
 
 
 __all__ = ["BaseScope", "Scope"]
-

{python_neva-3.5.1 → python_neva-3.6.0}/neva/arch/service_provider.py

@@ -8,6 +8,7 @@ container and optionally managing their lifecycle.
 from __future__ import annotations
 
 import abc
+import warnings
 from contextlib import AbstractAsyncContextManager
 from typing import (
     TYPE_CHECKING,
@@ -70,7 +71,7 @@ class ServiceProvider(abc.ABC):
     """
 
     app: "Application"
-    listen: ClassVar[dict[type[Event], list[type[EventListener[Any]]]]] = {}
+    listen: ClassVar[dict[type[Event[Any]], list[type[EventListener[Any]]]]] = {}
     when: ClassVar[Marker | None] = None
 
     def __init__(self, app: "Application") -> None:
@@ -106,17 +107,91 @@ class ServiceProvider(abc.ABC):
         interface: type | None = None,
         scope: BaseScope | None = None,
         when: BaseMarker | None = None,
-        cache: bool = True,
+        cache: bool | None = None,
     ) -> None:
-        """Binds a source to the container."""
+        """Binds a source to the container.
+
+        Prefer the named lifetimes — `singleton`, `scoped`, `transient`,
+        `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.
+
+        Args:
+            source: The class or factory to bind.
+            interface: The type to resolve it as. Defaults to `source`.
+            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.
+        """
+        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,
+            )
+
         _ = self.provider.provide(
             source=source,
             scope=scope,
             provides=interface,
-            cache=cache,
+            cache=True if cache is None else cache,
             when=when,
         )
 
+    def singleton(
+        self,
+        source: type | Callable[..., Any],
+        *,
+        interface: type | None = None,
+        when: BaseMarker | None = None,
+    ) -> Self:
+        """Binds the source at APP scope, as one instance for the process.
+
+        This is what a bare `bind` has always done; naming it makes the
+        lifetime visible at the call site.
+
+        Returns:
+            the provider itself for chaining purposes
+        """
+        self.bind(source, interface=interface, scope=Scope.APP, when=when, cache=True)
+        return self
+
+    def instance(
+        self,
+        value: object,
+        *,
+        interface: type | None = None,
+        when: BaseMarker | None = None,
+    ) -> Self:
+        """Binds an object that already exists.
+
+        Nothing is constructed: the value handed in is what every resolution
+        returns. Use it for configuration objects, clients built during boot,
+        and test doubles.
+
+        Args:
+            value: The object to hand out.
+            interface: The type to resolve it as. Defaults to `type(value)`.
+            when: Marker gating this binding.
+
+        Returns:
+            the provider itself for chaining purposes
+        """
+        self.bind(
+            lambda: value,
+            interface=interface if interface is not None else type(value),
+            scope=Scope.APP,
+            when=when,
+            cache=True,
+        )
+        return self
+
     def scoped(
         self,
         source: type | Callable[..., Any],
@@ -124,10 +199,10 @@ class ServiceProvider(abc.ABC):
         interface: type | None = None,
         when: BaseMarker | None = None,
     ) -> Self:
-        """Binds the source to the container.
+        """Binds the source at REQUEST scope.
 
-        Scope is REQUEST by default but a custom scope be provided.
-        Dependency declared with this are cached no matter what.
+        One instance is created per request scope and cached for its duration.
+        For any other scope, call `bind` with an explicit `scope`.
 
         Returns:
             the provider itself for chaining purposes

{python_neva-3.5.1 → python_neva-3.6.0}/neva/config/loader.py

@@ -14,6 +14,11 @@ from neva.support import Err, Ok, Option, Result
 from neva.support.accessors import get_attr
 
 
+# Deliberately not "neva.config": a config file named repository.py or
+# loader.py would otherwise displace the real module of that name.
+_CONFIG_MODULE_NAMESPACE = "neva._app_config"
+
+
 class ConfigLoader:
     """Loads configuration files from a directory.
 
@@ -90,15 +95,22 @@ class ConfigLoader:
         """
         try:
             spec = importlib.util.spec_from_file_location(
-                f"neva.config.{module_name}", file_path
+                f"{_CONFIG_MODULE_NAMESPACE}.{module_name}", file_path
             )
 
             if spec is None or spec.loader is None:
                 return Err(f"Could not load module spec for {file_path}")
 
             module = importlib.util.module_from_spec(spec)
+            # Registered so dataclasses, pickle and typing lookups inside the
+            # config file can resolve it, then removed: these are data files,
+            # not importable modules, and leaving them in place would let a
+            # second config directory shadow the first.
             sys.modules[spec.name] = module
-            spec.loader.exec_module(module)
+            try:
+                spec.loader.exec_module(module)
+            finally:
+                _ = sys.modules.pop(spec.name, None)
 
             config_dict = self._extract_config(module)
             return Ok(config_dict)

{python_neva-3.5.1 → python_neva-3.6.0}/neva/config/repository.py

@@ -5,6 +5,7 @@ store for all application configuration values. It supports dot notation for
 nested access and can be frozen to prevent modifications after initialization.
 """
 
+import copy
 from typing import Any, cast
 
 from typing_extensions import TypeForm
@@ -105,10 +106,11 @@ class ConfigRepository:
         """Get all configuration items as a dictionary.
 
         Returns:
-            A copy of the entire configuration dictionary.
+            A deep copy of the entire configuration dictionary. Mutating it
+            never reaches the repository, frozen or not.
 
         """
-        return self._items.copy()
+        return copy.deepcopy(self._items)
 
     def freeze(self) -> None:
         """Freeze the configuration to prevent further changes.
@@ -130,8 +132,10 @@ class ConfigRepository:
     def merge(self, key: str, items: dict[str, Any]) -> Result[None, str]:
         """Merge items into a configuration namespace.
 
-        Updates the dictionary at the given key with the provided items.
-        Creates the namespace if it doesn't exist.
+        Merges recursively: nested dictionaries are combined rather than
+        replaced, so a package can register defaults and an application can
+        override individual leaves without restating the whole namespace.
+        Non-dict values are replaced outright.
 
         Args:
             key: The namespace key to merge into.
@@ -153,5 +157,20 @@ class ConfigRepository:
                 f"existing value is {type(self._items[key]).__name__}, not dict"
             )
 
-        self._items[key].update(items)
+        _deep_merge(self._items[key], items)
         return Ok(None)
+
+
+def _deep_merge(target: dict[str, Any], source: dict[str, Any]) -> None:
+    """Merge source into target in place, recursing into nested dictionaries.
+
+    Args:
+        target: The dictionary to merge into. Modified in place.
+        source: The dictionary to read from.
+    """
+    for key, value in source.items():
+        existing = target.get(key)
+        if isinstance(existing, dict) and isinstance(value, dict):
+            _deep_merge(existing, value)
+        else:
+            target[key] = value

{python_neva-3.5.1 → python_neva-3.6.0}/neva/database/connection.py

@@ -63,6 +63,20 @@ class TransactionContext:
             return Some(registry.stack[-1])
         return Nothing()
 
+    def outermost(self) -> Option[BoundTransaction]:
+        """Get the outermost open transaction, across all connections.
+
+        This is the last one to commit, so work that must not outlive *any*
+        open transaction — a deferred event listener — belongs on it.
+
+        Returns:
+            The outermost transaction, if any.
+        """
+        registry = _tx_registry.get()
+        if registry is None or not registry.stack:
+            return Nothing()
+        return Some(registry.stack[0])
+
 
 @final
 class ConnectionManager:
@@ -97,15 +111,17 @@ class ConnectionManager:
     async def _scoped(self, tx: BoundTransaction) -> AsyncIterator[None]:
         """Expose the transaction on the registry for the duration of the block.
 
+        The registry may be unset in the current context: ``TransactionContext``
+        seeds it when it is constructed, and a task that did not inherit that
+        context — an ASGI request, when the lifespan ran on its own task — sees
+        the ``None`` default. Seed a fresh registry in that case, but still put
+        the transaction in it.
+
         Yields:
             None
         """
-        old_registry = _tx_registry.get()
-        token = (
-            _tx_registry.set(old_registry.extend(tx))
-            if old_registry is not None
-            else _tx_registry.set(TransactionRegistry())
-        )
+        old_registry = _tx_registry.get() or TransactionRegistry()
+        token = _tx_registry.set(old_registry.extend(tx))
         try:
             yield
         finally:

{python_neva-3.5.1 → python_neva-3.6.0}/neva/database/manager.py

@@ -68,6 +68,17 @@ class DatabaseManager:
         """
         return self._tx_context.current(connection)
 
+    def outermost(self) -> Option[BoundTransaction]:
+        """Returns the outermost open transaction, across all connections.
+
+        Unlike `current`, which returns the most recently opened transaction,
+        this returns the one that commits last.
+
+        Returns:
+            The outermost transaction, if any.
+        """
+        return self._tx_context.outermost()
+
     def session(self, connection: str | None = None) -> Option[asyncio.AsyncSession]:
         """Returns the current session for a connection.
 

{python_neva-3.5.1 → python_neva-3.6.0}/neva/database/provider.py

@@ -17,8 +17,8 @@ class DatabaseServiceProvider(ServiceProvider):
 
     @override
     def register(self) -> Result[Self, str]:
-        self.bind(TransactionContext)
-        self.bind(DatabaseManager)
+        _ = self.singleton(TransactionContext)
+        _ = self.singleton(DatabaseManager)
         return Ok(self)
 
     @asynccontextmanager
@@ -29,13 +29,15 @@ class DatabaseServiceProvider(ServiceProvider):
         logger.info("Beginning SQLAlchemy initialization...")
         match self.app.config.get("database", type_=DatabaseConfig):
             case Ok(config):
-                connections: dict[str, ConnectionConfig] = config["connections"]
+                connections: dict[str, ConnectionConfig] = config.get("connections", {})
                 for name, conn_config in connections.items():
                     db.register_connection(name, conn_config)
                     logger.info(f"Registered engine for connection '{name}'.")
                 logger.info("SQLAlchemy initialization complete.")
-                yield
-                await db.close()
             case Err(err):
                 logger.error(f"Failed to load database configuration: {err}")
-                yield
+
+        try:
+            yield
+        finally:
+            await db.close()

{python_neva-3.5.1 → python_neva-3.6.0}/neva/database/transaction.py

@@ -1,6 +1,5 @@
 """Transaction management systems."""
 
-import abc
 import asyncio
 from collections.abc import Awaitable
 from dataclasses import dataclass, field
@@ -24,7 +23,7 @@ class TransactionState(Enum):
 
 
 @dataclass
-class Transaction(abc.ABC):
+class Transaction:
     """Represents a database transaction with callback support."""
 
     conn_name: str

{python_neva-3.5.1 → python_neva-3.6.0}/neva/events/contracts/__init__.py

@@ -1,3 +1,5 @@
+"""Protocols describing the event system's public contracts."""
+
 from neva.events.contracts.dispatcher import (
     AsyncBeforeDispatchHook,
     BeforeDispatchHook,