snakemake-contracts 0.4.0

Lightweight contract helpers for Snakemake modules

snakemake-contracts

A small helper library for Snakemake workflows that use provides / requires-style contracts between modules.

Motivation

A lot of hidden complexities can stem from splitting a snakemake-based project into multiple independent submodules: how do you handle changing independent submodule outputs ?

This package exists for workflows that are split into many Snakemake submodules and need a disciplined way to connect them.

In practice, the goal is not just to reuse code. It is to make module boundaries explicit and stable:

• each module should declare what it consumes and what it exposes;
• each module should keep its own outputs defined in one place;
• the root workflow should not become the only place that knows where every generated file lives.

That matters once a workflow grows beyond a single Snakefile. At that point the top-level repo tends to accumulate accidental knowledge about other modules: hard-coded file paths, config overrides for foreign outputs, and ad hoc assumptions about directory layouts. Those shortcuts make the graph harder to reason about and much easier to break when a module changes shape.

The contract model used here is intentionally close to the requires / provides style found in systems like nREPL middleware chains: producers declare the interface they offer, consumers ask for a named capability, and the resolver stays small and mechanical. The point is to treat the dependency boundary as a contract, not as an implicit convention spread across the whole repository.

Using provides.yaml as the source of truth also has a practical benefit: the module itself remains the authoritative owner of its exported outputs. The repo root can still orchestrate modules, but it does not need to mirror every output name or path in a central registry. That reduces duplication and keeps the dependency metadata next to the module that owns it.

Scope

• resolve declared outputs by logical key
• locate module output directories
• validate provides.yaml files
• optionally compare declared contracts against a repo layout

Library Usage

The core API lives in snakemake_contracts.contracts and expects a repo layout like:

repo/
  modules/
    my_module/
      Snakefile
      provides.yaml
      out/

Typical usage:

from snakemake_contracts.contracts import load_provides, provides, validate_repo

mapping = load_provides("my_module", repo_root="/path/to/repo")
report = provides("my_module", "report", repo_root="/path/to/repo")
problems = validate_repo("/path/to/repo")

provides.yaml is the source of truth for logical output names, and provides() resolves them relative to the module's out/ directory.

Wrapper Layer

The repository now also includes a separate wrapper/ package, snakemake_contracts_wrapper, for Snakemake-facing command construction. That layer is intentionally thin: it reads the named input, output, and params objects already present in a rule and turns them into ordinary script arguments.

The script itself still stays unaware of Snakemake. It only sees CLI flags. The wrapper only removes the repetitive --flag {input.foo} wiring in the Snakefile.

When .cache is configured, the Snakemake wrapper can synthesize a default log path under .cache/logs/, but it only passes that path as --log when scripts_accept_log_arg: true is also set in the workflow config. This opt-in is required because cache usage alone does not prove that every wrapped script supports a --log CLI argument.

Current Surface

• load_provides(module, repo_root=None)
• provides(module, key, repo_root=None)
• out_dir(module, repo_root=None)
• list_modules(repo_root=None)
• mangle(name)
• validate_repo(repo_root=None)

Wrapper surface:

• build_argv(command, input=None, output=None, params=None, exclude_input=("script",))
• render_shell(command, input=None, output=None, params=None, exclude_input=("script",))

Tests

• tests/test_contracts.py exercises the library directly against a temporary repo layout.
• tests/test_wrapper.py covers the wrapper command helpers.

Status

This is a small utility package, not a general Snakemake extension. It is meant to support workflows that already use provides.yaml-style contracts and want a single place to validate and resolve them.