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

python_neva-3.7.0/.gitlab-ci.yml

@@ -0,0 +1,79 @@
+---
+variables:
+  PYTHON_VERSION: "3.12"
+  UV_VERSION: "0.9.28"
+  BASE_LAYER: bookworm-slim
+  UV_LINK_MODE: copy
+  UV_CACHE_DIR: .cache/uv
+
+stages:
+  - code_qa
+  - test
+  - deps
+
+##### Deps #####
+.uv_base:
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  cache:
+    key:
+      files:
+        - uv.lock
+    paths:
+      - .cache/uv
+      - .venv
+  before_script:
+    - uv sync --frozen --all-extras
+
+.default_rules:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+
+##### Code QA #####
+ruff:lint:
+  extends: [.uv_base, .default_rules]
+  stage: code_qa
+  script:
+    - uv run --frozen ruff check .
+
+ruff:format:
+  extends: [.uv_base, .default_rules]
+  stage: code_qa
+  script:
+    - uv run --frozen ruff format --check .
+
+pyrefly:
+  extends: [.uv_base, .default_rules]
+  stage: code_qa
+  script:
+    - uv run --frozen pyrefly check
+
+##### Test #####
+pytest:
+  extends: [.uv_base, .default_rules]
+  stage: test
+  script:
+    - uv run --frozen pytest
+
+##### Deps contract #####
+# Resolves every direct dependency at its declared floor, so a `>=` lower than
+# what the code needs fails here instead of in a user's install. Three things
+# keep this job honest, and dropping any one makes it pass without testing
+# anything: it must not extend .uv_base, whose before_script installs the
+# committed lock; --upgrade discards that lock as a preference set, without
+# which uv reuses it and lowers nothing; --frozen on sync and run stops uv
+# re-resolving at the default highest strategy and discarding the floors it
+# just computed. Rewriting uv.lock here is expected and must never be
+# committed.
+deps:floors:
+  extends: .default_rules
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  stage: deps
+  cache:
+    key: floors
+    paths:
+      - .cache/uv
+  script:
+    - uv lock --upgrade --resolution lowest-direct
+    - uv sync --frozen --all-extras
+    - uv run --frozen pytest

python_neva-3.7.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.16.5
+    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.7.0/CHANGELOG.md

@@ -0,0 +1,92 @@
+## 3.7.0 (2026-08-28)
+
+### ✨ Features
+
+- **deps**: require only what the core imports
+
+### 🐛🚑️ Fixes
+
+- **deps**: declare starlette directly
+
+### 💚👷 CI & Build
+
+- add the pipeline with a lowest-direct floors gate
+
+### 📌➕⬇️➖⬆️ Dependencies
+
+- upgrade all dependencies and adapt to ruff 0.16
+
+## 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
+
+- **database**: run commit callbacks after the commit, not before
+
+### 📝💡 Documentation
+
+- **general**: update docs
+- **README**: very short section on contribution
+- **docs**: extension ideas
+
+## 3.5.0 (2026-06-11)
+
+### ✨ Features
+
+- **arch**: improve app facade stub
+- **events**: make the event facade properly depend on the dispatcher contract
+- **events**: new tests for events
+
+### 🐛🚑️ Fixes
+
+- **events**: fixing handling of async before-dispatch hooks
+
+### 🏷️ Types
+
+- **events**: improve event facade stub
+
+## 3.4.0 (2026-06-10)
+
+### ✨ Features
+
+- **arch**: new from_context method
+- **tooling**: placeholder commit
+
+### 💚👷 CI & Build
+
+- **tooling**: default to base tag version for commitizen
+
+### 📝💡 Documentation
+
+- **project**: update doc
+- **core**: placeholde readme
+
+### 🔧🔨📦️ Configuration, Scripts, Packages
+
+- **tooling**: update changelog script
+- **project**: update versioning config

{python_neva-3.5.1 → python_neva-3.7.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.7.0}/PKG-INFO

@@ -1,22 +1,26 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 3.5.1
+Version: 3.7.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: asyncpg>=0.30.0
 Requires-Dist: cryptography>=46.0.3
 Requires-Dist: dishka>=1.10.0
-Requires-Dist: fastapi[all]>=0.129.0
-Requires-Dist: faststream>=0.6.6
 Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.62b0
 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: typer>=0.21.1
+Requires-Dist: typing-extensions>=4.13
 Provides-Extra: fastapi
-Requires-Dist: neva-fastapi>=1.0.0; extra == 'fastapi'
+Requires-Dist: neva-fastapi>=1.1.1; extra == 'fastapi'
+Provides-Extra: faststream
+Requires-Dist: faststream>=0.6.6; extra == 'faststream'
+Provides-Extra: polyfactory
+Requires-Dist: polyfactory>=3.1.0; extra == 'polyfactory'
 Provides-Extra: testing
 Requires-Dist: pytest-asyncio>=0.25.3; extra == 'testing'
 Requires-Dist: pytest>=9.0.2; extra == 'testing'
@@ -58,7 +62,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.7.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.7.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.7.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.7.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.7.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.7.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)