Snakefmt

此存储库提供了对Snakemake文件的格式化。它遵循Black的设计和规范。

⚠️警告⚠️: 默认情况下，snakefmt会就地修改文件，因此我们强烈建议在执行任何格式化之前确保您的文件处于版本控制之下。您也可以从stdin管道输入文件，它将打印到屏幕上，或者使用--diff或--check选项。有关更多详细信息，请参阅用法。

目录

• 安装
  • PyPi
  • Conda
  • 容器
  • 本地
• 示例文件
• 用法
  • 基本用法
  • 完整用法
• 配置
• 集成
  • 编辑器集成
  • 版本控制集成
  • GitHub Actions
• 插件
• 变更
• 贡献
• 引用

安装

PyPi

pip install snakefmt

Conda

conda install -c bioconda snakefmt

容器

由于snakefmt有一个Conda配方，因此Biocontainers为每个版本构建了一个匹配的镜像。

在以下示例中，所有标签（<tag>）都可以在此处找到。

Docker

$ docker run -it "quay.io/biocontainers/snakefmt:<tag>" snakefmt --help

Singularity

$ singularity exec "docker://quay.io/biocontainers/snakefmt:<tag>" snakefmt --help

本地

这些说明包括安装poetry。

# install poetry
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python3

git clone https://github.com/snakemake/snakefmt && cd snakefmt
# install snakefmt in a new environment
poetry install
# activate the environment so snakefmt is available on your PATH
poetry shell

示例文件

输入

from snakemake.utils import min_version
min_version("5.14.0")
configfile: "config.yaml" # snakemake keywords are treated like classes i.e. 2 newlines
SAMPLES = ['s1', 's2'] # strings are normalised
CONDITIONS = ["a", "b", "longlonglonglonglonglonglonglonglonglonglonglonglonglonglonglong"] # long lines are wrapped
include: "rules/foo.smk" # 2 newlines

rule all:
    input: "data/results.txt" # newlines after keywords enforced and trailing comma

rule gets_separated_by_two_newlines:
    input:
        files = expand("long/string/to/data/files/gets_broken_by_black/{sample}.{condition}",sample=SAMPLES, condition=CONDITIONS)
if True:
    rule can_be_inside_python_code:
        input: "parameters", "get_indented"
        threads: 4 # Numeric params stay unindented
        params: key_val = "PEP8_formatted"
        run:

                print("weirdly_spaced_string_gets_respaced")

输出

from snakemake.utils import min_version

min_version("5.14.0")


configfile: "config.yaml" # snakemake keywords are treated like classes i.e. 2 newlines


SAMPLES = ["s1", "s2"] # strings are normalised
CONDITIONS = [
    "a",
    "b",
    "longlonglonglonglonglonglonglonglonglonglonglonglonglonglonglong",
]  # long lines are wrapped


include: "rules/foo.smk" # 2 newlines


rule all:
    input:
        "data/results.txt", # newlines after keywords enforced and trailing comma


rule gets_separated_by_two_newlines:
    input:
        files=expand(
            "long/string/to/data/files/gets_broken_by_black/{sample}.{condition}",
            sample=SAMPLES,
            condition=CONDITIONS,
        ),


if True:

    rule can_be_inside_python_code:
        input:
            "parameters",
            "get_indented",
        threads: 4 # Numeric params stay unindented
        params:
            key_val="PEP8_formatted",
        run:
            print("weirdly_spaced_string_gets_respaced")

用法

基本用法

格式化单个Snakefile。

snakefmt Snakefile

格式化目录中所有Snakefile。

snakefmt workflows/

格式化文件，但将输出写入stdout。

snakefmt - < Snakefile

完整用法

$ snakefmt --help
Usage: snakefmt [OPTIONS] [SRC]...

  The uncompromising Snakemake code formatter.

  SRC specifies directories and files to format. Directories will be
  searched for file names that conform to the include/exclude patterns
  provided.

  Files are modified in-place by default; use diff, check, or  `snakefmt - <
  Snakefile` to avoid this.

Options:
  -l, --line-length INT  Lines longer than INT will be wrapped.  [default: 88]
  --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 error.

  -d, --diff             Don't write the files back, just output a diff for
                         each file to stdout.

  --compact-diff         Same as --diff but only shows lines that would change
                         plus a few lines of context.

  --include PATTERN      A regular expression that matches files and
                         directories that should be included on recursive
                         searches.  An empty value means all files are
                         included regardless of the name.  Use forward slashes
                         for directories on all platforms (Windows, too).
                         Exclusions are calculated first, inclusions later.
                         [default: (\.smk$|^Snakefile)]

  --exclude PATTERN      A regular expression that matches files and
                         directories that should be excluded on recursive
                         searches.  An empty value means no paths are
                         excluded. Use forward slashes for directories on all
                         platforms (Windows, too). Exclusions are calculated
                         first, inclusions later.  [default: (\.snakemake|\.eg
                         gs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_
                         build|buck-out|build|dist)]

  -c, --config PATH      Read configuration from PATH. By default, will try to
                         read from `./pyproject.toml`

  -h, --help             Show this message and exit.
  -V, --version          Show the version and exit.
  -v, --verbose          Turns on debug-level logging.

配置

snakefmt可以从pyproject.toml文件中读取其命令行选项的项目特定默认值。此外，它还会加载你在同一文件中设置的任何black配置。

默认情况下，snakefmt将在格式化的文件/文件夹的父目录中搜索名为pyproject.toml的文件，并使用该文件中的任何配置。如果你的配置文件位于其他位置或名称不同，请使用--config指定。

你在命令行上传递的任何选项都将覆盖配置文件中的默认值。

示例

pyproject.toml

[tool.snakefmt]
line_length = 90
include = '\.smk$|^Snakefile|\.py$'

# snakefmt passes these options on to black
[tool.black]
skip_string_normalization = true

在这个例子中，我们增加了--line-length的值，并且还包括了python（*.py）文件进行格式化 - 这实际上是在这些文件上运行black。内部，snakefmt还将[tool.black]设置传递给black。

集成

编辑器集成

有关如何将snakefmt集成到您选择的编辑器的说明，请参阅docs/editor_integration.md

版本控制集成

snakefmt支持pre-commit，这是一个管理git预提交钩子的框架。使用此框架，您可以在提交Snakefile或*.smk文件时运行snakefmt。如果snakefmt会修改文件，pre-commit将自动创建一个带有snakefmt的隔离虚拟环境，并停止提交。然后您将审查、暂存并重新提交这些更改。如果您的项目中没有GitHub actions之类的CI/CD系统，pre-commit特别有用。

为此，在项目目录根目录中创建文件.pre-commit-config.yaml，内容如下：

repos:
  - repo: https://github.com/snakemake/snakefmt
    rev: 0.5.0 # Replace by any tag/version ≥0.2.4 : https://github.com/snakemake/snakefmt/releases
    hooks:
      - id: snakefmt

然后安装pre-commit，并通过运行pre-commit install初始化pre-commit钩子（注意，您需要为您的仓库克隆运行此步骤一次）。可以在此处找到其他pre-commit钩子。

GitHub Actions

结合GitHub Actions和super-linter，您可以在您的仓库中自动运行所有Snakefile，例如在您推送新提交时。

为此，在您的仓库中创建文件.github/workflows/linter.yml。

---
name: Lint Code Base

on:
  push:
  pull_request:
    branches: [master]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v2

      - name: Lint Code Base
        uses: github/super-linter@v3
        env:
          VALIDATE_ALL_CODEBASE: false
          DEFAULT_BRANCH: master
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

          VALIDATE_SNAKEMAKE_SNAKEFMT: true

通过创建.github/linters/.snakefmt.toml，可以指定其他配置参数。

[tool.black]
skip_string_normalization = true

有关更多信息，请查看super-linter的readme。

插件

如果您喜欢徽章，那么您可以在项目中展示您正在使用snakefmt。

Markdown

[![Code style: snakefmt](https://img.shields.io/badge/code%20style-snakefmt-000000.svg)](https://github.com/snakemake/snakefmt)

ReStructuredText

.. image:: https://img.shields.io/badge/code%20style-snakefmt-000000.svg
    :target: https://github.com/snakemake/snakefmt

变更

请参阅CHANGELOG.md。

贡献

请参阅CONTRIBUTING.md。

引用

@article{snakemake2021,
  doi = {10.12688/f1000research.29032.2},
  url = {https://doi.org/10.12688/f1000research.29032.2},
  year = {2021},
  month = apr,
  publisher = {F1000 Research Ltd},
  volume = {10},
  pages = {33},
  author = {Felix M\"{o}lder and Kim Philipp Jablonski and Brice Letcher and Michael B. Hall and Christopher H. Tomkins-Tinch and Vanessa Sochat and Jan Forster and Soohyun Lee and Sven O. Twardziok and Alexander Kanitz and Andreas Wilm and Manuel Holtgrewe and Sven Rahmann and Sven Nahnsen and Johannes K\"{o}ster},
  title = {Sustainable data analysis with Snakemake},
  journal = {F1000Research}
}