Snakemake storage plugin: webdav

https://img.shields.io/badge/repository-github-blue?color=%23022c22 https://img.shields.io/badge/author-Johannes%20Koester-purple?color=%23064e3b PyPI - Version PyPI - License

A Snakemake storage plugin for webdav. Supports Basic auth with username and password. Depending on the server, the support for handling entire directories as input and output might be limited, as there seem to be some bugs in the used library webdav4 that have to be fixed first.

Installation

Install this plugin by installing it with pip or mamba, e.g.:

pip install snakemake-storage-plugin-webdav

Usage

Queries

Queries to this storage should have the following format:

Query type

Query

Description

any

dav://path/to/file.txt

A file on a webdav server

As default provider

If you want all your input and output (which is not explicitly marked to come from another storage) to be written to and read from this storage, you can use it as a default provider via:

snakemake --default-storage-provider webdav --default-storage-prefix ...

with ... being the prefix of a query under which you want to store all your results. You can also pass custom settings via command line arguments:

snakemake --default-storage-provider webdav --default-storage-prefix ... \
    --storage-webdav-max-requests-per-second ... \        --storage-webdav-username ... \        --storage-webdav-password ... \        --storage-webdav-host ... \        --storage-webdav-timeout ...

Within the workflow

If you want to use this storage plugin only for specific items, you can register it inside of your workflow:

# register storage provider (not needed if no custom settings are to be defined here)
storage:
    provider="webdav",
    # optionally add custom settings here if needed
    # alternatively they can be passed via command line arguments
    # starting with --storage-webdav-..., see
    # snakemake --help
    # Maximum number of requests per second for this storage provider. If nothing is specified, the default implemented by the storage plugin is used.
    max_requests_per_second=...,
    # Webdav username
    username=...,
    # Webdav username
    password=...,
    # Webdav hostname (e.g. http://someserver:80/webdav))
    host=...,
    # Webdav timeout
    timeout=...,

rule example:
    input:
        storage.webdav(
            # define query to the storage backend here
            ...
        ),
    output:
        "example.txt"
    shell:
        "..."

Using multiple entities of the same storage plugin

In case you have to use this storage plugin multiple times, but with different settings (e.g. to connect to different storage servers), you can register it multiple times, each time providing a different tag:

# register shared settings
storage:
    provider="webdav",
    # optionally add custom settings here if needed
    # alternatively they can be passed via command line arguments
    # starting with --storage-webdav-..., see below
    # Maximum number of requests per second for this storage provider. If nothing is specified, the default implemented by the storage plugin is used.
    max_requests_per_second=...,
    # Webdav username
    username=...,
    # Webdav username
    password=...,
    # Webdav hostname (e.g. http://someserver:80/webdav))
    host=...,
    # Webdav timeout
    timeout=...,

# register multiple tagged entities
storage foo:
    provider="webdav",
    # optionally add custom settings here if needed
    # alternatively they can be passed via command line arguments
    # starting with --storage-webdav-..., see below.
    # To only pass a setting to this tagged entity, prefix the given value with
    # the tag name, i.e. foo:max_requests_per_second=...
    # Maximum number of requests per second for this storage provider. If nothing is specified, the default implemented by the storage plugin is used.
    max_requests_per_second=...,
    # Webdav username
    username=...,
    # Webdav username
    password=...,
    # Webdav hostname (e.g. http://someserver:80/webdav))
    host=...,
    # Webdav timeout
    timeout=...,

rule example:
    input:
        storage.foo(
            # define query to the storage backend here
            ...
        ),
    output:
        "example.txt"
    shell:
        "..."

Settings

The storage plugin has the following settings (which can be passed via command line, the workflow or environment variables, if provided in the respective columns):

CLI setting

Workflow setting

Envvar setting

Description

Default

Choices

Required

Type

--storage-webdav-max-requests-per-second VALUE

max_requests_per_second

Maximum number of requests per second for this storage provider. If nothing is specified, the default implemented by the storage plugin is used.

None

str

--storage-webdav-username VALUE

username

SNAKEMAKE_STORAGE_WEBDAV_USERNAME

Webdav username

None

str

--storage-webdav-password VALUE

password

SNAKEMAKE_STORAGE_WEBDAV_PASSWORD

Webdav username

None

str

--storage-webdav-host VALUE

host

Webdav hostname (e.g. http://someserver:80/webdav))

None

str

--storage-webdav-timeout VALUE

timeout

Webdav timeout

30

str