transfer
¶
File transfer via SFTP and/or SCP.
- class fabric.transfer.Transfer(connection)¶
Connection
-wrapping class responsible for managing file upload/download.New in version 2.0.
- get(remote, local=None, preserve_mode=True)¶
Copy a file from wrapped connection’s host 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")
, sayget("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. (This is equivalent to giving"{basename}"
; see the below subsection on interpolation.)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
orscp
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
).This path will be interpolated with some useful parameters, using
str.format
:The
Connection
object’shost
,user
andport
attributes.The
basename
anddirname
of theremote
path, as derived byos.path
(specifically, itsposixpath
flavor, so that the resulting values are useful on remote POSIX-compatible SFTP servers even if the local client is Windows).Thus, for example,
"/some/path/{user}@{host}/{basename}"
will yield different local paths depending on the properties of both the connection and the remote path.
Note
If nonexistent directories are present in this path (including the final path component, if it ends in
os.sep
) they will be created automatically usingos.makedirs
.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.
Changed in version 2.6: Added
local
path interpolation of connection & remote file attributes.Changed in version 2.6: Create missing
local
directories automatically.
- 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 anOSError
.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/")
, sayput("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.
- __weakref__¶
list of weak references to the object (if defined)
- 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
orfabric.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 anOSError
or an error from within Paramiko.New in version 2.0.
- local¶
The local path the file was saved as, or the object it was saved into if a file-like object was given instead.
If a string path, this value is massaged to be absolute; see
orig_local
for the original argument value.
- orig_local¶
The original value given as the returning method’s
local
argument.
- remote¶
The remote path downloaded from. Massaged to be absolute; see
orig_remote
for the original argument value.
- orig_remote¶
The original argument value given as the returning method’s
remote
argument.
- connection¶
The
Connection
object this result was obtained from.
- __weakref__¶
list of weak references to the object (if defined)