title fixes and a bunch of other small stuff

hjwp · hjwp · commit f910bfe42b12 · 2020-07-30T15:09:19.000+01:00
diff --git a/book/appendix_csvs.html b/book/appendix_csvs.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="appendix_csvs">Appendix C: Swapping Out the Infrastructure: Do Everything with CSVs<a class="anchor" href="#appendix_csvs"></a>Appendix A: Swapping Out the Infrastructure: </h2>
+<h2 id="appendix_csvs">Appendix C: Swapping Out the Infrastructure: Do Everything with CSVs<a class="anchor" href="#appendix_csvs"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/appendix_django.html b/book/appendix_django.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="appendix_django">Appendix D: Repository and Unit of Work Patterns with Django<a class="anchor" href="#appendix_django"></a>Appendix A: Repository and Unit of Work </h2>
+<h2 id="appendix_django">Appendix D: Repository and Unit of Work Patterns with Django<a class="anchor" href="#appendix_django"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/appendix_ds1_table.html b/book/appendix_ds1_table.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="appendix_ds1_table">Appendix A: Summary Diagram and Table<a class="anchor" href="#appendix_ds1_table"></a>Appendix A: Summary Diagram and Table</h2>
+<h2 id="appendix_ds1_table">Appendix A: Summary Diagram and Table<a class="anchor" href="#appendix_ds1_table"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/appendix_project_structure.html b/book/appendix_project_structure.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="appendix_project_structure">Appendix B: A Template Project Structure<a class="anchor" href="#appendix_project_structure"></a>Appendix A: A Template Project Structure</h2>
+<h2 id="appendix_project_structure">Appendix B: A Template Project Structure<a class="anchor" href="#appendix_project_structure"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/appendix_validation.html b/book/appendix_validation.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="appendix_validation">Appendix E: Validation<a class="anchor" href="#appendix_validation"></a>Appendix A: Validation</h2>
+<h2 id="appendix_validation">Appendix E: Validation<a class="anchor" href="#appendix_validation"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/chapter_01_domain_model.html b/book/chapter_01_domain_model.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_01_domain_model">1: Domain Modeling<a class="anchor" href="#chapter_01_domain_model"></a>Domain Modeling</h2>
+<h2 id="chapter_01_domain_model">1: Domain Modeling<a class="anchor" href="#chapter_01_domain_model"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/chapter_02_repository.html b/book/chapter_02_repository.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_02_repository">2: Repository Pattern<a class="anchor" href="#chapter_02_repository"></a>Repository Pattern</h2>
+<h2 id="chapter_02_repository">2: Repository Pattern<a class="anchor" href="#chapter_02_repository"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>It&#8217;s time to make good on our promise to use the dependency inversion principle as
diff --git a/book/chapter_03_abstractions.html b/book/chapter_03_abstractions.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_03_abstractions">3: A Brief Interlude: On Coupling and Abstractions<a class="anchor" href="#chapter_03_abstractions"></a>A Brief Interlude: On Coupling </h2>
+<h2 id="chapter_03_abstractions">3: A Brief Interlude: On Coupling and Abstractions<a class="anchor" href="#chapter_03_abstractions"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
@@ -1121,7 +1121,7 @@ <h3 id="_wrap_up"><a class="anchor" href="#_wrap_up"></a>Wrap-Up</h3>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2020-05-13 20:35:58 +0100
+Last updated 2020-07-30 14:51:23 +0100
 </div>
 </div>
 <style>
diff --git a/book/chapter_04_service_layer.html b/book/chapter_04_service_layer.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_04_service_layer">4: Our First Use Case: Flask API and Service Layer<a class="anchor" href="#chapter_04_service_layer"></a>Our First Use Case: </h2>
+<h2 id="chapter_04_service_layer">4: Our First Use Case: Flask API and Service Layer<a class="anchor" href="#chapter_04_service_layer"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/chapter_05_high_gear_low_gear.html b/book/chapter_05_high_gear_low_gear.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_05_high_gear_low_gear">5: TDD in High Gear and Low Gear<a class="anchor" href="#chapter_05_high_gear_low_gear"></a>TDD in High Gear and Low Gear</h2>
+<h2 id="chapter_05_high_gear_low_gear">5: TDD in High Gear and Low Gear<a class="anchor" href="#chapter_05_high_gear_low_gear"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
@@ -193,7 +193,7 @@ <h3 id="_how_is_our_test_pyramid_looking"><a class="anchor" href="#_how_is_our_t
 <div class="content">
 <div class="listingblock skip">
 <div class="content">
-<pre class="pygments highlight"><code data-lang="sh"><span></span>$ grep -c test_ test_*.py
+<pre class="pygments highlight"><code data-lang="sh"><span></span>$ grep -c test_ **/test_*.py
 tests/unit/test_allocate.py:4
 tests/unit/test_batches.py:8
 tests/unit/test_services.py:3
@@ -791,7 +791,7 @@ <h3 id="_wrap_up"><a class="anchor" href="#_wrap_up"></a>Wrap-Up</h3>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2020-03-20 13:47:19 UTC
+Last updated 2020-07-30 14:51:23 +0100
 </div>
 </div>
 <style>
diff --git a/book/chapter_06_uow.html b/book/chapter_06_uow.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_06_uow">6: Unit of Work Pattern<a class="anchor" href="#chapter_06_uow"></a>Unit of Work Pattern</h2>
+<h2 id="chapter_06_uow">6: Unit of Work Pattern<a class="anchor" href="#chapter_06_uow"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/chapter_07_aggregate.html b/book/chapter_07_aggregate.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_07_aggregate">7: Aggregates and Consistency Boundaries<a class="anchor" href="#chapter_07_aggregate"></a>Aggregates and Consistency Boundaries</h2>
+<h2 id="chapter_07_aggregate">7: Aggregates and Consistency Boundaries<a class="anchor" href="#chapter_07_aggregate"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/chapter_08_events_and_message_bus.html b/book/chapter_08_events_and_message_bus.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_08_events_and_message_bus">8: Events and the Message Bus<a class="anchor" href="#chapter_08_events_and_message_bus"></a>Events and the Message Bus</h2>
+<h2 id="chapter_08_events_and_message_bus">8: Events and the Message Bus<a class="anchor" href="#chapter_08_events_and_message_bus"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/chapter_09_all_messagebus.html b/book/chapter_09_all_messagebus.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_09_all_messagebus">9: Going to Town on the Message Bus<a class="anchor" href="#chapter_09_all_messagebus"></a>Going to Town on the Message Bus</h2>
+<h2 id="chapter_09_all_messagebus">9: Going to Town on the Message Bus<a class="anchor" href="#chapter_09_all_messagebus"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/chapter_10_commands.html b/book/chapter_10_commands.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_10_commands">10: Commands and Command Handler<a class="anchor" href="#chapter_10_commands"></a>Commands and Command Handler</h2>
+<h2 id="chapter_10_commands">10: Commands and Command Handler<a class="anchor" href="#chapter_10_commands"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
diff --git a/book/chapter_11_external_events.html b/book/chapter_11_external_events.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_11_external_events">11: Event-Driven Architecture: Using Events to Integrate Microservices<a class="anchor" href="#chapter_11_external_events"></a>Event-Driven Architecture: Using Events to Integrate Microservices</h2>
+<h2 id="chapter_11_external_events">11: Event-Driven Architecture: Using Events to Integrate Microservices<a class="anchor" href="#chapter_11_external_events"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
@@ -603,7 +603,7 @@ <h3 id="_test_driving_it_all_using_an_end_to_end_test"><a class="anchor" href="#
     <span class="tok-c1"># start with two batches and an order allocated to one of them  </span>#<b class="conum">(1)</b>
     <span class="tok-n">orderid</span><span class="tok-p">,</span> <span class="tok-n">sku</span> <span class="tok-o">=</span> <span class="tok-n">random_orderid</span><span class="tok-p">(),</span> <span class="tok-n">random_sku</span><span class="tok-p">()</span>
     <span class="tok-n">earlier_batch</span><span class="tok-p">,</span> <span class="tok-n">later_batch</span> <span class="tok-o">=</span> <span class="tok-n">random_batchref</span><span class="tok-p">(</span><span class="tok-s1">'old'</span><span class="tok-p">),</span> <span class="tok-n">random_batchref</span><span class="tok-p">(</span><span class="tok-s1">'newer'</span><span class="tok-p">)</span>
-    <span class="tok-n">api_client</span><span class="tok-o">.</span><span class="tok-n">post_to_add_batch</span><span class="tok-p">(</span><span class="tok-n">earlier_batch</span><span class="tok-p">,</span> <span class="tok-n">sku</span><span class="tok-p">,</span> <span class="tok-n">qty</span><span class="tok-o">=</span><span class="tok-mi">10</span><span class="tok-p">,</span> <span class="tok-n">eta</span><span class="tok-o">=</span><span class="tok-s1">'2011-01-02'</span><span class="tok-p">)</span>  #<b class="conum">(2)</b>
+    <span class="tok-n">api_client</span><span class="tok-o">.</span><span class="tok-n">post_to_add_batch</span><span class="tok-p">(</span><span class="tok-n">earlier_batch</span><span class="tok-p">,</span> <span class="tok-n">sku</span><span class="tok-p">,</span> <span class="tok-n">qty</span><span class="tok-o">=</span><span class="tok-mi">10</span><span class="tok-p">,</span> <span class="tok-n">eta</span><span class="tok-o">=</span><span class="tok-s1">'2011-01-01'</span><span class="tok-p">)</span>  #<b class="conum">(2)</b>
     <span class="tok-n">api_client</span><span class="tok-o">.</span><span class="tok-n">post_to_add_batch</span><span class="tok-p">(</span><span class="tok-n">later_batch</span><span class="tok-p">,</span> <span class="tok-n">sku</span><span class="tok-p">,</span> <span class="tok-n">qty</span><span class="tok-o">=</span><span class="tok-mi">10</span><span class="tok-p">,</span> <span class="tok-n">eta</span><span class="tok-o">=</span><span class="tok-s1">'2011-01-02'</span><span class="tok-p">)</span>
     <span class="tok-n">response</span> <span class="tok-o">=</span> <span class="tok-n">api_client</span><span class="tok-o">.</span><span class="tok-n">post_to_allocate</span><span class="tok-p">(</span><span class="tok-n">orderid</span><span class="tok-p">,</span> <span class="tok-n">sku</span><span class="tok-p">,</span> <span class="tok-mi">10</span><span class="tok-p">)</span>  #<b class="conum">(2)</b>
     <span class="tok-k">assert</span> <span class="tok-n">response</span><span class="tok-o">.</span><span class="tok-n">json</span><span class="tok-p">()[</span><span class="tok-s1">'batchref'</span><span class="tok-p">]</span> <span class="tok-o">==</span> <span class="tok-n">earlier_batch</span>
@@ -947,7 +947,7 @@ <h3 id="_wrap_up"><a class="anchor" href="#_wrap_up"></a>Wrap-Up</h3>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2020-03-20 13:47:19 UTC
+Last updated 2020-07-30 14:51:25 +0100
 </div>
 </div>
 <style>
diff --git a/book/chapter_12_cqrs.html b/book/chapter_12_cqrs.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_12_cqrs">12: Command-Query Responsibility Segregation (CQRS)<a class="anchor" href="#chapter_12_cqrs"></a>Command-Query Responsibility Segregation (CQRS)</h2>
+<h2 id="chapter_12_cqrs">12: Command-Query Responsibility Segregation (CQRS)<a class="anchor" href="#chapter_12_cqrs"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
@@ -396,8 +396,8 @@ <h3 id="_postredirectget_and_cqs"><a class="anchor" href="#_postredirectget_and_
 write phases of our operation.</p>
 </div>
 <div class="paragraph">
-<p>This technique is a simple example of command-query separation (CQS). In CQS we
-follow one simple rule: functions should either modify state or answer
+<p>This technique is a simple example of command-query separation (CQS).<sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>
+We follow one simple rule: functions should either modify state or answer
 questions, but never both. This makes software easier to reason about: we should
 always be able to ask, "Are the lights on?" without flicking the light switch.</p>
 </div>
@@ -418,11 +418,12 @@ <h3 id="_postredirectget_and_cqs"><a class="anchor" href="#_postredirectget_and_
 </div>
 <div class="paragraph">
 <p>As you&#8217;ll see, we can use the CQS principle to make our systems faster and more
-scalable, but first, let&#8217;s fix the CQS violation in our existing code. Ages ago, we introduced an <code>allocate</code> endpoint that takes an order and
-calls our service layer to allocate some stock. At the end of the call, we
-return a 200 OK and the batch ID. That&#8217;s led to some ugly design flaws so that
-we can get the data we need. Let&#8217;s change it to return a simple OK message and
-instead provide a new read-only endpoint to retrieve allocation state:</p>
+scalable, but first, let&#8217;s fix the CQS violation in our existing code. Ages
+ago, we introduced an <code>allocate</code> endpoint that takes an order and calls our
+service layer to allocate some stock. At the end of the call, we return a 200
+OK and the batch ID. That&#8217;s led to some ugly design flaws so that we can get
+the data we need. Let&#8217;s change it to return a simple OK message and instead
+provide a new read-only endpoint to retrieve allocation state:</p>
 </div>
 <div id="api_test_does_get_after_post" class="exampleblock">
 <div class="title">API test does a GET after the POST (tests/e2e/test_api.py)</div>
@@ -1211,13 +1212,20 @@ <h3 id="_wrap_up"><a class="anchor" href="#_wrap_up"></a>Wrap-Up</h3>
 <td class="tableblock halign-left valign-top"><p class="tableblock">Adds another query language with its own quirks and syntax.</p></td>
 </tr>
 <tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Use hand-rolled SQL</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Use hand-rolled SQL to query your normal model tables</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">Offers fine control over performance with a standard query syntax.</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">Changes to DB schema have to be made to your hand-rolled queries <em>and</em> your
   ORM definitions. Highly normalized schemas may still have performance
   limitations.</p></td>
 </tr>
 <tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Add some extra (denormalized) tables to your DB as a read model</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A denormalized table can be much faster to query. If we update the
+  normalized and denormalized ones in the same transaction, we will
+  still have good guarantees of data consistency</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">It will slow down writes slightly</p></td>
+</tr>
+<tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">Create separate read stores with events</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">Read-only copies are easy to scale out. Views can be constructed when data
   changes so that queries are as simple as possible.</p></td>
@@ -1252,9 +1260,15 @@ <h3 id="_wrap_up"><a class="anchor" href="#_wrap_up"></a>Wrap-Up</h3>
   <a class="next_chapter_link" href="/book/chapter_13_dependency_injection.html">Next - 13: Dependency Injection (and Bootstrapping) &gt;&gt;</a>
 </div>
 </div>
+<div id="footnotes">
+<hr>
+<div class="footnote" id="_footnotedef_1">
+<a href="#_footnoteref_1">1</a>. We&#8217;re using the terms somewhat interchangeably, but CQS is normally something you apply to a single class or module: functions that read state should be separate from those that modify it.  And CQRS is something you apply to your whole application: the classes, modules, code paths and even databases that read state can be separated from the ones that modify it.
+</div>
+</div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2020-04-28 10:44:37 +0100
+Last updated 2020-07-30 14:51:25 +0100
 </div>
 </div>
 <style>
diff --git a/book/chapter_13_dependency_injection.html b/book/chapter_13_dependency_injection.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1">
-<h2 id="chapter_13_dependency_injection">13: Dependency Injection (and Bootstrapping)<a class="anchor" href="#chapter_13_dependency_injection"></a>Dependency Injection (and Bootstrapping)</h2>
+<h2 id="chapter_13_dependency_injection">13: Dependency Injection (and Bootstrapping)<a class="anchor" href="#chapter_13_dependency_injection"></a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>
@@ -421,9 +421,11 @@ <h3 id="_arent_explicit_dependencies_totally_weird_and_java_y"><a class="anchor"
 pass them on?</p>
 </div>
 <div class="paragraph">
-<p>That&#8217;s extra (duplicated) cruft for Flask, Redis, and our tests. Moreover,
-putting all the responsibility for passing dependencies to the right handler
-onto the message bus feels like a violation of the SRP.</p>
+<p>It needs to happen as early as possible in the process lifecycle, so the most
+obvious place is in our entrypoints. That would mean extra (duplicated) cruft
+in Flask and Redis, and in our tests. And we&#8217;d also have to add the
+responsibility for passing dependencies around to the message bus, which
+already has a job to do; it feels like a violation of the SRP.</p>
 </div>
 <div class="paragraph">
 <p>
@@ -681,7 +683,7 @@ <h3 id="_a_bootstrap_script"><a class="anchor" href="#_a_bootstrap_script"></a>A
 <ol>
 <li>
 <p><code>orm.start_mappers()</code> is our example of initialization work that needs
-to be done once at the beginning of an app. We also see things like
+to be done once at the beginning of an app. Another common example is
 setting up the <code>logging</code> module.
 </p>
 </li>
@@ -783,11 +785,11 @@ <h3 id="_a_bootstrap_script"><a class="anchor" href="#_a_bootstrap_script"></a>A
 </div>
 </div>
 <div class="paragraph">
-<p>Harry says he couldn&#8217;t even imagine writing out that many lines of code
-and having to look up that many function arguments manually.
-This is a perfectly viable solution, though, since it&#8217;s only one
-line of code or so per handler you add, and thus not a massive maintenance burden
-even if you have dozens of handlers.</p>
+<p>Harry says he couldn&#8217;t even imagine writing out that many lines of code and
+having to look up that many function arguments manually. It would be a
+perfectly viable solution, though, since it&#8217;s only one line of code or so per
+handler you add. Even if you have dozens of handlers, it wouldn&#8217;t be much of
+maintenance burden.</p>
 </div>
 <div class="paragraph">
 <p>Our app is structured in such a way that we always want to do dependency
@@ -804,9 +806,9 @@ <h3 id="_a_bootstrap_script"><a class="anchor" href="#_a_bootstrap_script"></a>A
 </div>
 <div class="paragraph">
 <p>At MADE, we&#8217;ve used <a href="https://pypi.org/project/Inject">Inject</a> in a few places,
-and it&#8217;s fine, although it makes Pylint unhappy.  You might also check out
+and it&#8217;s <em>fine</em> (although it makes Pylint unhappy).  You might also check out
 <a href="https://pypi.org/project/punq">Punq</a>, as written by Bob himself, or the
-DRY-Python crew&#8217;s <a href="https://github.com/dry-python/dependencies">dependencies</a>.</p>
+DRY-Python crew&#8217;s <a href="https://github.com/dry-python/dependencies">Dependencies</a>.</p>
 </div>
 </div>
 </div>
@@ -1460,7 +1462,7 @@ <h3 id="_wrap_up"><a class="anchor" href="#_wrap_up"></a>Wrap-Up</h3>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2020-03-20 13:47:19 UTC
+Last updated 2020-07-30 14:51:25 +0100
 </div>
 </div>
 <style>
diff --git a/book/epilogue_1_how_to_get_there_from_here.html b/book/epilogue_1_how_to_get_there_from_here.html
@@ -138,7 +138,7 @@
 </div>
 <div id="content">
 <div class="sect1 afterword">
-<h2 id="epilogue_1_how_to_get_there_from_here">Epilogue: Epilogue<a class="anchor" href="#epilogue_1_how_to_get_there_from_here"></a>Appendix A: Epilogue</h2>
+<h2 id="epilogue_1_how_to_get_there_from_here">Epilogue: Epilogue<a class="anchor" href="#epilogue_1_how_to_get_there_from_here"></a></h2>
 <div class="sectionbody">
 <div class="sect2">
 <h3 id="_what_now"><a class="anchor" href="#_what_now"></a>What Now?</h3>
diff --git a/book/introduction.html b/book/introduction.html
diff --git a/book/part1.html b/book/part1.html
diff --git a/book/part2.html b/book/part2.html
diff --git a/book/preface.html b/book/preface.html
diff --git a/rss.xml b/rss.xml
