python-hexagonal 0.1.1__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.1 → python_hexagonal-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-hexagonal"
-version = "0.1.1"
+version = "0.2.0"
 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",
 ]
 
@@ -27,5 +28,10 @@ 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.1 → python_hexagonal-0.2.0}/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.1 → 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.1 → 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.1 → python_hexagonal-0.2.0}/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,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)

{python_hexagonal-0.1.1 → 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.1 → 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.2.0/src/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",
+]