python-hexagonal 0.2.0__tar.gz → 0.3.1__tar.gz

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-hexagonal
-Version: 0.2.0
+Version: 0.3.1
 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>
@@ -27,6 +27,8 @@ two-line snippet is enough.
   [`docs/explanation/architecture-from-example.md`](docs/explanation/architecture-from-example.md)
 - Bootstrap the adapter-specific SQLAlchemy path:
   [`docs/how-to/bootstrap-sqlalchemy-app.md`](docs/how-to/bootstrap-sqlalchemy-app.md)
+- Migrate existing apps to the scoped execution model:
+  [`docs/how-to/migrate-to-0.3.0-scoped-execution.md`](docs/how-to/migrate-to-0.3.0-scoped-execution.md)
 - Learn the canonical testing workflow:
   [`docs/how-to/test-use-cases.md`](docs/how-to/test-use-cases.md)
 - Check the guardrails before copying imports:
@@ -71,6 +73,8 @@ The documented path is intentionally narrow.
   `hexagonal.entrypoints`
 - Reach for `hexagonal.integrations.sqlalchemy` when you need the reusable
   SQLAlchemy repository and unit-of-work utilities
+- Treat scoped execution as the default mental model: shared datastore and
+  mapper, fresh write/read scope per operation
 - Treat `hexagonal.entrypoints.sqlalchemy` as adapter-specific convenience, not
   the whole framework story
 - Do not treat `hexagonal.__init__` as the public integration surface; right now

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/README.md

@@ -13,6 +13,8 @@ two-line snippet is enough.
   [`docs/explanation/architecture-from-example.md`](docs/explanation/architecture-from-example.md)
 - Bootstrap the adapter-specific SQLAlchemy path:
   [`docs/how-to/bootstrap-sqlalchemy-app.md`](docs/how-to/bootstrap-sqlalchemy-app.md)
+- Migrate existing apps to the scoped execution model:
+  [`docs/how-to/migrate-to-0.3.0-scoped-execution.md`](docs/how-to/migrate-to-0.3.0-scoped-execution.md)
 - Learn the canonical testing workflow:
   [`docs/how-to/test-use-cases.md`](docs/how-to/test-use-cases.md)
 - Check the guardrails before copying imports:
@@ -57,6 +59,8 @@ The documented path is intentionally narrow.
   `hexagonal.entrypoints`
 - Reach for `hexagonal.integrations.sqlalchemy` when you need the reusable
   SQLAlchemy repository and unit-of-work utilities
+- Treat scoped execution as the default mental model: shared datastore and
+  mapper, fresh write/read scope per operation
 - Treat `hexagonal.entrypoints.sqlalchemy` as adapter-specific convenience, not
   the whole framework story
 - Do not treat `hexagonal.__init__` as the public integration surface; right now

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-hexagonal"
-version = "0.2.0"
+version = "0.3.1"
 description = "Framework to build hexagonal architecture applications in Python."
 readme = "README.md"
 authors = [
@@ -26,6 +26,22 @@ module-name = "hexagonal"
 select = ["I", "E", "F", "B"]
 fixable = ["I", "E", "F", "B"]
 
+[tool.mypy]
+mypy_path = ["src"]
+python_version = "3.12"
+strict = true
+namespace_packages = true
+explicit_package_bases = true
+show_error_codes = true
+
+[[tool.mypy.overrides]]
+module = ["alembic", "alembic.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+disable_error_code = ["attr-defined", "no-untyped-call", "no-untyped-def", "var-annotated"]
+
 [dependency-groups]
 dev = [
     "alembic>=1.18.4",

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/buses/base/command_bus.py

@@ -4,7 +4,6 @@ from eventsourcing.utils import get_topic
 
 from hexagonal.domain import (
     CloudMessage,
-    Command,
     HandlerAlreadyRegistered,
     HandlerNotRegistered,
     TCommand,
@@ -36,14 +35,14 @@ class BaseCommandBus(ICommandBus[TManager], MessageBus[TManager]):
 
     def register_handler(
         self, command_type: Type[TCommand], handler: IMessageHandler[TCommand]
-    ):
+    ) -> None:
         self.verify()
         name = self._get_name(command_type)
         if name in self._handlers:
             raise HandlerAlreadyRegistered(f"Command: {name}")
         self._handlers[name] = handler
 
-    def unregister_handler(self, command_type: Type[TCommand]):
+    def unregister_handler(self, command_type: Type[TCommand]) -> None:
         self.verify()
         name = self._get_name(command_type)
         if name in self._handlers:
@@ -52,18 +51,16 @@ class BaseCommandBus(ICommandBus[TManager], MessageBus[TManager]):
             raise HandlerNotRegistered(f"Command: {name}")
 
     def dispatch(
-        self, command: TCommand | CloudMessage[TCommand], *, to_outbox: bool = False
+        self,
+        command: CloudMessage[TCommand],
+        *,
+        to_outbox: bool = False,
     ) -> None:
         self.verify()
-        cmd = (
-            command
-            if not isinstance(command, Command)
-            else CloudMessage[command.__class__].new(command)  # type: ignore
-        )
         if to_outbox:
-            self.outbox_repository.save(cmd)
+            self.save_to_outbox(command)
         else:
-            self.process_command(cmd)
+            self.process_command(command)
 
     def process_command(self, command: CloudMessage[TCommand]) -> None:
         self._process_messages(command)

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/buses/base/event_bus.py

@@ -21,22 +21,36 @@ logger = logging.getLogger(__name__)
 class HandlerError(Exception):
     def __init__(
         self,
-        evento: CloudMessage[TEvento],
+        evento: CloudMessage[TEvento] | TEvento,
         handler: IMessageHandler[TEvent] | Callable[..., None],
         error: Exception,
-    ):
-        super().__init__(f"""
-Error al Manejar Evento {evento.__class__.__name__}
-    handler: {
-            handler.__class__.__name__  # pyright: ignore[reportUnknownMemberType]
+    ) -> None:
+        handler_name = (
+            handler.__class__.__name__
             if isinstance(handler, IMessageHandler)
             else handler.__name__
-        }   
-    evento: {evento.type}
-    datos: {evento.model_dump_json(indent=2)}
+        )
+        event_name = (
+            evento.__class__.__name__
+            if not isinstance(evento, CloudMessage)
+            else evento.payload.__class__.__name__
+        )
+        event_topic = (
+            evento.TOPIC if not isinstance(evento, CloudMessage) else evento.type
+        )
+        event_dump = (
+            evento.model_dump_json(indent=2)
+            if not isinstance(evento, CloudMessage)
+            else evento.model_dump_json(indent=2)
+        )
+        super().__init__(f"""
+Error al Manejar Evento {event_name}
+    handler: {handler_name}
+    evento: {event_topic}
+    datos: {event_dump}
     error: {error}
     stacktrace: {error.__traceback__}
-        """)  # type: ignore  # noqa: E501
+        """)
 
 
 class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
@@ -52,6 +66,9 @@ class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
     def _get_key(self, obj: Type[TEvent] | IMessageHandler[TEvent]) -> str:
         if not isinstance(obj, IMessageHandler):
             return get_topic(obj)
+        handler_key = getattr(obj, "handler_key", None)
+        if isinstance(handler_key, str):
+            return handler_key
         try:
             return get_topic(obj.__class__)
         except TopicError as e:
@@ -59,7 +76,9 @@ class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
                 f"Handler: {obj.__class__}, error: {e}"
             ) from e
 
-    def subscribe(self, event_type: Type[TEvent], handler: IMessageHandler[TEvent]):
+    def subscribe(
+        self, event_type: Type[TEvent], handler: IMessageHandler[TEvent]
+    ) -> None:
         self.verify()
         key_event = self._get_key(event_type)
         handlers = self.handlers.get(key_event, {})
@@ -69,7 +88,9 @@ class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
         handlers[key_handler] = handler
         self.handlers[key_event] = handlers
 
-    def unsubscribe(self, event_type: Type[TEvent], *handlers: IMessageHandler[TEvent]):
+    def unsubscribe(
+        self, event_type: Type[TEvent], *handlers: IMessageHandler[TEvent]
+    ) -> None:
         self.verify()
         key_event = self._get_key(event_type)
         if not handlers:
@@ -88,7 +109,9 @@ class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
         if not list(self.handlers[key_event].values()):
             del self.handlers[key_event]
 
-    def _wait_for(self, event_type: Type[TEvent], handler: Callable[[TEvent], None]):
+    def _wait_for(
+        self, event_type: Type[TEvent], handler: Callable[[TEvent], None]
+    ) -> None:
         name = self._get_key(event_type)
         if name not in self.wait_list:
             self.wait_list[name] = []
@@ -99,7 +122,7 @@ class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
             len(self.wait_list[name]),
         )
 
-    def _handle_wait_list(self, event: TEvento):
+    def _handle_wait_list(self, event: TEvento) -> None:
         event_type = type(event)
         key = self._get_key(event_type)
         logger.debug("    [DEBUG _handle_wait_list] Publishing event type=%s", key)
@@ -112,14 +135,17 @@ class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
             logger.debug("    [DEBUG _handle_wait_list] No handlers registered!")
         while wait_list:
             if self.raise_error:
-                handler = wait_list.pop()
-                handler(event)
+                immediate_handler = wait_list.pop()
+                immediate_handler(event)
             else:
+                queued_handler: Callable[[TEvento], None] | None = None
                 try:
-                    handler = wait_list.pop()
-                    handler(event)
+                    queued_handler = wait_list.pop()
+                    queued_handler(event)
                 except Exception as e:
-                    raise HandlerError(event, handler, e) from e  # type: ignore
+                    if queued_handler is None:
+                        raise
+                    raise HandlerError(event, queued_handler, e) from e
 
     @overload
     def wait_for_publish(
@@ -136,9 +162,10 @@ class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
     ) -> Callable[[Callable[[TEvent], None]], None] | None:
         self.verify()
         if handler:
-            return self._wait_for(event_type, handler)
+            self._wait_for(event_type, handler)
+            return None
 
-        def decorator(func: Callable[[TEvent], None]):
+        def decorator(func: Callable[[TEvent], None]) -> None:
             self._wait_for(event_type, func)
 
         return decorator
@@ -169,4 +196,4 @@ class BaseEventBus(IEventBus[TManager], MessageBus[TManager]):
             logger.error(e)
 
     def process_events(self, *events: CloudMessage[TEvent]) -> None:
-        return self._process_messages(*events)
+        self._process_messages(*events)

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/buses/base/infrastructure.py

@@ -16,23 +16,23 @@ class BaseBusInfrastructure(IBusInfrastructure[TManager], InfrastructureGroup):
         event_bus: IEventBus[TManager],
         query_bus: IQueryBus[TManager],
         *args: IBaseInfrastructure,
-    ):
+    ) -> None:
         self._command_bus = command_bus
         self._event_bus = event_bus
         self._query_bus = query_bus
         super().__init__(self._command_bus, self._event_bus, self._query_bus, *args)
 
     @property
-    def command_bus(self):
+    def command_bus(self) -> ICommandBus[TManager]:
         self.verify()
         return self._command_bus
 
     @property
-    def event_bus(self):
+    def event_bus(self) -> IEventBus[TManager]:
         self.verify()
         return self._event_bus
 
     @property
-    def query_bus(self):
+    def query_bus(self) -> IQueryBus[TManager]:
         self.verify()
         return self._query_bus

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/buses/base/message_bus.py

@@ -1,5 +1,5 @@
 from abc import abstractmethod
-from typing import Any
+from typing import Any, Callable
 
 from hexagonal.application import Infrastructure
 from hexagonal.domain import CloudMessage
@@ -9,6 +9,7 @@ from hexagonal.ports.drivens import (
     IOutboxRepository,
     TManager,
 )
+from hexagonal.ports.drivens.scoped import IWriteScopeRunner, TWriteScope
 
 
 class MessageBus(IBaseMessageBus[TManager], Infrastructure):
@@ -16,9 +17,13 @@ class MessageBus(IBaseMessageBus[TManager], Infrastructure):
         self,
         inbox_repository: IInboxRepository[TManager],
         outbox_repository: IOutboxRepository[TManager],
-    ):
+    ) -> None:
         self._inbox_repository = inbox_repository
         self._outbox_repository = outbox_repository
+        self._write_scope_runner: IWriteScopeRunner[Any] | None = None
+        self._outbox_repository_getter: (
+            Callable[[Any], IOutboxRepository[TManager]] | None
+        ) = None
         super().__init__()
 
     @property
@@ -29,19 +34,59 @@ class MessageBus(IBaseMessageBus[TManager], Infrastructure):
     def outbox_repository(self) -> IOutboxRepository[TManager]:
         return self._outbox_repository
 
+    def configure_scope_runtime(
+        self,
+        *,
+        write_scope_runner: IWriteScopeRunner[TWriteScope] | None = None,
+        outbox_repository_getter: Callable[[TWriteScope], IOutboxRepository[TManager]]
+        | None = None,
+    ) -> None:
+        self._write_scope_runner = write_scope_runner
+        self._outbox_repository_getter = outbox_repository_getter
+
+    def save_to_outbox(self, *messages: CloudMessage[Any]) -> None:
+        self.verify()
+        self._run_with_outbox_repository(
+            lambda outbox_repository: outbox_repository.save(*messages)
+        )
+
     # publish
-    def publish_from_outbox(self, limit: int | None = None):
+    def publish_from_outbox(self, limit: int | None = None) -> None:
         self.verify()
-        messages = self.outbox_repository.fetch_pending(limit=limit)
-        self._publish_messages(*messages)
+        self._run_with_outbox_repository(
+            lambda outbox_repository: self._publish_messages(
+                outbox_repository,
+                *outbox_repository.fetch_pending(limit=limit),
+            )
+        )
+
+    def _run_with_outbox_repository(
+        self,
+        work: Callable[[IOutboxRepository[TManager]], Any],
+    ) -> Any:
+        if self._write_scope_runner is None or self._outbox_repository_getter is None:
+            return work(self.outbox_repository)
+
+        outbox_repository_getter = self._outbox_repository_getter
+        scope = self._write_scope_runner.current_write_scope
+        if scope is not None:
+            return work(outbox_repository_getter(scope))
+
+        return self._write_scope_runner.run_in_write_scope(
+            lambda write_scope: work(outbox_repository_getter(write_scope))
+        )
 
-    def _publish_messages(self, *messages: CloudMessage[Any]) -> None:
+    def _publish_messages(
+        self,
+        outbox_repository: IOutboxRepository[TManager],
+        *messages: CloudMessage[Any],
+    ) -> None:
         for message in messages:
             try:
                 self._publish_message(message)
-                self.outbox_repository.mark_as_published(message.message_id)
+                outbox_repository.mark_as_published(message.message_id)
             except Exception as e:
-                self.outbox_repository.mark_as_failed(message.message_id, error=str(e))
+                outbox_repository.mark_as_failed(message.message_id, error=str(e))
 
     @abstractmethod
     def _publish_message(self, message: CloudMessage[Any]) -> None: ...

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/buses/base/query.py

@@ -15,6 +15,7 @@ from hexagonal.domain import (
     TView,
 )
 from hexagonal.ports.drivens import IQueryBus, IQueryHandler, TManager
+from hexagonal.ports.drivens.scoped import IReadScopeRunner
 
 
 class QueryBus(IQueryBus[TManager], Infrastructure):
@@ -22,8 +23,14 @@ class QueryBus(IQueryBus[TManager], Infrastructure):
 
     def initialize(self, env: Mapping[str, str]) -> None:
         self.handlers = {}
+        self._read_scope_runner: IReadScopeRunner[Any] | None = None
         super().initialize(env)
 
+    def configure_read_scope_runtime(
+        self, read_scope_runner: IReadScopeRunner[Any] | None = None
+    ) -> None:
+        self._read_scope_runner = read_scope_runner
+
     def _get_name(self, query_type: Type[QueryBase[TView]]) -> str:
         return get_topic(query_type)
 
@@ -37,14 +44,14 @@ class QueryBus(IQueryBus[TManager], Infrastructure):
         self,
         query_type: Type[TQuery],
         handler: IQueryHandler[TManager, TQuery, TView],
-    ):
+    ) -> None:
         self.verify()
         name = self._get_name(query_type)
         if name in self.handlers:
             raise HandlerAlreadyRegistered(f"Query: {name}")
         self.handlers[name] = handler
 
-    def unregister_handler(self, query_type: Type[TQuery]):
+    def unregister_handler(self, query_type: Type[TQuery]) -> None:
         self.verify()
         name = self._get_name(query_type)
         if name in self.handlers:

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/buses/inmemory/command_bus.py

@@ -16,7 +16,7 @@ class InMemoryCommandBus(BaseCommandBus[TManager]):
     def _publish_message(self, message: CloudMessage[TCommand]) -> None:
         return self._process_messages(message)
 
-    def consume(self, limit: int | None = None):
+    def consume(self, limit: int | None = None) -> None:
         return  # No-op for non-queued bus
 
 
@@ -66,5 +66,5 @@ class InMemoryQueueCommandBus(BaseCommandBus[TManager]):
             finally:
                 self.queue.task_done()
 
-    def consume(self, limit: int | None = None):
+    def consume(self, limit: int | None = None) -> None:
         self._worker.start()

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/buses/inmemory/event_bus.py

@@ -15,6 +15,9 @@ logger = logging.getLogger(__name__)
 
 
 class InMemoryEventBus(BaseEventBus[TManager]):
+    def shutdown(self) -> None:
+        return
+
     def _publish_message(self, message: CloudMessage[TEvento]) -> None:
         super()._publish_message(message)
         self._process_messages(message)
@@ -22,7 +25,7 @@ class InMemoryEventBus(BaseEventBus[TManager]):
     def publish(self, *events: CloudMessage[TEvent]) -> None:
         return self._publish_messages(*events)
 
-    def consume(self, limit: int | None = None):
+    def consume(self, limit: int | None = None) -> None:
         pass  # No-op for non-queued bus
 
 
@@ -68,5 +71,5 @@ class InMemoryQueueEventBus(BaseEventBus[TManager]):
             finally:
                 self.queue.task_done()
 
-    def consume(self, limit: int | None = None):
+    def consume(self, limit: int | None = None) -> None:
         self._worker.start()

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/mappers.py

@@ -91,8 +91,8 @@ class MessageMapper(Mapper[UUID]):
             getattr(cls, f"upcast_v{from_version}_v{from_version + 1}")(event_state)
             from_version += 1
         if issubclass(cls, AggregateSnapshot):
-            return cls.model_validate(event_state)  # type: ignore[return-value]
-        domain_event = object.__new__(cls)
+            return cast(DomainEventProtocol[UUID], cls.model_validate(event_state))
+        domain_event = cast(DomainEventProtocol[UUID], object.__new__(cls))
         domain_event.__dict__.update(event_state)
         return domain_event
 

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/repository/base/repository.py

@@ -38,22 +38,19 @@ class BaseRepositoryAdapter(IBaseRepository[TManager], Infrastructure):
         name = self.NAME or self.__class__.__name__.upper()
         env2.update(env)
         self.env = Environment(name, env2)
-        self._attached_to_uow = False
-        self._manager_at_uow: TManager | None = None
+        self._scope_connection_manager: TManager | None = None
         super().initialize(self.env)
 
     def attach_to_unit_of_work(self, uow: IUnitOfWork[TManager]) -> None:
-        self._attached_to_uow = True
-        self._manager_at_uow = uow.connection_manager
+        self._scope_connection_manager = uow.connection_manager
 
     def detach_from_unit_of_work(self) -> None:
-        self._attached_to_uow = False
-        self._manager_at_uow = None
+        self._scope_connection_manager = None
 
     @property
     def connection_manager(self) -> TManager:
-        if self._attached_to_uow and self._manager_at_uow is not None:
-            return self._manager_at_uow
+        if self._scope_connection_manager is not None:
+            return self._scope_connection_manager
         return self._connection_manager
 
 

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/repository/base/unit_of_work.py

@@ -1,4 +1,5 @@
-from typing import Mapping
+from types import TracebackType
+from typing import Any, Mapping, cast
 
 from eventsourcing.utils import get_topic
 
@@ -11,7 +12,7 @@ class BaseUnitOfWork(IUnitOfWork[TManager], InfrastructureGroup):
         self,
         *repositories: IBaseRepository[TManager],
         connection_manager: TManager,
-    ):
+    ) -> None:
         self._repositories = {get_topic(repo.__class__): repo for repo in repositories}
         self._initialized = False
         self._manager = connection_manager
@@ -20,20 +21,26 @@ class BaseUnitOfWork(IUnitOfWork[TManager], InfrastructureGroup):
     def initialize(self, env: Mapping[str, str]) -> None:
         self._initialized = True
         self._active = False
+        self._attached_repositories: list[IBaseRepository[TManager]] = []
         return super().initialize(env)
 
     @property
     def initialized(self) -> bool:
         return self._initialized and super().initialized
 
-    def attach_repo(self, repo: IBaseRepository[TManager]):
+    def attach_repo(self, repo: IBaseRepository[TManager]) -> None:
         topic = get_topic(repo.__class__)
         if topic in self._repositories:
             return
 
         self._repositories[topic] = repo
-        if self.initialized and self._active:
+        if (
+            self.initialized
+            and self._active
+            and repo.connection_manager is not self._manager
+        ):
             repo.attach_to_unit_of_work(self)
+            self._attached_repositories.append(repo)
 
     def detach_repo(self, repo: IBaseRepository[TManager]) -> None:
         topic = get_topic(repo.__class__)
@@ -45,21 +52,30 @@ class BaseUnitOfWork(IUnitOfWork[TManager], InfrastructureGroup):
         del self._repositories[topic]
 
     @property
-    def connection_manager(self):
+    def connection_manager(self) -> TManager:
         return self._manager
 
-    def __enter__(self):
+    def __enter__(self) -> "BaseUnitOfWork[TManager]":
         self.verify()
         if self._active:
             return self
         # get connection from manager, the connection is entered yet
         self._ctx = self._manager.start_connection()
+        self._attached_repositories = []
         for repo in self._repositories.values():
+            if repo.connection_manager is self._manager:
+                continue
             repo.attach_to_unit_of_work(self)
+            self._attached_repositories.append(repo)
         self._active = True
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):  # type: ignore
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
         self._active = False
         try:
             if exc_type is None:
@@ -70,6 +86,6 @@ class BaseUnitOfWork(IUnitOfWork[TManager], InfrastructureGroup):
             # Log or handle commit/rollback errors
             raise RuntimeError(f"Failed to finalize transaction: {e}") from e
         finally:
-            for repo in self._repositories.values():
+            for repo in self._attached_repositories:
                 repo.detach_from_unit_of_work()
-            self._ctx.__exit__(exc_type, exc_val, exc_tb)  # type: ignore
+            cast(Any, self._ctx).__exit__(exc_type, exc_val, exc_tb)

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/repository/sqlalchemy/__init__.py

@@ -6,7 +6,7 @@ backends (PostgreSQL, MySQL, SQLite) through SQLAlchemy's abstraction layer.
 """
 
 from .datastore import SQLAlchemyConnectionContextManager, SQLAlchemyDatastore
-from .infrastructure import SQLAlchemyInfrastructure
+from .infrastructure import SQLAlchemyInfrastructure, SQLAlchemyScopeRunner
 from .outbox import (
     SQLAlchemyInboxRepository,
     SQLAlchemyOutboxRepository,
@@ -27,6 +27,7 @@ __all__ = [
     "SQLAlchemyOutboxRepository",
     "SQLAlchemyInboxRepository",
     "SQLAlchemyInfrastructure",
+    "SQLAlchemyScopeRunner",
     "SQLAlchemyPairInboxOutbox",
     "SQLAlchemyEntityRepositoryAdapter",
     "SQLAlchemySearchRepositoryAdapter",

{python_hexagonal-0.2.0 → python_hexagonal-0.3.1}/src/hexagonal/adapters/drivens/repository/sqlalchemy/datastore.py

@@ -1,7 +1,7 @@
 """SQLAlchemy datastore and connection context manager."""
 
 from collections.abc import Iterator, Mapping
-from contextlib import contextmanager
+from contextlib import AbstractContextManager, contextmanager
 from typing import Any, Optional
 
 from eventsourcing.utils import strtobool
@@ -38,7 +38,7 @@ class SQLAlchemyDatastore:
         pool_recycle: int = 3600,
         pool_pre_ping: bool = True,
         max_overflow: int = 10,
-    ):
+    ) -> None:
         """Initialize SQLAlchemy datastore.
 
         Args:
@@ -142,7 +142,7 @@ class SQLAlchemyConnectionContextManager(IConnectionManager):
     Maintains a current connection reference for transaction coordination.
     """
 
-    def __init__(self, datastore: Optional[SQLAlchemyDatastore] = None):
+    def __init__(self, datastore: Optional[SQLAlchemyDatastore] = None) -> None:
         """Initialize connection context manager.
 
         Args:
@@ -151,7 +151,7 @@ class SQLAlchemyConnectionContextManager(IConnectionManager):
         """
         self._datastore = datastore
         self._current_connection: Optional[Connection] = None
-        self._connection_ctx: Optional[Any] = None
+        self._connection_ctx: Optional[AbstractContextManager[Connection]] = None
         self._initialized = datastore is not None
 
     @property
@@ -213,7 +213,10 @@ class SQLAlchemyConnectionContextManager(IConnectionManager):
         )
         self._initialized = True
 
-    def start_connection(self):
+    def create_scoped_manager(self) -> "SQLAlchemyConnectionContextManager":
+        return SQLAlchemyConnectionContextManager(self.datastore)
+
+    def start_connection(self) -> Any:
         """Start a new connection context.
 
         Returns:
@@ -280,7 +283,7 @@ class SQLAlchemyConnectionContextManager(IConnectionManager):
                 self._current_connection = None
                 conn = self.current_connection
             yield conn
-            if commit:
+            if commit and conn.in_transaction():
                 conn.commit()
         except Exception:
             # Reset connection on error