Improved aggregate example 6.

Author: johnbywater

docs/topics/examples/aggregate5.rst

@@ -42,7 +42,7 @@ Domain model
 
 The :class:`~examples.aggregate5.domainmodel.Dog` aggregate class is defined as immutable frozen data class
 that extends the aggregate base class. The aggregate event classes, :class:`~examples.aggregate5.domainmodel.Dog.Registered` and
-:class:`~examples.aggregate5.domainmodel.Dog.TrickAdded`, are explicitly defined.
+:class:`~examples.aggregate5.domainmodel.Dog.TrickAdded`, are explicitly defined as nested subclasses.
 
 The :class:`~examples.aggregate5.domainmodel.Dog` aggregate class defines a
 :func:`~examples.aggregate5.domainmodel.Dog.mutate` method, which evolves aggregate state by constructing a new

docs/topics/examples/aggregate6.rst

@@ -3,43 +3,105 @@
 Aggregate 6 - Functional style
 ==============================
 
-This example shows another variation of the ``Dog`` aggregate class used
-in the tutorial and module docs.
+This example shows how to define and use your own immutable aggregate base class with a more "functional"
+style than :doc:`example 5  </topics/examples/aggregate5>`.
 
-Like in the previous example, this example defines immutable ``Aggregate`` and
-``DomainEvent`` base classes, as frozen data classes. However, this time the
-aggregate class has no methods. All the functionality has been implemented
-as module-level functions.
+Base classes
+------------
+
+The :class:`~examples.aggregate6.baseclasses.DomainEvent` class is defined as a "frozen" Python :class:`dataclass`.
+
+.. literalinclude:: ../../../examples/aggregate6/baseclasses.py
+    :pyobject: DomainEvent
+
+The :class:`~examples.aggregate6.baseclasses.Aggregate` base class in this example is also defined as a "frozen" Python
+:class:`dataclass`.
+
+.. literalinclude:: ../../../examples/aggregate6/baseclasses.py
+    :pyobject: Aggregate
+
+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.
+
+.. literalinclude:: ../../../examples/aggregate6/baseclasses.py
+    :pyobject: aggregate_projector
 
-Like in the previous examples, the application code in this example must receive
-the domain events that are returned from the aggregate command methods. The aggregate
-projector function must also be supplied when getting an aggregate from the
-repository and when taking snapshots.
 
 
 Domain model
 ------------
 
+The :class:`~examples.aggregate6.domainmodel.Dog` aggregate class is defined as immutable frozen data class
+that extends the aggregate base class.
+
 .. literalinclude:: ../../../examples/aggregate6/domainmodel.py
+    :pyobject: Dog
+
+The aggregate event classes, :class:`~examples.aggregate6.domainmodel.DogRegistered` and
+:class:`~examples.aggregate6.domainmodel.TrickAdded`, are explicitly defined as separate module level classes.
+
+.. literalinclude:: ../../../examples/aggregate6/domainmodel.py
+    :pyobject: DogRegistered
+
+.. literalinclude:: ../../../examples/aggregate6/domainmodel.py
+    :pyobject: TrickAdded
+
+The aggregate commands, :func:`~examples.aggregate6.domainmodel.register_dog` and
+:func:`~examples.aggregate6.domainmodel.add_trick` are defined as module level functions.
+
+.. literalinclude:: ../../../examples/aggregate6/domainmodel.py
+    :pyobject: register_dog
+
+.. literalinclude:: ../../../examples/aggregate6/domainmodel.py
+    :pyobject: add_trick
+
+The mutator function, :func:`~examples.aggregate6.domainmodel.mutate_dog`, is defined as a module level function.
+
+.. literalinclude:: ../../../examples/aggregate6/domainmodel.py
+    :start-at: @singledispatch
+    :end-before: project_dog
+
+The aggregate projector function, :func:`~examples.aggregate6.domainmodel.project_dog`, is defined as a module
+level function by calling :func:`~examples.aggregate6.baseclasses.aggregate_projector` with
+:func:`~examples.aggregate6.domainmodel.mutate_dog` as the argument.
+
+.. literalinclude:: ../../../examples/aggregate6/domainmodel.py
+    :start-at: project_dog
 
 
 Application
 -----------
 
+The :class:`~examples.aggregate6.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/aggregate6/application.py
+    :pyobject: DogSchool
 
 
 Test case
 ---------
 
+The :class:`~examples.aggregate6.test_application.TestDogSchool` test case shows how the
+:class:`~examples.aggregate6.application.DogSchool` application can be used.
 
 .. literalinclude:: ../../../examples/aggregate6/test_application.py
+    :pyobject: TestDogSchool
 
 
 Code reference
 --------------
 
+.. automodule:: examples.aggregate6.baseclasses
+    :show-inheritance:
+    :member-order: bysource
+    :members:
+    :undoc-members:
+
 .. automodule:: examples.aggregate6.domainmodel
     :show-inheritance:
     :member-order: bysource

examples/aggregate6/baseclasses.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Callable, Iterable, Optional, TypeVar
+
+if TYPE_CHECKING:
+    from datetime import datetime
+    from uuid import UUID
+
+
+@dataclass(frozen=True)
+class DomainEvent:
+    originator_id: UUID
+    originator_version: int
+    timestamp: datetime
+
+
+@dataclass(frozen=True)
+class Aggregate:
+    id: UUID
+    version: int
+    created_on: datetime
+    modified_on: datetime
+
+
+TAggregate = TypeVar("TAggregate", bound=Aggregate)
+MutatorFunction = Callable[..., Optional[TAggregate]]
+
+
+def aggregate_projector(
+    mutator: MutatorFunction[TAggregate],
+) -> Callable[[TAggregate | None, Iterable[DomainEvent]], TAggregate | None]:
+    def project_aggregate(
+        aggregate: TAggregate | None, events: Iterable[DomainEvent]
+    ) -> TAggregate | None:
+        for event in events:
+            aggregate = mutator(event, aggregate)
+        return aggregate
+
+    return project_aggregate

examples/aggregate6/domainmodel.py

@@ -2,45 +2,11 @@
 
 from dataclasses import dataclass
 from functools import singledispatch
-from typing import TYPE_CHECKING, Callable, Iterable, Optional, Tuple, TypeVar
-from uuid import UUID, uuid4
+from typing import Tuple
+from uuid import uuid4
 
 from eventsourcing.domain import Snapshot, datetime_now_with_tzinfo
-
-if TYPE_CHECKING:
-    from datetime import datetime
-
-
-@dataclass(frozen=True)
-class DomainEvent:
-    originator_id: UUID
-    originator_version: int
-    timestamp: datetime
-
-
-@dataclass(frozen=True)
-class Aggregate:
-    id: UUID
-    version: int
-    created_on: datetime
-    modified_on: datetime
-
-
-TAggregate = TypeVar("TAggregate", bound=Aggregate)
-MutatorFunction = Callable[..., Optional[TAggregate]]
-
-
-def aggregate_projector(
-    mutator: MutatorFunction[TAggregate],
-) -> Callable[[TAggregate | None, Iterable[DomainEvent]], TAggregate | None]:
-    def project_aggregate(
-        aggregate: TAggregate | None, events: Iterable[DomainEvent]
-    ) -> TAggregate | None:
-        for event in events:
-            aggregate = mutator(event, aggregate)
-        return aggregate
-
-    return project_aggregate
+from examples.aggregate6.baseclasses import Aggregate, DomainEvent, aggregate_projector
 
 
 @dataclass(frozen=True)

tests/docs_tests/test_docs.py

@@ -88,9 +88,7 @@ def test_readme(self):
         # self.check_code_snippets_in_file(path)
 
     def test_docs(self):
-        skipped = [
-            # 'deployment.rst'
-        ]
+        skipped = ["aggregate6.rst"]  # has :start-from: complications...
 
         self._out = ""
         docs_path = os.path.join(base_dir, "docs")
@@ -210,8 +208,10 @@ def check_code_snippets_in_file(self, doc_path):
                     num_code_lines_in_block = 0
                 elif line.startswith(".. literalinclude::"):
                     is_literalinclude = True
-                    module = line.strip().split(" ")[-1]  # get the file path
-                    module = module[:-3]  # remove the '.py' from the end
+                    literal_include_path = line.strip().split(" ")[
+                        -1
+                    ]  # get the file path
+                    module = literal_include_path[:-3]  # remove the '.py' from the end
                     module = module.lstrip("./")  # remove all the ../../..
                     module = module.replace("/", ".")  # swap dots for slashes
                     line = ""