python-neva 0.6.0.dev4__tar.gz → 1.0.0__tar.gz

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/.pre-commit-config.yaml

@@ -1,4 +1,9 @@
 repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.24.2
+    hooks:
+      - id: gitleaks
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: python-neva
-Version: 0.6.0.dev4
+Version: 1.0.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: cryptography>=46.0.3
 Requires-Dist: dishka>=1.7.2
 Requires-Dist: fastapi[all]>=0.124.0
+Requires-Dist: faststream>=0.6.6
 Requires-Dist: flexmock>=0.13.0
 Requires-Dist: pwdlib[argon2,bcrypt]>=0.3.0
 Requires-Dist: pyinstrument>=5.1.1

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/neva/__init__.py

@@ -11,6 +11,7 @@ from neva.support import (
     from_optional,
 )
 
+
 __all__ = [
     "Err",
     "Nothing",

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/neva/arch/__init__.py

@@ -12,6 +12,7 @@ from neva.arch.service_provider import (
     ServiceProvider,
 )
 
+
 __all__ = [
     "App",
     "Application",

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/neva/arch/application.py

@@ -1,8 +1,8 @@
 """Base application for DI and facade injection."""
 
+import os
 from collections.abc import AsyncIterator, Iterator
 from contextlib import AsyncExitStack, asynccontextmanager, contextmanager
-import os
 from pathlib import Path
 from typing import Any, Callable, Self
 
@@ -10,8 +10,8 @@ import dishka
 from dishka.integrations.fastapi import FastapiProvider
 
 from neva import Err, Ok, Result
-from neva.arch.service_provider import Bootable, ServiceProvider
 from neva.arch.facade import Facade
+from neva.arch.service_provider import Bootable, ServiceProvider
 
 
 class Application:
@@ -27,9 +27,9 @@ class Application:
         Raises:
             RuntimeError: If the application fails to initialize.
         """
-        from neva.config.repository import ConfigRepository
-        from neva.config.provider import ConfigServiceProvider
         from neva.config.base_providers import base_providers
+        from neva.config.provider import ConfigServiceProvider
+        from neva.config.repository import ConfigRepository
 
         self.providers: dict[type, ServiceProvider] = {}
         self.di_provider: dishka.Provider = dishka.Provider(scope=dishka.Scope.APP)
@@ -65,6 +65,7 @@ class Application:
             case Err(e):
                 raise RuntimeError(f"Failed to load configuration during boot: {e}")
 
+        self._bind_event_listeners()
         self.container = dishka.make_container(self.di_provider)
 
     def bind_to_fastapi(self) -> None:
@@ -141,6 +142,28 @@ class Application:
                 if isinstance(provider, Bootable):
                     await stack.enter_async_context(provider.lifespan())
 
+            self._wire_event_listeners()
             yield
 
         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)
+
+    def _wire_event_listeners(self) -> None:
+        """Wire event-listener mappings from all providers onto the dispatcher."""
+        from neva.events.dispatcher import EventDispatcher
+
+        result = self.make(EventDispatcher)
+        if result.is_err:
+            return
+
+        dispatcher = result.unwrap()
+        for provider in self.providers.values():
+            for event_cls, listeners in provider.listen.items():
+                for listener_cls in listeners:
+                    dispatcher.listen(event_cls, listener_cls)

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/neva/arch/facade.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING, Any, ClassVar
 from neva import Option, Result, from_optional
 from neva.support.accessors import get_attr
 
+
 if TYPE_CHECKING:
     from neva.arch.application import Application
 
@@ -91,7 +92,7 @@ class FacadeMeta(ABCMeta):
             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."
+                "Call Facade.set_facade_application(app) first."
             )
             .and_then(
                 lambda x: cls._resolve_facade_instance(

python_neva-1.0.0/neva/arch/faststream.py

@@ -0,0 +1,76 @@
+"""FastStream wrapper for Neva."""
+
+from collections.abc import AsyncGenerator, AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, Callable
+
+import dishka
+import faststream
+from faststream._internal.broker import BrokerUsecase
+from faststream._internal.configs import BrokerConfig
+from starlette.types import StatelessLifespan
+
+from neva import Result
+from neva.arch import Application, ServiceProvider
+
+
+class FastStream(faststream.FastStream):
+    """FastStream wrapper for Neva."""
+
+    def __init__(
+        self,
+        broker: BrokerUsecase[Any, Any, BrokerConfig],
+        config_path: str | None = None,
+    ) -> None:
+        """Initialize the FastStream wrapper."""
+        self.application: Application = Application(config_path=config_path)
+        super().__init__(broker, lifespan=self._create_lifespan())
+
+    def register(
+        self,
+        provider: type[ServiceProvider],
+    ) -> Result[ServiceProvider, str]:
+        """Registers a service provider with the application.
+
+        Returns:
+            Result containing the registered provider instance or an error message.
+        """
+        return self.application.register(provider=provider)
+
+    def bind(
+        self,
+        source: type | Callable[..., Any],
+        *,
+        interface: type | None = None,
+        scope: dishka.BaseScope | None = None,
+    ) -> None:
+        """Binds a source to the container."""
+        self.application.bind(
+            source=source,
+            interface=interface,
+            scope=scope,
+        )
+
+    def make[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.
+        """
+        return self.application.make(interface=interface)
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncGenerator[None, None]:
+        """Async context manager for the application lifespan."""
+        async with self.application.lifespan():
+            yield
+
+    def _create_lifespan(
+        self,
+    ) -> StatelessLifespan["FastStream"]:
+        @asynccontextmanager
+        async def composed_lifespan(app: faststream.FastStream) -> AsyncIterator[None]:
+            async with self.lifespan():
+                yield
+
+        return composed_lifespan

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/neva/arch/service_provider.py

@@ -5,14 +5,19 @@ Service providers are responsible for binding services into the dependency injec
 container and optionally managing their lifecycle.
 """
 
+from __future__ import annotations
+
 import abc
 from contextlib import AbstractAsyncContextManager
-from typing import TYPE_CHECKING, Protocol, Self, runtime_checkable
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol, Self, runtime_checkable
 
 from neva import Result
 
+
 if TYPE_CHECKING:
     from neva.arch.application import Application
+    from neva.events.event import Event
+    from neva.events.listener import EventListener
 
 
 @runtime_checkable
@@ -46,10 +51,14 @@ class ServiceProvider(abc.ABC):
 
     Attributes:
         app: The application instance.
+        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.
 
     """
 
     app: "Application"
+    listen: ClassVar[dict[type[Event], list[type[EventListener[Any]]]]] = {}
 
     def __init__(self, app: "Application") -> None:
         """Initialize the service provider.

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/neva/config/__init__.py

@@ -3,6 +3,7 @@
 from neva.config.provider import ConfigServiceProvider
 from neva.config.repository import ConfigRepository
 
+
 __all__ = [
     "ConfigRepository",
     "ConfigServiceProvider",

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/neva/config/base_providers.py

@@ -6,6 +6,8 @@ to function properly.
 """
 
 from neva.arch import ServiceProvider
+from neva.database import DatabaseServiceProvider
+from neva.events.provider import EventServiceProvider
 from neva.obs import LogServiceProvider
 
 
@@ -22,4 +24,8 @@ def base_providers() -> set[type[ServiceProvider]]:
         Set of service provider classes to register.
 
     """
-    return {LogServiceProvider}
+    return {
+        DatabaseServiceProvider,
+        EventServiceProvider,
+        LogServiceProvider,
+    }

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/neva/config/repository.py

@@ -53,7 +53,7 @@ class ConfigRepository:
             elif not isinstance(current[k], dict):
                 return Err(
                     f"Cannot set '{key}': '{k}' is not a dictionary "
-                    + f"(found {type(current[k]).__name__})"
+                    f"(found {type(current[k]).__name__})"
                 )
             current = current[k]
 

python_neva-1.0.0/neva/database/__init__.py

@@ -0,0 +1,16 @@
+"""Database module."""
+
+from neva.database.config import DatabaseConfig
+from neva.database.connection import TransactionContext
+from neva.database.manager import DatabaseManager
+from neva.database.provider import DatabaseServiceProvider
+from neva.database.transaction import Transaction
+
+
+__all__ = [
+    "DatabaseConfig",
+    "DatabaseManager",
+    "DatabaseServiceProvider",
+    "Transaction",
+    "TransactionContext",
+]

python_neva-1.0.0/neva/database/connection.py

@@ -0,0 +1,124 @@
+"""Connection manager."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import final
+
+from tortoise.transactions import in_transaction
+
+from neva import Nothing, Option, Some, from_optional
+from neva.database.transaction import Transaction, TransactionState
+from neva.obs import LogManager
+
+
+@dataclass
+class TransactionRegistry:
+    """A registry of ongoing transactions."""
+
+    by_connection: dict[str, Transaction] = field(default_factory=dict)
+    stack: list[Transaction] = field(default_factory=list)
+
+    def extend(self, transaction: Transaction) -> "TransactionRegistry":
+        """Adds a new transaction to the registry.
+
+        Returns:
+            A new registry with the new transaction added.
+        """
+        return TransactionRegistry(
+            by_connection={**self.by_connection, transaction.conn_name: transaction},
+            stack=[*self.stack, transaction],
+        )
+
+
+_tx_registry: ContextVar[TransactionRegistry | None] = ContextVar(
+    "_tx_registry",
+    default=None,
+)
+
+
+class TransactionContext:
+    """Transaction context."""
+
+    def __init__(self) -> None:
+        if _tx_registry.get() is None:
+            _ = _tx_registry.set(TransactionRegistry())
+
+    def current(self, connection: str | None = None) -> Option[Transaction]:
+        """Get the current transaction.
+
+        Returns:
+            The current transaction, if any.
+        """
+        registry = _tx_registry.get()
+        if registry is None:
+            return Nothing()
+
+        if connection is not None:
+            tx = registry.by_connection.get(connection)
+            return from_optional(tx)
+
+        if registry.stack:
+            return Some(registry.stack[-1])
+        return Nothing()
+
+
+@final
+class ConnectionManager:
+    """Connection manager."""
+
+    def __init__(
+        self,
+        name: str,
+        tx_context: TransactionContext,
+        logger: LogManager | None,
+    ) -> None:
+        self.name = name
+        self.tx_context = tx_context
+        self.logger = logger
+
+    @asynccontextmanager
+    async def transaction(
+        self,
+    ) -> AsyncIterator[Transaction]:
+        """Open a new transaction.
+
+        Yields:
+            Transaction: The new transaction.
+        """
+        parent = self.tx_context.current(self.name)
+        tx = Transaction(self.name)
+        tx.parent = parent
+        old_registry = _tx_registry.get()
+        token = (
+            _tx_registry.set(old_registry.extend(tx))
+            if old_registry is not None
+            else _tx_registry.set(TransactionRegistry())
+        )
+
+        try:
+            async with in_transaction(self.name):
+                yield tx
+            tx.state = TransactionState.COMMITTED
+            if tx.is_root:
+                for result in await tx.execute_on_commit_callbacks():
+                    if result.is_err and self.logger is not None:
+                        self.logger.error(
+                            "commit callback failed",
+                            error=result.err().unwrap(),
+                            connection=self.name,
+                        )
+        except BaseException:
+            tx.state = TransactionState.ROLLED_BACK
+            if tx.is_root:
+                for result in await tx.execute_on_rollback_callbacks():
+                    if result.is_err and self.logger is not None:
+                        self.logger.error(
+                            "rollback callback failed",
+                            error=result.err().unwrap(),
+                            connection=self.name,
+                        )
+            raise
+        finally:
+            _tx_registry.reset(token)

python_neva-1.0.0/neva/database/manager.py

@@ -0,0 +1,44 @@
+"""Database manager."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import final
+
+from neva import Option
+from neva.database.connection import ConnectionManager, TransactionContext
+from neva.database.transaction import Transaction
+from neva.obs import LogManager
+
+
+@final
+class DatabaseManager:
+    """Database manager."""
+
+    def __init__(self, tx_context: TransactionContext, logger: LogManager) -> None:
+        self._tx_context = tx_context
+        self._logger = logger
+        self._connections: dict[str, ConnectionManager] = {}
+
+    def connection(self, name: str) -> ConnectionManager:
+        """Returns a new connection manager."""
+        return self._connections.setdefault(
+            name, ConnectionManager(name, self._tx_context, self._logger)
+        )
+
+    def current(self, connection: str | None = None) -> Option[Transaction]:
+        """Returns the current transaction.
+
+        If no connection is specified, this will return the most recent transaction on
+        any connection. This is something to keep in mind.
+        """
+        return self._tx_context.current(connection)
+
+    @asynccontextmanager
+    async def transaction(self, name: str = "default") -> AsyncIterator[Transaction]:
+        """Returns a transaction to the default connection.
+
+        Yields:
+            Transaction: The transaction.
+        """
+        async with self.connection(name).transaction() as tx:
+            yield tx

{python_neva-0.6.0.dev4 → python_neva-1.0.0}/neva/database/provider.py

@@ -5,8 +5,10 @@ from contextlib import asynccontextmanager
 from typing import Self, override
 
 from tortoise import Tortoise
+
 from neva import Err, Ok, Result
 from neva.arch import ServiceProvider
+from neva.database.connection import TransactionContext
 from neva.database.manager import DatabaseManager
 from neva.support.facade import Config, Log
 
@@ -16,6 +18,7 @@ class DatabaseServiceProvider(ServiceProvider):
 
     @override
     def register(self) -> Result[Self, str]:
+        self.app.bind(TransactionContext)
         self.app.bind(DatabaseManager)
         return Ok(self)
 

python_neva-1.0.0/neva/database/transaction.py

@@ -0,0 +1,96 @@
+"""Transaction management systems."""
+
+from collections.abc import Awaitable
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Callable, Self
+
+from neva import Err, Nothing, Option, Result, Some
+
+
+type TransactionCallback = Callable[[], Awaitable[Result[None, str]]]
+
+
+class TransactionState(Enum):
+    """Represents the state of a transaction."""
+
+    ACTIVE = auto()
+    COMMITTED = auto()
+    ROLLED_BACK = auto()
+
+
+@dataclass
+class Transaction:
+    """Represents a database transaction with callback support."""
+
+    conn_name: str
+    state: TransactionState = field(default=TransactionState.ACTIVE, init=False)
+    _on_commit: list[TransactionCallback] = field(default_factory=list, init=False)
+    _on_rollback: list[TransactionCallback] = field(default_factory=list, init=False)
+    parent: Option["Transaction"] = field(default_factory=Nothing, init=False)
+
+    @property
+    def is_active(self) -> bool:
+        """Determine if the transaction is active."""
+        return self.state == TransactionState.ACTIVE
+
+    @property
+    def is_root(self) -> bool:
+        """Determine if the transaction is the root transaction."""
+        return self.parent.is_nothing
+
+    def on_commit(self, callback: TransactionCallback) -> Self:
+        """Register a callback to be called when the root transaction is committed.
+
+        Returns:
+            Self: The current transaction, for chaining purposes.
+        """
+        match self.parent:
+            case Some(parent):
+                _ = parent.on_commit(callback)
+            case Nothing():
+                self._on_commit.append(callback)
+        return self
+
+    def on_rollback(self, callback: TransactionCallback) -> Self:
+        """Register a callback to be called when the root transaction is rolled back.
+
+        Returns:
+            Self: The current transaction, for chaining purposes.
+        """
+        match self.parent:
+            case Some(parent):
+                _ = parent.on_rollback(callback)
+            case Nothing():
+                self._on_rollback.append(callback)
+        return self
+
+    async def execute_on_commit_callbacks(self) -> list[Result[None, str]]:
+        """Execute all registered commit callbacks.
+
+        Returns:
+            A list of results from each callback.
+        """
+        results: list[Result[None, str]] = []
+        for callback in self._on_commit:
+            try:
+                results.append(await callback())
+            except Exception as e:
+                results.append(Err(f"Callback raised: {e}"))
+        self._on_commit.clear()
+        return results
+
+    async def execute_on_rollback_callbacks(self) -> list[Result[None, str]]:
+        """Execute all registered rollback callbacks.
+
+        Returns:
+            A list of results from each callback.
+        """
+        results: list[Result[None, str]] = []
+        for callback in self._on_rollback:
+            try:
+                results.append(await callback())
+            except Exception as e:
+                results.append(Err(f"Callback raised: {e}"))
+        self._on_rollback.clear()
+        return results

python_neva-1.0.0/neva/events/__init__.py

@@ -0,0 +1,23 @@
+"""Defines the events system.
+
+This module defines the event system, which is used to dispatch events to listener.
+Three components are of particular interest:
+- The base Event class, which is used to define events.
+- The @listener decorator, which is used to define listeners from handler functions.
+- The EventDispatcher class, which is used to registers listeners and dispatch events.
+"""
+
+from neva.events.dispatcher import EventDispatcher
+from neva.events.event import Event
+from neva.events.listener import EventListener, HandlingPolicy, listener
+from neva.events.provider import EventServiceProvider
+
+
+__all__ = [
+    "Event",
+    "EventDispatcher",
+    "EventListener",
+    "EventServiceProvider",
+    "HandlingPolicy",
+    "listener",
+]