# mothersauce

> The base recipes of production Python 3.15: factories, abstractions, dataclasses, pydantic, generators,
> context managers, generics and more, each a typed, tested module with a runnable demo, plus the practices
> around them. A CLI, a man page, an MCP server and an agent skill serve them to people and AI agents.

Install: `uv tool install mothersauce` or `pip install mothersauce`. Then `mothersauce list`,
`mothersauce search "<problem>"`, `mothersauce show <recipe>`, `mothersauce run <recipe>`, or
`mothersauce mcp` as an MCP server. `mothersauce guide` prints the full manual.

## Docs

- [README](https://github.com/jpsanders/mothersauce/blob/main/README.md): what it is, install, use with an agent
- [Manual](https://github.com/jpsanders/mothersauce/blob/main/docs/MANUAL.md): every command, the MCP tools, the workflow
- [Menu](https://github.com/jpsanders/mothersauce/blob/main/docs/RECIPES.md): every recipe with when to use it and when not
- [Skill](https://github.com/jpsanders/mothersauce/blob/main/skills/mothersauce/SKILL.md): which recipe for which problem
- [AGENTS.md](https://github.com/jpsanders/mothersauce/blob/main/AGENTS.md): working on this repository

## Recipes

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