python-hexagonal 0.1.0__tar.gz → 0.1.2__tar.gz

{python_hexagonal-0.1.0 → python_hexagonal-0.1.2}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.3
 Name: python-hexagonal
-Version: 0.1.0
+Version: 0.1.2
 Summary: Framework to build hexagonal architecture applications in Python.
 Author: jose-matos-9281
 Author-email: jose-matos-9281 <58991817+jose-matos-9281@users.noreply.github.com>
 Requires-Dist: eventsourcing>=9.4.6
 Requires-Dist: orjson>=3.11.5
 Requires-Dist: pydantic>=2.12.5
+Requires-Dist: sqlalchemy>=2.0.45
 Requires-Dist: uuid6>=2025.0.1
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown

{python_hexagonal-0.1.0 → python_hexagonal-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-hexagonal"
-version = "0.1.0"
+version = "0.1.2"
 description = "Framework to build hexagonal architecture applications in Python."
 readme = "README.md"
 authors = [
@@ -11,6 +11,7 @@ dependencies = [
     "eventsourcing>=9.4.6",
     "orjson>=3.11.5",
     "pydantic>=2.12.5",
+    "sqlalchemy>=2.0.45",
     "uuid6>=2025.0.1",
 ]
 
@@ -29,3 +30,6 @@ fixable = ["I", "E", "F", "B"]
 dev = [
     "pytest>=9.0.2",
 ]
+sqlalchemy = [
+    "sqlalchemy>=2.0.45",
+]

{python_hexagonal-0.1.0 → python_hexagonal-0.1.2}/src/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()

{python_hexagonal-0.1.0 → python_hexagonal-0.1.2}/src/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,15 @@ 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)
+    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)

python_hexagonal-0.1.2/src/hexagonal/adapters/drivens/repository/sqlalchemy/__init__.py

@@ -0,0 +1,27 @@
+"""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 SQLAlchemyRepositoryAdapter
+from .unit_of_work import SQLAlchemyUnitOfWork
+
+__all__ = [
+    "SQLAlchemyConnectionContextManager",
+    "SQLAlchemyDatastore",
+    "SQLAlchemyRepositoryAdapter",
+    "SQLAlchemyUnitOfWork",
+    "SQLAlchemyOutboxRepository",
+    "SQLAlchemyInboxRepository",
+    "SQLAlchemyInfrastructure",
+    "SQLAlchemyPairInboxOutbox",
+]

python_hexagonal-0.1.2/src/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

python_hexagonal-0.1.2/src/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"

python_hexagonal-0.1.2/src/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

python_hexagonal-0.1.2/src/hexagonal/adapters/drivens/repository/sqlalchemy/models.py

@@ -0,0 +1,156 @@
+"""SQLAlchemy table definitions for aggregates, events, outbox and inbox."""
+
+from sqlalchemy import (
+    Column,
+    DateTime,
+    Index,
+    Integer,
+    LargeBinary,
+    MetaData,
+    PrimaryKeyConstraint,
+    String,
+    Table,
+    Text,
+)
+
+# Global metadata for table definitions
+metadata = MetaData()
+
+
+def _get_table_key(table_name: str, schema: str | None = None) -> str:
+    """Get the key used by SQLAlchemy metadata to store the table."""
+    if schema:
+        return f"{schema}.{table_name}"
+    return table_name
+
+
+def create_aggregates_table(table_name: str, schema: str | None = None) -> Table:
+    """Create the aggregates snapshots table definition.
+
+    Args:
+        table_name: Base name for the table (will be prefixed with 'aggregates_')
+        schema: Optional database schema name
+
+    Returns:
+        SQLAlchemy Table object for aggregate snapshots
+    """
+    full_table_name = f"aggregates_{table_name}"
+    table_key = _get_table_key(full_table_name, schema)
+
+    # Return existing table if already defined
+    if table_key in metadata.tables:
+        return metadata.tables[table_key]
+
+    return Table(
+        full_table_name,
+        metadata,
+        Column("originator_id", String(36), nullable=False),
+        Column("aggregate_name", Text, nullable=False),
+        Column("originator_version", Integer, nullable=False),
+        Column("topic", Text, nullable=False),
+        Column("state", LargeBinary, nullable=False),
+        Column("timestamp", DateTime(timezone=True), nullable=False),
+        PrimaryKeyConstraint("originator_id", "aggregate_name"),
+        schema=schema,
+    )
+
+
+def create_events_table(table_name: str, schema: str | None = None) -> Table:
+    """Create the aggregates events history table definition.
+
+    Args:
+        table_name: Base name for the table (prefixed with 'aggregates_',
+            suffixed with '_events')
+        schema: Optional database schema name
+
+    Returns:
+        SQLAlchemy Table object for aggregate events history
+    """
+    full_table_name = f"aggregates_{table_name}_events"
+    table_key = _get_table_key(full_table_name, schema)
+
+    # Return existing table if already defined
+    if table_key in metadata.tables:
+        return metadata.tables[table_key]
+
+    return Table(
+        full_table_name,
+        metadata,
+        Column("originator_id", String(36), nullable=False),
+        Column("aggregate_name", Text, nullable=False),
+        Column("originator_version", Integer, nullable=False),
+        Column("topic", Text, nullable=False),
+        Column("state", LargeBinary, nullable=False),
+        Column("timestamp", DateTime(timezone=True), nullable=False),
+        PrimaryKeyConstraint("originator_id", "aggregate_name", "originator_version"),
+        schema=schema,
+    )
+
+
+def create_outbox_table(table_name: str = "outbox", schema: str | None = None) -> Table:
+    """Create the outbox table definition.
+
+    Args:
+        table_name: Name for the outbox table (default: 'outbox')
+        schema: Optional database schema name
+
+    Returns:
+        SQLAlchemy Table object for outbox messages
+    """
+    table_key = _get_table_key(table_name, schema)
+
+    # Return existing table if already defined
+    if table_key in metadata.tables:
+        return metadata.tables[table_key]
+
+    return Table(
+        table_name,
+        metadata,
+        Column("message_id", String(36), primary_key=True),
+        Column("topic", Text, nullable=False),
+        Column("message", LargeBinary, nullable=False),
+        Column("published_at", DateTime(timezone=True), nullable=True),
+        Column("failed_at", DateTime(timezone=True), nullable=True),
+        Column("error", Text, nullable=True),
+        Column("retry_count", Integer, nullable=False, default=0),
+        Column(
+            "created_at",
+            DateTime(timezone=True),
+            nullable=False,
+        ),
+        Index(f"idx_{table_name}_published", "published_at"),
+        Index(f"idx_{table_name}_topic", "topic"),
+        schema=schema,
+    )
+
+
+def create_inbox_table(table_name: str = "inbox", schema: str | None = None) -> Table:
+    """Create the inbox table definition.
+
+    Args:
+        table_name: Name for the inbox table (default: 'inbox')
+        schema: Optional database schema name
+
+    Returns:
+        SQLAlchemy Table object for inbox messages
+    """
+    table_key = _get_table_key(table_name, schema)
+
+    # Return existing table if already defined
+    if table_key in metadata.tables:
+        return metadata.tables[table_key]
+
+    return Table(
+        table_name,
+        metadata,
+        Column("message_id", String(36), nullable=False),
+        Column("handler", Text, nullable=False),
+        Column("received_at", DateTime(timezone=True), nullable=False),
+        Column("processed_at", DateTime(timezone=True), nullable=True),
+        Column("error", Text, nullable=True),
+        Column("retry_count", Integer, nullable=False, default=0),
+        Column("failed_at", DateTime(timezone=True), nullable=True),
+        PrimaryKeyConstraint("message_id", "handler"),
+        Index(f"idx_{table_name}_processed", "processed_at"),
+        schema=schema,
+    )