python-hexagonal 0.1.0__py3-none-any.whl

hexagonal/domain/aggregate.py

@@ -0,0 +1,159 @@
+from datetime import datetime
+from typing import (
+    Any,
+    Generic,
+    Self,
+    Type,
+    TypeVar,
+    get_args,
+    get_origin,
+)
+from uuid import UUID
+
+from eventsourcing.domain import (
+    AggregateCreated,
+    AggregateEvent,
+    BaseAggregate,
+    CanSnapshotAggregate,
+    MutableOrImmutableAggregate,
+    event,
+)
+from eventsourcing.utils import get_topic
+from pydantic import ConfigDict, TypeAdapter
+from uuid6 import uuid7
+
+from .base import Inmutable, ValueObject
+
+command = event
+
+
+class IdValueObject(ValueObject[UUID]):
+    @classmethod
+    def new(cls, *_: Any, **__: Any) -> Self:
+        return cls(value=uuid7())
+
+
+TIdEntity = TypeVar("TIdEntity", bound=IdValueObject)
+datetime_adapter = TypeAdapter(datetime)
+
+
+class SnapshotState(Inmutable, Generic[TIdEntity]):
+    model_config = ConfigDict(extra="allow")
+    id: TIdEntity
+    created_on: datetime
+    modified_on: datetime
+
+    def __init__(self, **kwargs: Any) -> None:
+        for key in ["_created_on", "_modified_on"]:
+            kwargs[key.removeprefix("_")] = datetime_adapter.validate_python(
+                kwargs[key]
+            )
+        super().__init__(**kwargs)
+
+
+TSnapshotState = TypeVar("TSnapshotState", bound=SnapshotState[Any])
+
+
+class AggregateSnapshot(Inmutable, CanSnapshotAggregate[UUID], Generic[TSnapshotState]):
+    originator_id: UUID
+    originator_version: int
+    timestamp: datetime
+    topic: str
+    state: TSnapshotState
+
+    @classmethod
+    def take(
+        cls,
+        aggregate: MutableOrImmutableAggregate[UUID],
+    ) -> Self:
+        """Creates a snapshot of the given :class:`Aggregate` object."""
+        aggregate_state = dict(aggregate.__dict__)
+        class_version = getattr(type(aggregate), "class_version", 1)
+        if class_version > 1:
+            aggregate_state["class_version"] = class_version
+        if isinstance(aggregate, AggregateRoot):
+            aggregate.complete_snapshot_state(aggregate_state)
+            aggregate_state.pop("_id")
+            aggregate_state.pop("_version")
+            aggregate_state.pop("_pending_events")
+        dict_snap = dict(
+            originator_id=aggregate.id,  # type: ignore[call-arg]
+            originator_version=aggregate.version,  # pyright: ignore[reportCallIssue]
+            timestamp=cls.create_timestamp(),  # pyright: ignore[reportCallIssue]
+            topic=get_topic(type(aggregate)),  # type: ignore[call-arg]
+            state=aggregate_state,  # pyright: ignore[reportCallIssue]
+        )
+        return cls.model_validate(dict_snap)
+
+
+class AggregateRoot(BaseAggregate[UUID], Generic[TIdEntity, TSnapshotState]):
+    _id_type: Type[TIdEntity]
+
+    Snapshot: Type[AggregateSnapshot[TSnapshotState]]
+
+    class Event(AggregateEvent):
+        pass
+
+    class Created(Event, AggregateCreated):
+        pass
+
+    class Deleted(Event):
+        def mutate(self, aggregate: Any) -> Any:
+            super().mutate(aggregate)
+            return None
+
+    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 issubclass(origin, AggregateRoot):
+                args = get_args(base)
+                if args:
+                    cls._id_type = args[0]
+                    state_type = args[1]
+
+                    cls.Snapshot = AggregateSnapshot[state_type]  # type: ignore[valid-type]
+
+    @classmethod
+    def create_id(cls, *args: Any, **kwargs: Any):
+        return cls._id_type.new(*args, **kwargs).value
+
+    @property
+    def value_id(self) -> TIdEntity:
+        # Instantiate the captured type using the stored `id` value
+        try:
+            return self._id_type(value=self.id)
+        except Exception as e:
+            raise ValueError(
+                f"Cannot instantiate {self._id_type} with value {self.id}: {e}"
+            ) from e
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, AggregateRoot):
+            return False
+        return self.value_id == other.value_id  # type: ignore
+
+    def __hash__(self) -> int:
+        return hash(self.value_id)
+
+    def complete_snapshot_state(self, state: dict[str, Any]) -> dict[str, Any]:
+        state["id"] = self.value_id
+        return state
+
+    @property
+    def state(self) -> TSnapshotState:
+        return self.Snapshot.take(self).state
+
+    @classmethod
+    def reconstruct_from_snapshot(
+        cls,
+        snapshot: AggregateSnapshot[TSnapshotState],
+    ) -> Self:
+        agg = snapshot.mutate(None)
+        assert isinstance(agg, cls)
+        return agg
+
+    def take_snapshot(self) -> AggregateSnapshot[TSnapshotState]:
+        return self.Snapshot.take(self)

hexagonal/domain/base.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any, ClassVar, Dict, Generic, Optional, Self, Type, TypeVar
+from uuid import UUID
+
+from eventsourcing.domain import CanCreateTimestamp
+from pydantic import BaseModel, ConfigDict, Field
+from uuid6 import uuid7
+
+
+class HasTopic:
+    TOPIC: ClassVar[str] = ""
+
+    def __init_subclass__(cls, *, topic_suffix: Optional[str] = None, **kwargs: Any):
+        # Extraemos nuestro argumento para no pasárselo a Pydantic
+        super().__init_subclass__(**kwargs)  # aquí Pydantic recibe sólo lo suyo
+        new_topic = topic_suffix or cls.__name__
+
+        # Buscamos el topic base más específico en toda la cadena de herencia
+        base_topic = ""
+        for base in cls.__mro__[1:]:  # Empezamos desde el padre más inmediato
+            if issubclass(base, HasTopic) and hasattr(base, "TOPIC") and base.TOPIC:
+                base_topic = base.TOPIC
+                break
+        actual_topic = cls.TOPIC
+        if actual_topic != base_topic:
+            set_topic = actual_topic
+        else:
+            set_topic = f"{base_topic}{'.' if base_topic != '' else ''}{new_topic}"
+        cls.TOPIC = set_topic  # type: ignore
+
+
+class Inmutable(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class FactoryMethod(ABC):
+    @classmethod
+    @abstractmethod
+    def new(cls, *_: Any, **__: Any) -> Self:
+        raise NotImplementedError
+
+
+class Message(Inmutable, FactoryMethod):
+    message_id: UUID = Field(default_factory=uuid7)
+    timestamp: datetime = Field(default_factory=CanCreateTimestamp.create_timestamp)
+
+
+class DomainEvent(Message, HasTopic): ...
+
+
+class IntegrationEvent(Message, HasTopic): ...
+
+
+class Command(Message, HasTopic): ...
+
+
+TValue = TypeVar("TValue")
+
+
+class ValueObject(Inmutable, FactoryMethod, Generic[TValue]):
+    value: TValue
+
+    @classmethod
+    def new(cls, value: TValue, *_: Any, **__: Any) -> Self:
+        return cls(value=value)
+
+
+TMessagePayload = IntegrationEvent | Command | DomainEvent
+
+TMessage = TypeVar("TMessage", bound=TMessagePayload)
+
+TMessagePayloadType = TypeVar("TMessagePayloadType", bound=TMessagePayload)
+
+
+class CloudMessage(Inmutable, FactoryMethod, Generic[TMessage]):
+    type: str
+    payload: TMessage
+    message_id: UUID
+    correlation_id: Optional[UUID] = None
+    causation_id: Optional[UUID] = None
+    occurred_at: datetime
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def new(
+        cls,
+        payload: TMessage,
+        *,
+        mid: UUID | None = None,
+        **kw: Any,
+    ) -> "CloudMessage[TMessage]":
+        mid = mid or payload.message_id
+        return cls(
+            type=payload.TOPIC,
+            payload=payload,
+            occurred_at=payload.timestamp,
+            message_id=mid,
+            correlation_id=mid,
+            metadata=kw,
+        )
+
+    def derive(
+        self,
+        payload: TMessagePayloadType,
+        *,
+        mid: UUID | None = None,
+        **kw: Any,
+    ) -> "CloudMessage[TMessagePayloadType]":
+        mid = mid or payload.message_id
+        return CloudMessage(
+            message_id=mid,
+            type=payload.TOPIC,
+            payload=payload,
+            correlation_id=self.correlation_id,
+            causation_id=self.message_id,
+            metadata=kw,
+            occurred_at=payload.timestamp,
+        )
+
+
+TCommand = TypeVar("TCommand", bound=Command)
+TEvento = DomainEvent | IntegrationEvent
+TEvent = TypeVar("TEvent", bound=TEvento)
+
+
+class View(Inmutable): ...
+
+
+TView = TypeVar("TView", bound=ValueObject[Any])
+
+
+class Query(Inmutable, FactoryMethod, HasTopic, Generic[TView]):
+    view: Type[TView]
+
+
+class QueryResults(Inmutable, Generic[TView], FactoryMethod):
+    items: list[TView]
+    limit: int
+    next_cursor: Optional[str] = None
+    prev_cursor: Optional[str] = None
+
+    def __len__(self):
+        return len(self.items)
+
+    @classmethod
+    def new(
+        cls,
+        items: list[TView],
+        limit: int,
+        next_cursor: Optional[str] = None,
+        prev_cursor: Optional[str] = None,
+    ):
+        return cls(
+            items=items, limit=limit, next_cursor=next_cursor, prev_cursor=prev_cursor
+        )
+
+
+class QueryResult(Inmutable, Generic[TView], FactoryMethod):
+    item: TView
+
+    @classmethod
+    def new(cls, item: TView):
+        return cls(item=item)
+
+
+TQuery = TypeVar("TQuery", bound=Query[Any], contravariant=True)

hexagonal/domain/exceptions.py

@@ -0,0 +1,38 @@
+class DomainException(Exception):
+    def __init__(self, message: str = ""):
+        self.message = f"Domain Exception: {message}"
+
+
+class DomainValueError(DomainException, ValueError):
+    def __init__(self, message: str = ""):
+        self.message = f"Domain Value Error: {message}"
+
+
+class AggregateNotFound(DomainException):
+    def __init__(self, message: str = ""):
+        self.message = f"Aggregate Not Found Exception: {message}"
+
+
+class AggregateVersionMismatch(DomainException):
+    def __init__(self, message: str = ""):
+        self.message = f"Aggregate Version Mismatch Exception: {message}"
+
+
+class HandlerNotRegistered(DomainException):
+    def __init__(self, message: str = ""):
+        self.message = f"Handler Not Registered Exception: {message}"
+
+
+class HandlerNotFound(DomainException):
+    def __init__(self, message: str = ""):
+        self.message = f"Handler Not Found Exception: {message}"
+
+
+class HandlerAlreadyRegistered(DomainException):
+    def __init__(self, message: str = ""):
+        self.message = f"Handler Already Registered Exception: {message}"
+
+
+class InfrastructureNotInitialized(DomainException, RuntimeError):
+    def __init__(self, message: str = ""):
+        self.message = f"Infrastructure Not Initialized Exception: {message}"

hexagonal/entrypoints/__init__.py

@@ -0,0 +1,4 @@
+from .app import AppEntrypoint
+from .base import Entrypoint, EntrypointGroup
+
+__all__ = ["AppEntrypoint", "Entrypoint", "EntrypointGroup"]

hexagonal/entrypoints/app.py

@@ -0,0 +1,53 @@
+# pyright: reportMissingParameterType=none, reportGeneralTypeIssues=none
+
+from typing import Type
+
+from hexagonal.adapters.drivers import ApplicationProxyAdapter
+from hexagonal.application import Application
+from hexagonal.ports.drivens import IPairInboxOutbox, TManager
+from hexagonal.ports.drivers import IBaseApplication, IBusApp
+
+from .base import Entrypoint
+from .bus import BusEntrypoint, BusEntrypointGroup
+
+
+class AppEntrypoint(Entrypoint[IBaseApplication[TManager]]):
+    name = "AppEntrypoint"
+    BUS_APP: Type[Entrypoint[IBusApp[TManager]]]
+    OUTBOX: Type[Entrypoint[IPairInboxOutbox[TManager]]]
+    BUS_INFRASTRUCTURE: Type[BusEntrypoint[TManager]]
+    BUS_GROUP: Type[BusEntrypointGroup[TManager]] = BusEntrypointGroup[TManager]
+
+    @classmethod
+    def setBusApp(cls, bus_app: Type[Entrypoint[IBusApp[TManager]]]):
+        cls.BUS_APP = bus_app
+
+    @classmethod
+    def setOutbox(cls, outbox: Type[Entrypoint[IPairInboxOutbox[TManager]]]):
+        cls.OUTBOX = outbox
+
+    @classmethod
+    def setBusInfrastructure(cls, bus_infrastructure: Type[BusEntrypoint[TManager]]):
+        cls.BUS_INFRASTRUCTURE = bus_infrastructure
+
+    @classmethod
+    def setBusEntrypointGroup(cls, bus_group: Type[BusEntrypointGroup[TManager]]):
+        cls.BUS_GROUP = bus_group
+
+    @classmethod
+    def get(cls, env=None) -> IBaseApplication[TManager]:
+        env = cls.construct_env(env)
+        if not hasattr(cls, "BUS_APP"):
+            raise ValueError("Bus app is not configured")
+        if not hasattr(cls, "OUTBOX"):
+            raise ValueError("Outbox is not configured")
+        if not hasattr(cls, "BUS_INFRASTRUCTURE"):
+            cls.setBusInfrastructure(cls.BUS_GROUP.getEntrypoint(env))
+
+        cls.BUS_INFRASTRUCTURE.setOutbox(cls.OUTBOX)
+        GeneralBusEntrypoint = cls.BUS_INFRASTRUCTURE
+
+        bus_app = cls.BUS_APP.get(env)
+        bus_infrastructure = GeneralBusEntrypoint.get(env)
+        app = Application(bus_app, bus_infrastructure)
+        return ApplicationProxyAdapter(app)

hexagonal/entrypoints/base.py

@@ -0,0 +1,105 @@
+import os
+from abc import ABC, abstractmethod
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Dict,
+    Generic,
+    List,
+    Mapping,
+    Optional,
+    Type,
+    TypeVar,
+)
+
+from eventsourcing.utils import Environment
+
+T = TypeVar("T", covariant=True)
+
+
+class Entrypoint(ABC, Generic[T]):
+    env: ClassVar[Mapping[str, str]] = {}
+    name: ClassVar[str]
+
+    @classmethod
+    def setName(cls, name: str | None = None):
+        if hasattr(cls, "name"):
+            return
+        cls.name = name or cls.__name__
+
+    @classmethod
+    @abstractmethod
+    def get(cls, env: Optional[Mapping[str, str]] = None) -> T: ...
+
+    @classmethod
+    def strategy(cls) -> Dict[str, Callable[[Optional[Mapping[str, str]]], T]]:
+        cls.setName()
+        return {cls.name: cls.get}
+
+    @classmethod
+    def construct_env(cls, env: Optional[Mapping[str, str]] = None) -> Environment:
+        """Constructs environment from which application will be configured."""
+        cls.setName()
+        _env = dict(cls.env)
+        _env.update(os.environ)
+        if env is not None:
+            _env.update(env)
+        return Environment(cls.name, _env)
+
+
+class EntrypointGroup(Entrypoint[T]):
+    env_key: ClassVar[str]
+    entrypoints: List[Type[Entrypoint[T]]]
+
+    def __init_subclass__(
+        cls,
+        **kwargs: Any,
+    ):
+        super().__init_subclass__(**kwargs)
+        cls.name = getattr(cls, "name", cls.__name__)
+        env_key = getattr(cls, "env_key", None)
+        if not env_key:
+            raise ValueError("env_key is required")
+        entrypoints = getattr(cls, "entrypoints", None)
+        if not entrypoints:
+            raise ValueError("entrypoints is required")
+        cls.env_key = env_key
+        cls.entrypoints = entrypoints
+
+    @classmethod
+    def addEntrypoint(cls, entrypoint: Type[Entrypoint[T]]):
+        cls.entrypoints.append(entrypoint)
+
+    @classmethod
+    def strategy(cls) -> Dict[str, Callable[[Optional[Mapping[str, str]]], T]]:
+        strategies: Dict[str, Callable[[Optional[Mapping[str, str]]], T]] = {}
+        for entrypoint in cls.entrypoints:
+            strategies.update(entrypoint.strategy())
+        return strategies
+
+    @classmethod
+    def getEntrypoint(
+        cls, env: Optional[Mapping[str, str]] = None
+    ) -> Type[Entrypoint[T]]:
+        env = cls.construct_env(env)
+        entrypoint_name = env.get(cls.env_key)
+        if entrypoint_name is None:
+            raise ValueError(f"Missing entrypoint name: {cls.env_key}")
+        entrypoint = next(
+            (ep for ep in cls.entrypoints if ep.name == entrypoint_name), None
+        )
+        if entrypoint is None:
+            raise ValueError(f"Unknown entrypoint: {entrypoint_name}")
+        return entrypoint
+
+    @classmethod
+    def get(cls, env: Optional[Mapping[str, str]] = None) -> T:
+        env = cls.construct_env(env)
+        strategy = cls.strategy()
+        entrypoint_name = env.get(cls.env_key)
+        if entrypoint_name is None:
+            raise ValueError(f"Missing entrypoint name: {cls.env_key}")
+        if entrypoint_name not in strategy:
+            raise ValueError(f"Unknown entrypoint: {entrypoint_name}")
+        return strategy[entrypoint_name](env)

hexagonal/entrypoints/bus.py

@@ -0,0 +1,68 @@
+import logging
+from abc import ABC
+from typing import Mapping, Optional, Type, cast
+
+from hexagonal.adapters.drivens.buses.inmemory import (
+    InMemoryBusInfrastructure,
+    InMemoryQueueBusInfrastructure,
+)
+from hexagonal.entrypoints.base import Entrypoint, EntrypointGroup
+from hexagonal.ports.drivens import (
+    IBusInfrastructure,
+    IPairInboxOutbox,
+    TManager,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BusEntrypoint(Entrypoint[IBusInfrastructure[TManager]], ABC):
+    env = {"ONLY_INTEGRATION": "False"}
+    OUTBOX: Type[Entrypoint[IPairInboxOutbox[TManager]]]
+
+    @classmethod
+    def setOutbox(cls, outbox: Type[Entrypoint[IPairInboxOutbox[TManager]]]):
+        cls.OUTBOX = outbox
+
+
+class InMemoryBusEntrypoint(BusEntrypoint[TManager]):
+    name = "inmemory"
+
+    @classmethod
+    def get(cls, env: Optional[Mapping[str, str]] = None):
+        env = cls.construct_env(env)
+        outbox = cls.OUTBOX.get(env)
+        logger.info("Using %s for events", type(outbox).__name__)
+        buses = InMemoryBusInfrastructure(outbox.inbox, outbox.outbox)
+        buses.initialize(env)
+        return buses
+
+
+class InMemoryQueueBusEntrypoint(BusEntrypoint[TManager]):
+    name = "inmemory_queue"
+
+    @classmethod
+    def get(cls, env: Optional[Mapping[str, str]] = None):
+        env = cls.construct_env(env)
+        outbox = cls.OUTBOX.get(env)
+        logger.info("Using %s for events", type(outbox).__name__)
+        buses = InMemoryQueueBusInfrastructure(outbox.inbox, outbox.outbox)
+        buses.initialize(env)
+        return buses
+
+
+class BusEntrypointGroup(EntrypointGroup[IBusInfrastructure[TManager]]):
+    env_key = "ENV_BUS"
+    entrypoints = [
+        InMemoryBusEntrypoint[TManager],
+        InMemoryQueueBusEntrypoint[TManager],
+    ]
+    env = {"ENV_BUS": "inmemory_queue"}
+
+    @classmethod
+    def getEntrypoint(
+        cls, env: Optional[Mapping[str, str]] = None
+    ) -> Type[BusEntrypoint[TManager]]:
+        entry = super().getEntrypoint(env)
+
+        return cast(Type[BusEntrypoint[TManager]], entry)

hexagonal/entrypoints/sqlite.py

@@ -0,0 +1,49 @@
+from typing import Mapping, Optional
+
+from eventsourcing.compressor import ZlibCompressor
+from eventsourcing.utils import strtobool
+
+from hexagonal.adapters.drivens.mappers import MessageMapper, OrjsonTranscoder
+from hexagonal.adapters.drivens.repository.sqlite import (
+    SQLiteConnectionContextManager,
+    SQLiteDatastore,
+    SQLiteInfrastructure,
+    SQLitePairInboxOutbox,
+)
+from hexagonal.entrypoints import AppEntrypoint, Entrypoint
+
+
+class SQLiteInfrastructureEntrypoint(Entrypoint[SQLiteInfrastructure]):
+    @classmethod
+    def get(cls, env: Optional[Mapping[str, str]] = None):
+        env = cls.construct_env(env)
+        db_path = env.get("SQLITE_DB_PATH")
+        if db_path is None:
+            raise ValueError("Database configuration is missing")
+        check_same_thread = strtobool(env.get("SQLITE_CHECK_SAME_THREAD", "True"))
+        datastore = SQLiteDatastore(
+            db_path,
+            check_same_thread=check_same_thread,
+        )
+        mapper = MessageMapper(
+            transcoder=OrjsonTranscoder(), compressor=ZlibCompressor()
+        )
+        infrastructure = SQLiteInfrastructure(mapper, datastore)
+        infrastructure.initialize(env)
+        return infrastructure
+
+
+class SQLiteOutboxEntrypoint(Entrypoint[SQLitePairInboxOutbox]):
+    @classmethod
+    def get(cls, env: Optional[Mapping[str, str]] = None):
+        env = cls.construct_env(env)
+        infrastructure = SQLiteInfrastructureEntrypoint.get(env)
+        pair = SQLitePairInboxOutbox(
+            infrastructure.mapper, infrastructure.connection_manager
+        )
+        pair.initialize(env)
+        return pair
+
+
+class SQLiteAppEntrypoint(AppEntrypoint[SQLiteConnectionContextManager]):
+    OUTBOX = SQLiteOutboxEntrypoint

hexagonal/ports/drivens/__init__.py

@@ -0,0 +1,43 @@
+from .application import IMessageHandler, IQueryHandler, IUseCase
+from .buses import (
+    IBaseMessageBus,
+    IBusInfrastructure,
+    ICommandBus,
+    IEventBus,
+    IQueryBus,
+)
+from .infrastructure import IBaseInfrastructure
+from .repository import (
+    IAggregateRepository,
+    IBaseRepository,
+    IConnectionManager,
+    IInboxRepository,
+    IOutboxRepository,
+    IPairInboxOutbox,
+    ISearchRepository,
+    IUnitOfWork,
+    TAggregate,
+    TManager,
+)
+
+__all__ = [
+    "IBaseInfrastructure",
+    "IBaseMessageBus",
+    "ICommandBus",
+    "IEventBus",
+    "IQueryBus",
+    "IBusInfrastructure",
+    "IInboxRepository",
+    "IOutboxRepository",
+    "IAggregateRepository",
+    "IBaseRepository",
+    "ISearchRepository",
+    "IConnectionManager",
+    "IUnitOfWork",
+    "IMessageHandler",
+    "IQueryHandler",
+    "TManager",
+    "IUseCase",
+    "TAggregate",
+    "IPairInboxOutbox",
+]