Merge branch atlas/august-ER

appendix_django.asciidoc

@@ -302,7 +302,7 @@ class DjangoUnitOfWork(AbstractUnitOfWork):
     objects that have been touched by every repository and manually
     updated them back to the ORM.
 
-TODO: maybe `.seen()` should live on the uow not the repo
+// TODO: maybe `.seen()` should live on the uow not the repo
 
 
 === API: Django Views Are Adapters
@@ -371,4 +371,4 @@ So why might you still do it?
   be a bad idea, it goes against the grain of wanting to decouple your model
   and business logic from the ORM...)
 
-// TODO: Expand on this wrap-up?
+// TODO: Expand on this wrap-up?

appendix_project_structure.asciidoc

@@ -46,11 +46,6 @@ be of interest to outline the moving parts.
 ----
 ====
 
-// TODO (DS): All this seems sensible.
-// It would be nice to include a dependency graph so we can see the layering
-// within src/allocation.
-// Maybe should include message bus too?
-
 <1> Our _docker-compose.yml_ and our _Dockerfile_ are the main bits of configuration
     for the containers that run our app, and can also run the tests (for CI).  A
     more complex project might have several Dockerfiles, although we've found that
@@ -67,7 +62,6 @@ be of interest to outline the moving parts.
     `docker-compose` and `pytest` directly, but if nothing else it's nice to
     have all the "common commands" in a list somewhere, and unlike
     documentation, a Makefile is code so it has less tendency to go out of date.
-// TODO (DS): Could mention invoke as an alternative.
 
 <3> All the actual source code for our app, including the domain model, the
     flask app, and infrastructure code, lives in a Python package inside
@@ -83,6 +77,15 @@ be of interest to outline the moving parts.
     (_conftest.py_) in the main tests folder, and nest more specific ones if we
     wish. This is also the place to keep _pytest.ini_.
 
+// TODO (DS): All this seems sensible.
+// It would be nice to include a dependency graph so we can see the layering
+// within src/allocation.
+// Maybe should include message bus too?
+
+// TODO (DS): Could mention invoke as an alternative to makefiles
+
+
+
 TIP:  The https://docs.pytest.org/en/latest/goodpractices.html#choosing-a-test-layout-import-rules[pytest docs]
     are really good on test layout and importability.
 
@@ -91,7 +94,7 @@ TIP:  The https://docs.pytest.org/en/latest/goodpractices.html#choosing-a-test-l
 
 Let's look at a few of these in more detail.
 
-TODO: add more subfolders/structure inside our main source tree?
+// TODO: add more subfolders/structure inside our main source tree?
 
 // TODO: DS: Going a bit further, you could consider structuring the code with
 // subpackages according to each layer. This would make it a lot more obvious
@@ -147,9 +150,7 @@ configuration gets put in there.
 
 https://github.com/python-leap/book/issues/52
 ////
-
-// TODO (DS): I reckon configuration patterns are an important part of the
-// architecture your outlining, i wonder if they belong in the main book?
+// TODO (DS): I reckon configuration patterns are an important part of the architecture your outlining, i wonder if they belong in the main book?
 
 Whenever our application code needs access to some config, it's going to
 get it from a file called _config.py__. <<config_dot_py>> shows a couple of

atlas.json

@@ -1,6 +1,7 @@
 {
   "branch": "master",
   "files": [
+    "cover.html",
     "titlepage.html",
     "copyright.html",
     "toc.html",
@@ -39,7 +40,7 @@
   "formats": {
     "pdf": {
       "version": "web",
-      "color_count": "1",
+      "color_count": "4",
       "index": true,
       "toc": true,
       "syntaxhighlighting": true,

author_bio.html

@@ -1,4 +1,6 @@
 <section data-type="colophon" class="abouttheauthor">
-  <h1>About the Author(s)</h1>
-  <p>John Doe does some interesting stuff...</p>
+  <h1>About the Authors</h1>
+  <p><strong>Harry Percival</strong> spent a few years being deeply unhappy as a management consultant. Soon he rediscovered his true geek nature and was lucky enough to fall in with a bunch of XP fanatics, working on the pioneering the sadly defunct Resolver One spreadsheet. He worked at PythonAnywhere LLP, spreading the gospel of TDD world-wide at talks, workshops and conferences. He is now with MADE.COM.</p>
+
+  <p><strong>Bob Gregory</strong> is a UK-based software architect with MADE.COM. He has been building event driven systems with domain-driven design for more than a decade.</p>
 </section>

chapter_01_domain_model.asciidoc

@@ -48,7 +48,7 @@ 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
-<<chapter_02,the next chapter>>) all come from the DDD tradition.
+<<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
 provides a useful model of some problem.  If we get that model right, then our

chapter_02_repository.asciidoc

@@ -586,7 +586,7 @@ image::images/repository_pattern_diagram.png[]
 ----
 
 
-TODO: not sure if this diagram is helping.
+// TODO: not sure if this diagram is helping.
 
 
 As always, we start with a test. This would probably be classified as an
@@ -839,9 +839,11 @@ a|
   from infrastructure concerns.
 * Writing the domain model before thinking about persistence helps us focus on
   the business problem at hand.
-* Our database schema is really simple because we have complete control over how
-  we map our objects to tables.
-  // TODO: Explain how Django ORM would intrude here.
+
+// TODO: Explain how Django ORM would intrude here.
+
+* Our database schema is really simple because we have complete control over how we map our objects to tables.
+
 a|
 * OTOH an ORM already buys you quite a lot of decoupling.  if you're using
   an ORM it should be pretty easy to swap between, eg, mysql and postgres

chapter_03_abstractions.asciidoc

@@ -615,7 +615,8 @@ a few heuristics and questions to ask yourself:
 
 * Can I choose a familiar Python datastructure to represent the state of the
   messy system, and try to imagine a single function that can return that
-  state?
+  state? 
+
 // TODO (DS): These are great heuristics... Maybe they deserve more attention?
 
 * Where can I draw a line between my systems, where can I carve out a seam, to

chapter_04_service_layer.asciidoc

@@ -587,7 +587,7 @@ This means it'll work both when the tests give it a `FakeRepository`, and
 when the flask app gives it a `SqlAlchemyRepository`.
 
 If you remember the <<dip,Dependency Inversion Principle section from the introduction>>,
-This is what we mean when we says we should "depend on abstractions". Our
+this is what we mean when we says we should "depend on abstractions". Our
 _high-level module_, the service layer, depends on the repository abstraction.
 And the _details_ of the implementation for our specific choice of persistent
 storage also depend on that same abstraction.
@@ -696,7 +696,7 @@ does to our test pyramid:
 [source,sh]
 [role="skip"]
 ----
-👉  grep -c test_ test_*.py
+$ grep -c test_ test_*.py
 test_allocate.py:4
 test_batches.py:8
 test_services.py:3

chapter_05_uow.asciidoc

@@ -302,7 +302,7 @@ def add_batch(
         uow: unit_of_work.AbstractUnitOfWork  #<1>
 ):
     with uow:
-        uow.batches.add(model.Batch(ref, sku, qty, eta))  #<2>
+        uow.batches.add(model.Batch(ref, sku, qty, eta))
         uow.commit()
 
 
@@ -312,7 +312,7 @@ def allocate(
 ) -> str:
     line = OrderLine(orderid, sku, qty)
     with uow:
-        batches = uow.batches.list()  #<2>
+        batches = uow.batches.list()
         if not is_valid_sku(line.sku, batches):
             raise InvalidSku(f'Invalid sku {line.sku}')
         batchref = model.allocate(line, batches)
@@ -536,7 +536,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).
 
-TODO: expand on this a bit?
+// TODO: expand on this a bit?
 
 
 .Exercise for the Reader

chapter_06_aggregate.asciidoc

@@ -375,7 +375,7 @@ def allocate(
 
 //TODO (DS): Another way you could present it is as a diff side by side.
 
-TODO: discuss, should repository raise `InvalidSku`?
+// TODO: discuss, should repository raise `InvalidSku`?
 
 //TODO (DS): More generally I'd be interested in some general principles about
 //handling exceptions in a layered architecture...
@@ -476,9 +476,9 @@ class Product:
 
 <1> There it is!
 
-TODO: more discussion of version number -- actual numebr doesn't matter,
-    we're just setting _something_ so the db complains, could use uids,
-    also discuss similarity with eventsourcing version numbers.
+// TODO: more discussion of version number -- actual numebr doesn't matter,
+//   we're just setting _something_ so the db complains, could use uids,
+//   also discuss similarity with eventsourcing version numbers.
 
 //TODO (DS): I guess it's just pragmatism, but it seems like the concurrency
 //protection isn't really in the abstraction, it just happens to be in the

copyright.html

@@ -8,21 +8,16 @@ <h1>Enterprise Architecture Patterns with Python</h1>
     <span class='firstname'>Bob </span>
     <span class='surname'>Gregory</span>
   </p>
-  <p class='copyright'>Copyright © FILL IN YEAR O&apos;Reilly Media. All rights reserved.</p>
+  <p class='copyright'>Copyright © 2020 O&apos;Reilly Media. All rights reserved.</p>
   <p class='printlocation'>Printed in the United States of America.</p>
   <p class='publisher'>
     Published by 
-    <span class='publishername'>O&apos;Reilly Media, Inc.</span>
-    , 1005 Gravenstein Highway North, Sebastopol, CA 95472.
+    <span class='publishername'>O&apos;Reilly Media, Inc.</span>, 1005 Gravenstein Highway North, Sebastopol, CA 95472.
   </p>
   <p>
     O&apos;Reilly books may be purchased for educational, business, or sales
-    promotional use. Online editions are also available for most titles (
-    <a href='http://oreilly.com/safari'>http://oreilly.com/safari</a>
-    ). For more information, contact our corporate/institutional sales
-    department: 800-998-9938 or 
-    <span data-type='email'>[email protected]</span>
-    .
+    promotional use. Online editions are also available for most titles (<a href='http://oreilly.com'>http://oreilly.com</a>). For more information, contact our corporate/institutional sales
+    department: 800-998-9938 or <span data-type='email'>[email protected]</span>.
   </p>
   <ul class='stafflist'>
     <li>
@@ -31,19 +26,19 @@ <h1>Enterprise Architecture Patterns with Python</h1>
     </li>
     <li>
       <span class='staffrole'>Production Editor:</span>
-       FILL IN PRODUCTION EDITOR
+       Katherine Tozer
     </li>
     <li>
       <span class='staffrole'>Copyeditor:</span>
-       FILL IN COPYEDITOR
+       To come
     </li>
     <li>
       <span class='staffrole'>Proofreader:</span>
-       FILL IN PROOFREADER
+       To come
     </li>
     <li>
       <span class='staffrole'>Indexer:</span>
-       FILL IN INDEXER
+       To come
     </li>
     <li>
       <span class='staffrole'>Interior Designer:</span>
@@ -66,10 +61,10 @@ <h1>Enterprise Architecture Patterns with Python</h1>
   </ul>
   <!--Add additional revdate spans below as needed.-->
   <div>
-    <h1 class='revisions'>Revision History for the First Edition</h1>
+    <h1 class='revisions'>Revision History for the Early Release</h1>
     <ul class='releases'>
       <li>
-        <span class='revdate'>YYYY-MM-DD:</span>
+        <span class='revdate'>2019-08-26:</span>
          First Release
       </li>
     </ul>
@@ -86,11 +81,11 @@ <h1 class='revisions'>Revision History for the First Edition</h1>
       trade dress are trademarks of O’Reilly Media, Inc.
     </p>
     <p>
-      The views expressed in this work are those of the author(s), and do not
+      The views expressed in this work are those of the authors, and do not
       represent the publisher&apos;s views. While the publisher and the
-      author(s) have used good faith efforts to ensure that the information and
+      authors have used good faith efforts to ensure that the information and
       instructions contained in this work are accurate, the publisher and the
-      author(s) disclaim all responsibility for errors or omissions, including
+      authors disclaim all responsibility for errors or omissions, including
       without limitation responsibility for damages resulting from the use of or
       reliance on this work. Use of the information and instructions contained
       in this work is at your own risk. If any code samples or other technology
@@ -106,6 +101,6 @@ <h1 class='revisions'>Revision History for the First Edition</h1>
   </div>
   <div class='copyright-bottom'>
     <p class='isbn'>978-1-492-05220-3</p>
-    <p class='printer'>[FILL IN]</p>
+    <p class='printer'>[To come]</p>
   </div>
-</section>
+</section>

cover.html

@@ -0,0 +1,3 @@
+<figure data-type="cover">
+<img src="images/cover.png"/>
+</figure>

theme/epub/layout.html

@@ -1,13 +1,13 @@
 {{ doctype }}
 <html lang="en" xmlns="http://www.w3.org/1999/xhtml">
   <head>
+    <title>{{ title }}</title>
     <meta charset="utf-8" />
     <meta name="publisher" content="O'Reilly Media, Inc."/>
-    <meta name="author" content="AUTHOR NAMES HERE"/>
-    <meta name="date" content="RETAIL AVAILABILITY DATE FROM PDB MANUFACTURING TAB HERE IN YYYY-MM-DD FORM (e.g., 2014-07-07)"/>
-    <meta name="description" content="BOOK MARKETING DESCRIPTION HERE. (This can be supplied by the author, but otherwise the Consumer Short Text from the Marketing tab in the PDB works here - just make sure not to paste curly quotes or em dashes! Replace with straight quotes and hyphens.)"/>
+    <meta name="author" content="Harry Percival and Bob Gregory"/>
+    <meta name="date" content="2019-08-26"/>
+    <meta name="description" content="As Python continues to grow in popularity, projects are becoming larger and more complex. Many Python developers are now taking an interest in high-level software architecture patterns such as hexagonal/clean architecture, event-driven architecture, and strategic patterns prescribed by domain-driven design (DDD). But translating those patterns into Python isn’t always straightforward. With this practical guide, Harry Percival and Bob Gregory from MADE.com introduce proven architectural design patterns to help Python developers manage application complexity."/>
     <meta name="identifier" content="TECH-BOOK-ISBN-13"/>
-    <title>{{ title }}</title>
   </head>
   <body data-type="book">
     {{ content }}

theme/mobi/layout.html

@@ -1,13 +1,13 @@
 {{ doctype }}
 <html lang="en" xmlns="http://www.w3.org/1999/xhtml">
   <head>
+    <title>{{ title }}</title>
     <meta charset="utf-8" />
     <meta name="publisher" content="O'Reilly Media, Inc."/>
-    <meta name="author" content="AUTHOR NAMES HERE"/>
-    <meta name="date" content="RETAIL AVAILABILITY DATE FROM PDB MANUFACTURING TAB HERE IN YYYY-MM-DD FORM (e.g., 2014-07-07)"/>
-    <meta name="description" content="BOOK MARKETING DESCRIPTION HERE. (This can be supplied by the author, but otherwise the Consumer Short Text from the Marketing tab in the PDB works here - just make sure not to paste curly quotes or em dashes! Replace with straight quotes and hyphens.)"/>
+    <meta name="author" content="Harry Percival and Bob Gregory"/>
+    <meta name="date" content="2019-08-26"/>
+    <meta name="description" content="As Python continues to grow in popularity, projects are becoming larger and more complex. Many Python developers are now taking an interest in high-level software architecture patterns such as hexagonal/clean architecture, event-driven architecture, and strategic patterns prescribed by domain-driven design (DDD). But translating those patterns into Python isn’t always straightforward. With this practical guide, Harry Percival and Bob Gregory from MADE.com introduce proven architectural design patterns to help Python developers manage application complexity."/>
     <meta name="identifier" content="TECH-BOOK-ISBN-13"/>
-    <title>{{ title }}</title>
   </head>
   <body data-type="book">
     {{ content }}

titlepage.html

@@ -2,7 +2,9 @@
 <h1>Enterprise Architecture Patterns with Python</h1>
 <!--(only include edition line if it's 2e or higher -->
 
-<p class="subtitle">How to Apply DDD, Ports and Adapters and More Application Architecture Patterns in a Pythonic Way</p>
+<p class="subtitle">How to Apply DDD, Ports and Adapters, and Enterprise Architecture Design Patterns in a Pythonic Way</p>
+
+<aside data-type="sidebar" class="preview-edition">With Early Release ebooks, you get books in their earliest form—the author's raw and unedited content as they write—so you can take advantage of these technologies long before the official release of these titles.</aside>
 
 <p class="author">Harry Percival and Bob Gregory</p>
 </section>