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

{python_neva-5.1.0 → python_neva-5.4.0}/.gitignore

@@ -18,3 +18,4 @@ profiles/
 
 # LLM Contexts
 llm-context.md
+.claude/

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

@@ -1,3 +1,52 @@
+## 5.4.0 (2026-09-07)
+
+### ✨ Features
+
+- **config**: let a provider declare its config namespace and its secrets
+- **events**: let a listener opt in to running concurrently
+- **arch**: add Application.create returning a Result instead of raising
+- **support**: export StrategyResolver as the driver-manager base
+- **security**: register SecurityProvider as a base provider
+- **support**: add collect, partition and collect_async for many results
+- **support**: add ResultPipeline and OptionPipeline for async chaining
+
+### 🐛🚑️ Fixes
+
+- **support**: evaluate an attribute once in get_attr rather than twice
+- **events**: return Err from the default listener handle instead of None
+- **database**: stop reporting an absent database namespace as a failure
+- **security**: surface key loading failures as Err rather than raising
+
+### ♻️ Refactorings
+
+- **arch**: build the facade root error only when it is needed
+- **support**: split the results module into a package
+
+### ✅🤡🧪 Tests
+
+- **support**: cover falsy values and arbitrary iterables in collect
+- **guidelines**: pin the boost manifest and the fragment requires floor
+
+### 📝💡 Documentation
+
+- **guidelines**: document composing the shared app config namespace
+
+## 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.4.0}/PKG-INFO

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

{python_neva-5.1.0 → python_neva-5.4.0}/neva/arch/application.py

@@ -9,13 +9,15 @@ from pathlib import Path
 from typing import Any, Self
 
 import dishka
+import pydantic
 from dishka.provider import BaseProvider
+from typing_extensions import TypeForm
 
 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, Some
+from neva.support import Err, Ok, Result, Some, partition
 
 
 _current_container: ContextVar["dishka.AsyncContainer"] = ContextVar(
@@ -95,9 +97,32 @@ class Application:
         )
         _ = self.root_provider.provide(source=lambda: self, provides=Application)
         self.register_providers(providers)
+        self._apply_provider_config_declarations()
         self._bind_event_listeners()
         self.build_container()
 
+    @classmethod
+    def create(cls, config_path: str | Path | None = None) -> Result[Self, str]:
+        """Build an application, reporting a boot failure as a value.
+
+        The constructor raises, because a constructor cannot return a Result.
+        This is the same construction with the framework's own convention, and
+        is the form to prefer at a boundary that already handles Results.
+
+        Args:
+            config_path: Path to the configuration directory. Defaults to
+                ``$NEVA_CONFIG_PATH``, else ``./config`` relative to the
+                current working directory.
+
+        Returns:
+            Ok with the application, or Err with the reason it could not boot.
+
+        """
+        try:
+            return Ok(cls(config_path))
+        except RuntimeError as e:
+            return Err(str(e))
+
     @property
     def container(self) -> dishka.AsyncContainer:
         """The application container, built on first access.
@@ -161,6 +186,53 @@ class Application:
             self._container = None
         return registered
 
+    def _apply_provider_config_declarations(self) -> None:
+        """Validate declared config namespaces and mark declared secrets.
+
+        Runs once, over the providers registered during construction. A
+        namespace that is absent is skipped: not using a subsystem is not a
+        configuration error. Every failure is reported together, so a boot
+        naming three bad namespaces takes one run rather than three.
+
+        Raises:
+            RuntimeError: If any declared namespace fails its shape.
+        """
+        checks: list[Result[None, str]] = []
+        for provider in self.providers.values():
+            declaring = type(provider)
+            self.config.mark_sensitive(*declaring.sensitive)
+            checks.extend(
+                self._validate_namespace(namespace, schema)
+                for namespace, schema in declaring.config_schema.items()
+            )
+
+        _, failures = partition(checks)
+        if failures:
+            raise RuntimeError("Invalid configuration: " + "; ".join(failures))
+
+    def _validate_namespace(
+        self, namespace: str, schema: TypeForm[Any]
+    ) -> Result[None, str]:
+        """Check one config namespace against the shape a provider declared.
+
+        Returns:
+            Ok when the namespace is absent or valid, otherwise Err naming the
+            namespace and the first offending field path.
+        """
+        value = self.config.get(namespace)
+        if value.is_err:
+            return Ok(None)
+
+        try:
+            _ = pydantic.TypeAdapter(schema).validate_python(value.unwrap())
+        except pydantic.ValidationError as e:
+            paths = ", ".join(
+                ".".join(str(part) for part in error["loc"]) or "<root>"
+                for error in e.errors()
+            )
+            return Err(f"'{namespace}' is malformed ({paths})")
+        return Ok(None)
+
     def register_providers(self, providers: Sequence[type[ServiceProvider]]) -> None:
         """Registers a set of providers."""
         for provider in providers:

{python_neva-5.1.0 → python_neva-5.4.0}/neva/arch/facade.py

@@ -94,9 +94,11 @@ class FacadeMeta(ABCMeta):
         """
         return (
             cls._get_app()
-            .ok_or(
-                f"A facade root (App instance) has not been set for {cls.__name__}. "
-                "Call Facade.set_facade_application(app) first."
+            .ok_or_else(
+                lambda: (
+                    f"A facade root (App instance) has not been set for "
+                    f"{cls.__name__}. Call Facade.set_facade_application(app) first."
+                )
             )
             .and_then(
                 lambda x: cls._resolve_facade_instance(

{python_neva-5.1.0 → python_neva-5.4.0}/neva/arch/service_provider.py

@@ -20,6 +20,7 @@ from typing import (
 )
 
 import dishka
+from typing_extensions import TypeForm
 
 from neva.arch.markers import BaseMarker, Marker
 from neva.arch.scopes import BaseScope, Scope
@@ -66,12 +67,20 @@ class ServiceProvider(abc.ABC):
         listen: A mapping of event types to listener classes.  Listeners
             declared here are automatically bound into the container during
             registration and wired to the event dispatcher during boot.
+        config_schema: Config namespaces this provider owns, mapped to the
+            shape each must have. Validated once at boot; a namespace that
+            is absent is skipped, since an absent namespace means the app
+            does not use that subsystem.
+        sensitive: Dot-notated config keys holding secrets. Redacted by
+            `ConfigRepository.redacted()`, never by `get()`.
 
     """
 
     app: "Application"
     listen: ClassVar[dict[type[Event[Any]], list[type[EventListener[Any]]]]] = {}
     when: ClassVar[Marker | None] = None
+    config_schema: ClassVar[dict[str, TypeForm[Any]]] = {}
+    sensitive: ClassVar[tuple[str, ...]] = ()
 
     def __init__(self, app: "Application") -> None:
         """Initialize the service provider.

{python_neva-5.1.0 → python_neva-5.4.0}/neva/config/base_providers.py

@@ -1,25 +1,18 @@
 """Base service providers.
 
 This module defines the core providers that are automatically registered.
-These providers are essential for the framework
-to function properly.
 """
 
 from neva.arch import ServiceProvider
 from neva.database import DatabaseServiceProvider
 from neva.events.provider import EventServiceProvider
 from neva.obs import LogServiceProvider
+from neva.security import SecurityProvider
 
 
 def base_providers() -> list[type[ServiceProvider]]:
     """Return the list of base service providers.
 
-    These providers are automatically registered during application
-    initialization and provide core framework functionality.
-
-    Note: ConfigServiceProvider is registered separately in Application.__init__
-    to allow custom config_path configuration.
-
     Returns:
         Set of service provider classes to register.
 
@@ -28,4 +21,5 @@ def base_providers() -> list[type[ServiceProvider]]:
         LogServiceProvider,
         EventServiceProvider,
         DatabaseServiceProvider,
+        SecurityProvider,
     ]

{python_neva-5.1.0 → python_neva-5.4.0}/neva/config/repository.py

@@ -13,6 +13,9 @@ from typing_extensions import TypeForm
 from neva.support import Err, Ok, Result
 
 
+REDACTED = "********"
+
+
 class ConfigRepository:
     """Central repository for application configuration with dot notation support.
 
@@ -30,6 +33,7 @@ class ConfigRepository:
         """Initialize an empty configuration repository."""
         self._items: dict[str, Any] = {}
         self._frozen: bool = False
+        self._sensitive: set[str] = set()
 
     def set(self, key: str, value: object) -> Result[None, str]:
         """Set a configuration value using dot notation.
@@ -102,6 +106,48 @@ class ConfigRepository:
         """
         return self.get(key).is_ok
 
+    def mark_sensitive(self, *keys: str) -> None:
+        """Mark dot-notated keys as holding secrets.
+
+        Marking changes nothing about `get`, which always returns the real
+        value: a consumer asking for a secret by name wants the secret.
+
+        Args:
+            keys: Dot-notated key paths whose values must never be displayed.
+        """
+        self._sensitive.update(keys)
+
+    @property
+    def sensitive(self) -> frozenset[str]:
+        """The keys marked as holding secrets.
+
+        Returns:
+            Every marked dot-notated key path.
+        """
+        return frozenset(self._sensitive)
+
+    def redacted(self) -> dict[str, Any]:
+        """Every value, with the marked ones replaced by a placeholder.
+
+        This is the form to display — a config dump, a debug endpoint, a
+        console command. `all()` is unchanged and still returns real values.
+
+        Returns:
+            A deep copy in which every marked key reads ``********``.
+        """
+        items = copy.deepcopy(self._items)
+        for key in self._sensitive:
+            *parents, leaf = key.split(".")
+            current: Any = items
+            for parent in parents:
+                if not isinstance(current, dict) or parent not in current:
+                    break
+                current = current[parent]
+            else:
+                if isinstance(current, dict) and leaf in current:
+                    current[leaf] = REDACTED
+        return items
+
     def all(self) -> dict[str, Any]:
         """Get all configuration items as a dictionary.
 

{python_neva-5.1.0 → python_neva-5.4.0}/neva/database/provider.py

@@ -2,7 +2,9 @@
 
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
-from typing import Self, override
+from typing import Any, ClassVar, Self, override
+
+from typing_extensions import TypeForm
 
 from neva.arch import ServiceProvider
 from neva.database.config import ConnectionConfig, DatabaseConfig
@@ -15,6 +17,8 @@ from neva.support import Err, Ok, Result
 class DatabaseServiceProvider(ServiceProvider):
     """Database service provider."""
 
+    config_schema: ClassVar[dict[str, TypeForm[Any]]] = {"database": DatabaseConfig}
+
     @override
     def register(self) -> Result[Self, str]:
         _ = self.singleton(TransactionContext)
@@ -26,16 +30,19 @@ class DatabaseServiceProvider(ServiceProvider):
         """Initialize and cleanup database connections."""
         logger: LogManager = (await self.app.make_async(LogManager)).unwrap()
         db: DatabaseManager = (await self.app.make_async(DatabaseManager)).unwrap()
-        logger.info("Beginning SQLAlchemy initialization...")
         match self.app.config.get("database", type_=DatabaseConfig):
             case Ok(config):
+                logger.info("Beginning SQLAlchemy initialization...")
                 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.")
-            case Err(err):
-                logger.error(f"Failed to load database configuration: {err}")
+            case Err():
+                # An absent namespace means the app has no database, which is
+                # not a failure. `get` errs only on a missing key, so a
+                # malformed namespace never reaches here.
+                logger.debug("No database configuration; skipping initialization.")
 
         try:
             yield

{python_neva-5.1.0 → python_neva-5.4.0}/neva/events/dispatcher.py

@@ -1,5 +1,6 @@
 """Base implementation of the event dispatcher."""
 
+import asyncio
 import inspect
 from typing import override
 
@@ -11,6 +12,21 @@ from neva.events.event_registry import EventRegistry, flatten_listeners
 from neva.support import Err, Nothing, Result, Some
 
 
+def _runs_concurrently[T: contracts.Event](
+    listener_cls: type[contracts.EventListener[T]],
+) -> bool:
+    """Whether a listener has opted in to running alongside the others.
+
+    Read defensively: the opt-in lives on the concrete base class, not on the
+    protocol, so a listener implementing the protocol directly has no such
+    attribute and stays sequential.
+
+    Returns:
+        True when the listener declares itself concurrency-safe.
+    """
+    return getattr(listener_cls, "concurrent", False) is True
+
+
 class EventDispatcher(contracts.EventDispatcher):
     """Event dispatcher implementation."""
 
@@ -77,15 +93,44 @@ class EventDispatcher(contracts.EventDispatcher):
             case Nothing():
                 immediate.extend(d for d in deferred if d not in immediate)
 
-        for listener_cls in immediate:
+        sequential = [c for c in immediate if not _runs_concurrently(c)]
+        concurrent = [c for c in immediate if _runs_concurrently(c)]
+
+        for listener_cls in sequential:
             listener = self._resolve_listener(listener_cls)
-            try:
-                results.append(await listener.handle(event))
-            except Exception as e:
-                results.append(Err(f"Listener raised: {e}"))
+            results.append(await self._run(listener, event))
+
+        if concurrent:
+            # Resolved before the group, so a resolution failure propagates the
+            # way it always has rather than arriving wrapped in an ExceptionGroup.
+            listeners = [self._resolve_listener(c) for c in concurrent]
+            async with asyncio.TaskGroup() as group:
+                tasks = [
+                    group.create_task(self._run(listener, event))
+                    for listener in listeners
+                ]
+            results.extend(task.result() for task in tasks)
 
         return results
 
+    async def _run[T: contracts.Event](
+        self,
+        listener: contracts.EventListener[T],
+        event: T,
+    ) -> Result[None, str]:
+        """Run a resolved listener, turning a raise into an Err.
+
+        Resolution stays outside, because a listener that cannot be built is a
+        wiring bug rather than a handling failure, and has always propagated.
+
+        Returns:
+            The listener's result, or an Err describing what it raised.
+        """
+        try:
+            return await listener.handle(event)
+        except Exception as e:
+            return Err(f"Listener raised: {e}")
+
     @override
     def listen[T: contracts.Event](
         self,

{python_neva-5.1.0 → python_neva-5.4.0}/neva/events/listener.py

@@ -1,11 +1,11 @@
 """Event listener protocol."""
 
 from types import new_class
-from typing import Callable, override
+from typing import Callable, ClassVar, override
 
 from neva.events import contracts
 from neva.events.policy import HandlingPolicy
-from neva.support import Result
+from neva.support import Err, Result
 from neva.support.strconv import snake2pascal
 
 
@@ -13,9 +13,24 @@ class EventListener[T: contracts.Event](contracts.EventListener[T]):
     """Base event listener class."""
 
     policy: HandlingPolicy = HandlingPolicy.IMMEDIATE
+    concurrent: ClassVar[bool] = False
+    """Whether this listener may run alongside the others for one event."""
 
     @override
-    async def handle(self, event: T) -> Result[None, str]: ...
+    async def handle(self, event: T) -> Result[None, str]:
+        """Handle an event.
+
+        Subclasses override this. The default body handles nothing and says so,
+        rather than returning None where the contract promises a Result.
+
+        Returns:
+            An Err naming the listener that failed to implement handle.
+
+        """
+        return Err(
+            f"{type(self).__name__} does not implement handle(), "
+            f"so {type(event).__name__} was received and discarded."
+        )
 
 
 def listener[T: contracts.Event](

{python_neva-5.1.0 → python_neva-5.4.0}/neva/guidelines/fragments/configuration.md

@@ -4,7 +4,7 @@ title: Configuration
 requires: python-neva>=4.0
 triggers: [reading a config value, adding a config file, Config.get, config namespace, environment settings, providers list]
 priority: 50
-verified_by: [tests/config/test_repository.py, tests/config/test_loader.py, tests/config/test_config_path_resolution.py, tests/arch/test_config_shapes.py]
+verified_by: [tests/config/test_provider_declarations.py, tests/config/test_repository.py, tests/config/test_loader.py, tests/config/test_config_path_resolution.py, tests/arch/test_config_shapes.py]
 ---
 
 # Configuration
@@ -55,7 +55,32 @@ config: AppConfig = {"key": "...", "providers": [ActorServiceProvider]}
 `AppConfig` (`neva.arch`) covers `app.key`, `app.previous_keys`, `app.providers`, all optional.
 `ProviderConfig` (`neva.arch`) covers `providers.providers`. `DatabaseConfig`
 (`neva.database`) covers the `database` namespace, and its `connections` key is **required**.
-The `app` namespace is shared — an integration package declares the keys it adds.
+
+### The `app` namespace is shared — compose the shapes
+
+`app` is the one namespace several packages read at once. The core owns `key`, `previous_keys`
+and `providers`; every integration you install owns the keys it adds. A `TypedDict` is closed,
+so **no single package's shape can annotate a whole `config/app.py`**. Inherit from each one you
+install:
+
+```python
+from neva.arch import AppConfig
+from neva.<integration> import IntegrationAppConfig
+
+
+class ServiceAppConfig(IntegrationAppConfig, AppConfig): ...
+
+
+config: ServiceAppConfig = {"key": "...", "providers": [ActorServiceProvider]}
+```
+
+Annotating with one package's shape alone then rejects every key the others own — `AppConfig`
+rejects a title, an integration's shape rejects `providers`. That is the ownership rule working,
+not a defect in either shape; do not "fix" it by having one package's shape extend another's.
+
+**A key two packages both read is declared by both, with the same type.** Nothing enforces that:
+diverging types make the composed shape unannotatable, and no package can test it because none
+installs its siblings.
 
 ## Reading
 
@@ -72,11 +97,48 @@ Config.get("app.debug", type_=bool).unwrap_or(False)
 
 **`type_` is a cast, not validation.** Nothing is coerced or checked:
 `Config.get("app.debug", type_=bool)` over `debug = 0` returns the integer `0`, merely *typed*
-as `bool`. Parse or validate separately, and wrap consumed config in a typed object.
+as `bool`. Validate the namespace at boot instead — see below.
 
 `has(key) -> bool` is `get(key).is_ok`. `all() -> dict` returns a deep copy; mutating it never
 reaches the repository, frozen or not.
 
+## Validating a namespace at boot
+
+A provider declares the shape its namespace must have, and it is checked once during
+construction (since 5.4). The declaration reuses the `TypedDict` shapes above — nothing needs
+to become a pydantic model.
+
+```python
+class DatabaseServiceProvider(ServiceProvider):
+    config_schema: ClassVar[dict[str, TypeForm[Any]]] = {"database": DatabaseConfig}
+```
+
+- **An absent namespace is skipped, not rejected.** Not using a subsystem is not a
+  configuration error; a provider that genuinely requires its config errors in `lifespan`.
+- Every failure is reported together: `Invalid configuration: 'database' is malformed
+  (connections.default.url)`.
+- A provider that declares nothing is validated not at all — the behaviour before 5.4.
+- The constructor raises, as it does for any config failure; `Application.create()` returns it
+  as an `Err` instead.
+
+## Secrets
+
+A provider marks the keys that hold secrets, and they are replaced in the display form only.
+
+```python
+class SecurityProvider(ServiceProvider):
+    sensitive: ClassVar[tuple[str, ...]] = ("app.key", "app.previous_keys")
+```
+
+| Call | Marked key reads |
+| ---- | ---------------- |
+| `get("app.key")` | the real value — asking by name means you want it |
+| `all()` | the real value — unchanged from before 5.4 |
+| `redacted()` | `********` |
+
+Use `redacted()` for anything displayed: a config dump, a debug endpoint, a console command.
+`all()` deliberately did **not** change, so no existing caller sees different data on upgrade.
+
 ## Writing
 
 Mutable until frozen. This is the extension seam — a package registers defaults, an application

python_neva-5.4.0/neva/guidelines/fragments/drivers.md

@@ -0,0 +1,87 @@
+---
+id: drivers
+title: Swappable drivers
+requires: python-neva>=5.3
+triggers: [swappable backend, driver manager, multiple implementations, choosing an implementation from config, registering a driver, plugin extension point]
+priority: 70
+verified_by: [tests/support/test_strategy.py, tests/support/test_strategy_imports.py]
+---
+
+# Swappable drivers
+
+A subsystem with interchangeable backends — cache stores, storage disks, queue transports,
+hashers, log channels — subclasses `StrategyResolver`. **Never hand-roll a name-to-instance
+dict**: the caching, the default lookup and the error shape are already decided here.
+
+```python
+from neva.support import StrategyResolver          # since 5.4
+from neva.support.strategy import StrategyResolver  # any version
+```
+
+## The contract
+
+Subclass `StrategyResolver[T]` where `T` is the driver protocol, register factories in
+`__init__`, and implement `default()` reading the name from config.
+
+```python
+class CacheManager(StrategyResolver[Store]):
+    def __init__(self, app: Application) -> None:
+        super().__init__(app)
+        _ = self.register("memory", self._create_memory_store)
+        _ = self.register("redis", self._create_redis_store)
+
+    @override
+    def default(self) -> Option[str]:
+        return self.app.config.get("cache.driver", type_=str).ok()
+
+    def _create_memory_store(self, manager: StrategyResolver[Store]) -> MemoryStore:
+        return MemoryStore()
+```
+
+A factory takes the resolver, not the app — reach config through `manager.app.config`. That is
+what lets a plugin register a driver against a resolver it did not construct.
+
+## Resolving
+
+| Call | Does |
+| ---- | ---- |
+| `use()` | The default driver, created once and cached |
+| `use("redis")` | That driver, created once and cached |
+| `resolve(name)` | Builds a fresh instance, bypassing the cache |
+| `register(name, factory)` | Adds a factory; returns `self` for chaining |
+| `clear()` | Drops cached instances, keeps the factories |
+| `strategies` | The instances built so far |
+
+- `use` returns `Result[T, str]`. `Err` when no default is configured, when the name is
+  unregistered, or when the factory raised — the factory's exception is caught and becomes
+  `Err`, never propagates.
+- `use` caches per name; `resolve` does not. A driver holding a connection wants `use`.
+- `default()` returns `Option[str]`, so "no driver configured" is `Nothing`, not an exception.
+  Read it from config with `.ok()` on the `Result`.
+
+## Registering a driver from a plugin
+
+The resolver is a singleton in the container, so a provider's `register()` can add to it:
+
+```python
+class RedisCacheProvider(ServiceProvider):
+    def register(self) -> Result[Self, str]:
+        return self.app.make(CacheManager).map(
+            lambda cache: cache.register("redis", _create_redis_store)
+        ).map(lambda _: self)
+```
+
+## Rules
+
+- One resolver per subsystem, bound as a **singleton** — the instance cache lives on it, so a
+  transient resolver caches nothing.
+- The driver type `T` is a protocol, not a base class. Drivers are structural.
+- Do not raise from a factory to signal a bad configuration; it becomes an opaque
+  `Err(f"Registered strategy '{name}' creation failed: {e}")`. Validate before constructing.
+- `set_container(app)` exists for tests and re-binding. Ordinary code never calls it.
+
+## Worked examples in the core
+
+`HashManager` (`neva/security/hashing/hash_manager.py`) resolves `argon2` / `bcrypt` from
+`hashing.driver`. `ChannelResolver` (`neva/obs/logging/resolver.py`) resolves log channels.
+Copy either; they are the same shape.