cheesefactory-sftp 0.37

A (soon to be) beautiful SFTP wrapper for Paramiko.

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',
)

Argument	Type	Default	Description
host	str	127.0.0.1	Remote server.
port	str	'22'	SFTP TCP port.
user	str		SFTP username
password	str		SFTP password
key_path	str		Path to private key file.
key_password		str	Password for encrypted private key.

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
)

Argument	Type	Default	Description
local_path	str		Local/destination path and filename.
log_checksum	bool	False	Calculate file SHA256 checksum and log resulting value.
preserve_mtime	boole	False	Keep modification time of source file.
remote_path	str		Remote/source path and filename.
remove_source	bool	False	Remove the remote source file.

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
)

Argument	Type	Default	Description
log_checksum	bool	False	Calculate file SHA256 checksum and log resulting value.
preserve_mtime	bool	True	Keep modification time of source file.
file_list	List[dict]		List of dictionaries in the format [{'src': '', 'dst': ''}, ...]
remove_source	bool	False	Remove the remote source file.

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

Method	Description
chdir()	Change current remote directory.
chmod()	Change the permissions of a remote file.
chown()	Change the owner and group of a remote file.
cwd()	Return the current remote directory.
delete()	Alias for remove_file(). DEPRECATED
exists()	Does a remote file or directory exist?
file_size_match()	Determine if the sizes of a remote and a local file match.
is_dir()	Is the current remote path a directory?
is_file()	Is the current remote path a file?
list_dir()	Return a list of remote directory contents (without . and ..).
list_files()	Return a list of remote directory contents (without . and ..). DEPRECATED
mkdir()	Create a remote directory.
remove()	Delete a remote file or directory.
remove_dir()	Delete a remote directory.
remove_file()	Delete a remote file.
rename()	Rename a remote flie or folder.
stat()	Retrieve information about a remote file. Mimics Python's os.stat structure.

---

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