datalad_next.shell.operations.posix.download

datalad_next.shell.operations.posix.download(shell: ShellCommandExecutor, remote_path: PurePosixPath, local_path: Path, *, progress_callback: Callable[[int, int], None] | None = None, response_generator_class: type[DownloadResponseGenerator] = <class 'datalad_next.shell.operations.posix.DownloadResponseGeneratorPosix'>, check: bool = False) ExecutionResult[source]

Download a file from the connected shell

This method downloads a file from the connected shell.

The requirements for download via instances of class DownloadResponseGeneratorPosix are: - The connected shell must support ls -dln. - The connected shell must support echo -e. - The connected shell must support awk. - The connected shell must support cat.

Parameters:
  • shell (ShellCommandExecutor) -- The shell from which a file should be downloaded.

  • remote_path (PurePosixPath) -- The path of the file on the connected shell that should be downloaded.

  • local_path (Path) -- The path of the local file that will contain the downloaded content.

  • progress_callback (callable[[int, int], None], optional, default: None) -- If given, the callback is called with the number of bytes that have been received and the total number of bytes that should be received.

  • response_generator_class (type[DownloadResponseGenerator], optional, default: DownloadResponseGeneratorPosix) -- The response generator that should be used to handle the download output. It must be a subclass of DownloadResponseGenerator. The default works if the connected shell runs on a Unix-like system that provides ls -dln, cat, echo, and awk, e.g. Linux or OSX.

  • check (bool, optional, default: False) -- If True, raise a CommandError if the remote operation does not exit with a 0 as return code.

Returns:

The result of the download operation.

Return type:

ExecutionResult

Raises:

CommandError: -- If the remote operation does not exit with a 0 as return code, and check is True, a CommandError is raised. It will contain the exit code and the last (up to chunk_size (defined by the chunk_size keyword argument to shell())) bytes of stderr output.