Skip to main content

mothersauce: the base recipes of production Python

CI Release 1.0.1 PyPI Python 3.15 26 recipes MCP server Claude Code plugin Agent skill mypy strict Code style: black Tests: pytest and pytest-bdd Coverage floor 95% One dependency MIT licence Last commit Stars

Every cuisine rests on a handful of mother sauces. Learn them and every other sauce is a variation. Production Python is the same: a few dozen patterns carry almost every codebase, from the dataclass that holds a value to the context manager that commits a transaction.

mothersauce is those patterns as 26 recipes. Each code recipe is one small module of Python 3.15 with full type hints, Sphinx docstrings, a demo you can run and its own tests, plus a card that says when to use it and when not to. You read them on the command line or in a man page; your AI agent reads the same recipes over MCP or through a skill.

uv tool install mothersauce
mothersauce search "retry a flaky api call"
mothersauce show decorators
mothersauce run pipeline
$ mothersauce run pipeline
The pipeline: Most recipes plated together: a small, real ETL with quality rules, upserts by key and JSON logs.

run-1: read 16, loaded 12, already loaded 0, quarantined 3, invalid 1 in 40 ms
run-2: read 16, loaded 0, already loaded 12, quarantined 3, invalid 1 in 1 ms
findings on the first run: {'large_quantity': 1, 'known_station': 1, 'quantity_positive': 1, 'unique_key': 1}
invalid: ['RecordError: line 16, opened_at: input should have timezone info']
dishes by station: {'cold': 25, 'sauce': 12, 'grill': 6, 'pastry': 4, 'fry': 2}
prices keep their cents: '31.50'
4 JSON log lines, each carrying its run id

Why

Most of what makes Python production grade is never in the tutorial. Parse untrusted input once, at the edge. Freeze values. Pair every acquire with its release. Stream instead of loading. Keep the cause when you raise. Log JSON with a run id. These are learned on the job, one incident at a time, and an AI agent that learned Python from the internet writes code that runs but is rarely shaped like this.

Each recipe holds one pattern in one module, written the way it would be in a production codebase: typed for mypy's strict mode, documented, tested, and short enough to read in one sitting. The recipes share one example domain, a restaurant's ticket feed, so they read as one system, and the pipeline recipe loads that feed using most of the others.

The menu

Section Recipe What it gives you
Mise en place workflow pyenv and pyenv-virtualenv, make targets, and CI that runs exactly what your machine runs.
Mise en place layout The src layout: one package, one concept per module, tests that mirror it, data shipped inside.
Mise en place style Ten checks that end style arguments: black, isort, flake8, darglint, mypy strict, bandit and more.
Mother sauces dataclasses Small, honest value objects: frozen, slotted, validated, replaced rather than mutated.
Mother sauces pydantic Parse, don't validate, at the edges: frozen models that forbid extras, reusable constraints, unions.
Mother sauces enums Closed sets of names: StrEnum, IntEnum, Flag, a state machine, and exhaustive match with assert_never.
Mother sauces abstractions ABCs for families you own, with a template method; Protocols for shapes you accept.
Mother sauces factories Decide which class to build in one place: registries, init_subclass, from_ constructors, plugins.
Mother sauces generics Write the container once and keep every type: PEP 695 syntax, bounds, defaults, ParamSpec, Result.
Mother sauces generators Any size of input in the memory of one record: streams, stages, batches, windows, send, cursors.
Mother sauces context-managers Every acquire paired with its release: timers, atomic writes, nested transactions, ExitStack.
Mother sauces decorators Cross cutting behaviour written once: typed retry with backoff and jitter, caches, singledispatch.
Mother sauces oop Composition over inheritance, dunder protocols, properties, descriptors and slots.
Mother sauces data-structures The container that makes the code obvious: Counter, deque, heapq, bisect, ChainMap, graphlib.
Mother sauces errors A hierarchy you can catch, chains you can follow, and batches that report every failure at once.
On the line sql Injection proof queries with template strings, schema evolution, idempotent upserts and high watermarks.
On the line data-quality Rules as data, severities, quarantine, and overrides with an audit trail.
On the line pipeline Most recipes plated together: a small, real ETL with quality rules, upserts by key and JSON logs.
Service logging JSON lines with a run id from a ContextVar, secrets redacted, configured once with dictConfig.
Service config One frozen settings object from defaults, TOML, environment and flags, with where each value came from.
Service concurrency Wait for many slow things at once, bounded, in order, without losing a single error.
Service performance Measure first, then make the common path cheap: lazy imports, timeit, import costs.
Service cli This package's own CLI: subcommands, --json wherever there is data, exit codes, a man page, lazy imports.
Service mcp-server This package's own MCP server: JSON-RPC over stdio with tools, resources and prompts.
The pass testing Fixtures, parametrize, fakes over mocks, doctests and a coverage gate: nothing broken leaves the pass.
The pass bdd Gherkin features run by pytest-bdd: behaviour written so a person can read it and pytest can run it.

The full cards, with when to use each recipe and when not to, are in docs/RECIPES.md.

Use it

mothersauce                              # the menu
mothersauce search stream a huge csv     # which recipe for a problem
mothersauce show generators              # the card, the notes and the full tested source
mothersauce show generators --notes      # the card and the notes only
mothersauce run generators               # its demo
mothersauce style                        # the house style
mothersauce guide                        # the whole manual; or: mothersauce man --install && man mothersauce

Every command that prints data takes --json. It is on PyPI and needs Python 3.15:

uv tool install mothersauce     # uv fetches Python 3.15 if you lack it
pipx install mothersauce
pip install mothersauce

For AI agents

Claude Code plugin: the skill and the MCP server in one step.

/plugin install mothersauce --marketplace jpsanders/mothersauce

On Claude Code before 2.1.275, add the marketplace first, /plugin marketplace add jpsanders/mothersauce, then /plugin install mothersauce@mothersauce.

Every other harness: mothersauce integrate registers the server in Claude Code, Codex, OpenCode, Gemini CLI and Cursor, and installs the skill in the three that read skills folders: Claude Code, Codex and OpenCode. Claude Code and Codex are changed through their own command line; other configuration files get a backup first. --dry-run shows exactly what a real run would do. Or add the server to any MCP client by hand, with nothing installed first:

{"mcpServers": {"mothersauce": {"command": "uvx", "args": ["mothersauce", "mcp"]}}}
Tool What it returns
search_recipes The recipes for a problem described in a few words, best first
get_recipe One recipe as Markdown: when to use it, when not, and its complete, tested source
list_recipes Every recipe's card, optionally one section or kind
get_style_guide The house style: layout, naming, typing, docstrings, errors, logging, tests

Every tool is read only. The server also offers each recipe as a resource, mothersauce://recipes/<id>, and two prompts, apply_recipe and review_python. It is one module of the standard library: the mcp-server recipe is its own source.

Without a server: mothersauce skill prints the skill, and npx skills add jpsanders/mothersauce installs it in the harnesses that tool knows. mothersauce style --agents prints a short block for a project's AGENTS.md or CLAUDE.md that tells any agent to write Python this way. llms.txt maps the repository for agents that read it directly.

Python 3.15, used for real

The recipes use the newest Python where it makes production code better, not to show off:

Feature Version Where
lazy import 3.15 cli: the command starts without loading pydantic; performance measures it
frozendict 3.15 enums for a transition table, data-structures for a menu, factories for options
sentinel() 3.15 config: int | UNSET for a flag left out, narrowed by mypy; concurrency: a stop marker
Unpacking in comprehensions 3.15 generators: (*group for group in groups)
TypedDict(closed=True) 3.15 data-structures: a JSON shape with no extra keys
Template strings, t"..." 3.14 sql: values always become parameters, names pass a checked {name:id} spec
except A, B: 3.14 errors and data-quality
Type parameter defaults 3.13 generics: Page[T, C = str], Result[T, E = str]
TypeIs, warnings.deprecated, copy.replace 3.13 generics, decorators, dataclasses
class Repository[K: Hashable, V] 3.12 generics, and across the recipes

Light and fast

One dependency, pydantic, and the command never imports it unless a recipe needs it. Measured on the author's machine with make bench, best of 20 runs each:

Command Time
python -c pass (the interpreter alone) 8 ms
mothersauce --version 31 ms
mothersauce list 35 ms

CI runs the same benchmark on the built wheel and fails if mothersauce list imports a heavy module. The recipes measure themselves too: mothersauce run performance times its comparisons on your machine, the generators demo shows a million integers taking 40 MB as a list against 216 bytes as a generator, and the oop demo shows __slots__ saving about 40% of the memory of 10,000 objects.

Mise en place: the workflow

mothersauce started from python-package-template; the first two commits are the template as it was and the rename. It keeps the template's workflow: one virtual environment per project, one Makefile for every command, and CI that runs exactly what the Makefile runs.

git clone https://github.com/jpsanders/mothersauce && cd mothersauce
pyenv install 3.15.2 && pyenv virtualenv 3.15.2 mothersauce && pyenv local mothersauce
make init-dev
make checks      # isort, black, editorconfig, darglint, flake8, mypy strict, bandit, docs, man page, pytest

make checks is the pass: nothing broken leaves it. CI runs the same checks in the same order, the static ones on Linux and the tests on Linux and macOS, then installs the built wheel in a clean environment and runs its commands. The workflow recipe has the details, releases included.

Tests

Plain pytest for units, with fixtures, parametrize and fakes rather than mocks. Doctests run, so no example in a docstring can drift from the code. Acceptance behaviour is written in Gherkin and run by pytest-bdd:

Scenario: A second run loads nothing new
  Given the staff meal is approved by the head chef
  When the pipeline runs
  And the pipeline runs again
  Then 0 lines are loaded
  And 12 lines are skipped as already loaded

Coverage has a floor of 95% with branch coverage, and mypy checks the tests in strict mode too.

Why the name

A mother sauce is one of the five sauces of classical French cooking that every other sauce is built from: béchamel, velouté, espagnole, tomato and hollandaise. The author spent seventeen years in professional kitchens, apprentice to head chef, before writing Python for a living, and the kitchen's habits carried over. Mise en place: prepare everything before service starts. The pass: the counter where every plate is checked, and nothing broken leaves it. The menu here is laid out the same way.

Development

make init-dev    # the package in editable mode with every development tool
make format      # black and isort
make checks      # every check CI runs
make docs        # rebuild docs/RECIPES.md, the README menu, llms.txt and the skill copy from the catalogue
make man         # rebuild the man page from docs/MANUAL.md
make bench       # start up times
make demo        # run every recipe's demo

A new recipe is a module in src/mothersauce/recipes/ with a demo(), its tests in tests/mothersauce/recipes/, and an entry in src/mothersauce/data/recipes.toml. See CONTRIBUTING.md and SECURITY.md.

Star history

Star history of jpsanders/mothersauce

Licence

MIT. Made by James Phillip Sanders.

Metadata

Release files for mothersauce 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mothersauce 1.0.1
File Size Uploaded Provenance Actions
mothersauce-1.0.1.tar.gz 331.7 kB With provenance Details for mothersauce-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mothersauce 1.0.1
File Interpreter ABI Platform Actions
mothersauce-1.0.1-py3-none-any.whl Python 3 none any Details for mothersauce-1.0.1-py3-none-any.whl

Total release size: 452.1 kB

Release files / mothersauce-1.0.1.tar.gz

Download URL mothersauce-1.0.1.tar.gz
Size 331.7 kB
Tags Source
SHA-256 checksum
How to use checksums
8ada7ec523a6ac2cb79b4958615f4a9205568afcc594da9479953ad392bda887
BLAKE2b-256 checksum
How to use checksums
4103f6c14afb82b1add79fb5e2c35352b830f21c32eeeb3b9e7432d5a8363fed
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / mothersauce-1.0.1-py3-none-any.whl

Download URL mothersauce-1.0.1-py3-none-any.whl
Size 120.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bf47bf181c3ed4b5fc5c420e0722f3926982bf99ded7306bf88c7d15a4ecfbf4
BLAKE2b-256 checksum
How to use checksums
9c0f1156760fd4892ffd6c475aad56ffbb097c5bd0f34bcef941de6633aaea0b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for mothersauce 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mothersauce-1.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page