datalad_next.shell.operations.posix.upload

datalad_next.shell.operations.posix.upload(shell: ShellCommandExecutor, local_path: Path, remote_path: PurePosixPath, *, progress_callback: Callable[[int, int], None] | None = None, check: bool = False) → ExecutionResult[source]

Upload a local file to a named file in the connected shell

This function uploads a file to the connected shell shell. It uses head to limit the number of bytes that the remote shell will read. This ensures that the upload is terminated.

The requirements for upload are: - The connected shell must be a POSIX shell. - head must be installed in the remote shell.

Parameters:

  • shell (ShellCommandExecutor) -- The shell that should be used to upload the file.

  • local_path (Path) -- The path of the file that should be uploaded.

  • remote_path (PurePosixPath) -- The path of the file on the connected shell that will contain the uploaded content.

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

  • 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 upload 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.