ibridges.data_operations.download

ibridges.data_operations.download(irods_path, local_path, overwrite=False, on_error='fail', resc_name='', copy_empty_folders=True, options=None, dry_run=False, metadata=None, progress_bar=True)

Download a collection or data object to the local filesystem.

Parameters:

  • irods_path (IrodsPath) – Absolute irods source path pointing to a collection

  • local_path (Union[str, Path]) – Absolute path to the destination directory

  • overwrite (bool) – If data object or collection already exists on iRODS, overwrite.

  • on_error (str) – When a transfer of a file fails, by default the whole transfer will stop and print the error message(fail). By setting ‘on-error’ to ‘warn’, those errors will be turned into warnings and the transfer continues with the next file. Setting ‘on-error’ to ‘skip’ will omit any message and simply proceed.

  • resc_name (str) – Name of the resource from which data is downloaded, by default the server will decide.

  • copy_empty_folders (bool) – Create respective local directory for empty collections.

  • options (Optional[dict]) – Python-irodsclient options found in irods.keywords. The following keywords will be ignored since they are set by iBridges: FORCE_FLAG_KW, RESC_NAME_KW, NUM_THREADS_KW, REG_CHKSUM_KW, VERIFY_CHKSUM_KW.

  • dry_run (bool) – Whether to do a dry run before uploading the files/folders.

  • metadata (Union[None, str, Path]) – If not None, the path to store the metadata to in JSON format. It is recommended to use the .json suffix.

  • progress_bar (bool) – Whether to display a progress bar.

Return type:

Operations

Returns:

Operations object that can be used to execute the download in case of a dry-run.

Raises:

  • PermissionError: – If the iRODS server (for whatever reason) forbids downloading the file or (part of the) collection.

  • DoesNotExistError: – If the irods_path is not pointing to either a collection or a data object.

  • FileExistsError: – If the irods_path points to a data object and the local file already exists.

  • NotADirectoryError: – If the irods_path is a collection, while the destination is a file.

Examples

>>> # Below will create a directory "some_local_dir/some_collection"
>>> download(IrodsPath(session, "~/some_collection"), "some_local_dir")

>>> # Below will create a file "some_local_dir/some_obj.txt"
>>> download(IrodsPath(session, "some_obj.txt"), "some_local_dir")

>>> # Below will create a file "new_file.txt" in two steps.
>>> ops = download(IrodsPath(session, "some_obj.txt", "new_file.txt", dry_run=True)
>>> ops.execute()