Skip to content

milestone: v2 — patterns as modules, exemplary dunder files, minimal docs - #28

Merged
SuperElectron merged 11 commits into
mainfrom
staging
Aug 27, 2026
Merged

milestone: v2 — patterns as modules, exemplary dunder files, minimal docs#28
SuperElectron merged 11 commits into
mainfrom
staging

Conversation

@SuperElectron

@SuperElectron SuperElectron commented Aug 27, 2026

Copy link
Copy Markdown
Owner

The complete v2 line, reviewed PR by PR on staging (#17–#27):

  • 32 patterns as self-contained modules: importable pattern/ code, three teaching docs each, runnable mini-projects (main.py entry points), isolated behavioral tests.
  • MCP server (src/design_patterns/mcp/): search/recommend → docs → sandboxed example runs → source, with the hardened sandbox contract.
  • Exemplary dunder-file policy, machine-enforced: no __main__.py, no empty __init__.py (PEP 420), no __all__ — the loader rejects violations.
  • Docs: minimal one-table README, root CONTRIBUTING.md, per-unit docs only; top-level docs/ and process files deleted.
  • v2.0.0 in pyproject; wheel verified to ship the full catalog.

make check: 548 tests, mypy --strict, ruff, readme drift — green. CI green on staging tip.

🤖 Generated with Claude Code

SuperElectron and others added 11 commits August 27, 2026 11:43
@SuperElectron @claude
feat: v2 pilot — chain_of_responsibility as module + engine support (#17
35b44ef 
)

* chore: ignore .cache/ local working files

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: v2 pilot — chain_of_responsibility as module + engine support

Pilot for the patterns-as-modules refactor (.cache/plan.md):
- chain_of_responsibility rebuilt: pattern/ (Chain, Handler), docs/
  {fundamentals,implementation,examples}.md, examples/ticket_escalation/,
  isolated tests; naive/pythonic/real_world files removed
- src/design_patterns_mcp -> src/design_patterns/mcp (top-level 'mcp'
  collides with the MCP SDK)
- loader: dual-shape support, strict validation for module-shape units
- sandbox: run example packages (python -I -m, scrubbed env, 10s/64KB)
- MCP tools: get_pattern_docs, list_examples, run_example, read_source
  + pattern://<id>/docs/<doc> resources

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: pilot review findings — shape-aware MCP surfaces, handle_or, strict half-migration validation

- recommend_pattern/get_pattern/instructions/prompts branch on unit shape
- Chain.handle_or no longer swallows nested UnhandledRequestError; adds
  insert/remove for ordered-mutation
- loader: any of pattern|docs|examples claims module shape (half-migrations
  fail CI); stale legacy files in module units are errors; examples/__init__.py
  validated
- resource errors explain themselves; get_pattern delegates to _get
- tests: real-unit sandbox run, both-shapes catalog pin, nested-chain regression

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: raise ResourceError so resource error hints reach MCP clients

ValueError is wrapped opaquely by the SDK's template handler; ResourceError
passes through (mirror of the tools' ToolError). Adds client-boundary tests
asserting the hint text, and routes prompt lookups through _get.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
feat: v2 modules — creational group (#18)
bfce75d 
* feat: v2 modules — abstract_factory (report_renderer) and builder (sql_select_builder)

Migrate two creational units to the module template: pattern/ importable
APIs (DocumentFamily families; SelectBuilder -> frozen Query with staged
validation), docs/{fundamentals,implementation,examples}.md, runnable
mini-projects (quarterly report through two families; order analytics on
in-memory sqlite), isolated behavioral tests. Legacy variant files removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: v2 modules — factory_method, prototype, singleton

Migrated to the patterns-as-modules template (creational batch 2/2):
- factory_method: pattern/ = the three dodges (inject, class-attribute,
  instance-attribute factories); examples/feed_client mirrors
  http.client's response_class slot
- prototype: pattern/ = TemplateRegistry over template callables
  (partial + dataclasses.replace); examples/report_job_templates
  promotes the existing scheduler seed
- singleton: pattern/ = Shared lazy accessor with reset seam;
  examples/app_config = process-wide settings behind get_settings()
- docs/{fundamentals,implementation,examples}.md per unit; classic-form
  listings absorb the old GoF files; legacy variant files removed

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: v2 modules — creational group (abstract_factory, builder, factory_method, prototype, singleton)

Assembles feat/v2-creational-1 + -2. Also: ignore agent worktrees; make
engine tests shape-robust (synthetic legacy unit fixture; pilot unit as the
stable module-shape target) so group migrations don't break them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: creational review findings — factory_method re-domained, fleet-wide example-imports-pattern check

factory_slot trap-safe class-attribute factory; docs no longer teach the
descriptor-binding TypeError; every module unit's examples must import its
own pattern package (catalog test); legacy variant dispatch + recommend-note
tests restored against synthetic fixtures; assorted test tightenings.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
feat: v2 modules — structural group (#19)
d59de6b 
* feat: v2 migration — adapter, bridge, composite as modules

Structural batch 1 of the patterns-as-modules refactor:
- adapter: pattern/ DelegatingAdapter; examples/payment_gateways (one
  checkout over two mismatched vendor SDKs, failure conventions unified)
- bridge: pattern/ Transport protocol + notifiers (PR #14 seed promoted);
  examples/notification_center (per-team transport routing)
- composite: pattern/ generic Composite/HasTotal with honest interfaces;
  examples/org_chart (headcount+cost rollups in one pass)
- three docs files per unit; legacy variant files removed

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: v2 migration — decorator, facade, flyweight, proxy as modules

Structural batch 2/2 of the patterns-as-modules refactor:
- decorator: pattern/ ships logged/timed/retry/rate_limited (ParamSpec-typed,
  effects injected); examples/resilient_client stacks them on a flaky client
  and pins the ordering policy
- facade: place_order checkout facade promoted to pattern/ (rollback intact,
  honest saga boundary); examples/order_checkout batch-processes orders
  through the one door
- flyweight: pattern/ ships InternPool with an immutability guard;
  examples/glyph_styles holds ~30k glyphs on 2 shared styles
- proxy: pattern/ ships stackable LazyProxy/ProtectionProxy/MeteringProxy;
  examples/db_gateway composes all three over one expensive connection
- each unit: docs/{fundamentals,implementation,examples}.md with the
  classic-form contrast and cited external usages; legacy variant files and
  tests removed

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: v2 modules — structural group (adapter, bridge, composite, decorator, facade, flyweight, proxy)

Assembles feat/v2-structural-1 + -2. Also: fleet example-imports-pattern
check upgraded to an AST import walk; legacy sandbox test moved onto the
synthetic legacy fixture.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: structural review findings — LazyProxy sentinel, recursive InternPool guard, fleet examples test

_MISSING sentinel caches falsy subjects; strict interning recurses into
containers; bridge 2x3 asserted + registry house rule; all legacy sandbox
tests on the synthetic fixture; parametrized run of every module unit's
examples; facade rollback releases on any charge failure.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
feat: v2 modules — behavioral group (#20)
eb25cac 
* feat: v2 modules — memento, observer, state (behavioral 2/3)

Migrated to the patterns-as-modules template:
- memento: History caretaker (undo stack + named checkpoints);
  config_checkpoints mini-project (validate-or-rollback, atomic batches);
  pickle CWE-502 warning preserved in docs/examples.md
- observer: Signal with explicit failure policy (propagate or on_error
  isolation); order_events mini-project (independent subscribers,
  dead-letter quarantine)
- state: StateMachine (transition table, guards, step log);
  order_lifecycle mini-project (order FSM, data guards, audit log)

Each unit: pattern/ + docs/{fundamentals,implementation,examples}.md +
examples/<project>/ + isolated tests; legacy variant files removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: v2 modules — strategy, template_method, visitor

Migrated to the module template (pattern/ + docs/ + examples/ + tests/):
- strategy: StrategyRegistry; promotions mini-project (registered pricing
  rules, best-rule engine, comparison report)
- template_method: Skeleton (fixed spine, injected steps, with_steps);
  report_pipeline mini-project (CSV/Markdown variants off one baseline)
- visitor: Operation (singledispatch family with strict default);
  doc_exporters mini-project (markdown/plain-text/word-count over one tree)

Legacy variant files and tests removed per the loader contract.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: v2 migration — command, interpreter, iterator, mediator as modules

Four behavioral units rebuilt to the v2 module template (pilot shape):
- command: Undoable/UndoStack in pattern/; editor_undo mini-project
  (insert/delete/replace with undo, redo, command log)
- interpreter: tuple-tree Interpreter (depth-capped) + hardened safe_eval
  preserved in pattern/; flag_rules mini-project (rules-as-data engine)
- iterator: iterate_pages generator in pattern/; paginated_client
  mini-project with observably lazy fetching
- mediator: Field in pattern/; checkout_form mini-project (promoted
  cascading-rules domain)

Each: docs/{fundamentals,implementation,examples}.md, isolated behavioral
tests, legacy variant files removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: v2 modules — behavioral group (command, interpreter, iterator, mediator, memento, observer, state, strategy, template_method, visitor)

Assembles feat/v2-behavioral-1/-2/-3. Also: last shape-fragile resource
test split into module-doc + synthetic legacy variant coverage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: behavioral review findings — registry house rule, safe_eval pinning, mediator re-scoped

StrategyRegistry/History refuse silent duplicates; safe_eval operator table
pinned, ZeroDivisionError wrapped, single live MAX_DEPTH knob; mediator's
Form base moves the machinery into pattern/; comparison boundaries, docs
accuracy, and mutation gaps closed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
feat: v2 modules — modern group (#21)
d35c406 
* feat: v2 modules — async_producer_consumer, context_manager

Migrate both units to the module template: pattern/ (WorkerPool with both
shutdown disciplines; AtomicWrite + temporarily), docs/ (fundamentals with
classic-form contrast, implementation guide, cited external examples),
mini-projects (feed_fetcher with per-item failure capture; atomic_deploy
with ExitStack rollback), isolated behavioral tests. Legacy variant files
removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat: v2 modules — dependency_injection, registry, repository

Migrate three modern units to the patterns-as-modules template:
- dependency_injection: ReminderService with Protocol seams in pattern/;
  invoice_reminders mini-project with adapters + a real composition root
- registry: typed Registry[T] with explicit duplicate/unknown-key policies;
  export_plugins mini-project with a separate-module plugin demonstrating
  the import-time caveat
- repository: Invoices Protocol port + InMemoryInvoices fake + domain
  services in pattern/; invoice_ledger mini-project with a sqlite adapter
  and one contract test suite parametrized over both backends
Each: docs/{fundamentals,implementation,examples}.md, isolated behavioral
tests, legacy variant files removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: modern review findings — observable shutdown disciplines, durable sqlite, backpressure pinned

Mechanism tests kill both discipline-collapse mutations; SqliteInvoices
commits (file-backed reopen test); pytest-timeout 30s; backpressure and
sentinel accounting asserted; AtomicWrite atomicity via os.replace spy;
duplicate-add contract decided (refused, both backends); docs snippets
runnable as written.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
feat: v2 modules — python + principle groups (catalog complete: 32/32) (
1f5ae3a 
#22)

* feat: v2 modules — python group + composition_over_inheritance

Migrates python/global_object, python/prebound_method,
python/sentinel_object, principle/composition_over_inheritance to the
module template: pattern/ (Lazy; prebound Counter + shares_instance;
Sentinel/MISSING; Filter/Transform/Sink axes + composed Logger),
docs/{fundamentals,implementation,examples}.md, mini-projects
(settings_module, metrics, layered_config, notification_router), isolated
tests. Legacy variant files removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: python+principle review findings — subprocess import proof, Pipeline core, module-flow MCP surface

global_object's laziness proven in a subprocess the fixtures can't erase;
composition's pattern/ owns the Pipeline core the example composes; MCP
instructions describe the module flow for every unit (legacy demoted,
kept for synthetic fixtures, removal deferred to wrap); sentinel identity
semantics pinned and honest.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
chore: v2 wrap — remove legacy shape, rewrite docs for the module ana…
2023766 
…tomy, v2.0.0 (#23)

Loader/server/tests drop the legacy variant vocabulary entirely (strict
module validation everywhere, stale-variant-file debris still refused);
top-level docs and README describe the module template; code-review.md
moves to .github/ with the settled house rules + mutation discipline;
CLAUDE.md/AGENTS.md/new-pattern scaffold updated; version 2.0.0.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
refactor: exemplary __init__.py — bare re-exports, no __all__, proces…
70fb0de 
…s doc removed (#24)

* wip: partial __init__ sweep baseline (agent run resumed under plan-v2)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor: relative as-alias re-exports for creational/modern/python/principle __init__ files

Unit root imports through .pattern; pattern/__init__ imports from defining
modules; export_plugins keeps its load-bearing plugin import with a one-line
why. No __all__, no docstrings anywhere in scope.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor: behavioral+structural __init__ to bare relative as-alias re-exports

Unit root and pattern/__init__ hold only 'from .pattern.<mod> import X as X'
lines; example package inits empty; no __all__, docstrings, or comments.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor: minimal engine/root __init__ files, drop the code-review doc

src/design_patterns/__init__.py emptied (version via importlib.metadata);
conftest's synthetic unit models the as-alias house style; code-review.md
removed and its references folded inline; scaffold emits the minimal shape;
house rule recorded in CLAUDE.md/AGENTS.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
refactor: delete empty __init__.py — namespace packages carry the str…
f24af1e 
…ucture (#25)

* refactor: delete all 104 empty __init__.py — namespace packages (PEP 420)

Only load-bearing __init__.py remain (64 unit API files + registry's
plugin-registration demo). pytest --import-mode=importlib for same-basename
tests; mypy explicit_package_bases + mypy_path; ruff known-first-party
declared (no __init__ to infer from); loader now REJECTS empty __init__.py
and no longer demands example packages be regular packages; fixtures emit
the new shape.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: house rule and scaffold for the no-empty-__init__ shape

CLAUDE.md template tree + house rule updated (delete, don't create; PEP 420);
AGENTS.md regenerated as mirror; /new-pattern scaffolds without empty inits.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
refactor: __main__.py -> main.py everywhere — run via python -m <pack…
7863d59 
…age>.main (#26)

Mat's rule: zero __main__.py in the repo. 32 entry points renamed (content
unchanged, guards kept); run commands, docs, scaffold, and test imports
updated; loader discovers examples by main.py and BANS __main__.py as
debris; sandbox executes <package>.main.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron @claude
docs: delete docs/, root CONTRIBUTING.md, one-table minimal README (#27)
89148d6 
* docs: delete docs/, root CONTRIBUTING.md, minimal README with one catalog table

docs/ was human-facing meta the MCP never serves: contributing moves to the
GitHub-standard root file, MCP usage becomes bullets at the top of README,
the rest (index/verdicts/how-to-read) is deleted — verdicts are spelled out
in the table itself. Table generator emits one table with a Group column.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: drop the unit tree diagram from README

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: MCP section as three commented examples, no bullets

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@SuperElectron
SuperElectron merged commit 8dfde3c into main Aug 27, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@SuperElectron