eventsourcing 9.3.3__py3-none-any.whl → 9.3.4__py3-none-any.whl

eventsourcing/examples/cargoshipping/domainmodel.py

@@ -1,330 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime, timedelta
-from enum import Enum
-from typing import Dict, List, Optional, Tuple, Union, cast
-from uuid import UUID, uuid4
-
-from eventsourcing.dispatch import singledispatchmethod
-from eventsourcing.domain import Aggregate
-
-
-class Location(Enum):
-    """
-    Locations in the world.
-    """
-
-    HAMBURG = "HAMBURG"
-    HONGKONG = "HONGKONG"
-    NEWYORK = "NEWYORK"
-    STOCKHOLM = "STOCKHOLM"
-    TOKYO = "TOKYO"
-
-    NLRTM = "NLRTM"
-    USDAL = "USDAL"
-    AUMEL = "AUMEL"
-
-
-class Leg:
-    """
-    Leg of an itinerary.
-    """
-
-    def __init__(
-        self,
-        origin: str,
-        destination: str,
-        voyage_number: str,
-    ):
-        self.origin: str = origin
-        self.destination: str = destination
-        self.voyage_number: str = voyage_number
-
-
-class Itinerary:
-    """
-    An itinerary along which cargo is shipped.
-    """
-
-    def __init__(
-        self,
-        origin: str,
-        destination: str,
-        legs: Tuple[Leg, ...],
-    ):
-        self.origin = origin
-        self.destination = destination
-        self.legs = legs
-
-
-class HandlingActivity(Enum):
-    RECEIVE = "RECEIVE"
-    LOAD = "LOAD"
-    UNLOAD = "UNLOAD"
-    CLAIM = "CLAIM"
-
-
-# Custom static types.
-LegDetails = Dict[str, str]
-
-ItineraryDetails = Dict[str, Union[str, List[LegDetails]]]
-
-NextExpectedActivity = Optional[Tuple[HandlingActivity, Location, str]]
-
-
-# Some routes from one location to another.
-REGISTERED_ROUTES = {
-    ("HONGKONG", "STOCKHOLM"): [
-        Itinerary(
-            origin="HONGKONG",
-            destination="STOCKHOLM",
-            legs=(
-                Leg(
-                    origin="HONGKONG",
-                    destination="NEWYORK",
-                    voyage_number="V1",
-                ),
-                Leg(
-                    origin="NEWYORK",
-                    destination="STOCKHOLM",
-                    voyage_number="V2",
-                ),
-            ),
-        )
-    ],
-    ("TOKYO", "STOCKHOLM"): [
-        Itinerary(
-            origin="TOKYO",
-            destination="STOCKHOLM",
-            legs=(
-                Leg(
-                    origin="TOKYO",
-                    destination="HAMBURG",
-                    voyage_number="V3",
-                ),
-                Leg(
-                    origin="HAMBURG",
-                    destination="STOCKHOLM",
-                    voyage_number="V4",
-                ),
-            ),
-        )
-    ],
-}
-
-
-class Cargo(Aggregate):
-    """
-    The Cargo aggregate is an event-sourced domain model aggregate that
-    specifies the routing from origin to destination, and can track what
-    happens to the cargo after it has been booked.
-    """
-
-    def __init__(
-        self,
-        origin: Location,
-        destination: Location,
-        arrival_deadline: datetime,
-    ):
-        self._origin: Location = origin
-        self._destination: Location = destination
-        self._arrival_deadline: datetime = arrival_deadline
-        self._transport_status: str = "NOT_RECEIVED"
-        self._routing_status: str = "NOT_ROUTED"
-        self._is_misdirected: bool = False
-        self._estimated_time_of_arrival: datetime | None = None
-        self._next_expected_activity: NextExpectedActivity = None
-        self._route: Itinerary | None = None
-        self._last_known_location: Location | None = None
-        self._current_voyage_number: str | None = None
-
-    @property
-    def origin(self) -> Location:
-        return self._origin
-
-    @property
-    def destination(self) -> Location:
-        return self._destination
-
-    @property
-    def arrival_deadline(self) -> datetime:
-        return self._arrival_deadline
-
-    @property
-    def transport_status(self) -> str:
-        return self._transport_status
-
-    @property
-    def routing_status(self) -> str:
-        return self._routing_status
-
-    @property
-    def is_misdirected(self) -> bool:
-        return self._is_misdirected
-
-    @property
-    def estimated_time_of_arrival(
-        self,
-    ) -> datetime | None:
-        return self._estimated_time_of_arrival
-
-    @property
-    def next_expected_activity(self) -> NextExpectedActivity:
-        return self._next_expected_activity
-
-    @property
-    def route(self) -> Itinerary | None:
-        return self._route
-
-    @property
-    def last_known_location(self) -> Location | None:
-        return self._last_known_location
-
-    @property
-    def current_voyage_number(self) -> str | None:
-        return self._current_voyage_number
-
-    @classmethod
-    def new_booking(
-        cls,
-        origin: Location,
-        destination: Location,
-        arrival_deadline: datetime,
-    ) -> Cargo:
-        return cls._create(
-            event_class=cls.BookingStarted,
-            id=uuid4(),
-            origin=origin,
-            destination=destination,
-            arrival_deadline=arrival_deadline,
-        )
-
-    class BookingStarted(Aggregate.Created):
-        origin: Location
-        destination: Location
-        arrival_deadline: datetime
-
-    class Event(Aggregate.Event):
-        def apply(self, aggregate: Aggregate) -> None:
-            cast(Cargo, aggregate).when(self)
-
-    @singledispatchmethod
-    def when(self, event: Event) -> None:
-        """
-        Default method to apply an aggregate event to the aggregate object.
-        """
-
-    def change_destination(self, destination: Location) -> None:
-        self.trigger_event(
-            self.DestinationChanged,
-            destination=destination,
-        )
-
-    class DestinationChanged(Event):
-        destination: Location
-
-    @when.register
-    def _(self, event: Cargo.DestinationChanged) -> None:
-        self._destination = event.destination
-
-    def assign_route(self, itinerary: Itinerary) -> None:
-        self.trigger_event(self.RouteAssigned, route=itinerary)
-
-    class RouteAssigned(Event):
-        route: Itinerary
-
-    @when.register
-    def _(self, event: Cargo.RouteAssigned) -> None:
-        self._route = event.route
-        self._routing_status = "ROUTED"
-        self._estimated_time_of_arrival = Cargo.Event.create_timestamp() + timedelta(
-            weeks=1
-        )
-        self._next_expected_activity = (HandlingActivity.RECEIVE, self.origin, "")
-        self._is_misdirected = False
-
-    def register_handling_event(
-        self,
-        tracking_id: UUID,
-        voyage_number: str | None,
-        location: Location,
-        handling_activity: HandlingActivity,
-    ) -> None:
-        self.trigger_event(
-            self.HandlingEventRegistered,
-            tracking_id=tracking_id,
-            voyage_number=voyage_number,
-            location=location,
-            handling_activity=handling_activity,
-        )
-
-    class HandlingEventRegistered(Event):
-        tracking_id: UUID
-        voyage_number: str
-        location: Location
-        handling_activity: str
-
-    @when.register
-    def _(self, event: Cargo.HandlingEventRegistered) -> None:
-        assert self.route is not None
-        if event.handling_activity == HandlingActivity.RECEIVE:
-            self._transport_status = "IN_PORT"
-            self._last_known_location = event.location
-            self._next_expected_activity = (
-                HandlingActivity.LOAD,
-                event.location,
-                self.route.legs[0].voyage_number,
-            )
-        elif event.handling_activity == HandlingActivity.LOAD:
-            self._transport_status = "ONBOARD_CARRIER"
-            self._current_voyage_number = event.voyage_number
-            for leg in self.route.legs:
-                if (
-                    leg.origin == event.location.value
-                    and leg.voyage_number == event.voyage_number
-                ):
-                    self._next_expected_activity = (
-                        HandlingActivity.UNLOAD,
-                        Location[leg.destination],
-                        event.voyage_number,
-                    )
-                    break
-            else:
-                msg = "Can't find leg with origin={} and voyage_number={}".format(
-                    event.location,
-                    event.voyage_number,
-                )
-                raise Exception(msg)
-
-        elif event.handling_activity == HandlingActivity.UNLOAD:
-            self._current_voyage_number = None
-            self._last_known_location = event.location
-            self._transport_status = "IN_PORT"
-            if event.location == self.destination:
-                self._next_expected_activity = (
-                    HandlingActivity.CLAIM,
-                    event.location,
-                    "",
-                )
-            elif event.location.value in [leg.destination for leg in self.route.legs]:
-                for i, leg in enumerate(self.route.legs):
-                    if leg.voyage_number == event.voyage_number:
-                        next_leg: Leg = self.route.legs[i + 1]
-                        assert Location[next_leg.origin] == event.location
-                        self._next_expected_activity = (
-                            HandlingActivity.LOAD,
-                            event.location,
-                            next_leg.voyage_number,
-                        )
-                        break
-            else:
-                self._is_misdirected = True
-                self._next_expected_activity = None
-
-        elif event.handling_activity == HandlingActivity.CLAIM:
-            self._next_expected_activity = None
-            self._transport_status = "CLAIMED"
-
-        else:
-            msg = f"Unsupported handling event: {event.handling_activity}"
-            raise Exception(msg)

eventsourcing/examples/cargoshipping/interface.py

@@ -1,143 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Union
-from uuid import UUID
-
-from eventsourcing.examples.cargoshipping.domainmodel import (
-    HandlingActivity,
-    Itinerary,
-    ItineraryDetails,
-    LegDetails,
-    Location,
-)
-
-if TYPE_CHECKING:  # pragma: nocover
-    from eventsourcing.examples.cargoshipping.application import BookingApplication
-
-NextExpectedActivityDetails = Optional[Tuple[str, ...]]
-CargoDetails = Dict[
-    str, Optional[Union[str, bool, datetime, NextExpectedActivityDetails]]
-]
-
-
-class BookingService:
-    """
-    Presents an application interface that uses
-    simple types of object (str, bool, datetime).
-    """
-
-    def __init__(self, app: BookingApplication):
-        self.app = app
-
-    def book_new_cargo(
-        self,
-        origin: str,
-        destination: str,
-        arrival_deadline: datetime,
-    ) -> str:
-        tracking_id = self.app.book_new_cargo(
-            Location[origin],
-            Location[destination],
-            arrival_deadline,
-        )
-        return str(tracking_id)
-
-    def get_cargo_details(self, tracking_id: str) -> CargoDetails:
-        cargo = self.app.get_cargo(UUID(tracking_id))
-
-        # Present 'next_expected_activity'.
-        next_expected_activity: NextExpectedActivityDetails
-        if cargo.next_expected_activity is None:
-            next_expected_activity = None
-        elif len(cargo.next_expected_activity) == 2:
-            next_expected_activity = (
-                cargo.next_expected_activity[0].value,
-                cargo.next_expected_activity[1].value,
-            )
-        elif len(cargo.next_expected_activity) == 3:
-            next_expected_activity = (
-                cargo.next_expected_activity[0].value,
-                cargo.next_expected_activity[1].value,
-                cargo.next_expected_activity[2],
-            )
-        else:
-            msg = f"Invalid next expected activity: {cargo.next_expected_activity}"
-            raise Exception(msg)
-
-        # Present 'last_known_location'.
-        if cargo.last_known_location is None:
-            last_known_location = None
-        else:
-            last_known_location = cargo.last_known_location.value
-
-        # Present the cargo details.
-        return {
-            "id": str(cargo.id),
-            "origin": cargo.origin.value,
-            "destination": cargo.destination.value,
-            "arrival_deadline": cargo.arrival_deadline,
-            "transport_status": cargo.transport_status,
-            "routing_status": cargo.routing_status,
-            "is_misdirected": cargo.is_misdirected,
-            "estimated_time_of_arrival": cargo.estimated_time_of_arrival,
-            "next_expected_activity": next_expected_activity,
-            "last_known_location": last_known_location,
-            "current_voyage_number": cargo.current_voyage_number,
-        }
-
-    def change_destination(self, tracking_id: str, destination: str) -> None:
-        self.app.change_destination(UUID(tracking_id), Location[destination])
-
-    def request_possible_routes_for_cargo(
-        self, tracking_id: str
-    ) -> List[ItineraryDetails]:
-        routes = self.app.request_possible_routes_for_cargo(UUID(tracking_id))
-        return [self.dict_from_itinerary(route) for route in routes]
-
-    def dict_from_itinerary(self, itinerary: Itinerary) -> ItineraryDetails:
-        legs_details = []
-        for leg in itinerary.legs:
-            leg_details: LegDetails = {
-                "origin": leg.origin,
-                "destination": leg.destination,
-                "voyage_number": leg.voyage_number,
-            }
-            legs_details.append(leg_details)
-        route_details: ItineraryDetails = {
-            "origin": itinerary.origin,
-            "destination": itinerary.destination,
-            "legs": legs_details,
-        }
-        return route_details
-
-    def assign_route(
-        self,
-        tracking_id: str,
-        route_details: ItineraryDetails,
-    ) -> None:
-        routes = self.app.request_possible_routes_for_cargo(UUID(tracking_id))
-        for route in routes:
-            if route_details == self.dict_from_itinerary(route):
-                self.app.assign_route(UUID(tracking_id), route)
-
-    def register_handling_event(
-        self,
-        tracking_id: str,
-        voyage_number: str | None,
-        location: str,
-        handling_activity: str,
-    ) -> None:
-        self.app.register_handling_event(
-            UUID(tracking_id),
-            voyage_number,
-            Location[location],
-            HandlingActivity[handling_activity],
-        )
-
-
-# Stub function that picks an itinerary from a list of possible itineraries.
-def select_preferred_itinerary(
-    itineraries: List[ItineraryDetails],
-) -> ItineraryDetails:
-    return itineraries[0]

eventsourcing/examples/cargoshipping/test.py

@@ -1,231 +0,0 @@
-from __future__ import annotations
-
-import unittest
-from datetime import timedelta
-
-from eventsourcing.examples.cargoshipping.application import BookingApplication
-from eventsourcing.examples.cargoshipping.domainmodel import Cargo
-from eventsourcing.examples.cargoshipping.interface import (
-    BookingService,
-    select_preferred_itinerary,
-)
-
-
-class TestBookingService(unittest.TestCase):
-    def setUp(self) -> None:
-        self.service = BookingService(BookingApplication())
-
-    def test_admin_can_book_new_cargo(self) -> None:
-        arrival_deadline = Cargo.Event.create_timestamp() + timedelta(weeks=3)
-
-        cargo_id = self.service.book_new_cargo(
-            origin="NLRTM",
-            destination="USDAL",
-            arrival_deadline=arrival_deadline,
-        )
-
-        cargo_details = self.service.get_cargo_details(cargo_id)
-        self.assertTrue(cargo_details["id"])
-        self.assertEqual(cargo_details["origin"], "NLRTM")
-        self.assertEqual(cargo_details["destination"], "USDAL")
-
-        self.service.change_destination(cargo_id, destination="AUMEL")
-        cargo_details = self.service.get_cargo_details(cargo_id)
-        self.assertEqual(cargo_details["destination"], "AUMEL")
-        self.assertEqual(
-            cargo_details["arrival_deadline"],
-            arrival_deadline,
-        )
-
-    def test_scenario_cargo_from_hongkong_to_stockholm(
-        self,
-    ) -> None:
-        # Test setup: A cargo should be shipped from
-        # Hongkong to Stockholm, and it should arrive
-        # in no more than two weeks.
-        origin = "HONGKONG"
-        destination = "STOCKHOLM"
-        arrival_deadline = Cargo.Event.create_timestamp() + timedelta(weeks=2)
-
-        # Use case 1: booking.
-
-        # A new cargo is booked, and the unique tracking
-        # id is assigned to the cargo.
-        tracking_id = self.service.book_new_cargo(origin, destination, arrival_deadline)
-
-        # The tracking id can be used to lookup the cargo
-        # in the repository.
-        # Important: The cargo, and thus the domain model,
-        # is responsible for determining the status of the
-        # cargo, whether it is on the right track or not
-        # and so on. This is core domain logic. Tracking
-        # the cargo basically amounts to presenting
-        # information extracted from the cargo aggregate
-        # in a suitable way.
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(
-            cargo_details["transport_status"],
-            "NOT_RECEIVED",
-        )
-        self.assertEqual(cargo_details["routing_status"], "NOT_ROUTED")
-        self.assertEqual(cargo_details["is_misdirected"], False)
-        self.assertEqual(
-            cargo_details["estimated_time_of_arrival"],
-            None,
-        )
-        self.assertEqual(cargo_details["next_expected_activity"], None)
-
-        # Use case 2: routing.
-        #
-        # A number of possible routes for this cargo is
-        # requested and may be presented to the customer
-        # in some way for him/her to choose from.
-        # Selection could be affected by things like price
-        # and time of delivery, but this test simply uses
-        # an arbitrary selection to mimic that process.
-        itineraries = self.service.request_possible_routes_for_cargo(tracking_id)
-        route_details = select_preferred_itinerary(itineraries)
-
-        # The cargo is then assigned to the selected
-        # route, described by an itinerary.
-        self.service.assign_route(tracking_id, route_details)
-
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(
-            cargo_details["transport_status"],
-            "NOT_RECEIVED",
-        )
-        self.assertEqual(cargo_details["routing_status"], "ROUTED")
-        self.assertEqual(cargo_details["is_misdirected"], False)
-        self.assertTrue(cargo_details["estimated_time_of_arrival"])
-        self.assertEqual(
-            cargo_details["next_expected_activity"],
-            ("RECEIVE", "HONGKONG", ""),
-        )
-
-        # Use case 3: handling
-
-        # A handling event registration attempt will be
-        # formed from parsing the data coming in as a
-        # handling report either via the web service
-        # interface or as an uploaded CSV file. The
-        # handling event factory tries to create a
-        # HandlingEvent from the attempt, and if the
-        # factory decides that this is a plausible
-        # handling event, it is stored. If the attempt
-        # is invalid, for example if no cargo exists for
-        # the specified tracking id, the attempt is
-        # rejected.
-        #
-        # Handling begins: cargo is received in Hongkong.
-        self.service.register_handling_event(tracking_id, None, "HONGKONG", "RECEIVE")
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(cargo_details["transport_status"], "IN_PORT")
-        self.assertEqual(
-            cargo_details["last_known_location"],
-            "HONGKONG",
-        )
-        self.assertEqual(
-            cargo_details["next_expected_activity"],
-            ("LOAD", "HONGKONG", "V1"),
-        )
-
-        # Load onto voyage V1.
-        self.service.register_handling_event(tracking_id, "V1", "HONGKONG", "LOAD")
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(cargo_details["current_voyage_number"], "V1")
-        self.assertEqual(
-            cargo_details["last_known_location"],
-            "HONGKONG",
-        )
-        self.assertEqual(
-            cargo_details["transport_status"],
-            "ONBOARD_CARRIER",
-        )
-        self.assertEqual(
-            cargo_details["next_expected_activity"],
-            ("UNLOAD", "NEWYORK", "V1"),
-        )
-
-        # Incorrectly unload in Tokyo.
-        self.service.register_handling_event(tracking_id, "V1", "TOKYO", "UNLOAD")
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(cargo_details["current_voyage_number"], None)
-        self.assertEqual(cargo_details["last_known_location"], "TOKYO")
-        self.assertEqual(cargo_details["transport_status"], "IN_PORT")
-        self.assertEqual(cargo_details["is_misdirected"], True)
-        self.assertEqual(cargo_details["next_expected_activity"], None)
-
-        # Reroute.
-        itineraries = self.service.request_possible_routes_for_cargo(tracking_id)
-        route_details = select_preferred_itinerary(itineraries)
-        self.service.assign_route(tracking_id, route_details)
-
-        # Load in Tokyo.
-        self.service.register_handling_event(tracking_id, "V3", "TOKYO", "LOAD")
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(cargo_details["current_voyage_number"], "V3")
-        self.assertEqual(cargo_details["last_known_location"], "TOKYO")
-        self.assertEqual(
-            cargo_details["transport_status"],
-            "ONBOARD_CARRIER",
-        )
-        self.assertEqual(cargo_details["is_misdirected"], False)
-        self.assertEqual(
-            cargo_details["next_expected_activity"],
-            ("UNLOAD", "HAMBURG", "V3"),
-        )
-
-        # Unload in Hamburg.
-        self.service.register_handling_event(tracking_id, "V3", "HAMBURG", "UNLOAD")
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(cargo_details["current_voyage_number"], None)
-        self.assertEqual(cargo_details["last_known_location"], "HAMBURG")
-        self.assertEqual(cargo_details["transport_status"], "IN_PORT")
-        self.assertEqual(cargo_details["is_misdirected"], False)
-        self.assertEqual(
-            cargo_details["next_expected_activity"],
-            ("LOAD", "HAMBURG", "V4"),
-        )
-
-        # Load in Hamburg
-        self.service.register_handling_event(tracking_id, "V4", "HAMBURG", "LOAD")
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(cargo_details["current_voyage_number"], "V4")
-        self.assertEqual(cargo_details["last_known_location"], "HAMBURG")
-        self.assertEqual(
-            cargo_details["transport_status"],
-            "ONBOARD_CARRIER",
-        )
-        self.assertEqual(cargo_details["is_misdirected"], False)
-        self.assertEqual(
-            cargo_details["next_expected_activity"],
-            ("UNLOAD", "STOCKHOLM", "V4"),
-        )
-
-        # Unload in Stockholm
-        self.service.register_handling_event(tracking_id, "V4", "STOCKHOLM", "UNLOAD")
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(cargo_details["current_voyage_number"], None)
-        self.assertEqual(
-            cargo_details["last_known_location"],
-            "STOCKHOLM",
-        )
-        self.assertEqual(cargo_details["transport_status"], "IN_PORT")
-        self.assertEqual(cargo_details["is_misdirected"], False)
-        self.assertEqual(
-            cargo_details["next_expected_activity"],
-            ("CLAIM", "STOCKHOLM", ""),
-        )
-
-        # Finally, cargo is claimed in Stockholm.
-        self.service.register_handling_event(tracking_id, None, "STOCKHOLM", "CLAIM")
-        cargo_details = self.service.get_cargo_details(tracking_id)
-        self.assertEqual(cargo_details["current_voyage_number"], None)
-        self.assertEqual(
-            cargo_details["last_known_location"],
-            "STOCKHOLM",
-        )
-        self.assertEqual(cargo_details["transport_status"], "CLAIMED")
-        self.assertEqual(cargo_details["is_misdirected"], False)
-        self.assertEqual(cargo_details["next_expected_activity"], None)