Added "vertical slices" example.

Author: johnbywater

Makefile

@@ -30,10 +30,10 @@ install-packages:
 
 .PHONY: poetry-update
 poetry-update:
-	$(POETRY) lock
+	$(POETRY) update
 
 .PHONY: update
-update: poetry-update install
+update: poetry-update install-packages
 
 .PHONY: lint
 lint: lint-black lint-ruff lint-isort lint-pyright lint-mypy #lint-dockerfile

docs/topics/examples.rst

@@ -43,6 +43,7 @@ Example applications
    examples/content-management
    examples/searchable-timestamps
    examples/fts-content-management
+   examples/shop-vertical
 
 .. _Example projections:
 

docs/topics/examples/shop-vertical.rst

@@ -0,0 +1,85 @@
+.. _Vertical slices example:
+
+Application 6 - Vertical slices
+===============================
+
+This example demonstrates how to do event sourcing with the "vertical slice architecture" advocated by the event
+modelling community.
+
+Get cart items
+--------------
+
+.. literalinclude:: ../../../examples/shopvertical/slices/get_cart_items/query.py
+    :pyobject: CartItem
+
+.. literalinclude:: ../../../examples/shopvertical/slices/get_cart_items/query.py
+    :pyobject: GetCartItems
+
+.. literalinclude:: ../../../examples/shopvertical/slices/get_cart_items/test.py
+    :pyobject: TestGetCartItems
+
+Add item to cart
+----------------
+
+.. literalinclude:: ../../../examples/shopvertical/slices/add_item_to_cart/cmd.py
+    :pyobject: AddItemToCart
+
+.. literalinclude:: ../../../examples/shopvertical/slices/add_item_to_cart/test.py
+    :pyobject: TestAddItemToCart
+
+Remove item from cart
+---------------------
+
+.. literalinclude:: ../../../examples/shopvertical/slices/remove_item_from_cart/cmd.py
+    :pyobject: RemoveItemFromCart
+
+.. literalinclude:: ../../../examples/shopvertical/slices/remove_item_from_cart/test.py
+    :pyobject: TestRemoveItemFromCart
+
+Clear cart
+----------
+
+.. literalinclude:: ../../../examples/shopvertical/slices/clear_cart/cmd.py
+    :pyobject: ClearCart
+
+.. literalinclude:: ../../../examples/shopvertical/slices/clear_cart/test.py
+    :pyobject: TestClearCart
+
+Submit cart
+-----------
+
+.. literalinclude:: ../../../examples/shopvertical/slices/submit_cart/cmd.py
+    :pyobject: SubmitCart
+
+.. literalinclude:: ../../../examples/shopvertical/slices/submit_cart/test.py
+    :pyobject: TestSubmitCart
+
+Adjust product inventory
+------------------------
+
+.. literalinclude:: ../../../examples/shopvertical/slices/adjust_product_inventory/cmd.py
+    :pyobject: AdjustProductInventory
+
+.. literalinclude:: ../../../examples/shopvertical/slices/adjust_product_inventory/test.py
+    :pyobject: TestAdjustProductInventory
+
+Events
+------
+
+.. literalinclude:: ../../../examples/shopvertical/events.py
+
+Exceptions
+----------
+
+.. literalinclude:: ../../../examples/shopvertical/exceptions.py
+
+Common code
+-----------
+
+.. literalinclude:: ../../../examples/shopvertical/common.py
+
+Integration test
+----------------
+
+.. literalinclude:: ../../../examples/shopvertical/test.py
+    :pyobject: TestShop

examples/shopvertical/__init__.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, cast
+
+from eventsourcing.application import Application
+from examples.shopvertical.events import DomainEvent
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+
+class Command(ABC):
+    @abstractmethod
+    def handle(self, events: tuple[DomainEvent, ...]) -> tuple[DomainEvent, ...]:
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def execute(self) -> int | None:
+        pass  # pragma: no cover
+
+
+_event_store = Application().events
+
+
+def get_events(originator_id: UUID) -> tuple[DomainEvent, ...]:
+    return cast(tuple[DomainEvent, ...], tuple(_event_store.get(originator_id)))
+
+
+def put_events(events: tuple[DomainEvent, ...]) -> int | None:
+    recordings = _event_store.put(events)
+    return recordings[-1].notification.id if recordings else None

examples/shopvertical/common.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from decimal import Decimal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+
+class DomainEvent(BaseModel, frozen=True):
+    model_config = ConfigDict(extra="forbid")
+
+    originator_id: UUID
+    originator_version: int
+
+
+class AddedItemToCart(DomainEvent, frozen=True):
+    product_id: UUID
+    description: str
+    price: Decimal
+    name: str
+
+
+class RemovedItemFromCart(DomainEvent, frozen=True):
+    product_id: UUID
+
+
+class ClearedCart(DomainEvent, frozen=True):
+    pass
+
+
+class SubmittedCart(DomainEvent, frozen=True):
+    pass
+
+
+class AdjustedProductInventory(DomainEvent, frozen=True):
+    adjustment: int

examples/shopvertical/events.py

@@ -0,0 +1,10 @@
+class CartFullError(Exception):
+    pass
+
+
+class ProductNotInCartError(Exception):
+    pass
+
+
+class InsufficientInventoryError(Exception):
+    pass

examples/shopvertical/exceptions.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from examples.shopvertical.common import Command, get_events, put_events
+from examples.shopvertical.events import (
+    AddedItemToCart,
+    ClearedCart,
+    DomainEvent,
+    RemovedItemFromCart,
+)
+from examples.shopvertical.exceptions import CartFullError
+
+if TYPE_CHECKING:
+    from decimal import Decimal
+    from uuid import UUID
+
+
+@dataclass(frozen=True)
+class AddItemToCart(Command):
+    cart_id: UUID
+    product_id: UUID
+    description: str
+    price: Decimal
+    name: str
+
+    def handle(self, events: tuple[DomainEvent, ...]) -> tuple[DomainEvent, ...]:
+        product_ids = []
+        for event in events:
+            if isinstance(event, AddedItemToCart):
+                product_ids.append(event.product_id)
+            elif isinstance(event, RemovedItemFromCart):
+                product_ids.remove(event.product_id)
+            elif isinstance(event, ClearedCart):
+                product_ids.clear()
+
+        if len(product_ids) >= 3:
+            raise CartFullError
+
+        return (
+            AddedItemToCart(
+                originator_id=self.cart_id,
+                originator_version=len(events) + 1,
+                product_id=self.product_id,
+                description=self.description,
+                price=self.price,
+                name=self.name,
+            ),
+        )
+
+    def execute(self) -> int | None:
+        return put_events(self.handle(get_events(self.cart_id)))