transfer

File transfer via SFTP and/or SCP.

class fabric.transfer.Result(local, orig_local, remote, orig_remote, connection)

A container for information about the result of a file transfer.

See individual attribute/method documentation below for details.

Note

Unlike similar classes such as invoke.runners.Result or fabric.runners.Result (which have a concept of “warn and return anyways on failure”) this class has no useful truthiness behavior. If a file transfer fails, some exception will be raised, either an OSError or an error from within Paramiko.

New in version 2.0.

__weakref__

list of weak references to the object (if defined)

class fabric.transfer.Transfer(connection)

Connection-wrapping class responsible for managing file upload/download.

New in version 2.0.

__weakref__

list of weak references to the object (if defined)

get(remote, local=None, preserve_mode=True)

Download a file from the current connection to the local filesystem.

Parameters:
  • remote (str) –

    Remote file to download.

    May be absolute, or relative to the remote working directory.

    Note

    Most SFTP servers set the remote working directory to the connecting user’s home directory, and (unlike most shells) do not expand tildes (~).

    For example, instead of saying get("~/tmp/archive.tgz"), say get("tmp/archive.tgz").

  • local –

    Local path to store downloaded file in, or a file-like object.

    If None or another ‘falsey’/empty value is given (the default), the remote file is downloaded to the current working directory (as seen by os.getcwd) using its remote filename.

    If a string is given, it should be a path to a local directory or file and is subject to similar behavior as that seen by common Unix utilities or OpenSSH’s sftp or scp tools.

    For example, if the local path is a directory, the remote path’s base filename will be added onto it (so get('foo/bar/file.txt', '/tmp/') would result in creation or overwriting of /tmp/file.txt).

    Note

    When dealing with nonexistent file paths, normal Python file handling concerns come into play - for example, a local path containing non-leaf directories which do not exist, will typically result in an OSError.

    If a file-like object is given, the contents of the remote file are simply written into it.

  • preserve_mode (bool) – Whether to os.chmod the local file so it matches the remote file’s mode (default: True).
Returns:

A Result object.

New in version 2.0.

put(local, remote=None, preserve_mode=True)

Upload a file from the local filesystem to the current connection.

Parameters:
  • local –

    Local path of file to upload, or a file-like object.

    If a string is given, it should be a path to a local (regular) file (not a directory).

    Note

    When dealing with nonexistent file paths, normal Python file handling concerns come into play - for example, trying to upload a nonexistent local path will typically result in an OSError.

    If a file-like object is given, its contents are written to the remote file path.

  • remote (str) –

    Remote path to which the local file will be written.

    Note

    Most SFTP servers set the remote working directory to the connecting user’s home directory, and (unlike most shells) do not expand tildes (~).

    For example, instead of saying put("archive.tgz", "~/tmp/"), say put("archive.tgz", "tmp/").

    In addition, this means that ‘falsey’/empty values (such as the default value, None) are allowed and result in uploading to the remote home directory.

    Note

    When local is a file-like object, remote is required and must refer to a valid file path (not a directory).

  • preserve_mode (bool) – Whether to chmod the remote file so it matches the local file’s mode (default: True).
Returns:

A Result object.

New in version 2.0.