pysftp

A friendly Python SFTP interface.

class pysftp.Connection(host, username=None, private_key=None, password=None, port=22, private_key_pass=None, ciphers=None, log=False)

Connects and logs into the specified hostname. Arguments that are not given are guessed from the environment.

Parameters:
  • host (str) – The Hostname or IP of the remote machine.
  • username (str) – Your username at the remote machine.
  • private_key – path to private key file(str) or paramiko.AgentKey
  • password (str) – Your password at the remote machine.
  • port (int) – The SSH port of the remote machine.(default: 22)
  • private_key_pass (str) – password to use, if private_key is encrypted.
  • ciphers (list) – List of ciphers to use in order.
  • log (bool|str) – log connection/handshake details? (default=False) if set to True, pysftp creates a temporary file and logs to that. If set to a valid path and filename, pysftp logs to that. The name of the logfile can be found at .logfile
Returns:

a connection to the requested host

Raises:

ConnectionException, CredentialException, SSHException, AuthenticationException, PasswordRequiredException

active_ciphers

Get tuple of currently used local and remote ciphers.

Returns:a tuple of currently used ciphers (local_cipher, remote_cipher)
chdir(remotepath)

change the current working directory on the remote

Parameters:remotepath (str) – the remote path to change to
Returns:nothing
Raises:IOError
chmod(remotepath, mode=777)

set the mode of a remotepath to mode, where mode is an integer representation of the octal mode to use.

Parameters:
  • remotepath (str) – the remote path/file to modify
  • mode (int) – int representation of octal mode for directory, default 777
Returns:

None

Raises:

IOError if the file doesn’t exist

chown(remotepath, uid=None, gid=None)

set uid and/or gid on a remotepath, you may specify either or both. Unless you have permission to do this on the remote server, you will raise an IOError: 13 - permission denied

Parameters:
  • remotepath (str) – the remote path/file to modify
  • uid (int) – the user id to set on the remotepath
  • gid (int) – the group id to set on the remotepath
Returns None:
Raises IOError:

if you don’t have permission or the file doesn’t exist

close()

Closes the connection and cleans up.

execute(command)

Execute the given commands on a remote machine. The command is executed without regard to the remote cwd.

Parameters:command (str) – the command to execute.
Returns:results
Raises:Any exception raised by command will be passed through.
exists(remotepath)

Test whether a remotepath exists.

Parameters:remotepath (str) – the remote path to verify
Returns bool:True if remotepath exists, else False
get(remotepath, localpath=None, callback=None, preserve_mtime=False)

Copies a file between the remote host and the local host.

Parameters:
  • remotepath (str) – the remote path and filename, source
  • localpath (str) – the local path and filename to copy, destination. If not specified, file is copied to local cwd
  • callback (callable) – optional callback function (form: func(int, int)) that accepts the bytes transferred so far and the total bytes to be transferred.
  • preserve_mtime (bool) – Default: False - make the modification time(st_mtime) on the local file match the time on the remote. (st_atime can differ because stat’ing the localfile can/does update it’s st_atime)
Returns:

nothing

Raises:

IOError

getcwd()

return the current working directory on the remote

Returns:a string representing the current remote path
getfo(remotepath, flo, callback=None)

Copy a remote file (remotepath) to a file-like object, flo.

Parameters:
  • remotepath (str) – the remote path and filename, source
  • flo – open file like object to write, destination.
  • callback (callable) – optional callback function (form: func(int, int)) that accepts the bytes transferred so far and the total bytes to be transferred.
Returns int:

the number of bytes written to the opened file object

Raises:

Any exception raised by operations will be passed through.

isdir(remotepath)

return true if remotepath is a directory

Parameters:remotepath (str) – the path to test
Returns bool:
isfile(remotepath)

return true if remotepath is a file

Parameters:remotepath (str) – the path to test
Returns bool:
lexists(remotepath)

Test whether a remotepath exists. Returns True for broken symbolic links

Parameters:remotepath (str) – the remote path to verify
Returns bool:True if lexists, else False
listdir(remotepath='.')

return a list of files/directories for the given remote path

Parameters:remotepath (str) – path to list on the server
Returns:a list of entries
logfile

return the name of the file used for logging or False it not logging

Returns:logfile(str) or False(bool)
lstat(remotepath)

return information about file/directory for the given remote path, without following symbolic links. Otherwise, the same as .stat()

Parameters:remotepath (str) – path to stat
Returns:SFTPAttributes object
makedirs(remotedir, mode=777)

create all directories in remotedir as needed, setting their mode to mode, if created.

If remotedir already exists, silently complete. If a regular file is in the way, raise an exception.

Parameters:
  • remotedir (str) – the direcotry structure to create
  • mode (int) – int representation of octal mode for directory, default 777
Returns:

None

Raises:

OSError

mkdir(remotepath, mode=777)

Create a directory named remotepath with mode. On some systems, mode is ignored. Where it is used, the current umask value is first masked out.

Parameters:
  • remotepath (str) – directory to create`
  • mode (int) – int representation of octal mode for directory, default 777
Returns:

nothing

open(remote_file, mode='r', bufsize=-1)

Open a file on the remote server.

See http://paramiko-docs.readthedocs.org/en/latest/api/sftp.html?highlight=open#paramiko.sftp_client.SFTPClient.open for details.

Parameters:
  • remote_file (str) – name of the file to open.
  • mode (str) – mode (Python-style) to open file (always assumed binary)
  • bufsize (int) – desired buffering (-1 = default buffer size)
Returns:

an SFTPFile object representing the open file

Raises:

IOError - if the file could not be opened.

put(localpath, remotepath=None, callback=None, confirm=True, preserve_mtime=False)

Copies a file between the local host and the remote host.

Parameters:
  • localpath (str) – the local path and filename
  • remotepath (str) – the remote path, else the remote cwd() and filename is used.
  • callback (callable) – optional callback function (form: func(int, int)) that accepts the bytes transferred so far and the total bytes to be transferred..
  • confirm (bool) – whether to do a stat() on the file afterwards to confirm the file size
  • preserve_mtime (bool) – Default: False - make the modification time(st_mtime) on the remote file match the time on the local. (st_atime can differ because stat’ing the localfile can/does update it’s st_atime)
Returns:

SFTPAttributes object containing attributes about the given file

Raises:

IOError, OSError

putfo(flo, remotepath=None, file_size=0, callback=None, confirm=True)

Copies the contents of a file like object to remotepath.

Parameters:
  • flo – a file-like object that supports .read()
  • remotepath (str) – the remote path.
  • file_size (int) – the size of flo, if not given the second param passed to the callback function will always be 0.
  • callback (callable) – optional callback function (form: func(int, int)) that accepts the bytes transferred so far and the total bytes to be transferred..
  • confirm (bool) – whether to do a stat() on the file afterwards to confirm the file size
Returns:

SFTPAttributes object containing attributes about the given file

Raises:

TypeError if remotepath not specified, any underlying error

remove(remotefile)

remove the file @ remotefile, remotefile may include a path, if no path, then cwd is used. This method only works on files

Parameters:remotefile (str) – the remote file to delete
Returns:nothing
Raises:IOError
rename(remote_src, remote_dest)

rename a file or directory on the remote host.

Parameters:
  • remote_src (str) – the remote file/directory to rename
  • remote_dest (str) – the remote file/directory to put it
Returns:

nothing

Raises:

IOError

rmdir(remotepath)

remove remote directory

Parameters:remotepath (str) – the remote directory to remove
Returns:nothing
security_options

return the available security options recognized by paramiko.

Returns SecurityOptions:
 a simple object security preferences of an ssh transport. These are tuples of acceptable ciphers, digests, key types, and key exchange algorithms, listed in order of preference.
sftp_client

give access to the underlying, connected paramiko SFTPClient object

see http://paramiko-docs.readthedocs.org/en/latest/api/sftp.html?highlight=sftpclient

Params:None
Returns:the active SFTPClient object
stat(remotepath)

return information about file/directory for the given remote path

Parameters:remotepath (str) – path to stat
Returns:SFTPAttributes object

create a symlink for a remote file on the server

Parameters:
  • remote_src (str) – path of original file
  • remote_dest (str) – path of the created symlink
Returns:

None

Raises:

any underlying error, IOError if something already exists at remote_dest

exception pysftp.ConnectionException(host, port)

Exception raised for connection problems

Attributes:
message – explanation of the error
exception pysftp.CredentialException(message)

Exception raised for credential problems

Attributes:
message – explanation of the error
pysftp.path_advance(thepath, sep='/')

generator to iterate over a file path forwards

Parameters:
  • thepath (str) – the path to navigate forwards
  • sep (str) – the path separator to use, defaults to os.sep
Returns generator:
 

of strings

pysftp.path_retreat(thepath, sep='/')

generator to iterate over a file path in reverse

Parameters:
  • thepath (str) – the path to retreat over
  • sep (str) – the path separator to use, default to os.sep
Returns generator:
 

of strings

pysftp.st_mode_to_int(val)

SFTAttributes st_mode returns an stat type that shows more than what can be set. Trim off those bits and convert to an int representation. if you want an object that was chmod 711 to return a value of 711, use this function

Parameters:val (int) – the value of an st_mode attr returned by SFTPAttributes
Returns int:integer representation of octal mode

Callbacks

callback function (form: func(int, int)) where the first int is the bytes transferred so far and the second int is the total bytes to be transferred.

Note: On a .putfo, if you don’t set the file_size parameter, it will always be passed a zero, the default file_size value.

SecurityOptions

a simple object returned with available Security Options

see http://paramiko-docs.readthedocs.org/en/latest/api/transport.html?highlight=ciphers#paramiko.transport.SecurityOptions for details