python-patterns Admin & Contributor Guide

This guide is for maintainers, contributors, and architects working on the python-patterns repository — as opposed to developers simply reading the patterns (covered in the User Guide). It documents how the collection is structured, how its self-testing machinery works, the toolchain and CI that keep it consistent, the contribution contract, and the known issues and improvement opportunities surfaced by the project's own issue tracker.

1. Executive Summary

python-patterns is a teaching catalog, not a deployable application or a published library. Its "product" is a set of ~33 self-contained Python files, each demonstrating one design pattern or idiom, grouped by the classic Gang of Four taxonomy plus a few project-specific categories.

Important

Because there is no service and no published package, the operational concerns here are entirely about repository hygiene: keeping every pattern consistent in style, ensuring every documented example actually runs, and managing contributions. There is nothing to deploy, monitor, scale, or secure at runtime. This guide reframes the usual "deployment / operations" chapters accordingly.

2. Architecture

The repository has two architectures worth understanding: the content taxonomy (how patterns are organized) and the self-verification architecture (how every example stays correct).

2.1 Content taxonomy

patterns/
├── creational/      7 patterns — object creation
│   ├── abstract_factory.py  borg.py  builder.py  factory.py
│   ├── lazy_evaluation.py    pool.py  prototype.py
│   └── viz/                  rendered .png class diagrams (one per pattern)
├── structural/      10 patterns — object/class composition
│   ├── 3-tier.py  adapter.py  bridge.py  composite.py  decorator.py
│   ├── facade.py  flyweight.py  flyweight_with_metaclass.py
│   ├── front_controller.py  mvc.py  proxy.py
│   └── viz/
├── behavioral/      17 patterns — communication & responsibility
│   ├── catalog.py  chain_of_responsibility.py  chaining_method.py
│   ├── command.py  iterator.py  iterator_alt.py  mediator.py
│   ├── memento.py  observer.py  publish_subscribe.py  registry.py
│   ├── servant.py  specification.py  state.py  strategy.py
│   ├── template.py  visitor.py
│   └── viz/
├── fundamental/     1 pattern — foundational idioms
│   └── delegation_pattern.py
├── other/           3 non-GoF patterns
│   ├── blackboard.py  graph_search.py
│   └── hsm/hsm.py   (hierarchical state machine + its own exceptions)
├── dependency_injection.py   design-for-testability (3 variants)
└── __init__.py

Each viz/ subfolder holds pre-rendered *.py.png class diagrams (one per pattern) used by the README. These are generated artifacts, not source.

Note

The taxonomy is deliberately the same one the Gang of Four book uses, so the repository doubles as a navigable index into that canon. The fundamental, design-for-testability (dependency_injection.py), and other buckets extend it with idioms the GoF set does not cover.

2.2 Self-verification architecture — the core design decision

The single most important architectural choice in this repository is that every pattern file is its own test. There is no separate "examples vs. tests" split for the demonstration code; the demonstration is a test.

┌─────────────────────────────────────────────┐
│  patterns/<category>/<name>.py               │
│                                              │
│  """module docstring — the WHY + trade-offs"""│
│                                              │
│  class / function implementations            │
│                                              │
│  def main():                                 │
│      """                                     │
│      >>> usage example                       │   ← doctest: doc + example + test
│      expected output                         │
│      """                                     │
│                                              │
│  if __name__ == "__main__":                  │
│      import doctest                           │
│      doctest.testmod()                       │   ← runs the doctest on execution
└─────────────────────────────────────────────┘
            │                        │
            ▼                        ▼
   python <file>.py          pytest --doctest-modules patterns/
   (runs that file's          (discovers and runs EVERY pattern's
    doctest, silent on         doctest in one pass)
    success)

In parallel, a conventional unit-test suite mirrors the pattern tree:

tests/
├── behavioral/    test_catalog.py, test_mediator.py, test_memento.py,
│                  test_observer.py, test_publish_subscribe.py, test_servant.py,
│                  test_state.py, test_strategy.py, test_visitor.py
├── creational/    test_abstract_factory.py, test_borg.py, test_builder.py,
│                  test_factory.py, test_lazy.py, test_pool.py, test_prototype.py
├── structural/    test_adapter.py, test_bridge.py, test_decorator.py,
│                  test_facade.py, test_flyweight.py, test_mvc.py, test_proxy.py
├── fundamental/   test_delegation.py
└── test_hsm.py

Important

Two test surfaces coexist: doctests inside patterns/ (which verify the documented usage examples) and pytest unit tests inside tests/ (which verify behavior more rigorously). The pyproject.toml addopts wires both together with --doctest-modules. When you change a pattern, you may have to update both the in-file docstring and the matching tests/ file.

2.3 Negative space — what the architecture intentionally omits

• No runtime dependencies. pyproject.toml's dependencies array is empty. This is a hard design constraint: every pattern must work on a clean standard-library Python so it can be copied out in isolation.
• No Singleton, God Object, or deep-inheritance examples. These are listed in the README as anti-patterns and are deliberately not implemented.
• No interpreter.py. Although an "interpreter" row appears in the README's behavioral table, no such file exists in this revision (commit 74151cf). Treat the on-disk file tree, not the README table, as the source of truth for what exists.
• No build/packaging output. There is no dist/, no wheel pipeline intended for PyPI distribution; the editable install exists only to support testing.

3. System Requirements

Note

The requirements-dev.txt file lists the dev tools unpinned (flake8, black, isort, pytest, pytest-randomly, mypy, pyupgrade, tox). The authoritative pinned versions live in pyproject.toml's dev extra. When the two drift, prefer pyproject.toml.

4. Development Environment Setup

git clone https://github.com/faif/python-patterns.git
cd python-patterns
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
python -m pip install -e ".[dev]"

• [ ] Python 3.10+ active (python --version)
• [ ] Virtual environment created and activated
• [ ] pip install -e ".[dev]" completed without errors
• [ ] pytest runs green
• [ ] ./lint.sh runs clean (bash-compatible shell)

Warning

The Makefile targets (make pyupgrade, make pylinter) assume an embedded venv at ./venv, not a virtualenv elsewhere — the checkvenv target hard-fails if $VIRTUAL_ENV is unset, and pyupgrade looks for venv/bin/pip-compile. Create the venv exactly as python -m venv venv for the Makefile to work as written.

5. Testing

5.1 Test configuration

The pytest configuration lives in pyproject.toml under [tool.pytest.ini_options]:

testpaths = ["tests"]
python_files = ["test_*.py", "*_test.py"]
addopts = "--doctest-modules --randomly-seed=1234 --cov=patterns --cov-report=term-missing"
doctest_optionflags = ["ELLIPSIS", "NORMALIZE_WHITESPACE"]
log_level = "INFO"

Key points:

• --doctest-modules makes pytest collect and run the doctests embedded in the pattern files, in addition to the tests/ unit tests.
• --randomly-seed=1234 (from pytest-randomly) fixes the test execution order so randomized ordering is reproducible.
• --cov=patterns produces a coverage report for the patterns/ package, with missing lines listed in the terminal.
• doctest_optionflags enables ELLIPSIS (so ... matches variable output like memory addresses) and NORMALIZE_WHITESPACE.

Note

A second, minimal pytest config exists at pytest_local.ini (addopts = -q, testpaths = tests). It is a lightweight local override for running just the unit tests quietly, without coverage or doctest collection.

5.2 Running the tests

Everything (coverage + doctests)

pytest

Just the unit tests, quietly

pytest -c pytest_local.ini

Just the in-file doctests

pytest --doctest-modules patterns/

A single pattern's doctest, verbose

python -m doctest -v patterns/creational/factory.py

5.3 Coverage configuration

[tool.coverage.*] in pyproject.toml enables branch coverage with a per-test dynamic context and excludes boilerplate lines from the report:

[tool.coverage.run]
branch = true
source = ["./"]
relative_files = true
parallel = true
dynamic_context = "test_function"

[tool.coverage.report]
exclude_lines = [
    "def __repr__", "if self\\.debug", "raise AssertionError",
    "raise NotImplementedError", "if 0:",
    "if __name__ == .__main__.:", "@(abc\\.)?abstractmethod",
]

Tip

The exclude_lines patterns mean abstract methods, __repr__, and the __main__ guards do not count against coverage — so a green coverage report reflects the pattern logic, not the scaffolding around it. An HTML report is configured to land in coverage_html_report/.

6. Quality Toolchain & CI

6.1 The linting pipeline

The canonical lint sequence is captured in lint.sh:

codespell --quiet-level=2 ./patterns       # spelling
flake8 ./patterns --count --show-source --statistics
isort --profile black ./patterns           # import ordering
tox                                         # tests across env
mypy --ignore-missing-imports ./patterns || true
pytest ./patterns
pytest --doctest-modules ./patterns || true
shopt -s globstar && pyupgrade --py312-plus ./patterns/*.py

Caution

There are two different flake8 line-length settings in play. pyproject.toml's [tool.flake8] sets max-line-length = 120, while the Makefile's pylinter target passes --max-line-length 88 (matching black's default) with a broader --select/--ignore set. The Makefile path is the stricter one. When reconciling lint failures, know which entry point produced them.

6.2 Continuous integration

CI runs on Travis CI (.travis.yml):

os: linux
dist: noble
language: python
jobs:
  include:
    - python: "3.12"
      env: TOXENV=py312
install:
  - pip install codecov tox
script:
  - tox
after_success:
  - codecov

The pipeline installs tox + codecov, runs tox, and uploads coverage to Codecov on success.

6.3 tox

tox configuration lives inline in pyproject.toml under [tool.tox] as legacy_tox_ini:

[tox]
envlist = py312,cov-report
skip_missing_interpreters = true
usedevelop = true

Note

Most of the per-environment tox command detail (the [testenv] and [testenv:cov-report] blocks) is commented out in the current legacy_tox_ini. The active configuration declares the py312 and cov-report environments with usedevelop = true (editable install) and skip_missing_interpreters = true. If you are revamping CI, this commented block is the historical reference for what the full matrix used to run (flake8, coverage run -m pytest --doctest-modules, then a combined coverage report).

7. Module & Pattern Reference (selected internals)

Rather than re-document every pattern (the User Guide catalogs all of them), this section highlights the implementations whose internals are notable for a maintainer.

Tip

Several patterns lean on Python's data-model hooks (__new__, __getattr__, __get__/__set__/__set_name__, metaclasses). These are exactly the places where a "port from Java" would look different — and the module docstrings frequently call out the Python-specific simplification (e.g. "in Python the interface is simply a callable").

7.1 Error/exception inventory

The patterns raise a small, well-defined set of exceptions — useful when writing or reviewing tests:

8. Code Conventions

The contribution guidelines in the README codify the house style:

1. Module docstring required. Every pattern starts with a docstring describing the pattern, ideally with *What is this pattern about?, *What does this example do?, *Where is the pattern used practically?, *References:, and a *TL;DR line. structural/facade.py is cited as the gold-standard detailed example; behavioral/template.py as an acceptable shorter one.
2. "Examples in Python ecosystem" sections are encouraged where real-world equivalents exist (e.g. Django Signals for Observer, ast.NodeVisitor for Visitor, Django middleware for Chain of Responsibility).
3. Type hints throughout. Most files annotate parameters and return types; mypy runs in CI.
4. Black formatting + isort ordering are mandatory before submitting.
5. Doctests as examples. New patterns put their worked example in a main() docstring as a doctest so it is verified automatically.
6. README update. When a pattern is added or changed, the corresponding README table/section must be updated to match.

Important

The README explicitly states the project's editorial stance: emphasize why you'd choose a pattern (and its trade-offs) over how to implement it. Contributions that add an exotic implementation without explaining when to reach for it run against the grain of the project.

9. Contribution Workflow

1. Implement / modify a pattern under patterns/<category>/<name>.py
2. Add a module docstring (why + example + references + TL;DR)
3. Add a main() doctest demonstrating usage
4. Add/adjust the mirror test under tests/<category>/test_<name>.py
5. Run quality gates:
     black .
     ./lint.sh         (bash-compatible shells)
     tox   or   tox -e ci37
6. Update the matching README section/table
7. Open a PR

Pre-submission checklist (from the README's "Travis CI" contribution note):

• [ ] black . applied
• [ ] tox (or tox -e ci37) passes
• [ ] ./lint.sh clean (if you have a bash-compatible shell)
• [ ] README updated to reflect the change

Note

The README also points contributors at CodeTriage for issue/PR triage, and notes that Python 2-compatible versions of some patterns are preserved on the legacy git tag — relevant if a contributor asks where Python 2 support went.

10. Security Analysis

There is no running service, no network surface, no authentication, no secrets, and no third-party runtime dependencies — so the conventional application threat model does not apply. The realistic security considerations are repository-and-supply-chain concerns:

Caution

The biggest governance gap is the missing LICENSE file (tracked as issue #143). Without an explicit license, the default is "all rights reserved," which complicates downstream reuse despite the educational intent. This is a legal/compliance issue rather than a runtime security one, but it is the most consequential open item for anyone copying code out of the repo.

11. Known Issues & Improvement Opportunities

These are drawn from the project's own open GitHub issues (community-reported, real signal):

Tip

Issue #120 (3-tier vs. MVC near-duplication) is a genuine code-quality observation: both files use the same milk/eggs/cheese product model and a similar layered structure. If you touch either, consider adding a comment cross-referencing the other and clarifying the strict vs. non-strict layering distinction that motivates having both.

11.1 Additional maintainer-visible gaps

• README vs. file tree drift. The README's behavioral table lists an interpreter pattern, but no interpreter.py exists in this revision. Either add the implementation or correct the table. (Per the README's own contribution rule #6, the table should track the files.)
• Dev dependency duplication. requirements-dev.txt (unpinned) and pyproject.toml's dev extra (pinned) list overlapping but not identical tool sets. Consolidating to a single source would prevent drift.
• Two flake8 line lengths (120 in pyproject.toml, 88 in the Makefile) — reconcile to one.
• Mostly-commented tox matrix. The active legacy_tox_ini declares environments but leaves the command detail commented out; the real test commands effectively come from pyproject.toml's addopts. Consider making tox self-contained again.

12. Quick Reference

Commands

Key files

Configuration facts