dough

Roll your own typed wrapper.

[!WARNING] dough is still pre-1.0. The API is still evolving and can break in minor releases.

dough is a small framework for building typed Python wrappers around the output files of simulation codes. It ships the generic machinery — file parsers, declarative output mappings, optional library converters — and stays out of the way of the code-specific details. Code-specific wrappers live in their own packages (see Packages built on dough below).

🌯 The current layers

• Parsers — turn one output file into a plain dict. One parser per file format; stateless, with a single parse(content) method.
• Output mappings — frozen dataclasses whose fields are Annotated[T, Spec(...)]. Each field declares the output's name, type, unit (in its docstring), and how to extract it from the parsed dicts via a glom Spec. One source of truth per quantity.
• Converters — optional adapters that turn base Python outputs into ase, pymatgen, or aiida-core objects. Heavy third-party imports stay lazy so wrapper packages don't pay for them at import time.

See the outputs design page for the full picture.

🧪 Testing

dough.testing ships shared pytest fixtures (json_serializer, robust_data_regression_check) used by downstream wrapper packages for regression tests. It's an opt-in plugin — activate it in your top-level conftest.py with pytest_plugins = ["dough.testing.plugin"]. See the testing design page.

🚀 Bootstrapping a wrapper

First create a git-tracked package directory:

mkdir my-package
cd my-package
git init

Or clone a fresh repo from e.g. GitHub. Then copy the template:

copier copy --trust https://github.com/mbercx/dough .

This renders the typed-output scaffolding, then chains an opinionated non-interactive python-copier run for the Python project skeleton.

📦 Packages built on dough

📚 Docs

Full documentation at mbercx.github.io/dough.

🤝 Contributing

It's still early days, and too soon to accept external contributions. Feedback is most welcome though, feel free to open issue!