snakefmt

Format a specific Snakefile

$ snakefmt [path/to/snakefile]

$ snakefmt [path/to/directory]

$ snakefmt --config [path/to/config.toml] [path/to/snakefile]

$ snakefmt --line-length [100] [path/to/snakefile]

$ snakefmt --diff [path/to/snakefile]

snakefmt [options] [path...]

-h, --help
    Show the program's help message and exit.

-c, --check
    Don't write the files back, just return the status. Return code 0 means nothing would change. Return code 1 means some files would be reformatted. Return code 123 means there was an internal error.

-d, --diff
    Don't write the files back, just print unified diffs to stdout.

-v, --verbose
    Print more information, like the names of files being reformatted and why.

-l, --line-length
    How many characters per line to allow. Defaults to 88.

--target-version {py36,py37,py38,py39,py310,py311}
    Python versions that should be supported by Black's output. (This is for the underlying Black formatter).

--skip-version-check
    Don't fail if the Black and isort versions used by snakefmt do not match your installed ones.

--style
    Path to a pyproject.toml containing snakefmt, black and isort config.

--config
    Read configuration from PATH (e.g., pyproject.toml).

--version
    Show the version and exit.

--force-exclusion
    Don't respect .snakefmt and .gitignore exclude patterns.

--list-files
    Print the names of files that would be formatted.

--stdin
    Read Snakemake code from stdin and print formatted code to stdout.

--single-quote
    Use single quotes for strings where appropriate (for Black).

--fmt-error-on-diff
    Return 1 if there's any diff, even if no formatting changes occurred (e.g., just whitespace).

--fmt-error-on-change
    Return 1 if any file was changed due to formatting.

snakefmt is an opinionated code formatter specifically designed for Snakemake workflows. It aims to provide a consistent and readable style across all Snakemake files by automatically reformatting them according to a predefined set of rules.

It leverages the formatting power of popular Python formatters like Black and isort to handle Python code blocks within Snakemake rules, while also applying specific formatting for Snakemake's unique syntax (e.g., rule definitions, input/output sections, shell commands).

By automating the formatting process, snakefmt helps reduce cognitive load during code reviews, minimizes style-related disagreements, and improves the overall maintainability and readability of Snakemake projects. It can be used to format individual files, directories, or even standard input, and offers options for checking formatting without applying changes, showing differences, and controlling line length.

snakefmt is designed exclusively for Snakemake workflows and does not format arbitrary Python files. While it uses Black and isort internally, its primary focus is on Snakemake-specific syntax.

It relies on a pyproject.toml file for project-specific configurations, which might require some initial setup. Although snakefmt aims for idempotence (running it multiple times on the same code yields the same result), unexpected interactions with other linters or manual edits might sometimes require running it again.

snakefmt can be easily integrated into Continuous Integration/Continuous Delivery (CI/CD) pipelines to automatically enforce code style on every commit or pull request. Using the --check or --diff flags, CI/CD systems can verify that all Snakemake files adhere to the defined formatting rules before merging code, preventing unformatted code from entering the main codebase.

Like Black, snakefmt is opinionated, meaning it makes most formatting decisions for you, reducing configuration overhead and style debates. While some options like line-length are configurable, the core formatting logic is fixed, ensuring high consistency across projects.

snakefmt was created to address the lack of a dedicated formatter for Snakemake workflows, which often contain a mix of Snakemake-specific syntax and Python code. Prior to its development, formatting Snakemake files was largely a manual effort or relied on generic Python formatters that couldn't handle Snakemake's unique structure.

By integrating and adapting the robust formatting capabilities of Black and isort, snakefmt provides an automated and opinionated solution for maintaining consistent style, making Snakemake code more readable and easier to collaborate on. Its development filled a crucial gap in the Snakemake ecosystem, promoting best practices for code style.

snakemake(1), black(1), isort(1), yapf(1)