Merge remote-tracking branch 'atlas/master' into indexing

Author: hjwp

appendix_csvs.asciidoc

@@ -240,7 +240,7 @@ And here's((("Unit of Work pattern", "UoW for CSVs"))) what a UoW for CSVs would
 
 
 [[csvs_uow]]
-.A UoW for CSVs: commit = csv.writer. (src/allocation/service_layer/csv_uow.py)
+.A UoW for CSVs: commit = csv.writer (src/allocation/service_layer/csv_uow.py)
 ====
 [source,python]
 ----

appendix_django.asciidoc

@@ -104,8 +104,12 @@ but it is still made up of familiar-looking Django code:
 def test_repository_can_retrieve_a_batch_with_allocations():
     sku = "PONY-STATUE"
     d_line = django_models.OrderLine.objects.create(orderid="order1", sku=sku, qty=12)
-    d_b1 = django_models.Batch.objects.create(reference="batch1", sku=sku, qty=100, eta=None)
-    d_b2 = django_models.Batch.objects.create(reference="batch2", sku=sku, qty=100, eta=None)
+    d_b1 = django_models.Batch.objects.create(
+    reference="batch1", sku=sku, qty=100, eta=None
+)
+d_b2 = django_models.Batch.objects.create(
+    reference="batch2", sku=sku, qty=100, eta=None
+)
     django_models.Allocation.objects.create(line=d_line, batch=d_batch1)
 
     repo = repository.DjangoRepository()

appendix_validation.asciidoc

@@ -230,7 +230,7 @@ bear in mind that invalid data wandering through your system is a time bomb;
 the deeper it gets, the more damage it can do, and the fewer tools
 you have to respond to it.
 
-Back in <<chapter_06_uow>>, we said that the message bus was a great place to put
+Back in <<chapter_08_events_and_message_bus>>, we said that the message bus was a great place to put
 cross-cutting concerns, and validation is a perfect example of that. Here's how
 we might change our bus to perform validation for us:
 

chapter_01_domain_model.asciidoc

@@ -75,7 +75,7 @@ too late, and OO enthusiasts will tell you to look further back to Ivar
 Jacobson and Grady Booch; the term has been around since the mid-1980s.]
 and it's been a hugely successful movement in transforming the way people
 design software by focusing on the core business domain. Many of the
-architecture patterns that we cover in this book—including Entity, Aggregate, Value Object (see <<chapter_06_uow>>), and Repository (in
+architecture patterns that we cover in this book—including Entity, Aggregate, Value Object (see <<chapter_07_aggregate>>), and Repository (in
 <<chapter_02_repository,the next chapter>>)—come from the DDD tradition.
 
 In a nutshell, DDD says that the most important thing about software is that it
@@ -212,6 +212,11 @@ We can't allocate the same line twice. For example:
 Batches have an _ETA_ if they are currently shipping, or they may be in _warehouse stock_. We allocate to warehouse stock in preference to shipment batches. We allocate to shipment batches in order of which has the earliest ETA.
 ****
 
+=== Unit Testing Domain Models
+
+We're not going to show you how TDD works in this book, but we want to show you
+how we would construct a model from this business conversation.((("unit testing", "of domain models", id="ix_UTDM")))((("domain modeling", "unit testing domain models", id="ix_dommodUT")))
+
 [role="nobreakinside less_space"]
 .Exercise for the Reader
 ******************************************************************************
@@ -227,12 +232,6 @@ scratch, or combine/rewrite them however you like.
 
 ******************************************************************************
 
-
-=== Unit Testing Domain Models
-
-We're not going to show you how TDD works in this book, but we want to show you
-how we would construct a model from this business conversation.((("unit testing", "of domain models", id="ix_UTDM")))((("domain modeling", "unit testing domain models", id="ix_dommodUT")))
-
 Here's what one of our first tests might look like:
 
 [[first_test]]
@@ -970,7 +969,7 @@ Not everything has to be an object::
     or `get_baz()` waiting to happen.((("functions")))
 
 This is the time to apply your best OO design principles::
-    Revisit the ((("object-oriented design principles")))SOLID principles and all the other good heuristics like "a versus is-a,"
+    Revisit the ((("object-oriented design principles")))SOLID principles and all the other good heuristics like "has a versus is-a,"
     "prefer composition over inheritance," and so on.
 
 You'll((("domain modeling", startref="ix_dommod"))) also want to think about consistency boundaries and aggregates::

chapter_02_repository.asciidoc

@@ -86,7 +86,7 @@ We'll need a way to retrieve batch info from the database and instantiate our do
 model objects from it, and we'll also need a way of saving them back to the
 database.
 
-_(What? Oh, "gubbins" is a British word for "stuff." You can just ignore that. It's pseudocode, OK?)_
+_What? Oh, "gubbins" is a British word for "stuff." You can just ignore that. It's pseudocode, OK?_
 
 
 === Applying the DIP to Data Access
@@ -269,7 +269,7 @@ inversion and the Repository pattern to Django.
 ==== Inverting the Dependency: ORM Depends on Model
 
 Well, thankfully, that's not the only way to use SQLAlchemy.((("object-relational mappers (ORMs)", "ORM depends on the data model")))((("domain model", "translating to relational database", "ORM depends on the model")))((("dependency inversion principle", "ORM depends on the data model")))((("SQLAlchemy", "explicit ORM mapping with SQLAlchemy Table objects")))((("classical mapping")))((("mappers")))  The alternative is
-to define your schema separately, and an explicit _mapper_ for how to convert
+to define your schema separately, and to define an explicit _mapper_ for how to convert
 between the schema and our domain model, what SQLAlchemy calls a
 https://oreil.ly/ZucTG[classical mapping]:
 
@@ -666,9 +666,9 @@ def test_repository_can_retrieve_a_batch_with_allocations(session):
     assert retrieved == expected  # Batch.__eq__ only compares reference  #<3>
     assert retrieved.sku == expected.sku  #<4>
     assert retrieved._purchased_quantity == expected._purchased_quantity
-    assert retrieved._allocations == {
+    assert retrieved._allocations == {  #<4>
         model.OrderLine("order1", "GENERIC-SOFA", 12),
-    }  #<4>
+    }
 ----
 ====
 

chapter_03_abstractions.asciidoc

@@ -668,9 +668,7 @@ Steve Freeman has a great example of overmocked tests in his talk
 https://oreil.ly/jAmtr["Test-Driven Development"].
 You should also check out this PyCon talk, https://oreil.ly/s3e05["Mocking and Patching Pitfalls"],
 by our esteemed tech reviewer, Ed Jung, which also addresses mocking and its
-alternatives.(((""Test-Driven Development: That's Not What We Meant"", primary-sortas="Test-Driven Development")))((("Freeman, Steve")))((("PyCon talk on Mocking Pitfalls")))((("Jung, Ed")))
-
-And while we're recommending talks, don't miss Brandon Rhodes talking about
+alternatives.(((""Test-Driven Development: That's Not What We Meant"", primary-sortas="Test-Driven Development")))((("Freeman, Steve")))((("PyCon talk on Mocking Pitfalls")))((("Jung, Ed"))) And while we're recommending talks, don't miss Brandon Rhodes talking about
 https://oreil.ly/oiXJM["Hoisting Your I/O"],
 which really nicely covers the issues we're talking about, using another simple example.((("hoisting I/O")))((("Rhodes, Brandon")))
 

chapter_04_service_layer.asciidoc

@@ -13,14 +13,14 @@ business logic, and interfacing code, and we introduce the _Service Layer_
 pattern to take care of orchestrating our workflows and defining the use
 cases of our system.
 
-We'll also discuss testing: by combining the Service Layer with our Repository
+We'll also discuss testing: by combining the Service Layer with our repository
 abstraction over the database, we're able to write fast tests, not just of
 our domain model but of the entire workflow for a use case.
 
 <<maps_service_layer_after>> shows what we're aiming for: we're going to
 add a Flask API that will talk to the service layer, which will serve as the
 entrypoint to our domain model. Because our service layer depends on the
-`AbstractRepository`, we can unit test it by using `FakeRepository` but run it our production code using `SqlAlchemyRepository`.
+`AbstractRepository`, we can unit test it by using `FakeRepository` but run our production code using `SqlAlchemyRepository`.
 
 NOTE: In our diagrams, we are using the convention that new components
     are highlighted with bold text/lines (and yellow/orange color, if you're
@@ -42,7 +42,7 @@ chapter_04_service_layer branch https://oreil.ly/TBRuy[on GitHub]:
 git clone https://github.com/cosmicpython/code.git
 cd code
 git checkout chapter_04_service_layer
-# or to code along, checkout the previous chapter:
+# or to code along, checkout Chapter 2:
 git checkout chapter_02_repository
 ----
 ====
@@ -669,7 +669,7 @@ Here's one way we could organize things:
 <1> Let's have a folder for our domain model.((("domain model", "folder for")))  Currently that's just one file,
     but for a more complex application, you might have one file per class; you
     might have helper parent classes for `Entity`, `ValueObject`, and
-    `Aggregate`, you might add an __exceptions.py__ for domain-layer exceptions
+    `Aggregate`, and you might add an __exceptions.py__ for domain-layer exceptions
     and, as you'll see in <<part2>>, pass:[<span class="keep-together"><em>commands.py</em></span>] and __events.py__.
 
 <2> We'll distinguish the service layer. Currently that's just one file

chapter_05_high_gear_low_gear.asciidoc

@@ -428,7 +428,7 @@ NOTE: Are you thinking to yourself, POST to _/add_batch_? That's not
     very RESTful!  You're quite right.  We're being happily sloppy, but
     if you'd like to make it all more RESTy, maybe a POST to _/batches_,
     then knock yourself out!  Because Flask is a thin adapter, it'll be
-    easy.  See the next sidebar.
+    easy. See <<types_of_test_rules_of_thumb, the next sidebar>>.
 
 And our hardcoded SQL queries from _conftest.py_ get replaced with some
 API calls, meaning the API tests have no dependencies other than the API,
@@ -515,3 +515,5 @@ Error handling counts as a feature::
     unit tests, of course).((("test-driven development (TDD)", startref="ix_TDD")))
 
 ******************************************************************************
+
+Onto the next chapter!

chapter_06_uow.asciidoc

@@ -22,7 +22,7 @@ chapter_06_uow branch https://oreil.ly/MoWdZ[on GitHub]:
 git clone https://github.com/cosmicpython/code.git
 cd code
 git checkout chapter_06_uow
-# or to code along, check out the previous chapter:
+# or to code along, checkout Chapter 4:
 git checkout chapter_04_service_layer
 ----
 ====
@@ -31,7 +31,7 @@ git checkout chapter_04_service_layer
 .Without UoW: API talks directly to three layers
 image::images/apwp_0601.png[]
 
-<<after_uow_diagram>> shows our target state: the Flask API now does only two
+<<after_uow_diagram>> shows our target state. The Flask API now does only two
 things: it initializes a unit of work, and it invokes a service. The service
 collaborates with the UoW (we like to think of the UoW as being part of the
 service layer), but neither the service function itself nor Flask now needs

chapter_07_aggregate.asciidoc

@@ -185,7 +185,7 @@ ____
 
 Per Evans, our aggregate has a root entity (the Cart) that encapsulates access
 to items. Each item has its own identity, but other parts of the system will always
-refer to the cart only as an indivisible whole.
+refer to the Cart only as an indivisible whole.
 
 TIP: Just as we sometimes use pass:[<code><em>_leading_underscores</em></code>] to mark methods or functions
     as "private," you can think of aggregates as being the "public" classes of our
@@ -655,7 +655,7 @@ There are essentially three options((("version numbers", "implementation options
 1. `version_number` lives in the domain; we add it to the `Product` constructor,
    and `Product.allocate()` is responsible for incrementing it.
 
-2. The services layer could do it!  The version number isn't _strictly_ a domain
+2. The service layer could do it!  The version number isn't _strictly_ a domain
    concern, so instead our service layer could assume that the current version number
    is attached to `Product` by the repository, and the service layer will increment it
    before it does the `commit()`.
@@ -882,7 +882,7 @@ performing some performance experiments.((("testing", "for data integrity rules"
 
 Specific choices around concurrency control vary a lot based on business
 circumstances and storage technology choices, but we'd like to bring this
-chapter back to the((("aggregates", "and consistency boundaries recap"))) conceptual idea of an Aggregate: we explicitly model an
+chapter back to the((("aggregates", "and consistency boundaries recap"))) conceptual idea of an aggregate: we explicitly model an
 object as being the main entrypoint to some subset of our model, and as being in
 charge of enforcing the invariants and business rules that apply across all of
 those objects.
@@ -987,7 +987,7 @@ models that represent the shared language of your business experts. Hurrah!
 NOTE: At the risk of laboring the point--we've been at pains to point out that
     each pattern comes at a cost.((("patterns, deciding whether you need to use them"))) Each layer of indirection has a price in terms
     of complexity and duplication in our code and will be confusing to programmers
-    who've never seen them before. If your app is essentially a simple CRUD
+    who've never seen these patterns before. If your app is essentially a simple CRUD
     wrapper around a database and isn't likely to be anything more than that
     in the foreseeable future, _you don't need these patterns_. Go ahead and
     use Django, and save yourself a lot of bother.((("CRUD wrapper around a database")))