Improved aggregate examples 6, 7 and 8.

Author: johnbywater

docs/topics/examples/aggregate6.rst

@@ -20,6 +20,12 @@ The :class:`~examples.aggregate6.baseclasses.Aggregate` base class in this examp
 .. literalinclude:: ../../../examples/aggregate6/baseclasses.py
     :pyobject: Aggregate
 
+The :class:`~examples.aggregate6.baseclasses.Snapshot` class in this example is also defined as a "frozen" Python
+:class:`dataclass` that extends :class:`~examples.aggregate6.baseclasses.DomainEvent`.
+
+.. literalinclude:: ../../../examples/aggregate6/baseclasses.py
+    :pyobject: Snapshot
+
 A generic :class:`~examples.aggregate6.baseclasses.aggregate_projector` function is also defined, which takes
 a mutator function and returns a function that can reconstruct an aggregate of a particular type from an iterable
 of domain events.

docs/topics/examples/aggregate7.rst

@@ -3,58 +3,74 @@
 Aggregate 7 - Pydantic and orjson
 =================================
 
-This example shows another variation of the ``Dog`` aggregate class used
-in the tutorial and module docs.
-
-Similar to the previous example, the model is expressed in a functional
-style. In contrast to the previous example, this example uses Pydantic
-to define immutable aggregate and event classes, rather than defining
-them as Python frozen data classes. This has implications for the
-persistence layer.
-
-The application class in this example uses its own persistence classes
-``PydanticMapper`` and ``OrjsonTranscoder``. Pydantic is responsible
-for converting domain model objects to object types that orjson can
-serialise, and for reconstructing model objects from JSON objects
-that have been deserialised by orjson.
-
-One advantage of using Pydantic here is that any custom value objects
-will be automatically reconstructed without needing to define the
-transcoding classes that would be needed when using the library's
-default ``JSONTranscoder``. This is demonstrated in the example below
-with the ``Trick`` class, which is used in both aggregate events and
-aggregate state, and which is reconstructed from serialised string
-values, representing only the name of the trick, from both recorded
-aggregate events and from recorded snapshots.
+This example shows how to use Pydantic to define immutable aggregate and event classes.
+
+The main advantage of using Pydantic here is that any custom value objects
+used in the domain model will be automatically serialised and deserialised,
+without needing also to define custom :ref:`transcoding<Transcodings>` classes.
+
+This is demonstrated in the example below with the :class:`~examples.aggregate7.domainmodel.Trick` class,
+which is used in both aggregate events and aggregate state, and which is reconstructed from serialised string
+values, representing only the name of the trick, from both recorded aggregate events and from recorded snapshots.
 
 Pydantic mapper and orjson transcoder
 -------------------------------------
 
+The application class in this example uses a :ref:`mapper<Mapper>` that supports Pydantic and a :ref:`transcoder<Transcoder>` that uses orjson.
+
+The :class:`~examples.aggregate7.orjsonpydantic.PydanticMapper` class is a
+:ref:`mapper<Mapper>` that supports Pydantic. It is responsible for converting
+domain model objects to object types that orjson can serialise, and for
+reconstructing model objects from JSON objects that have been deserialised by orjson.
+
 .. literalinclude:: ../../../examples/aggregate7/orjsonpydantic.py
+    :pyobject: PydanticMapper
+
+The :class:`~examples.aggregate7.orjsonpydantic.OrjsonTranscoder` class is a
+:ref:`transcoder<Transcoder>` that uses orjson, possibly the fastest JSON transcoder
+available in Python.
+
+.. literalinclude:: ../../../examples/aggregate7/orjsonpydantic.py
+    :pyobject: OrjsonTranscoder
 
 
 Pydantic model for immutable aggregate
 --------------------------------------
 
+The code below shows how to define base classes for immutable aggregates that use Pydantic.
+
 .. literalinclude:: ../../../examples/aggregate7/immutablemodel.py
 
 
 Domain model
 ------------
 
+The code below shows how to define an immutable aggregate in a functional style, using the Pydantic module for immutable aggregates.
+
 .. literalinclude:: ../../../examples/aggregate7/domainmodel.py
 
 
 Application
 -----------
 
+The :class:`~examples.aggregate7.application.DogSchool` application in this example uses the library's
+:class:`~eventsourcing.application.Application` class. It must receive the new events that are returned
+by the aggregate command methods, and pass them to its :func:`~eventsourcing.application.Application.save`
+method. The aggregate projector function must also be supplied when reconstructing an aggregate from the
+repository, and when taking snapshots.
+
 .. literalinclude:: ../../../examples/aggregate7/application.py
+    :pyobject: DogSchool
 
 
 Test case
 ---------
 
+The :class:`~examples.aggregate7.test_application.TestDogSchool` test case shows how the
+:class:`~examples.aggregate7.application.DogSchool` application can be used.
+
 .. literalinclude:: ../../../examples/aggregate7/test_application.py
+    :pyobject: TestDogSchool
 
 
 Code reference

docs/topics/examples/aggregate8.rst

@@ -3,52 +3,50 @@
 Aggregate 8 - Pydantic with declarative syntax
 ==============================================
 
-This example shows another variation of the ``Dog`` aggregate class used
-in the tutorial and module docs.
-
-Similar to :doc:`example 1  </topics/examples/aggregate1>`, the aggregate is expressed
-using the library's declarative syntax. And similar to :doc:`example 7  </topics/examples/aggregate7>`,
-the model events are defined using Pydantic.
-
-The application class in this example uses the persistence classes ``PydanticMapper``
-and ``OrjsonTranscoder`` from :doc:`example 7  </topics/examples/aggregate7>`. Pydantic
-is responsible for converting domain model objects to object types that orjson can serialise,
-and for reconstructing model objects from JSON objects that have been deserialised by orjson.
-The application class also uses the custom ``Snapshot`` class, which also is defined as a
-Pydantic model.
-
-One advantage of using Pydantic here is that any custom value objects
-will be automatically reconstructed without needing to define the
-transcoding classes that would be needed when using the library's
-default ``JSONTranscoder``. This is demonstrated in the example below
-with the ``Trick`` class, which is used in both aggregate events and
-aggregate state, and which is reconstructed from serialised string
-values, representing only the name of the trick, from both recorded
-aggregate events and from recorded snapshots.
+This example shows how to use Pydantic with the library's declarative syntax.
 
+Similar to :doc:`example 1  </topics/examples/aggregate1>`, aggregates are expressed
+using the library's declarative syntax. This is the most concise way of defining an
+event-sourced aggregate.
+
+Similar to :doc:`example 7  </topics/examples/aggregate7>`, domain event and custom value objects
+are defined using Pydantic. The main advantage of using Pydantic here is that any custom value objects
+used in the domain model will be automatically serialised and deserialised, without needing also to
+define custom :ref:`transcoding<Transcodings>` classes.
 
 Pydantic model for mutable aggregate
 ------------------------------------
 
+The code below shows how to define base classes for mutable aggregates that use Pydantic.
+
 .. literalinclude:: ../../../examples/aggregate8/mutablemodel.py
 
 
 Domain model
 ------------
 
+The code below shows how to define an aggregate using the Pydantic and the library's declarative syntax.
+
 .. literalinclude:: ../../../examples/aggregate8/domainmodel.py
 
 
 Application
 -----------
 
+The :class:`~examples.aggregate8.application.DogSchool` application in this example uses the library's
+:class:`~eventsourcing.application.Application` class. It also uses the
+:class:`~examples.aggregate7.orjsonpydantic.PydanticMapper` and
+:class:`~examples.aggregate7.orjsonpydantic.OrjsonTranscoder` classes
+from :doc:`example 7  </topics/examples/aggregate7>`.
 
 .. literalinclude:: ../../../examples/aggregate8/application.py
 
 
 Test case
 ---------
 
+The :class:`~examples.aggregate7.test_application.TestDogSchool` test case shows how the
+:class:`~examples.aggregate7.application.DogSchool` application can be used.
 
 .. literalinclude:: ../../../examples/aggregate8/test_application.py
 

eventsourcing/domain.py

@@ -1552,12 +1552,6 @@ class VersionError(OriginatorVersionError):
 
 
 class SnapshotProtocol(DomainEventProtocol, Protocol):
-    @property
-    def topic(self) -> str:
-        """
-        Snapshots have a read-only 'topic'.
-        """
-
     @property
     def state(self) -> Dict[str, Any]:
         """

examples/aggregate6/application.py

@@ -3,6 +3,7 @@
 from typing import TYPE_CHECKING, Any, Dict
 
 from eventsourcing.application import Application
+from examples.aggregate6.baseclasses import Snapshot
 from examples.aggregate6.domainmodel import add_trick, project_dog, register_dog
 
 if TYPE_CHECKING:
@@ -11,6 +12,7 @@
 
 class DogSchool(Application):
     is_snapshotting_enabled = True
+    snapshot_class = Snapshot
 
     def register_dog(self, name: str) -> UUID:
         event = register_dog(name)

examples/aggregate6/baseclasses.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Callable, Iterable, Optional, TypeVar
+from typing import TYPE_CHECKING, Any, Callable, Dict, Iterable, Optional, TypeVar
+
+from eventsourcing.domain import datetime_now_with_tzinfo
 
 if TYPE_CHECKING:
     from datetime import datetime
@@ -23,6 +25,20 @@ class Aggregate:
     modified_on: datetime
 
 
+@dataclass(frozen=True)
+class Snapshot(DomainEvent):
+    state: Dict[str, Any]
+
+    @classmethod
+    def take(cls, aggregate: Aggregate) -> Snapshot:
+        return Snapshot(
+            originator_id=aggregate.id,
+            originator_version=aggregate.version,
+            timestamp=datetime_now_with_tzinfo(),
+            state=aggregate.__dict__,
+        )
+
+
 TAggregate = TypeVar("TAggregate", bound=Aggregate)
 MutatorFunction = Callable[..., Optional[TAggregate]]
 

examples/aggregate6/domainmodel.py

@@ -5,8 +5,13 @@
 from typing import Tuple
 from uuid import uuid4
 
-from eventsourcing.domain import Snapshot, datetime_now_with_tzinfo
-from examples.aggregate6.baseclasses import Aggregate, DomainEvent, aggregate_projector
+from eventsourcing.domain import datetime_now_with_tzinfo
+from examples.aggregate6.baseclasses import (
+    Aggregate,
+    DomainEvent,
+    Snapshot,
+    aggregate_projector,
+)
 
 
 @dataclass(frozen=True)
@@ -44,7 +49,7 @@ def add_trick(dog: Dog, trick: str) -> DomainEvent:
 
 
 @singledispatch
-def mutate_dog(_: DomainEvent | Snapshot, __: Dog | None) -> Dog | None:
+def mutate_dog(_: DomainEvent, __: Dog | None) -> Dog | None:
     """Mutates aggregate with event."""