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

{python_neva-5.3.0 → python_neva-5.4.1}/.gitignore

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

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

@@ -1,3 +1,43 @@
+## 5.4.1 (2026-09-09)
+
+### 🐛🚑️ Fixes
+
+- **config**: apply provider declarations on a late registration
+- **guidelines**: render the drivers fragment for apps below 5.3
+
+## 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

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

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

{python_neva-5.3.0 → python_neva-5.4.1}/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(
@@ -66,6 +68,7 @@ class Application:
         self._extra_providers: list[BaseProvider] = []
         self._container: dishka.AsyncContainer | None = None
         self._booted: bool = False
+        self._declarations_applied: bool = False
 
         configuration_path = _resolve_config_path(config_path)
         match ConfigLoader(configuration_path).load_all():
@@ -95,9 +98,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.
@@ -139,6 +165,15 @@ class Application:
         would orphan. Registering after boot is an error rather than a
         silently ignored call.
 
+        A provider arriving after construction has its declared config
+        namespaces validated here, and its secrets marked once it registers, so
+        that it is held to the same shape as one named in the `providers`
+        config namespace. Validation runs before the provider is instantiated:
+        a malformed namespace leaves nothing registered and no secret marked.
+        Providers registered *during* construction are skipped here and
+        validated together by `_apply_provider_config_declarations`, which
+        reports every bad namespace in one message.
+
         Returns:
             Result containing the registered provider instance or an error message.
         """
@@ -152,15 +187,85 @@ class Application:
                 "or declare them in the 'providers' config namespace."
             )
 
+        late = self._declarations_applied
+        if late and (failures := self._declaration_failures(provider)):
+            return Err("Invalid configuration: " + "; ".join(failures))
+
         registered = (
             provider(self)
             .register()
             .map(lambda p: self.providers.setdefault(provider, p))
         )
         if registered.is_ok:
+            if late:
+                self.config.mark_sensitive(*provider.sensitive)
             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.
+
+        Providers registered after this point go through `register`, which
+        applies the same declarations one provider at a time.
+
+        Raises:
+            RuntimeError: If any declared namespace fails its shape.
+        """
+        failures: list[str] = []
+        for provider in self.providers.values():
+            declaring = type(provider)
+            self.config.mark_sensitive(*declaring.sensitive)
+            failures.extend(self._declaration_failures(declaring))
+
+        if failures:
+            raise RuntimeError("Invalid configuration: " + "; ".join(failures))
+
+        self._declarations_applied = True
+
+    def _declaration_failures(self, declaring: type[ServiceProvider]) -> list[str]:
+        """Check one provider's declared namespaces, applying nothing.
+
+        Args:
+            declaring: The provider type whose `config_schema` to check.
+
+        Returns:
+            One message per malformed namespace, empty when every declared
+            namespace is absent or valid.
+        """
+        _, failures = partition(
+            self._validate_namespace(namespace, schema)
+            for namespace, schema in declaring.config_schema.items()
+        )
+        return 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.3.0 → python_neva-5.4.1}/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.3.0 → python_neva-5.4.1}/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.3.0 → python_neva-5.4.1}/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.3.0 → python_neva-5.4.1}/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.3.0 → python_neva-5.4.1}/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.3.0 → python_neva-5.4.1}/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.3.0 → python_neva-5.4.1}/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.3.0 → python_neva-5.4.1}/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,59 @@ 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 at boot (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.
+- **A provider registered after construction is checked too, and reports as an `Err` from
+  `Application.register` rather than raising** (since 5.4.1). That is the path
+  `App.register` on `neva-fastapi` and `neva-faststream` delegates to; before 5.4.1 it skipped
+  validation and marked no secrets. A rejected provider is not registered at all.
+
+**`type_` is a cast, not validation, so the value a malformed key holds is still whatever the
+file put there.** Validation only *rejects* it — nothing is coerced and written back, and
+pydantic's default lax mode accepts `"false"` for a `bool`. A namespace whose values must be
+exactly typed declares `__pydantic_config__ = ConfigDict(strict=True)` on its `TypedDict`.
+
+## Secrets
+
+A provider marks the keys that hold secrets, and they are replaced in the display form only.
+Marking happens wherever the provider is registered — at construction, or through
+`Application.register` (since 5.4.1).
+
+```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