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

python_hexagonal-0.2.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.3
+Name: python-hexagonal
+Version: 0.2.0
+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
+
+`python-hexagonal` is a library for building hexagonal applications in Python.
+The real usage story lives in `src/example` and the proof lives in
+`src/tests/use_cases`, so this documentation starts there instead of pretending a
+two-line snippet is enough.
+
+## Start here
+
+- Install the package: `pip install python-hexagonal`
+- Follow the example-backed guide: [`docs/getting-started/first-app.md`](docs/getting-started/first-app.md)
+- Understand the architecture roles:
+  [`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)
+- 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:
+  [`docs/reference/supported-surface.md`](docs/reference/supported-surface.md)
+- Review the evidence map if you want to verify a claim against code or tests:
+  [`docs/reference/evidence-map.yaml`](docs/reference/evidence-map.yaml)
+
+## What you learn from the first path
+
+After the first-app guide you should understand:
+
+- where the domain model lives and why it stays isolated
+- how application APIs wrap command, query, and event buses
+- how ports describe the infrastructure your app needs
+- how entrypoints assemble an app from environment and infrastructure
+- how the use-case tests prove the workflow end to end
+
+## The blueprint we actually trust
+
+These files are the baseline for the supported adoption story:
+
+- `src/example/contacto/domain/contacto.py` - aggregate behavior, value-object
+  strategy, and query entry points
+- `src/example/contacto/application/app.py` - application composition through
+  `BusAppGroup`
+- `src/example/contacto/ports/drivens.py` - infrastructure contracts and
+  repository boundaries
+- `src/example/app/application/api.py` - top-level API wrapper consumers call
+- `src/example/app/entrypoints/main.py` - environment-driven bootstrap via
+  `EntrypointGroup`
+- `src/example/app/entrypoints/db/sqlalchemy.py` - SQLAlchemy-specific
+  infrastructure assembly
+- `src/tests/use_cases/base.py` - canonical test bootstrap with migrations,
+  entrypoint creation, and topic registration
+
+## Supported path vs internals
+
+The documented path is intentionally narrow.
+
+- Start from `hexagonal.domain`, `hexagonal.application`,
+  `hexagonal.ports.drivens`, `hexagonal.ports.drivers`, and
+  `hexagonal.entrypoints`
+- Reach for `hexagonal.integrations.sqlalchemy` when you need the reusable
+  SQLAlchemy repository and unit-of-work utilities
+- 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
+  it only exposes `hello()`
+- Do not cargo-cult example names like `exampleAPI`, `exampleEntrypoint`, or
+  `Exampletate`; copy the roles, not the labels
+- Do not build new code against `hexagonal.adapters.*`; that path is kept for
+  compatibility, while the supported SQLAlchemy extension surface now lives under
+  `hexagonal.integrations.sqlalchemy`
+
+## Companion skill
+
+This repo also ships an installable companion skill at
+`skills/python-hexagonal-usage/SKILL.md`.
+It is there to inspect a user repository, map it to the same architecture, and
+point people back to the written docs. It does NOT replace the docs and it does
+NOT get to invent new supported APIs.

python_hexagonal-0.2.0/README.md

@@ -0,0 +1,76 @@
+# python-hexagonal
+
+`python-hexagonal` is a library for building hexagonal applications in Python.
+The real usage story lives in `src/example` and the proof lives in
+`src/tests/use_cases`, so this documentation starts there instead of pretending a
+two-line snippet is enough.
+
+## Start here
+
+- Install the package: `pip install python-hexagonal`
+- Follow the example-backed guide: [`docs/getting-started/first-app.md`](docs/getting-started/first-app.md)
+- Understand the architecture roles:
+  [`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)
+- 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:
+  [`docs/reference/supported-surface.md`](docs/reference/supported-surface.md)
+- Review the evidence map if you want to verify a claim against code or tests:
+  [`docs/reference/evidence-map.yaml`](docs/reference/evidence-map.yaml)
+
+## What you learn from the first path
+
+After the first-app guide you should understand:
+
+- where the domain model lives and why it stays isolated
+- how application APIs wrap command, query, and event buses
+- how ports describe the infrastructure your app needs
+- how entrypoints assemble an app from environment and infrastructure
+- how the use-case tests prove the workflow end to end
+
+## The blueprint we actually trust
+
+These files are the baseline for the supported adoption story:
+
+- `src/example/contacto/domain/contacto.py` - aggregate behavior, value-object
+  strategy, and query entry points
+- `src/example/contacto/application/app.py` - application composition through
+  `BusAppGroup`
+- `src/example/contacto/ports/drivens.py` - infrastructure contracts and
+  repository boundaries
+- `src/example/app/application/api.py` - top-level API wrapper consumers call
+- `src/example/app/entrypoints/main.py` - environment-driven bootstrap via
+  `EntrypointGroup`
+- `src/example/app/entrypoints/db/sqlalchemy.py` - SQLAlchemy-specific
+  infrastructure assembly
+- `src/tests/use_cases/base.py` - canonical test bootstrap with migrations,
+  entrypoint creation, and topic registration
+
+## Supported path vs internals
+
+The documented path is intentionally narrow.
+
+- Start from `hexagonal.domain`, `hexagonal.application`,
+  `hexagonal.ports.drivens`, `hexagonal.ports.drivers`, and
+  `hexagonal.entrypoints`
+- Reach for `hexagonal.integrations.sqlalchemy` when you need the reusable
+  SQLAlchemy repository and unit-of-work utilities
+- 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
+  it only exposes `hello()`
+- Do not cargo-cult example names like `exampleAPI`, `exampleEntrypoint`, or
+  `Exampletate`; copy the roles, not the labels
+- Do not build new code against `hexagonal.adapters.*`; that path is kept for
+  compatibility, while the supported SQLAlchemy extension surface now lives under
+  `hexagonal.integrations.sqlalchemy`
+
+## Companion skill
+
+This repo also ships an installable companion skill at
+`skills/python-hexagonal-usage/SKILL.md`.
+It is there to inspect a user repository, map it to the same architecture, and
+point people back to the written docs. It does NOT replace the docs and it does
+NOT get to invent new supported APIs.

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

@@ -1,6 +1,6 @@
 [project]
 name = "python-hexagonal"
-version = "0.1.2"
+version = "0.2.0"
 description = "Framework to build hexagonal architecture applications in Python."
 readme = "README.md"
 authors = [
@@ -28,7 +28,9 @@ fixable = ["I", "E", "F", "B"]
 
 [dependency-groups]
 dev = [
+    "alembic>=1.18.4",
     "pytest>=9.0.2",
+    "python-dotenv>=1.2.2",
 ]
 sqlalchemy = [
     "sqlalchemy>=2.0.45",

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

{python_hexagonal-0.1.2 → python_hexagonal-0.2.0}/src/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.
 

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

@@ -123,6 +123,8 @@ class MessageMapper(Mapper[UUID]):
 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
 
 

{python_hexagonal-0.1.2 → python_hexagonal-0.2.0}/src/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",
 ]

{python_hexagonal-0.1.2 → python_hexagonal-0.2.0}/src/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],
+): ...

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

@@ -12,7 +12,11 @@ from .outbox import (
     SQLAlchemyOutboxRepository,
     SQLAlchemyPairInboxOutbox,
 )
-from .repository import SQLAlchemyRepositoryAdapter
+from .repository import (
+    SQLAlchemyEntityRepositoryAdapter,
+    SQLAlchemyRepositoryAdapter,
+    SQLAlchemySearchRepositoryAdapter,
+)
 from .unit_of_work import SQLAlchemyUnitOfWork
 
 __all__ = [
@@ -24,4 +28,6 @@ __all__ = [
     "SQLAlchemyInboxRepository",
     "SQLAlchemyInfrastructure",
     "SQLAlchemyPairInboxOutbox",
+    "SQLAlchemyEntityRepositoryAdapter",
+    "SQLAlchemySearchRepositoryAdapter",
 ]

{python_hexagonal-0.1.2 → python_hexagonal-0.2.0}/src/hexagonal/adapters/drivens/repository/sqlalchemy/models.py

@@ -19,7 +19,7 @@ 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:
+    if schema and schema != "":
         return f"{schema}.{table_name}"
     return table_name
 
@@ -34,6 +34,7 @@ def create_aggregates_table(table_name: str, schema: str | None = None) -> Table
     Returns:
         SQLAlchemy Table object for aggregate snapshots
     """
+    schema = schema if schema and schema != "" else None
     full_table_name = f"aggregates_{table_name}"
     table_key = _get_table_key(full_table_name, schema)
 
@@ -45,7 +46,7 @@ def create_aggregates_table(table_name: str, schema: str | None = None) -> Table
         full_table_name,
         metadata,
         Column("originator_id", String(36), nullable=False),
-        Column("aggregate_name", Text, nullable=False),
+        Column("aggregate_name", String(255), nullable=False),
         Column("originator_version", Integer, nullable=False),
         Column("topic", Text, nullable=False),
         Column("state", LargeBinary, nullable=False),
@@ -66,6 +67,7 @@ def create_events_table(table_name: str, schema: str | None = None) -> Table:
     Returns:
         SQLAlchemy Table object for aggregate events history
     """
+    schema = schema if schema and schema != "" else None
     full_table_name = f"aggregates_{table_name}_events"
     table_key = _get_table_key(full_table_name, schema)
 
@@ -77,7 +79,7 @@ def create_events_table(table_name: str, schema: str | None = None) -> Table:
         full_table_name,
         metadata,
         Column("originator_id", String(36), nullable=False),
-        Column("aggregate_name", Text, nullable=False),
+        Column("aggregate_name", String(255), nullable=False),
         Column("originator_version", Integer, nullable=False),
         Column("topic", Text, nullable=False),
         Column("state", LargeBinary, nullable=False),
@@ -97,6 +99,7 @@ def create_outbox_table(table_name: str = "outbox", schema: str | None = None) -
     Returns:
         SQLAlchemy Table object for outbox messages
     """
+    schema = schema if schema and schema != "" else None
     table_key = _get_table_key(table_name, schema)
 
     # Return existing table if already defined
@@ -107,7 +110,7 @@ def create_outbox_table(table_name: str = "outbox", schema: str | None = None) -
         table_name,
         metadata,
         Column("message_id", String(36), primary_key=True),
-        Column("topic", Text, nullable=False),
+        Column("topic", String(255), nullable=False),
         Column("message", LargeBinary, nullable=False),
         Column("published_at", DateTime(timezone=True), nullable=True),
         Column("failed_at", DateTime(timezone=True), nullable=True),
@@ -134,6 +137,7 @@ def create_inbox_table(table_name: str = "inbox", schema: str | None = None) ->
     Returns:
         SQLAlchemy Table object for inbox messages
     """
+    schema = schema if schema and schema != "" else None
     table_key = _get_table_key(table_name, schema)
 
     # Return existing table if already defined
@@ -144,7 +148,7 @@ def create_inbox_table(table_name: str = "inbox", schema: str | None = None) ->
         table_name,
         metadata,
         Column("message_id", String(36), nullable=False),
-        Column("handler", Text, nullable=False),
+        Column("handler", String(255), nullable=False),
         Column("received_at", DateTime(timezone=True), nullable=False),
         Column("processed_at", DateTime(timezone=True), nullable=True),
         Column("error", Text, nullable=True),

{python_hexagonal-0.1.2 → python_hexagonal-0.2.0}/src/hexagonal/adapters/drivens/repository/sqlalchemy/outbox.py

@@ -313,7 +313,7 @@ class SQLAlchemyInboxRepository(
 
     def _cursor(self):
         """Get the current connection for executing statements."""
-        return self._connection_manager.cursor()
+        return self.connection_manager.cursor()
 
     def create_tables(self) -> None:
         """Create the inbox table if it doesn't exist."""

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

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, ClassVar, Dict, Mapping, Sequence, Tuple, TypeVar, cast
+from abc import abstractmethod
+from typing import Any, ClassVar, Dict, Mapping, Sequence, Tuple, cast
 from uuid import UUID
 
 from eventsourcing.domain import CanMutateAggregate
@@ -11,24 +12,104 @@ from eventsourcing.persistence import StoredEvent
 from eventsourcing.utils import strtobool
 from sqlalchemy import Connection, delete, insert, select, update
 
-from hexagonal.adapters.drivens.repository.base import BaseAggregateRepositoryAdapter
+from hexagonal.adapters.drivens.repository.base import (
+    BaseAggregateRepositoryAdapter,
+    BaseEntityRepositoryAdapter,
+    BaseSearchRepositoryAdapter,
+)
 from hexagonal.domain import (
     AggregateNotFound,
-    AggregateRoot,
     AggregateSnapshot,
     AggregateVersionMismatch,
     SnapshotState,
+    TAggregate,
+    TEntity,
     TIdEntity,
+    TQuery,
+    TView,
 )
 
 from .datastore import SQLAlchemyConnectionContextManager
 from .models import create_aggregates_table, create_events_table
 
-TAggregate = TypeVar("TAggregate", bound=AggregateRoot[Any, Any])
-
 logger = logging.getLogger(__name__)
 
 
+class SQLAlchemyEntityRepositoryAdapter(
+    BaseEntityRepositoryAdapter[SQLAlchemyConnectionContextManager, TEntity, TIdEntity]
+):
+    """SQLAlchemy repository adapter for entities.
+
+    This adapter implements the IEntityRepository interface using SQLAlchemy
+    as the backing store. It handles the persistence and retrieval of entities.
+
+    Supports multiple database backends (PostgreSQL, MySQL, SQLite) through
+    SQLAlchemy's abstraction layer.
+
+    Args:
+        mapper: Mapper for converting between domain and persistence models
+        connection_manager: SQLAlchemy connection context manager
+    """
+
+    def initialize(self, env: Mapping[str, str]) -> None:
+        """Initialize the repository from environment variables."""
+        super().initialize(env)
+        self._schema_name: str | None = self.env.get("SCHEMA_NAME")
+
+    def _get(self, conn: Connection, id: TIdEntity) -> TEntity | None:
+        """Fetch entity from database."""
+        # Implement entity retrieval logic using SQLAlchemy
+        # This is a placeholder implementation and should be replaced with actual logic
+        return None
+
+    def _insert(self, conn: Connection, entity: TEntity) -> None:
+        """Save an entity to the database."""
+        # Implement entity persistence logic using SQLAlchemy
+        # This is a placeholder implementation and should be replaced with actual logic
+        pass
+
+    def _update(self, conn: Connection, entity: TEntity) -> None:
+        """Update an existing entity in the database."""
+        # Implement entity update logic using SQLAlchemy
+        # This is a placeholder implementation and should be replaced with actual logic
+        pass
+
+    def _delete(self, conn: Connection, id: TIdEntity) -> None:
+        """Delete an entity from the database."""
+        # Implement entity deletion logic using SQLAlchemy
+        # This is a placeholder implementation and should be replaced with actual logic
+        pass
+
+    def get(self, id: TIdEntity) -> TEntity:
+        """Get an entity by its ID."""
+        self.verify()
+        with self.connection_manager.cursor() as conn:
+            entity = self._get(conn, id)
+        if entity is None:
+            raise AggregateNotFound(f"Entity with id {id} not found")
+        return entity
+
+    def save(self, entity: TEntity):
+        """Save an entity to the repository."""
+        self.verify()
+        with self.connection_manager.cursor() as conn:
+            existing = self._get(conn, entity.id)
+            if existing is None:
+                self._insert(conn, entity)
+            else:
+                self._update(conn, entity)
+
+    def delete(self, id: TIdEntity) -> TEntity:
+        """Delete an entity from the repository."""
+        self.verify()
+        with self.connection_manager.cursor() as conn:
+            entity = self._get(conn, id)
+            if entity is None:
+                raise AggregateNotFound(f"Entity with id {id} not found")
+            self._delete(conn, id)
+        return entity
+
+
 class SQLAlchemyRepositoryAdapter(
     BaseAggregateRepositoryAdapter[
         SQLAlchemyConnectionContextManager, TAggregate, TIdEntity
@@ -322,3 +403,40 @@ class SQLAlchemyRepositoryAdapter(
             self._save_event_history(conn, events)
             self._delete(conn, id)
         return agg
+
+
+class SQLAlchemySearchRepositoryAdapter(
+    BaseSearchRepositoryAdapter[SQLAlchemyConnectionContextManager, TQuery, TView]
+):
+    """SQLAlchemy repository adapter for search queries.
+
+    This adapter implements the ISearchRepository interface using SQLAlchemy
+    as the backing store. It handles executing search queries and returning
+    results in a view format.
+
+    Supports multiple database backends (PostgreSQL, MySQL, SQLite) through
+    SQLAlchemy's abstraction layer.
+
+    Args:
+        mapper: Mapper for converting between domain and persistence models
+        connection_manager: SQLAlchemy connection context manager
+    """
+
+    @abstractmethod
+    def _search(self, conn: Connection, query: TQuery) -> Sequence[TView]: ...
+
+    def search(self, query: TQuery) -> Sequence[TView]:
+        """Execute a search query against the repository.
+
+        Args:
+            query: The search query to execute
+
+        Returns:
+            A sequence of view objects matching the query criteria
+
+        Raises:
+            RuntimeError: If not attached to a unit of work
+        """
+        self.verify()
+        with self.connection_manager.cursor() as conn:
+            return self._search(conn, query)

{python_hexagonal-0.1.2 → python_hexagonal-0.2.0}/src/hexagonal/application/__init__.py

@@ -1,15 +1,31 @@
-from .api import BaseAPI, GetEvent
+from .api import BaseAPI, GetEvent, TBaseApp
 from .app import Application
 from .bus_app import BusAppGroup, ComposableBusApp
-from .handlers import CommandHandler, EventHandler, MessageHandler, QueryHandler
+from .handlers import (
+    CommandHandler,
+    CommandHandlerBase,
+    EventHandler,
+    EventHandlerBase,
+    MessageHandler,
+    QueryHandler,
+)
 from .infrastructure import (
     ComposableInfrastructure,
     Infrastructure,
     InfrastructureGroup,
 )
-from .query import AggregateView, GetById, GetByIdHandler, SearchAggregateRepository
+from .query import (
+    AggregateView,
+    GetAggregateByIdHandler,
+    GetById,
+    GetByIdHandler,
+    GetEntityByIdHandler,
+    SearchAggregateRepository,
+)
+from .topics import RegisterTopics
 
 __all__ = [
+    "TBaseApp",
     "BaseAPI",
     "GetEvent",
     "Application",
@@ -26,4 +42,9 @@ __all__ = [
     "SearchAggregateRepository",
     "AggregateView",
     "GetByIdHandler",
+    "RegisterTopics",
+    "GetAggregateByIdHandler",
+    "GetEntityByIdHandler",
+    "CommandHandlerBase",
+    "EventHandlerBase",
 ]