datalad.api.create_sibling_osf

datalad.api.create_sibling_osf(title=None, name='osf', storage_name=None, dataset=None, mode='annex', existing='error', trust_level=None, tags=None, public=False, category='data', description=None)

Create a dataset representation at OSF.

This will create a node on OSF and initialize an osf special remote to point to it. There are two modes this can operate in: ‘annex’ and ‘export’. The former uses the OSF node as a key-value store, that can be used by git-annex to copy data to and retrieve data from (potentially by any clone of the original dataset). The latter allows to use ‘git annex export’ to publish a snapshot of a particular version of the dataset. Such an OSF node will - in opposition to the ‘annex’ - be human-readable.

For authentication with OSF, you can define environment variables: Either ‘OSF_TOKEN’, or both ‘OSF_USERNAME’ and ‘OSF_PASSWORD’. If neither of these is defined, the tool will fall back to the datalad credential manager and inquire for credentials interactively.

Parameters:

  • title (str or None, optional) – title of the to-be created OSF node that is displayed on the OSF website. Defaults to the basename of the root directory of the local dataset. [Default: None]

  • name (str, optional) – Name of the to-be initialized osf-special-remote. [Default: ‘osf’]

  • storage_name (str or None, optional) – Name of the storage sibling (git-annex special remote). Must not be identical to the sibling name. If not specified, defaults to the sibling name plus ‘-storage’ suffix. [Default: None]

  • dataset (Dataset or None, optional) – Dataset to create a sibling for. [Default: None]

  • mode ({'annex', 'export', 'exportonly', 'gitonly'}, optional) – [Default: ‘annex’]

  • existing ({'skip', 'error'} or None, optional) – Action to perform, if a (storage) sibling is already configured under the given name and/or a target already exists. In this case, a dataset can be skipped (‘skip’), or the command be instructed to fail (‘error’). [Default: ‘error’]

  • trust_level ({'trust', 'semitrust', 'untrust'} or None, optional) – specify a trust level for the storage sibling. If not specified, the default git-annex trust level is used. [Default: None]

  • tags – specific one or more tags for the to-be-create OSF node. A tag ‘DataLad dataset’ and the dataset ID (if there is any) will be automatically added as additional tags. . [Default: None]

  • public (bool, optional) – make OSF node public. [Default: False]

  • category ({'analysis', 'communication', 'data', 'hypothesis', 'instrumentation', 'methods and measures', 'procedure', 'project', 'software', 'other'}, optional) – specific the OSF node category to be used for the node. The categorization determines what icon is displayed with the node on the OSF, and helps with search organization. [Default: ‘data’]

  • description (str or None, optional) – Description of the OSF node that will be displayed on the associated project page. By default a description will be generated based on the mode the sibling is put into. [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 – select rendering mode command results. ‘tailored’ enables a command- specific rendering style that is typically tailored to human consumption, if there is one for a specific command, or otherwise falls back on the the ‘generic’ result renderer; ‘generic’ renders each result in one line with key info like action, status, path, and an optional message); ‘json’ a complete JSON line serialization of the full result record; ‘json_pp’ like ‘json’, but pretty-printed spanning multiple lines; ‘disabled’ turns off result rendering entirely; ‘<template>’ reports any value(s) of any result properties in any format indicated by the template (e.g. ‘{path}’, compare with JSON output for all key-value choices). The template syntax follows the Python “format() language”. It is possible to report individual dictionary values, e.g. ‘{metadata[name]}’. If a 2nd-level key contains a colon, e.g. ‘music:Genre’, ‘:’ must be substituted by ‘#’ in the template, like so: ‘{metadata[music#Genre]}’. [Default: ‘tailored’]

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