cheesefactory-sftp

A beautiful SFTP wrapper for Paramiko.

Note

This is a major rewrite, now based on Paramiko. The focus has been on basic GET and PUT. As such, some features are not yet finished and this README is woefully inadequate, but things will soon be better than ever.

If I did something bad for you in with this update, I'm sorry. Please import cheesefactory-sftp==0.33

Main Features

Note: This package is still in beta status. As such, future versions may not be backwards compatible and features may change. Parts of it may even be broken.

• Built using paramiko.

Coming Soon

TBA

Connect to the remote SFTP server

from cheesefactory-sftp import CfSftp

sftp = CfSftp.connect(
    host='mysftp.example.com',
    port='22',
    username='testuser',
    password='testpass',
)

Get or Put a file

transfer_log = sftp.get(
    remote_path='/remote_dir/remote_file.txt',
    local_path='/local_dir/local_file.txt', 
    preserve_mtime=False,
    remove_source=False
)

...

transfer_log = sftp.put(
    remote_path='/remote_dir/remote_file.txt',
    local_path='/local_dir/local_file.txt', 
    preserve_mtime=False,
    remove_source=False
)

Get or Put multiple files

transfer_log = sftp.get_by_list(
    log_checksum=False,
    preserve_mtime=True, 
    file_list=[
        {'src:': '/remote_dir_a/file1.txt', 'dst': '/local_dir/file_a.txt'},
        {'src:': '/remote_dir_a/file2.txt', 'dst': '/local_dir/file_b.txt'},
        {'src:': '/remote_dir_b/file1.txt', 'dst': '/local_dir/file_c.txt'},
    ],
    remove_source=False
)

...

transfer_log = sftp.put_by_list(
    log_checksum=False,
    preserve_mtime=True, 
    file_list=[
        {'src:': '/remote_dir_a/file1.txt', 'dst': '/local_dir/file_a.txt'},
        {'src:': '/remote_dir_a/file2.txt', 'dst': '/local_dir/file_b.txt'},
        {'src:': '/remote_dir_b/file1.txt', 'dst': '/local_dir/file_c.txt'},
    ],
    remove_source=False
)

Other methods

close()

Close the SFTP connection.

sftp = CfSftp.connect(...)
sftp.close()

status()

Retrieve connection status.

sftp = SFTP.connect(...)
status, message = sftp.status()

Returns:

1. True (connected) or False (not connected), and
2. 'Transport open and authenticated', 'Transport open. Not authenticated', or 'Transport closed, Not authenticated'

File and Directory Methods

chdir()

Change current remote directory.

sftp = SFTP.connect(...)
sftp.chdir('/tmp/downloads')

Args:
 path (str): New remote directory.

chmod()

Change the permissions of a remote file.

sftp = SFTP.connect(...)
sftp.chmod(path='/tmp/myfile', mode=644)

Args:
 path (str): Remote file path.
 mode (int): Unix-style permission (e.g. 0644)

chown()

Change the owner and group of a remote file.

sftp = SFTP.connect(...)
sftp.chown(path='/tmp/myfile', uid=1003, gid=1003)

Args:
 path (str): Remote file path.
 uid (int): New user ID.
 gid (int): New group ID.

cwd()

Return the current remote directory.

sftp = SFTP.connect(...)
sftp.cwd()

Returns:
 (str) Current remote working directory.

exists()

Does a remote file or directory exist?

sftp = SFTP.connect(...)
sftp.exists('/tmp/myfile')

Args:
 path (str): File or directory to test.

Returns:
 (int) True if file or directory exists. False if it does not.

is_dir()

Is the current remote path a directory?

sftp = SFTP.connect(...)
sftp.is_dir()

Args:
 path (str): The path to test.

Returns:
 (bool) True if it is, False if it ain't.

is_file()

Is the current remote path a file?

sftp = SFTP.connect(...)
sftp.is_file()

Args:
 path (str): The path to test.

Returns:
 (bool) True if it is, False if it is not.

list_dir()

Return a list of remote directory contents (without . and ..).

sftp = SFTP.connect(...)
sftp.list_dir()

Args:
 path (str): Remote path.
 recursive (bool): Include contents of sub-directories in output?

Returns:
 (list) A list of directory contents.

mkdir()

Create a remote directory.

sftp = SFTP.connect(...)
sftp.mkdir()

Args:
 path (str): Name of the folder to create.
 mode (int): Posix-style permissions for the folder. Given in octal (without preceding 0)

remove()

Delete a remote file or directory.

sftp = SFTP.connect(...)
sftp.remove()

Args:
 path (str): Relative or absolute path of file or directory to delete.

Raises:
 IOError: if path is neither directory nor file.

remove_dir()

Delete a remote directory.

sftp = SFTP.connect(...)
sftp.remove_dir()

Args:
 path (str): Relative or absolute path of directory to delete.

remove_file()

Delete a remote file.

sftp = SFTP.connect(...)
sftp.remove_file()

Args:
 path (str): Relative or absolute path of file to delete.

rename()

Rename a remote flie or folder.

sftp = SFTP.connect(...)
sftp.rename()

Args:
 old_path (str): Existing name of file or directory.  new_path (str): New name for the file or directory. Must not already exist.

stat()

Retrieve information about a remote file. Mimics Python's os.stat structure.

Supported fields: st_mode, st_size, st_uid, st_gid, st_atime, and st_mtime.

sftp = SFTP.connect(...)
sftp.stat()

Args:
 path (str): The filename to stat.

Returns:
 (paramiko.SFTPAttributes()) Attributes about the given file.

Log

Metrics concerning the status and performance of CfSftp are available via the log attribute.

sftp = CfSftp.connect(
    host='mysftp.example.com',
    port='22',
    username='testuser',
    password='testpass',
)

>>> sftp.log
{'sftp_host': 'mysftp.example.com', 'sftp_password': 'testpass', 'sftp_port': '22', 'sftp_username': 'testuser'}

Log keys

The following log keys are available:

• connection_ok: bool (Was the SFTP connection established successfully?)
• connection_note: str (Connection problem details)
• host: str
• last_utility_note
• password: str
• port: str
• transfers: List (Details for each transfer during the SFTP session.)
  • action: 'GET' or 'PUT'
  • action_ok: bool
  • client: str
  • local_path: str
  • note: str
  • preserve_mtime: bool
  • preserve_mtime_ok: bool
  • remote_path: str
  • remove_source: bool
  • remove_source_ok: bool
  • size: int
  • size_match: bool
  • size_match_ok: bool
  • status: 'OK', 'ERROR'
• user: str