change all xrefs

Readme.md

@@ -19,16 +19,16 @@ In the meantime, pull requests, typofixes, and more substantial feedback + sugge
 | [Chapter 2: Repository](chapter_02_repository.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_02_repository)](https://travis-ci.org/cosmicpython/code) |
 | [Chapter 3: Interlude: Abstractions](chapter_03_abstractions.asciidoc) | |
 | [Chapter 4: Service Layer (and Flask API)](chapter_04_service_layer.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_04_service_layer)](https://travis-ci.org/cosmicpython/code) |
-| [Chapter 5: TDD in High Gear and Low Gear](chapter_04b_high_gear_low_gear.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_04b_high_gear_low_gear)](https://travis-ci.org/cosmicpython/code) |
-| [Chapter 6: Unit of Work](chapter_05_uow.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_05_uow)](https://travis-ci.org/cosmicpython/code) |
-| [Chapter 7: Aggregates](chapter_06_aggregate.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_06_aggregate)](https://travis-ci.org/cosmicpython/code) |
+| [Chapter 5: TDD in High Gear and Low Gear](chapter_05_high_gear_low_gear.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_05_high_gear_low_gear)](https://travis-ci.org/cosmicpython/code) |
+| [Chapter 6: Unit of Work](chapter_06_uow.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_06_uow)](https://travis-ci.org/cosmicpython/code) |
+| [Chapter 7: Aggregates](chapter_07_aggregate.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_07_aggregate)](https://travis-ci.org/cosmicpython/code) |
 | [**Part 2 Intro**](part2.asciidoc) | |
-| [Chapter 8: Domain Events and a Simple Message Bus](chapter_07_events_and_message_bus.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_07_events_and_message_bus)](https://travis-ci.org/cosmicpython/code) |
-| [Chapter 9: Going to Town on the MessageBus](chapter_08_all_messagebus.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_08_all_messagebus)](https://travis-ci.org/cosmicpython/code) |
-| [Chapter 10: Commands](chapter_09_commands.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_09_commands)](https://travis-ci.org/cosmicpython/code) |
-| [Chapter 11: External Events for Integration](chapter_10_external_events.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_10_external_events)](https://travis-ci.org/cosmicpython/code) |
-| [Chapter 12: CQRS](chapter_11_cqrs.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_11_cqrs)](https://travis-ci.org/cosmicpython/code) |
-| [Chapter 13: Dependency Injection](chapter_12_dependency_injection.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_12_dependency_injection)](https://travis-ci.org/cosmicpython/code) |
+| [Chapter 8: Domain Events and a Simple Message Bus](chapter_08_events_and_message_bus.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_08_events_and_message_bus)](https://travis-ci.org/cosmicpython/code) |
+| [Chapter 9: Going to Town on the MessageBus](chapter_09_all_messagebus.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_09_all_messagebus)](https://travis-ci.org/cosmicpython/code) |
+| [Chapter 10: Commands](chapter_10_commands.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_10_commands)](https://travis-ci.org/cosmicpython/code) |
+| [Chapter 11: External Events for Integration](chapter_11_external_events.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_11_external_events)](https://travis-ci.org/cosmicpython/code) |
+| [Chapter 12: CQRS](chapter_12_cqrs.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_12_cqrs)](https://travis-ci.org/cosmicpython/code) |
+| [Chapter 13: Dependency Injection](chapter_13_dependency_injection.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=chapter_13_dependency_injection)](https://travis-ci.org/cosmicpython/code) |
 | [Epilogue: How do I get there from here?](epilogue_1_how_to_get_there_from_here.asciidoc) | |
 | [Appendix B: Project Structure](appendix_project_structure.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=appendix_project_structure)](https://travis-ci.org/cosmicpython/code) |
 | [Appendix C: A major infrastructure change, made easy](appendix_csvs.asciidoc) | [![Build Status](https://travis-ci.org/cosmicpython/code.svg?branch=appendix_csvs)](https://travis-ci.org/cosmicpython/code) |

appendix_csvs.asciidoc

@@ -4,7 +4,7 @@
 
 This appendix is intended as a little illustration of the benefits of the
 Repository, Unit of Work, and Service Layer patterns. It's intended to
-follow on from <<chapter_05_uow>>.
+follow on from <<chapter_06_uow>>.
 
 Just as we finish building out our Flask API and getting it ready for release,
 the business come to us apologetically saying they're not ready to use our API

appendix_project_structure.asciidoc

@@ -177,7 +177,7 @@ at if you get tired of hand-rolling your own environment-based config functions.
 TIP: Don't let this config module become a dumping ground full of things that
     are only vaguely related to config, and is then imported all over the place.
     Keep things immutable and only modify them via environment variables.
-    If you decide to use a <<chapter_12_dependency_injection,bootstrap script>>,
+    If you decide to use a <<chapter_13_dependency_injection,bootstrap script>>,
     you can make it the only place (other than tests) that config is imported.
 
 === Docker-Compose and Containers Config

atlas.json

@@ -13,17 +13,17 @@
     "chapter_02_repository.asciidoc",
     "chapter_03_abstractions.asciidoc",
     "chapter_04_service_layer.asciidoc",
-    "chapter_04b_high_gear_low_gear.asciidoc",
-    "chapter_05_uow.asciidoc",
-    "chapter_06_aggregate.asciidoc",
+    "chapter_05_high_gear_low_gear.asciidoc",
+    "chapter_06_uow.asciidoc",
+    "chapter_07_aggregate.asciidoc",
 
     "part2.asciidoc",
-    "chapter_07_events_and_message_bus.asciidoc",
-    "chapter_08_all_messagebus.asciidoc",
-    "chapter_09_commands.asciidoc",
-    "chapter_10_external_events.asciidoc",
-    "chapter_11_cqrs.asciidoc",
-    "chapter_12_dependency_injection.asciidoc",
+    "chapter_08_events_and_message_bus.asciidoc",
+    "chapter_09_all_messagebus.asciidoc",
+    "chapter_10_commands.asciidoc",
+    "chapter_11_external_events.asciidoc",
+    "chapter_12_cqrs.asciidoc",
+    "chapter_13_dependency_injection.asciidoc",
 
     "epilogue_1_how_to_get_there_from_here.asciidoc",
 

book.asciidoc

@@ -29,26 +29,26 @@ include::chapter_03_abstractions.asciidoc[]
 
 include::chapter_04_service_layer.asciidoc[]
 
-include::chapter_04b_high_gear_low_gear.asciidoc[]
+include::chapter_05_high_gear_low_gear.asciidoc[]
 
-include::chapter_05_uow.asciidoc[]
+include::chapter_06_uow.asciidoc[]
 
-include::chapter_06_aggregate.asciidoc[]
+include::chapter_07_aggregate.asciidoc[]
 
 
 include::part2.asciidoc[]
 
-include::chapter_07_events_and_message_bus.asciidoc[]
+include::chapter_08_events_and_message_bus.asciidoc[]
 
-include::chapter_08_all_messagebus.asciidoc[]
+include::chapter_09_all_messagebus.asciidoc[]
 
-include::chapter_09_commands.asciidoc[]
+include::chapter_10_commands.asciidoc[]
 
-include::chapter_10_external_events.asciidoc[]
+include::chapter_11_external_events.asciidoc[]
 
-include::chapter_11_cqrs.asciidoc[]
+include::chapter_12_cqrs.asciidoc[]
 
-include::chapter_12_dependency_injection.asciidoc[]
+include::chapter_13_dependency_injection.asciidoc[]
 
 
 include::appendix_project_structure.asciidoc[]

chapter_01_domain_model.asciidoc

@@ -56,7 +56,7 @@ 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, like Entity, Aggregate,
-and Value Objects (see <<chapter_05_uow>>), and Repository pattern (in
+and Value Objects (see <<chapter_06_uow>>), and Repository pattern (in
 <<chapter_02_repository,the next chapter>>), all come from the DDD tradition.
 
 In a nutshell, DDD says that the most important thing about software is that it
@@ -1013,6 +1013,6 @@ This is the time to apply your best OO design principles::
     "prefer composition over inheritance", and so on.
 
 You'll also want to think about consistency boundaries and Aggregates::
-    But that's a topic for <<chapter_06_aggregate>>.
+    But that's a topic for <<chapter_07_aggregate>>.
 
 *****************************************************************

chapter_02_repository.asciidoc

@@ -479,7 +479,7 @@ repository, and `get` to return a previously added item.footnote:[
 You may be thinking, what about `list` or `delete` or `update`, but in the
 ideal world, we only modify our model objects one at a time, and delete is
 usually handled as a soft-delete, ie `batch.cancel()`. Finally, update is
-taken care of by the Unit of Work, as we'll see in <<chapter_05_uow>>.]
+taken care of by the Unit of Work, as we'll see in <<chapter_06_uow>>.]
 We stick rigidly to using these methods for data access in our domain and our
 service layer. This self-imposed simplicity stops us from coupling our domain
 model to the database.
@@ -631,7 +631,7 @@ def test_repository_can_save_a_batch(session):
 <2> We keep the `.commit()` outside of the repository, and make
     it the responsibility of the caller.  There are pros and cons for
     this, some of our reasons will become clearer when we get to
-    <<chapter_05_uow>>.
+    <<chapter_06_uow>>.
 
 <3> And we use the raw SQL to verify that the right data has been saved.
 

chapter_03_abstractions.asciidoc

@@ -580,10 +580,10 @@ Instead, we like to clearly identify the responsibilities in our codebase, and t
 separate those responsibilities out into small, focused objects that are easy to
 replace with a test double.
 
-NOTE: You can see an example in <<chapter_07_events_and_message_bus>>
+NOTE: You can see an example in <<chapter_08_events_and_message_bus>>
     where we `mock.patch()` out an email-sending module, but eventually we
     replace that with an explicit bit of dependency injection, in
-    <<chapter_12_dependency_injection>>.
+    <<chapter_13_dependency_injection>>.
 
 There are three closely related reasons for our preference:
 
@@ -688,7 +688,7 @@ so that's our functional core.  The service layer that we build around it
 and we use dependency injection to provide those services with stateful
 components, so we can still unit test them.
 
-See <<chapter_12_dependency_injection>> for more exploration of making our
+See <<chapter_13_dependency_injection>> for more exploration of making our
 dependency injection more explicit and centralized.
 ******************************************************************************
 

chapter_04_service_layer.asciidoc

@@ -388,7 +388,7 @@ class FakeSession():
 ====
 
 This fake session is only a temporary solution.  We'll get rid of it and make
-things even nicer in the next chapter, <<chapter_05_uow>>. But in the meantime
+things even nicer in the next chapter, <<chapter_06_uow>>. But in the meantime
 the fake `.commit()` lets us migrate a third test from the E2E layer:
 
 
@@ -602,7 +602,7 @@ require any change to our service layer or domain layer!
 TIP: If you decide you want to build a read-only endpoint for retrieving allocation
     info, just do the simplest thing that can possibly work (TM), which is
     `repo.get()` right in the Flask handler.  We'll talk more about reads vs
-    writes in <<chapter_11_cqrs>>.
+    writes in <<chapter_12_cqrs>>.
 
 ******************************************************************************
 
@@ -868,10 +868,10 @@ Wonderful.  But there are still some bits of awkwardness to tidy up:
 
 * the service layer is still tightly coupled to the domain, because
   its API is expressed in terms of `OrderLine` objects.  In
-  <<chapter_04b_high_gear_low_gear>> we'll fix that, and talk about
+  <<chapter_05_high_gear_low_gear>> we'll fix that, and talk about
   the way that Service Layer enables more productive TDD.
 
-* The service layer is tightly coupled to a `session` object.  In <<chapter_05_uow>>
+* The service layer is tightly coupled to a `session` object.  In <<chapter_06_uow>>
   we'll introduce one more pattern that works closely with Repository and
   Service Layer, the Unit of Work, and everything will be absolutely lovely.
   You'll see!
@@ -897,7 +897,7 @@ a|
 * When combined with _Repository Pattern_ and a `FakeRepository`, we've got
   a nice way of writing tests at a higher level than the Domain Layer;
   we can test more of our workflow without needing to go to integration tests
-  (read on to <<chapter_04b_high_gear_low_gear>> for more elaboration on this).
+  (read on to <<chapter_05_high_gear_low_gear>> for more elaboration on this).
 
 a|
 * If your app is _purely_ a web app, your controllers/view functions can be

chapter_05_high_gear_low_gear.asciidoc

@@ -1,4 +1,4 @@
-[[chapter_04b_high_gear_low_gear]]
+[[chapter_05_high_gear_low_gear]]
 == TDD in High Gear and Low Gear
 
 We've introduced the service layer to capture some of the additional
@@ -501,7 +501,7 @@ Write the bulk of your tests against the service layer::
 A valid concern about writing tests at a higher level is that it can lead to
 combinatorial explosion, for more complex use cases.  In these cases dropping
 down to lower-level unit tests of the various collaborating domain objects
-can be useful.  But see also <<chapter_07_events_and_message_bus>> and
+can be useful.  But see also <<chapter_08_events_and_message_bus>> and
 <<fake_message_bus>>]
     cover all the edge cases and ins+outs of your business logic.
 

chapter_06_uow.asciidoc

@@ -1,4 +1,4 @@
-[[chapter_05_uow]]
+[[chapter_06_uow]]
 == Unit of Work Pattern
 
 In this chapter we'll introduce the final piece of the puzzle that ties
@@ -35,11 +35,11 @@ And we'll do it all using a lovely piece of Python syntax, a context manager.
 [TIP]
 ====
 You can find our code for this chapter at
-https://github.com/cosmicpython/code/tree/chapter_05_uow[github.com/cosmicpython/code/tree/chapter_05_uow].
+https://github.com/cosmicpython/code/tree/chapter_06_uow[github.com/cosmicpython/code/tree/chapter_06_uow].
 
 ----
 git clone https://github.com/cosmicpython/code.git && cd code
-git checkout chapter_05_uow
+git checkout chapter_06_uow
 # or, if you want to code along, checkout the previous chapter:
 git checkout chapter_04_service_layer
 ----
@@ -436,7 +436,7 @@ def test_rolls_back_on_error(session_factory):
 TIP: We haven't shown it here, but it can be worth testing some of the more
     "obscure" database behavior, like transactions, against the "real"
     database, ie the same engine.  For now we're getting away with using
-    SQLite instead of Postgres, but in <<chapter_06_aggregate>> we'll switch
+    SQLite instead of Postgres, but in <<chapter_07_aggregate>> we'll switch
     some of the tests to using the real DB.  It's convenient that our UoW
     class makes that easy!
 
@@ -594,7 +594,7 @@ it's doing are covered in _test_repository.py_.  That last you might keep around
 but we could certainly see an argument for just keeping everything at the highest
 possible level of abstraction (just as we did for the unit tests).
 
-TIP: This is another example of the lesson from <<chapter_04b_high_gear_low_gear>>:
+TIP: This is another example of the lesson from <<chapter_05_high_gear_low_gear>>:
     As we build better abstractions, we can move our tests to run against them,
     which leaves us free to change the underlying details.
 
@@ -610,7 +610,7 @@ or rollback on exit.  If you feel like going all-functional rather than
 messing about with all these classes, you could use `@contextmanager` from
 `contextlib`.
 
-https://github.com/cosmicpython/code/tree/chapter_05_uow_exercise
+https://github.com/cosmicpython/code/tree/chapter_06_uow_exercise
 
 We've stripped out both the actual UoW and the fakes, as well as paring back
 the abstract UoW.  Why not send us a link to your repo if you come up with
@@ -685,7 +685,7 @@ SQLAlchemy already implements this pattern::
 *****************************************************************
 
 
-[[chapter_05_uow_tradeoffs]]
+[[chapter_06_uow_tradeoffs]]
 [options="header"]
 .Unit of Work: The Trade-Offs
 |===

chapter_07_aggregate.asciidoc

@@ -1,4 +1,4 @@
-[[chapter_06_aggregate]]
+[[chapter_07_aggregate]]
 == Aggregates and Consistency Boundaries
 
 In this chapter we'd like to revisit our domain model to talk about invariants
@@ -29,7 +29,7 @@ https://github.com/cosmicpython/code/tree/appendix_csvs[github.com/cosmicpython/
 git clone https://github.com/cosmicpython/code.git && cd code
 git checkout appendix_csvs
 # or, if you want to code along, checkout the previous chapter:
-git checkout chapter_05_uow
+git checkout chapter_06_uow
 ----
 ====
 
@@ -499,7 +499,7 @@ if you do that, you'll still have to solve a few challenges on your own,
 like adding the model to the ORM and making sure all the moving parts can
 talk to each other, which we hope will be instructive.
 
-https://github.com/cosmicpython/code/tree/chapter_06_aggregate_exercise
+https://github.com/cosmicpython/code/tree/chapter_07_aggregate_exercise
 
 We've put in a "cheating" implementation in that delegates to the existing
 `allocate()` function, so you should be able to evolve that towards the real
@@ -817,7 +817,7 @@ Aggregates and concurrency issues go together::
 *****************************************************************
 
 
-[[chapter_06_aggregate_tradoffs]]
+[[chapter_07_aggregate_tradoffs]]
 [options="header"]
 .Aggregates: The Trade-Offs
 |===