snakemake-contracts 0.1.0__py3-none-any.whl

snakemake_contracts/__init__.py

@@ -0,0 +1 @@
+from .contracts import ContractError, load_provides, out_dir, provides, list_modules, mangle, validate_repo

snakemake_contracts/cli.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+from .contracts import list_modules, load_provides, provides, validate_repo
+
+
+def _cmd_list_modules(args: argparse.Namespace) -> int:
+    for module in list_modules(args.repo_root):
+        print(module)
+    return 0
+
+
+def _cmd_list_keys(args: argparse.Namespace) -> int:
+    data = load_provides(args.module, args.repo_root)
+    for key in sorted(data):
+        print(f"{key}\t{data[key]}")
+    return 0
+
+
+def _cmd_resolve(args: argparse.Namespace) -> int:
+    print(provides(args.module, args.key, args.repo_root))
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    problems = validate_repo(args.repo_root)
+    if problems:
+        for problem in problems:
+            print(problem, file=sys.stderr)
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="snakemake-contracts")
+    parser.add_argument("--repo-root", type=Path, default=None)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("list-modules")
+    p.set_defaults(func=_cmd_list_modules)
+
+    p = sub.add_parser("list-keys")
+    p.add_argument("module")
+    p.set_defaults(func=_cmd_list_keys)
+
+    p = sub.add_parser("resolve")
+    p.add_argument("module")
+    p.add_argument("key")
+    p.set_defaults(func=_cmd_resolve)
+
+    p = sub.add_parser("validate")
+    p.set_defaults(func=_cmd_validate)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

snakemake_contracts/contracts.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass(frozen=True)
+class ContractError(Exception):
+    message: str
+
+    def __str__(self) -> str:
+        return self.message
+
+
+def _repo_root(repo_root: str | Path | None = None) -> Path:
+    if repo_root is None:
+        return Path(__file__).resolve().parents[2]
+    return Path(repo_root)
+
+
+def modules_dir(repo_root: str | Path | None = None) -> Path:
+    return _repo_root(repo_root) / "modules"
+
+
+def load_provides(module: str, repo_root: str | Path | None = None) -> dict[str, str]:
+    path = modules_dir(repo_root) / module / "provides.yaml"
+    if not path.exists():
+        raise FileNotFoundError(f"{path} not found")
+    with path.open() as f:
+        data = yaml.safe_load(f) or {}
+    if not isinstance(data, dict):
+        raise ContractError(f"{path} must contain a mapping of logical keys to relative paths")
+    bad = [k for k, v in data.items() if not isinstance(k, str) or not isinstance(v, str)]
+    if bad:
+        raise ContractError(f"{path} contains non-string keys/values: {bad}")
+    return data
+
+
+def out_dir(module: str, repo_root: str | Path | None = None) -> Path:
+    return modules_dir(repo_root) / module / "out"
+
+
+def provides(module: str, key: str, repo_root: str | Path | None = None) -> str:
+    mapping = load_provides(module, repo_root=repo_root)
+    if key not in mapping:
+        raise KeyError(f"{module}:{key} not declared; available keys: {sorted(mapping)}")
+    return str(out_dir(module, repo_root=repo_root) / mapping[key])
+
+
+def list_modules(repo_root: str | Path | None = None) -> list[str]:
+    root = modules_dir(repo_root)
+    if not root.exists():
+        return []
+    return sorted(p.name for p in root.iterdir() if p.is_dir() and (p / "Snakefile").exists())
+
+
+def mangle(name: str) -> str:
+    return name.replace("-", "_").replace(".", "_")
+
+
+def validate_repo(repo_root: str | Path | None = None) -> list[str]:
+    root = _repo_root(repo_root)
+    problems: list[str] = []
+    for module in list_modules(root):
+        p = modules_dir(root) / module / "provides.yaml"
+        if not p.exists():
+            continue
+        try:
+            load_provides(module, root)
+        except Exception as exc:  # noqa: BLE001
+            problems.append(f"{module}: {exc}")
+    return problems

snakemake_contracts-0.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: snakemake-contracts
+Version: 0.1.0
+Summary: Lightweight contract helpers for Snakemake modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+
+# 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:
+
+```text
+repo/
+  modules/
+    my_module/
+      Snakefile
+      provides.yaml
+      out/
+```
+
+Typical usage:
+
+```python
+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.
+
+## 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.
+

snakemake_contracts-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+snakemake_contracts/__init__.py,sha256=YlDffLM2jrfYFELcyxkVhPVwEtTUJvoPmZR940an28E,108
+snakemake_contracts/cli.py,sha256=pfKXWX7QnXSo5ypf3WFU-N7k9VIYRufc5BT0rE_mPPY,1688
+snakemake_contracts/contracts.py,sha256=KpNobLzfXGedcnIJAOnhu095uuTm2S8l1EODhnOhR_o,2386
+snakemake_contracts-0.1.0.dist-info/entry_points.txt,sha256=MucvaXCixO2EncluCLB3cQWqGwkuBdUgmXBnZCnwLpU,68
+snakemake_contracts-0.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+snakemake_contracts-0.1.0.dist-info/METADATA,sha256=U-uDQF_YKd-aWM4xYnYhR3Ba4_QBKZ0j5XZ4-w8XgDk,4238
+snakemake_contracts-0.1.0.dist-info/RECORD,,

snakemake_contracts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

snakemake_contracts-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+snakemake-contracts=snakemake_contracts.cli:main
+