datalad.api.x_export_to_webdav

datalad.api.x_export_to_webdav(to, url=None, mode='auto', dataset=None, recursive=False, recursion_limit=None)

Export a dataset to a WEBDAV server

WEBDAV is standard HTTP protocol extension for placing files on a server that is supported by a number of commericial storage services (e.g. 4shared.com, box.com), but also instances of cloud-storage solutions like Nextcloud or ownCloud. This command is a frontend for git-annex's export functionality that can synchronize a remote WEBDAV target with a particular state of a local dataset. It does not expose all of git-annex's capabilities, such as transparent encryption, but aims to facilitate the use case of sharing the latest saved state of a (nested) dataset with non-DataLad users via a common WEBDAV-enabled storage service.

For the initial export, only a name for the export WEBDAV target (e.g. 'myowncloud') and a URL for the WEBDAV server are required. An optional path component of the URL will determine the placement of the export in the directory hierarchy on the server. For example, 'https://webdav.example.com/datasets/one' will place the root of the dataset export in directory 'datasets/one' on the server. It is recommended to place datasets into dedicated subdirectories on the server.

Subsequent exports do not require a re-specification of a URL, the given name is sufficient. In case only a single WEBDAV export is configured, no parameter is needed at all.

When exporting recursively, subdatasets exports are placed at their corresponding locations on the WEBDAV server. Matching export configurations are generated automatically based on the superdataset's configuration.

Note

This command needs git-annex 8.20210312 (or later).

See also

https://git-annex.branchable.com/git-annex-export

Documentation on git-annex export

Examples

Export a single dataset to 4shared.com:

> x_export_to_webdav('4shared', url='https://webdav.4shared.com/myds')

Recursively export nested datasets into a single directory tree in a box.com account:

> x_export_to_webdav('box', recursive=True, url='https://dav.box.com/dav/myds')
Parameters
  • to (str or None) -- name of the WEBDAV service.

  • url (str or None, optional) -- url of the WEBDAV service. [Default: None]

  • mode ({'auto', 'verify'}, optional) -- on repeated exports, git-annex relies on local knowledge which content was previously exported, and will only upload changes ('auto'); when content was modified independently at the export site this can lead to omissions, and a verification of file existence can be perform prior export ('verify') as a mitigation (this verification is not able to detect remote content changes). [Default: 'auto']

  • dataset (Dataset or None, optional) -- specify the dataset to export. [Default: None]

  • recursive (bool, optional) -- if set, recurse into potential subdataset. [Default: False]

  • recursion_limit (int or None, optional) -- limit recursion into subdataset to the given number of levels. [Default: None]

  • on_failure ({'ignore', 'continue', 'stop'}, optional) -- behavior to perform on failure: 'ignore' any failure is reported, but does not cause an exception; 'continue' if any failure occurs an exception will be raised at the end, but processing other actions will continue for as long as possible; 'stop': processing will stop on first failure and an exception is raised. A failure is any result with status 'impossible' or 'error'. Raised exception is an IncompleteResultsError that carries the result dictionaries of the failures in its failed attribute. [Default: 'continue']

  • result_filter (callable or None, optional) -- if given, each to-be-returned status dictionary is passed to this callable, and is only returned if the callable's return value does not evaluate to False or a ValueError exception is raised. If the given callable supports **kwargs it will additionally be passed the keyword arguments of the original API call. [Default: None]

  • result_renderer ({'default', 'json', 'json_pp', 'tailored'} or None, optional) -- format of return value rendering on stdout. [Default: None]

  • result_xfm ({'datasets', 'successdatasets-or-none', 'paths', 'relpaths', 'metadata'} or callable or None, optional) -- if given, each to-be-returned result status dictionary is passed to this callable, and its return value becomes the result instead. This is different from result_filter, as it can perform arbitrary transformation of the result value. This is mostly useful for top- level command invocations that need to provide the results in a particular format. Instead of a callable, a label for a pre-crafted result transformation can be given. [Default: None]

  • return_type ({'generator', 'list', 'item-or-list'}, optional) -- return value behavior switch. If 'item-or-list' a single value is returned instead of a one-item return value list, or a list in case of multiple return values. None is return in case of an empty list. [Default: 'list']