A

CodeAlmanac Notes For Cosmic Python

Source: https://github.com/cosmicpython/book

Converted from vendored commit: d4522c44ed89eb320ad9eed2525d2af3b149bd3f

License in source repo: Creative Commons CC-By-ND

This directory contains Markdown-only reference copies of Architecture Patterns with Python by Harry Percival and Bob Gregory. The Markdown files are mechanical format conversions from the upstream AsciiDoc files. Do not rewrite, abridge, rearrange, or edit the book text here. Put CodeAlmanac-specific interpretation in this file, repo docs, or .almanac/ pages.

Use During Python Coding#

Before non-trivial Python implementation, read the chapters that match the shape being changed:

Task Read
Persistence boundary, SQLite stores, fake stores chapter_02_repository.md
Product verbs, CLI-to-service boundary chapter_04_service_layer.md
Test shape and fast service tests chapter_05_high_gear_low_gear.md
Transaction boundaries and atomic writes chapter_06_uow.md
Message/event workflows chapter_08_events_and_message_bus.md
External message adapters chapter_11_external_events.md
Command objects and run requests chapter_10_commands.md
Composition root and dependency wiring chapter_13_dependency_injection.md
Package layout comparison appendix_project_structure.md

Useful Lines#

  • Chapter 2 argues for a domain model with "no dependencies whatsoever."
  • Chapter 4 says the service layer defines "the use cases of our system."
  • Chapter 6 describes Unit of Work as an abstraction over "atomic operations."
  • Chapter 11 frames outside messages as adapter input that gets deserialized before it reaches the application core.
  • Chapter 13 uses a bootstrap/composition root so entrypoints stop doing setup.

Translation To CodeAlmanac#

CodeAlmanac does not need to copy the book's exact folders. The useful transfer is the dependency rule:

cli
  -> app
    -> workflows
      -> services
        -> stores
        -> ports
          -> integrations

For this repo:

  • Repository pattern maps to store.py, *_store.py, and store fakes.
  • Service layer maps to services/*/service.py.
  • Unit of Work maps to explicit SQLite transaction ownership inside services and workflows.
  • External event adapters map to transcript/GitHub/Git runtime adapters that turn outside shapes into service-owned Pydantic models.
  • Bootstrap maps to src/codealmanac/app.py.
  • Adapters map to integrations/*, implementing ports defined by services.

When a future plan quotes the book, keep quotes short and cite the local chapter path.