python-hexagonal 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

hexagonal/adapters/drivens/buses/base/event_bus.py

@@ -28,9 +28,9 @@ class HandlerError(Exception):
         super().__init__(f"""
 Error al Manejar Evento {evento.__class__.__name__}
     handler: {
-            handler.__class__.__name__   # pyright: ignore[reportUnknownMemberType]
+            handler.__class__.__name__  # pyright: ignore[reportUnknownMemberType]
             if isinstance(handler, IMessageHandler)
-            else handler.__name__ 
+            else handler.__name__
         }   
     evento: {evento.type}
     datos: {evento.model_dump_json(indent=2)}
@@ -93,11 +93,23 @@ class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
         if name not in self.wait_list:
             self.wait_list[name] = []
         self.wait_list[name].append(handler)
+        logger.debug(
+            "    [DEBUG _wait_for] Added handler to wait_list[%s], now has %s handlers",
+            name,
+            len(self.wait_list[name]),
+        )
 
     def _handle_wait_list(self, event: TEvento):
         event_type = type(event)
         key = self._get_key(event_type)
+        logger.debug("    [DEBUG _handle_wait_list] Publishing event type=%s", key)
         wait_list = self.wait_list.get(key)
+        if wait_list:
+            logger.debug(
+                "    [DEBUG _handle_wait_list] Found %s handlers", len(wait_list)
+            )
+        else:
+            logger.debug("    [DEBUG _handle_wait_list] No handlers registered!")
         while wait_list:
             if self.raise_error:
                 handler = wait_list.pop()

hexagonal/adapters/drivens/buses/base/query.py

@@ -7,6 +7,8 @@ from hexagonal.domain import (
     HandlerAlreadyRegistered,
     HandlerNotRegistered,
     Query,
+    QueryBase,
+    QueryOne,
     QueryResult,
     QueryResults,
     TQuery,
@@ -22,12 +24,12 @@ class QueryBus(IQueryBus[TManager], Infrastructure):
         self.handlers = {}
         super().initialize(env)
 
-    def _get_name(self, query_type: Type[Query[TView]]) -> str:
+    def _get_name(self, query_type: Type[QueryBase[TView]]) -> str:
         return get_topic(query_type)
 
     def _get_handler(
-        self, query: Query[TView]
-    ) -> IQueryHandler[TManager, Query[TView], TView] | None:
+        self, query: QueryBase[TView]
+    ) -> IQueryHandler[TManager, QueryBase[TView], TView] | None:
         name = self._get_name(query.__class__)
         return self.handlers.get(name)
 
@@ -50,6 +52,14 @@ class QueryBus(IQueryBus[TManager], Infrastructure):
         else:
             raise HandlerNotRegistered(f"Query: {name}")
 
+    @overload
+    def get(
+        self,
+        query: QueryOne[TView],
+        *,
+        one: bool = False,
+    ) -> QueryResult[TView]: ...
+
     @overload
     def get(self, query: Query[TView], *, one: Literal[True]) -> QueryResult[TView]: ...
 
@@ -63,7 +73,7 @@ class QueryBus(IQueryBus[TManager], Infrastructure):
 
     def get(
         self,
-        query: Query[TView],
+        query: Query[TView] | QueryOne[TView],
         *,
         one: bool = False,
     ) -> QueryResult[TView] | QueryResults[TView]:
@@ -73,7 +83,7 @@ class QueryBus(IQueryBus[TManager], Infrastructure):
         if not handler:
             raise HandlerNotRegistered(f"Query: {name}")
         results = handler.get(query)
-        if not one:
+        if not (one or isinstance(query, QueryOne)):
             return results
         if len(results) == 0:
             raise ValueError("No results found")

hexagonal/adapters/drivens/buses/inmemory/event_bus.py

@@ -5,6 +5,8 @@ import threading
 from queue import Empty, Queue
 from typing import Mapping
 
+from eventsourcing.utils import strtobool
+
 from hexagonal.adapters.drivens.buses.base import BaseEventBus
 from hexagonal.domain import CloudMessage, TEvent, TEvento
 from hexagonal.ports.drivens import TManager
@@ -28,7 +30,8 @@ class InMemoryQueueEventBus(BaseEventBus[TManager]):
     def initialize(self, env: Mapping[str, str]) -> None:
         self.queue: Queue[CloudMessage[TEvento]] = Queue()  # o Queue(maxsize=...)
         self._stop = threading.Event()
-        self._worker = threading.Thread(target=self._worker_loop, daemon=True)
+        daemon = strtobool(env.get("EVENT_BUS_WORKER_DAEMON", "true"))
+        self._worker = threading.Thread(target=self._worker_loop, daemon=daemon)
 
         super().initialize(env)
 
@@ -41,8 +44,8 @@ class InMemoryQueueEventBus(BaseEventBus[TManager]):
         return self._publish_messages(*events)
 
     def _publish_message(self, message: CloudMessage[TEvento]) -> None:
-        super()._publish_message(message)
         self.verify()
+        super()._publish_message(message)
         self.queue.put(message)
         # No llamamos consume() aquí: el worker se encarga.
 

hexagonal/adapters/drivens/mappers.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+from decimal import Decimal
 from typing import Any, Hashable, cast
 from uuid import UUID
 
@@ -119,9 +120,17 @@ class MessageMapper(Mapper[UUID]):
         return cls.model_validate(event_state)
 
 
+def default_orjson_value_serializer(obj: Any) -> Any:
+    if isinstance(obj, (UUID, Decimal)):
+        return str(obj)
+    if isinstance(obj, Inmutable):
+        return obj.model_dump(mode="json")
+    raise TypeError
+
+
 class OrjsonTranscoder(Transcoder):
     def encode(self, obj: Any) -> bytes:
-        return orjson.dumps(obj)
+        return orjson.dumps(obj, default=default_orjson_value_serializer)
 
     def decode(self, data: bytes) -> Any:
         return orjson.loads(data)

hexagonal/adapters/drivens/repository/base/__init__.py

@@ -1,7 +1,8 @@
 from .repository import (
     BaseAggregateRepositoryAdapter,
+    BaseEntityRepositoryAdapter,
     BaseRepositoryAdapter,
-    TAggregate,
+    BaseSearchRepositoryAdapter,
 )
 from .unit_of_work import BaseUnitOfWork
 
@@ -9,5 +10,6 @@ __all__ = [
     "BaseRepositoryAdapter",
     "BaseAggregateRepositoryAdapter",
     "BaseUnitOfWork",
-    "TAggregate",
+    "BaseEntityRepositoryAdapter",
+    "BaseSearchRepositoryAdapter",
 ]

hexagonal/adapters/drivens/repository/base/repository.py

@@ -1,12 +1,10 @@
 # pyright: reportMissingTypeStubs=false, reportUnknownArgumentType=false, reportMissingParameterType=none, reportGeneralTypeIssues=none
 
 from typing import (
-    Any,
     ClassVar,
     Dict,
     Mapping,
     Type,
-    TypeVar,
     get_args,
     get_origin,
 )
@@ -16,16 +14,16 @@ from eventsourcing.persistence import Mapper
 from eventsourcing.utils import Environment
 
 from hexagonal.application import Infrastructure
-from hexagonal.domain import AggregateRoot, TIdEntity
+from hexagonal.domain import TAggregate, TEntity, TIdEntity, TQuery, TView
 from hexagonal.ports.drivens import (
     IAggregateRepository,
     IBaseRepository,
+    IEntityRepository,
+    ISearchRepository,
     IUnitOfWork,
     TManager,
 )
 
-TAggregate = TypeVar("TAggregate", bound=AggregateRoot[Any, Any])
-
 
 class BaseRepositoryAdapter(IBaseRepository[TManager], Infrastructure):
     ENV: ClassVar[Dict[str, str]] = {}
@@ -83,3 +81,35 @@ class BaseAggregateRepositoryAdapter(
     @property
     def aggregate_name(self) -> str:
         return self._type_of_aggregate.__name__
+
+
+class BaseEntityRepositoryAdapter(
+    BaseRepositoryAdapter[TManager],
+    IEntityRepository[TManager, TEntity, TIdEntity],
+):
+    _type_of_entity: Type[TEntity]
+
+    def __init_subclass__(cls) -> None:
+        super().__init_subclass__()
+        # Inspect generic base to find the concrete type argument
+        for base in getattr(cls, "__orig_bases__", []):
+            origin = get_origin(base)
+            if origin and issubclass(origin, BaseEntityRepositoryAdapter):
+                args = get_args(base)
+                if args:
+                    cls._type_of_entity = args[0]
+                    cls.NAME = cls._type_of_entity.__name__.upper()
+
+    def __init__(self, mapper: Mapper[UUID], connection_manager: TManager):
+        super().__init__(connection_manager)
+        self._mapper = mapper
+
+    @property
+    def entity_name(self) -> str:
+        return self._type_of_entity.__name__
+
+
+class BaseSearchRepositoryAdapter(
+    BaseRepositoryAdapter[TManager],
+    ISearchRepository[TManager, TQuery, TView],
+): ...

hexagonal/adapters/drivens/repository/sqlalchemy/__init__.py

@@ -0,0 +1,33 @@
+"""SQLAlchemy adapters for the repository pattern.
+
+This module provides SQLAlchemy-based implementations of the repository,
+outbox, inbox, and unit of work patterns. Supports multiple database
+backends (PostgreSQL, MySQL, SQLite) through SQLAlchemy's abstraction layer.
+"""
+
+from .datastore import SQLAlchemyConnectionContextManager, SQLAlchemyDatastore
+from .infrastructure import SQLAlchemyInfrastructure
+from .outbox import (
+    SQLAlchemyInboxRepository,
+    SQLAlchemyOutboxRepository,
+    SQLAlchemyPairInboxOutbox,
+)
+from .repository import (
+    SQLAlchemyEntityRepositoryAdapter,
+    SQLAlchemyRepositoryAdapter,
+    SQLAlchemySearchRepositoryAdapter,
+)
+from .unit_of_work import SQLAlchemyUnitOfWork
+
+__all__ = [
+    "SQLAlchemyConnectionContextManager",
+    "SQLAlchemyDatastore",
+    "SQLAlchemyRepositoryAdapter",
+    "SQLAlchemyUnitOfWork",
+    "SQLAlchemyOutboxRepository",
+    "SQLAlchemyInboxRepository",
+    "SQLAlchemyInfrastructure",
+    "SQLAlchemyPairInboxOutbox",
+    "SQLAlchemyEntityRepositoryAdapter",
+    "SQLAlchemySearchRepositoryAdapter",
+]

hexagonal/adapters/drivens/repository/sqlalchemy/datastore.py

@@ -0,0 +1,288 @@
+"""SQLAlchemy datastore and connection context manager."""
+
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any, Optional
+
+from eventsourcing.utils import strtobool
+from sqlalchemy import Connection, Engine, create_engine, text
+from sqlalchemy.pool import QueuePool, StaticPool
+
+from hexagonal.ports.drivens.repository import IConnectionManager
+
+from .env_vars import (
+    SQLALCHEMY_DATABASE_URL,
+    SQLALCHEMY_ECHO,
+    SQLALCHEMY_MAX_OVERFLOW,
+    SQLALCHEMY_POOL_PRE_PING,
+    SQLALCHEMY_POOL_RECYCLE,
+    SQLALCHEMY_POOL_SIZE,
+    SQLALCHEMY_POOL_TIMEOUT,
+)
+
+
+class SQLAlchemyDatastore:
+    """Core SQLAlchemy engine and connection management.
+
+    Wraps SQLAlchemy Engine with connection pooling configuration.
+    Provides context managers for connection and transaction handling.
+    """
+
+    def __init__(
+        self,
+        database_url: str,
+        *,
+        echo: bool = False,
+        pool_size: int = 5,
+        pool_timeout: int = 30,
+        pool_recycle: int = 3600,
+        pool_pre_ping: bool = True,
+        max_overflow: int = 10,
+    ):
+        """Initialize SQLAlchemy datastore.
+
+        Args:
+            database_url: SQLAlchemy database URL (e.g., postgresql://user:pass@host/db)
+            echo: Enable SQL statement logging
+            pool_size: Connection pool size (ignored for SQLite)
+            pool_timeout: Connection pool timeout in seconds
+            pool_recycle: Connection recycle time in seconds
+            pool_pre_ping: Pre-ping connections before use
+            max_overflow: Maximum overflow connections (ignored for SQLite)
+        """
+        self._database_url = database_url
+
+        # SQLite uses StaticPool for single connection (avoids database lock issues)
+        # Other databases use QueuePool with configurable settings
+        is_sqlite = database_url.startswith("sqlite")
+
+        pool_class = StaticPool if is_sqlite else QueuePool
+        pool_kwargs: dict[Any, Any] = {}
+
+        if is_sqlite:
+            # For SQLite with StaticPool, we need connect_args
+            pool_kwargs["connect_args"] = {"check_same_thread": False}
+        else:
+            pool_kwargs.update(
+                {
+                    "pool_size": pool_size,
+                    "pool_timeout": pool_timeout,
+                    "pool_recycle": pool_recycle,
+                    "pool_pre_ping": pool_pre_ping,
+                    "max_overflow": max_overflow,
+                }
+            )
+
+        self._engine: Engine = create_engine(
+            database_url,
+            echo=echo,
+            poolclass=pool_class,
+            **pool_kwargs,
+        )
+
+    @property
+    def engine(self) -> Engine:
+        """Get the SQLAlchemy engine."""
+        return self._engine
+
+    @property
+    def database_url(self) -> str:
+        """Get the database URL."""
+        return self._database_url
+
+    @contextmanager
+    def get_connection(self) -> Iterator[Connection]:
+        """Get a database connection from the pool.
+
+        Yields:
+            SQLAlchemy Connection object
+
+        The connection is returned to the pool when the context exits.
+        """
+        with self._engine.connect() as connection:
+            # Enable foreign key support for SQLite
+            if self._database_url.startswith("sqlite"):
+                connection.execute(text("PRAGMA foreign_keys = ON"))
+            yield connection
+
+    @contextmanager
+    def transaction(self, commit: bool = False) -> Iterator[Connection]:
+        """Get a connection with transaction management.
+
+        Args:
+            commit: If True, commit the transaction on success
+
+        Yields:
+            SQLAlchemy Connection object within a transaction
+
+        Raises:
+            RuntimeError: If the transaction fails (wraps original exception)
+        """
+        with self.get_connection() as connection:
+            trans = connection.begin()
+            try:
+                yield connection
+                if commit:
+                    trans.commit()
+                else:
+                    trans.rollback()
+            except Exception as exc:
+                trans.rollback()
+                raise RuntimeError("Transaction failed") from exc
+
+    def dispose(self) -> None:
+        """Dispose of the engine and all connections."""
+        self._engine.dispose()
+
+
+class SQLAlchemyConnectionContextManager(IConnectionManager):
+    """Connection context manager implementing IConnectionManager interface.
+
+    Manages SQLAlchemy connection lifecycle for repositories.
+    Maintains a current connection reference for transaction coordination.
+    """
+
+    def __init__(self, datastore: Optional[SQLAlchemyDatastore] = None):
+        """Initialize connection context manager.
+
+        Args:
+            datastore: Optional SQLAlchemyDatastore instance.
+                      If not provided, must call initialize() before use.
+        """
+        self._datastore = datastore
+        self._current_connection: Optional[Connection] = None
+        self._connection_ctx: Optional[Any] = None
+        self._initialized = datastore is not None
+
+    @property
+    def initialized(self) -> bool:
+        """Check if the connection manager is initialized."""
+        return self._initialized
+
+    @property
+    def datastore(self) -> SQLAlchemyDatastore:
+        """Get the underlying datastore.
+
+        Raises:
+            RuntimeError: If datastore is not initialized
+        """
+        if self._datastore is None:
+            raise RuntimeError("Datastore not initialized. Call initialize() first.")
+        return self._datastore
+
+    def initialize(self, env: Mapping[str, str]) -> None:
+        """Initialize the datastore from environment variables.
+
+        Args:
+            env: Environment variables mapping
+
+        Environment variables:
+            SQLALCHEMY_DATABASE_URL: Database connection URL (required)
+            SQLALCHEMY_ECHO: Enable SQL logging (default: False)
+            SQLALCHEMY_POOL_SIZE: Pool size (default: 5)
+            SQLALCHEMY_POOL_TIMEOUT: Pool timeout (default: 30)
+            SQLALCHEMY_POOL_RECYCLE: Pool recycle time (default: 3600)
+            SQLALCHEMY_POOL_PRE_PING: Pre-ping connections (default: True)
+            SQLALCHEMY_MAX_OVERFLOW: Max overflow (default: 10)
+        """
+        if self._datastore is not None:
+            self._initialized = True
+            return
+
+        database_url = env.get(SQLALCHEMY_DATABASE_URL)
+        if database_url is None:
+            raise ValueError(
+                f"Database configuration is missing. Set {SQLALCHEMY_DATABASE_URL}."
+            )
+
+        echo = strtobool(env.get(SQLALCHEMY_ECHO, "False"))
+        pool_size = int(env.get(SQLALCHEMY_POOL_SIZE, "5"))
+        pool_timeout = int(env.get(SQLALCHEMY_POOL_TIMEOUT, "30"))
+        pool_recycle = int(env.get(SQLALCHEMY_POOL_RECYCLE, "3600"))
+        pool_pre_ping = strtobool(env.get(SQLALCHEMY_POOL_PRE_PING, "True"))
+        max_overflow = int(env.get(SQLALCHEMY_MAX_OVERFLOW, "10"))
+
+        self._datastore = SQLAlchemyDatastore(
+            database_url,
+            echo=bool(echo),
+            pool_size=pool_size,
+            pool_timeout=pool_timeout,
+            pool_recycle=pool_recycle,
+            pool_pre_ping=bool(pool_pre_ping),
+            max_overflow=max_overflow,
+        )
+        self._initialized = True
+
+    def start_connection(self):
+        """Start a new connection context.
+
+        Returns:
+            The connection context manager (already entered)
+
+        This manually enters the connection context and sets it as current.
+        Call the returned context's __exit__ to clean up.
+        """
+        self._connection_ctx = self.datastore.get_connection()
+        self._current_connection = self._connection_ctx.__enter__()
+        return self._connection_ctx
+
+    @property
+    def current_connection(self) -> Connection:
+        """Get the current active connection.
+
+        Returns:
+            The current SQLAlchemy Connection
+
+        Note:
+            If no connection exists or it's closed, a new one will be created.
+        #"""
+        if self._current_connection is None or self._current_connection.closed:
+            self._connection_ctx = self.datastore.get_connection()
+            self._current_connection = self._connection_ctx.__enter__()
+        if self._current_connection is None:
+            raise RuntimeError("Failed to establish a database connection.")
+        return self._current_connection
+
+    @current_connection.setter
+    def current_connection(self, connection: Optional[Connection]) -> None:
+        """Set the current connection, cleaning up any existing one.
+
+        Args:
+            connection: The new connection or None to clear
+        """
+        if self._connection_ctx is not None:
+            try:
+                self._connection_ctx.__exit__(None, None, None)
+            except Exception:
+                pass  # Ignore errors during cleanup
+            self._connection_ctx = None
+        self._current_connection = connection
+
+    @contextmanager
+    def cursor(self, commit: bool = True) -> Iterator[Connection]:
+        """Get a connection for executing statements.
+
+        This is provided for compatibility with the SQLite interface.
+        In SQLAlchemy, we use the connection directly instead of a cursor.
+
+        Handles closed connections by re-establishing.
+
+        Args:
+            commit: Whether to commit after the context exits (default: True)
+
+        Yields:
+            Current connection for executing statements
+        """
+        try:
+            # Check if connection is usable
+            conn = self.current_connection
+            if conn.closed:
+                self._current_connection = None
+                conn = self.current_connection
+            yield conn
+            if commit:
+                conn.commit()
+        except Exception:
+            # Reset connection on error
+            self._current_connection = None
+            raise

hexagonal/adapters/drivens/repository/sqlalchemy/env_vars.py

@@ -0,0 +1,22 @@
+"""Environment variable constants for SQLAlchemy adapter configuration."""
+
+# Database connection URL (e.g., postgresql://user:pass@host/db, sqlite:///path.db)
+SQLALCHEMY_DATABASE_URL = "SQLALCHEMY_DATABASE_URL"
+
+# Enable SQL statement logging
+SQLALCHEMY_ECHO = "SQLALCHEMY_ECHO"
+
+# Connection pool size (default: 5)
+SQLALCHEMY_POOL_SIZE = "SQLALCHEMY_POOL_SIZE"
+
+# Connection pool timeout in seconds (default: 30)
+SQLALCHEMY_POOL_TIMEOUT = "SQLALCHEMY_POOL_TIMEOUT"
+
+# Connection recycle time in seconds (default: 3600)
+SQLALCHEMY_POOL_RECYCLE = "SQLALCHEMY_POOL_RECYCLE"
+
+# Pre-ping connections before use (default: True)
+SQLALCHEMY_POOL_PRE_PING = "SQLALCHEMY_POOL_PRE_PING"
+
+# Maximum overflow connections (default: 10)
+SQLALCHEMY_MAX_OVERFLOW = "SQLALCHEMY_MAX_OVERFLOW"

hexagonal/adapters/drivens/repository/sqlalchemy/infrastructure.py

@@ -0,0 +1,41 @@
+"""SQLAlchemy infrastructure grouping."""
+
+from hexagonal.adapters.drivens.mappers import MessageMapper
+from hexagonal.application import ComposableInfrastructure
+
+from .datastore import SQLAlchemyConnectionContextManager, SQLAlchemyDatastore
+
+
+class SQLAlchemyInfrastructure(ComposableInfrastructure):
+    """Groups SQLAlchemy connection manager and mapper for dependency injection.
+
+    Provides a convenient way to initialize and access the core
+    SQLAlchemy infrastructure components needed by repositories.
+    """
+
+    def __init__(
+        self,
+        mapper: MessageMapper,
+        datastore: SQLAlchemyDatastore | None = None,
+    ):
+        """Initialize SQLAlchemy infrastructure.
+
+        Args:
+            mapper: Message mapper for serialization/deserialization
+            datastore: Optional SQLAlchemyDatastore instance.
+                      If not provided, connection_manager.initialize() must be called.
+        """
+        self._datastore = datastore
+        self._mapper = mapper
+        self._connection_manager = SQLAlchemyConnectionContextManager(datastore)
+        super().__init__(self._connection_manager)
+
+    @property
+    def connection_manager(self) -> SQLAlchemyConnectionContextManager:
+        """Get the connection context manager."""
+        return self._connection_manager
+
+    @property
+    def mapper(self) -> MessageMapper:
+        """Get the message mapper."""
+        return self._mapper