datalad.api.x_export_bagit

datalad.api.x_export_bagit(to, archive=None, dataset=None, recursive=False, recursion_limit=None)

Export a dataset to a Bag-it

This is a proof-of-principle implementation that can export a DataLad dataset into a BagIt bag, a standardized storage and and transfer format for arbitrary digital content.

TODOs:

See also

RFC8493

BagIt specification.

Examples

Export dataset to a bag directory at /tmp/bag:

> x_export_bagit('/tmp/bag')

Export dataset to a ZIP archive bag at /tmp/bag.zip:

> x_export_bagit('/tmp/bag', archive='zip')
Parameters
  • to (str or None) -- location to export to. With archive this is the base path, and a filename extension will be appended to it.

  • archive ({'tar', 'tgz', 'bz2', 'zip', None}, optional) -- export bag as a single-file archive in the given format. [Default: None]

  • 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']