eventsourcing 9.2.22__py3-none-any.whl → 9.3.0__py3-none-any.whl

eventsourcing/examples/searchabletimestamps/sqlite.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, List, Sequence, Tuple, cast
+from uuid import UUID
+
+from eventsourcing.domain import Aggregate
+from eventsourcing.examples.searchabletimestamps.persistence import (
+    SearchableTimestampsRecorder,
+)
+from eventsourcing.sqlite import (
+    Factory,
+    SQLiteApplicationRecorder,
+    SQLiteCursor,
+    SQLiteDatastore,
+)
+
+if TYPE_CHECKING:  # pragma: nocover
+    from eventsourcing.persistence import ApplicationRecorder, StoredEvent
+
+
+class SearchableTimestampsApplicationRecorder(
+    SearchableTimestampsRecorder, SQLiteApplicationRecorder
+):
+    def __init__(
+        self,
+        datastore: SQLiteDatastore,
+        events_table_name: str = "stored_events",
+        event_timestamps_table_name: str = "event_timestamps",
+    ):
+        self.event_timestamps_table_name = event_timestamps_table_name
+        super().__init__(datastore, events_table_name)
+        self.insert_event_timestamp_statement = (
+            f"INSERT INTO {self.event_timestamps_table_name} VALUES (?, ?, ?)"
+        )
+        self.select_event_timestamp_statement = (
+            f"SELECT originator_version FROM {self.event_timestamps_table_name} WHERE "
+            "originator_id = ? AND "
+            "timestamp <= ? "
+            "ORDER BY originator_version DESC "
+            "LIMIT 1"
+        )
+
+    def construct_create_table_statements(self) -> List[str]:
+        statements = super().construct_create_table_statements()
+        statements.append(
+            "CREATE TABLE IF NOT EXISTS "
+            f"{self.event_timestamps_table_name} ("
+            "originator_id TEXT, "
+            "timestamp timestamp, "
+            "originator_version INTEGER, "
+            "PRIMARY KEY "
+            "(originator_id, timestamp))"
+        )
+        return statements
+
+    def _insert_events(
+        self,
+        c: SQLiteCursor,
+        stored_events: List[StoredEvent],
+        **kwargs: Any,
+    ) -> Sequence[int] | None:
+        notification_ids = super()._insert_events(c, stored_events, **kwargs)
+
+        # Insert event timestamps.
+        event_timestamps_data = cast(
+            List[Tuple[UUID, datetime, int]], kwargs["event_timestamps_data"]
+        )
+        for originator_id, timestamp, originator_version in event_timestamps_data:
+            c.execute(
+                self.insert_event_timestamp_statement,
+                (originator_id.hex, timestamp, originator_version),
+            )
+
+        return notification_ids
+
+    def get_version_at_timestamp(
+        self, originator_id: UUID, timestamp: datetime
+    ) -> int | None:
+        with self.datastore.transaction(commit=False) as c:
+            c.execute(
+                self.select_event_timestamp_statement, (originator_id.hex, timestamp)
+            )
+            for row in c.fetchall():
+                version = row["originator_version"]
+                break
+            else:
+                version = Aggregate.INITIAL_VERSION - 1
+            return version
+
+
+class SearchableTimestampsInfrastructureFactory(Factory):
+    def application_recorder(self) -> ApplicationRecorder:
+        recorder = SearchableTimestampsApplicationRecorder(datastore=self.datastore)
+        recorder.create_table()
+        return recorder
+
+
+del Factory

eventsourcing/examples/searchabletimestamps/test_searchabletimestamps.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import os
+from datetime import timedelta
+from time import sleep
+from typing import ClassVar, Dict
+from unittest import TestCase
+
+from eventsourcing.application import AggregateNotFoundError
+from eventsourcing.domain import create_utc_datetime_now
+from eventsourcing.examples.cargoshipping.domainmodel import Location
+from eventsourcing.examples.searchabletimestamps.application import (
+    SearchableTimestampsApplication,
+)
+from eventsourcing.postgres import PostgresDatastore
+from eventsourcing.tests.postgres_utils import drop_postgres_table
+
+
+class SearchableTimestampsTestCase(TestCase):
+    env: ClassVar[Dict[str, str]]
+
+    def test(self) -> None:
+        # Construct application.
+        app = SearchableTimestampsApplication(env=self.env)
+        timestamp0 = create_utc_datetime_now()
+        sleep(1e-5)
+
+        # Book new cargo.
+        tracking_id = app.book_new_cargo(
+            origin=Location["NLRTM"],
+            destination=Location["USDAL"],
+            arrival_deadline=create_utc_datetime_now() + timedelta(weeks=3),
+        )
+        timestamp1 = create_utc_datetime_now()
+        sleep(1e-5)
+
+        # Change destination.
+        app.change_destination(tracking_id, destination=Location["AUMEL"])
+        timestamp2 = create_utc_datetime_now()
+        sleep(1e-5)
+
+        # View the state of the cargo tracking at particular times.
+        with self.assertRaises(AggregateNotFoundError):
+            app.get_cargo_at_timestamp(tracking_id, timestamp0)
+
+        cargo_at_timestamp1 = app.get_cargo_at_timestamp(tracking_id, timestamp1)
+        self.assertEqual(cargo_at_timestamp1.destination, Location["USDAL"])
+
+        cargo_at_timestamp2 = app.get_cargo_at_timestamp(tracking_id, timestamp2)
+        self.assertEqual(cargo_at_timestamp2.destination, Location["AUMEL"])
+
+
+class WithSQLite(SearchableTimestampsTestCase):
+    env: ClassVar[Dict[str, str]] = {
+        "PERSISTENCE_MODULE": "eventsourcing.examples.searchabletimestamps.sqlite",
+        "SQLITE_DBNAME": ":memory:",
+    }
+
+
+class WithPostgreSQL(SearchableTimestampsTestCase):
+    env: ClassVar[Dict[str, str]] = {
+        "PERSISTENCE_MODULE": "eventsourcing.examples.searchabletimestamps.postgres"
+    }
+
+    def setUp(self) -> None:
+        super().setUp()
+        os.environ["POSTGRES_DBNAME"] = "eventsourcing"
+        os.environ["POSTGRES_HOST"] = "127.0.0.1"
+        os.environ["POSTGRES_PORT"] = "5432"
+        os.environ["POSTGRES_USER"] = "eventsourcing"
+        os.environ["POSTGRES_PASSWORD"] = "eventsourcing"  # noqa: S105
+        self.drop_tables()
+
+    def tearDown(self) -> None:
+        self.drop_tables()
+        super().tearDown()
+
+    def drop_tables(self) -> None:
+        with PostgresDatastore(
+            os.environ["POSTGRES_DBNAME"],
+            os.environ["POSTGRES_HOST"],
+            os.environ["POSTGRES_PORT"],
+            os.environ["POSTGRES_USER"],
+            os.environ["POSTGRES_PASSWORD"],
+        ) as datastore:
+            drop_postgres_table(
+                datastore, "public.searchabletimestampsapplication_events"
+            )
+            drop_postgres_table(
+                datastore, "public.searchabletimestampsapplication_timestamps"
+            )
+
+
+del SearchableTimestampsTestCase

eventsourcing/examples/test_invoice.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Dict, cast
+from unittest import TestCase
+
+from eventsourcing.application import Application
+from eventsourcing.domain import Aggregate, Snapshot, event
+from eventsourcing.persistence import Transcoding
+
+if TYPE_CHECKING:  # pragma: nocover
+    from datetime import datetime
+
+
+class Status(Enum):
+    INITIATED = 1
+    ISSUED = 2
+    SENT = 3
+
+
+class SendMethod(Enum):
+    EMAIL = 1
+    POST = 2
+
+
+@dataclass
+class Person:
+    name: str
+    address: str
+
+
+class Invoice(Aggregate):
+    @event("Initiated")
+    def __init__(
+        self,
+        number: str,
+        amount: Decimal,
+        issued_to: Person,
+        timestamp: datetime | Any = None,
+    ):
+        self._number = number
+        self._amount = amount
+        self.issued_to = issued_to
+        self.initiated_at = timestamp
+        self.status = Status.INITIATED
+
+    def _get_number(self) -> str:
+        return self._number
+
+    @event
+    def _number_updated(self, value: str) -> None:
+        assert self.status == Status.INITIATED
+        self._number = value
+
+    number = property(_get_number, _number_updated)
+
+    def _get_amount(self) -> Decimal:
+        return self._amount
+
+    @event("AmountUpdated")
+    def _set_amount(self, value: Decimal) -> None:
+        assert self.status == Status.INITIATED
+        self._amount = value
+
+    amount = property(_get_amount, _set_amount)
+
+    @event("Issued")
+    def issue(self, issued_by: str, timestamp: datetime | Any = None) -> None:
+        self.issued_by = issued_by
+        self.issued_on = timestamp
+        self.status = Status.ISSUED
+
+    @event("Sent")
+    def send(self, sent_via: SendMethod, timestamp: datetime | Any = None) -> None:
+        self.sent_via = sent_via
+        self.sent_at = timestamp
+        self.status = Status.SENT
+
+
+class PersonAsDict(Transcoding):
+    name = "person_as_dict"
+    type = Person
+
+    def encode(self, obj: Person) -> Dict[str, Any]:
+        return obj.__dict__
+
+    def decode(self, data: Dict[str, Any]) -> Person:
+        return Person(**data)
+
+
+class SendMethodAsStr(Transcoding):
+    name = "send_method_str"
+    type = SendMethod
+
+    def encode(self, obj: SendMethod) -> str:
+        return obj.name
+
+    def decode(self, data: str) -> SendMethod:
+        return getattr(SendMethod, data)
+
+
+class StatusAsStr(Transcoding):
+    name = "status_str"
+    type = Status
+
+    def encode(self, obj: Status) -> str:
+        return obj.name
+
+    def decode(self, data: str) -> Status:
+        return getattr(Status, data)
+
+
+class TestInvoice(TestCase):
+    def test(self) -> None:
+        invoice = Invoice(
+            number="INV/2021/11/01",
+            amount=Decimal("34.20"),
+            issued_to=Person("Oscar the Grouch", "123 Sesame Street"),
+        )
+        self.assertEqual(invoice.number, "INV/2021/11/01")
+        self.assertEqual(invoice.amount, Decimal("34.20"))
+        self.assertEqual(
+            invoice.issued_to, Person("Oscar the Grouch", "123 Sesame Street")
+        )
+        self.assertEqual(invoice.status, Status.INITIATED)
+
+        invoice.number = "INV/2021/11/02"
+        self.assertEqual(invoice.number, "INV/2021/11/02")
+
+        invoice.amount = Decimal("43.20")
+        self.assertEqual(invoice.number, "INV/2021/11/02")
+
+        invoice.issue(issued_by="Cookie Monster")
+        self.assertEqual(invoice.issued_by, "Cookie Monster")
+        self.assertEqual(invoice.status, Status.ISSUED)
+
+        with self.assertRaises(AssertionError):
+            invoice.number = "INV/2021/11/03"
+
+        with self.assertRaises(AssertionError):
+            invoice.amount = Decimal("54.20")
+
+        invoice.send(sent_via=SendMethod.EMAIL)
+        self.assertEqual(invoice.sent_via, SendMethod.EMAIL)
+        self.assertEqual(invoice.status, Status.SENT)
+
+        app: Application = Application(env={"IS_SNAPSHOTTING_ENABLED": "y"})
+        app.mapper.transcoder.register(PersonAsDict())
+        app.mapper.transcoder.register(SendMethodAsStr())
+        app.mapper.transcoder.register(StatusAsStr())
+
+        app.save(invoice)
+
+        copy: Invoice = app.repository.get(invoice.id)
+        self.assertEqual(invoice, copy)
+
+        assert app.snapshots is not None
+        snapshots = list(app.snapshots.get(invoice.id))
+        self.assertEqual(len(snapshots), 0)
+
+        app.take_snapshot(invoice.id)
+
+        copy = app.repository.get(invoice.id)
+        self.assertEqual(invoice, copy)
+
+        copy = app.repository.get(invoice.id, version=1)
+        self.assertNotEqual(invoice, copy)
+
+        snapshots = list(app.snapshots.get(invoice.id))
+        self.assertEqual(len(snapshots), 1)
+
+        snapshot = cast(Snapshot, snapshots[0])
+        copy2 = cast(Invoice, snapshot.mutate(None))
+        self.assertEqual(invoice, copy2)

eventsourcing/examples/test_parking_lot.py

@@ -0,0 +1,206 @@
+"""
+After Ed Blackburn's https://github.com/edblackburn/parking-lot/.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import List, Type, cast
+from unittest import TestCase
+from uuid import NAMESPACE_URL, UUID, uuid5
+
+from eventsourcing.application import AggregateNotFoundError, Application
+from eventsourcing.domain import Aggregate, triggers
+from eventsourcing.system import NotificationLogReader
+
+
+@dataclass
+class LicencePlate:
+    number: str
+    regex = re.compile("^[0-9]{3}-[0-9]{3}$")
+
+    def __post_init__(self) -> None:
+        if not bool(self.regex.match(self.number)):
+            raise ValueError
+
+
+@dataclass
+class Booking:
+    start: datetime
+    finish: datetime
+
+
+class Product:
+    delta = timedelta()
+
+    @classmethod
+    def calc_finish(cls, start: datetime) -> datetime:
+        return start + cls.delta
+
+
+class EndOfDay(Product):
+    delta = timedelta(days=1, seconds=-1)
+
+
+class EndOfWeek(Product):
+    delta = timedelta(days=7, seconds=-1)
+
+
+class Vehicle(Aggregate):
+    class Event(Aggregate.Event):
+        pass
+
+    class Registered(Event, Aggregate.Created):
+        licence_plate_number: str
+
+    class Booked(Event):
+        start: datetime
+        finish: datetime
+
+    class Unbooked(Event):
+        when: datetime
+
+    @triggers(Registered)
+    def __init__(self, licence_plate_number: str):
+        self.licence_plate_number = licence_plate_number
+        self.bookings: List[Booking] = []
+        self.inspection_failures: List[datetime] = []
+
+    @triggers(Booked)
+    def book(self, start: datetime, finish: datetime) -> None:
+        self.bookings.append(Booking(start, finish))
+
+    @triggers(Unbooked)
+    def fail_inspection(self, when: datetime) -> None:
+        self.inspection_failures.append(when)
+
+    @property
+    def licence_plate(self) -> LicencePlate:
+        return LicencePlate(self.licence_plate_number)
+
+    def inspect(self, when: datetime) -> None:
+        for booking in self.bookings:
+            if booking.start < when < booking.finish:
+                break
+        else:
+            self.fail_inspection(when)
+
+    @staticmethod
+    def create_id(licence_plate_number: str) -> UUID:
+        return uuid5(NAMESPACE_URL, f"/licence_plate_numbers/{licence_plate_number}")
+
+
+class ParkingLot(Application):
+    def book(self, licence_plate: LicencePlate, product: Type[Product]) -> None:
+        try:
+            vehicle = self.get_vehicle(licence_plate)
+        except AggregateNotFoundError:
+            vehicle = Vehicle(licence_plate.number)
+        start = Vehicle.Event.create_timestamp()
+        finish = product.calc_finish(start)
+        vehicle.book(start=start, finish=finish)
+        self.save(vehicle)
+
+    def inspect(self, licence_plate: LicencePlate, when: datetime) -> None:
+        vehicle = self.get_vehicle(licence_plate)
+        vehicle.inspect(when)
+        self.save(vehicle)
+
+    def get_vehicle(self, licence_plate: LicencePlate) -> Vehicle:
+        return cast(
+            Vehicle, self.repository.get(Vehicle.create_id(licence_plate.number))
+        )
+
+
+class TestParkingLot(TestCase):
+    def test_licence_plate(self) -> None:
+        # Valid.
+        licence_plate = LicencePlate("123-123")
+        self.assertIsInstance(licence_plate, LicencePlate)
+        self.assertEqual(licence_plate.number, "123-123")
+
+        # Invalid.
+        with self.assertRaises(ValueError):
+            LicencePlate("abcdef")
+
+    def test_parking_lot(self) -> None:
+        # Construct the application object to use an SQLite database.
+        app = ParkingLot(
+            env={
+                "PERSISTENCE_MODULE": "eventsourcing.sqlite",
+                "SQLITE_DBNAME": ":memory:",
+            }
+        )
+
+        # Create a valid licence plate.
+        licence_plate = LicencePlate("123-123")
+
+        # Book unregistered vehicle.
+        app.book(licence_plate, EndOfDay)
+
+        # Check vehicle state.
+        vehicle = app.get_vehicle(licence_plate)
+        self.assertEqual(vehicle.licence_plate, licence_plate)
+        self.assertEqual(len(vehicle.bookings), 1)
+        self.assertEqual(len(vehicle.inspection_failures), 0)
+        booking1 = vehicle.bookings[-1]
+
+        # Book registered vehicle.
+        app.book(licence_plate, EndOfWeek)
+
+        # Check vehicle state.
+        vehicle = app.get_vehicle(licence_plate)
+        self.assertEqual(len(vehicle.bookings), 2)
+        self.assertEqual(len(vehicle.inspection_failures), 0)
+        booking2 = vehicle.bookings[-1]
+
+        # Inspect whilst has booking.
+        app.inspect(licence_plate, Vehicle.Event.create_timestamp())
+
+        # Check vehicle state.
+        vehicle = app.get_vehicle(licence_plate)
+        self.assertEqual(len(vehicle.bookings), 2)
+        self.assertEqual(len(vehicle.inspection_failures), 0)
+
+        # Inspect after bookings expired.
+        inspected_on = Vehicle.Event.create_timestamp() + timedelta(days=10)
+        app.inspect(licence_plate, inspected_on)
+
+        # Check vehicle state.
+        vehicle = app.get_vehicle(licence_plate)
+        self.assertEqual(len(vehicle.bookings), 2)
+        self.assertEqual(len(vehicle.inspection_failures), 1)
+
+        # Check all domain events in bounded context.
+        notifications = NotificationLogReader(app.notification_log).read(start=1)
+        domain_events = [app.mapper.to_domain_event(n) for n in notifications]
+        self.assertEqual(len(domain_events), 4)
+
+        vehicle1_id = Vehicle.create_id("123-123")
+        event0 = domain_events[0]
+        assert isinstance(event0, Vehicle.Registered)
+        self.assertEqual(event0.originator_id, vehicle1_id)
+        self.assertEqual(event0.originator_version, 1)
+        self.assertEqual(event0.licence_plate_number, "123-123")
+
+        event1 = domain_events[1]
+        assert isinstance(event1, Vehicle.Booked)
+        self.assertEqual(event1.originator_id, vehicle1_id)
+        self.assertEqual(event1.originator_version, 2)
+        self.assertEqual(event1.start, booking1.start)
+        self.assertEqual(event1.finish, booking1.finish)
+
+        event2 = domain_events[2]
+        assert isinstance(event2, Vehicle.Booked)
+        self.assertEqual(event2.originator_id, vehicle1_id)
+        self.assertEqual(event2.originator_version, 3)
+        self.assertEqual(event2.start, booking2.start)
+        self.assertEqual(event2.finish, booking2.finish)
+
+        event3 = domain_events[3]
+        assert isinstance(event3, Vehicle.Unbooked)
+        self.assertEqual(event3.originator_id, vehicle1_id)
+        self.assertEqual(event3.originator_version, 4)
+        self.assertEqual(event3.when, inspected_on)

eventsourcing/interface.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 from abc import ABC, abstractmethod
 from base64 import b64decode, b64encode
-from typing import Generic, List, Optional, Sequence
+from typing import Generic, List, Sequence
 from uuid import UUID
 
 from eventsourcing.application import NotificationLog, Section, TApplication
@@ -125,7 +125,7 @@ class NotificationLogJSONClient(NotificationLog):
         self,
         start: int,
         limit: int,
-        stop: Optional[int] = None,
+        _: int | None = None,
         topics: Sequence[str] = (),
     ) -> List[Notification]:
         """