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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.