sftpretty 1.1.0

Pretty secure file transfer made easy.

sftpretty

A pretty quick and simple interface to paramiko SFTP. Provides multi-threaded routines with progress notifications for reliable, asynchronous transfers. A Python3 optimized fork of pysftp with additional features & improvements.

• Built-in retry decorator

• Hash function for integrity checking

• Improved local & remote directory mapping

• Improved logging mechanism

• More tests

• Multi-threaded directory transfers

• OpenSSH config file support

• Progress notifications

• Support for ciphers, compression, digests, kex & key type options

• Support for disabled algorithms

• Support for ED25519 & ECDSA keys

• Support for private key passwords

• Thread-safe connection manager

Example

from sftpretty import CnOpts, Connection


# Basic

with Connection('hostname', username='me', password='secret') as sftp:
    # Temporarily chdir to public/.
    with sftp.cd('public'):
        # Upload file to public/ on remote.
        sftp.put('/my/local/filename')
        # Download a remote file from public/.
        sftp.get('remote_file')


with Connection('hostname', private_key='~/.ssh/id_ed25519',
                private_key_pass='secret') as sftp:
    # Upload local directory to remote_directory.
    sftp.put_d('/my/local', '/remote_directory')

    # Recursively download a remote_directory and save it to /tmp locally.
    sftp.get_r('remote_directory', '/tmp')


# Advanced

# Use password authentication
with Connection('hostname', username='me', password='secret') as sftp:
    # Upload local directory to remote_directory. On occurance of any
    # exception or child of, passed in the tuple, retry the operation.
    # Between each attempt increment a pause equal to backoff * delay.
    # Run a total of tries (six) times including the first attempt.
    sftp.put_d('/my/local', '/remote_directory', backoff=2, delay=1,
               exceptions=(NoValidConnectionsError, socket.timeout,
                           SSHException), tries=6)


# Use public key authentication with optional private key password
with Connection('hostname', private_key='~/.ssh/id_ed25519',
                private_key_pass='secret') as sftp:
    # Recursively download a remote_directory and save it to /tmp locally.
    # Don't confirm files, useful in a scenario where the server removes
    # the remote file immediately after download. Preserve remote mtime on
    # local copy.
    sftp.get_r('remote_directory', '/tmp', confirm=False,
               preserve_mtime=True)


# Use OpenSSH format config for public key authentication. Configuration
# connection values are prioritized when available. Credentials still need
# to be provided. There may be a significant delta between your ssh program
# and support for newer security option algorithms due to lagging support
# in paramiko.
cnopts = CnOpts(config='~/.ssh/config', knownhosts='server.pub')
with Connection('alias', cnopts=cnopts, private_key_pass='secret') as sftp:
    # Rename existing file on remote server
    sftp.rename('/remote/old_name', '/remote/new_name')


# Pass custom host key file for verification
cnopts = CnOpts(knownhosts='sftpserver.pub')
# Use connection options to set preferred encryption standards
cnopts.ciphers= ('aes256-ctr', 'aes128-ctr')
cnopts.digests = ('hmac-sha2-512', 'hmac-sha2-256')
cnopts.kex = ('ecdh-sha2-nistp521', 'ecdh-sha2-nistp384')
cnopts.key_types = ('ssh-ed25519', 'ecdsa-sha2-nistp521')
# Turn on verbose logging and set custom log file
cnopts.log = '/var/log/backups/daily.log'
cnopts.log_level = 'debug'
# Pass options object directly to connection object
with Connection('hostname', cnopts=cnopts, private_key='~/.ssh/id_backup',
                private_key_pass='secret') as sftp:
    # Aggressively retry important operation
    sftp.put_r('/local_backup', '/remote_backup', backoff=2, delay=1,
               exceptions=socket.timeout, preserve_mtime=True, tries=11)

Additional Information

• Project: https://github.com/byteskeptical/sftpretty

• Download: https://pypi.python.org/pypi/sftpretty

• Documentation: https://docs.sftpretty.com

• License: BSD

Requirements

paramiko >= 1.17.0

Supports

Tested on Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11

Change Log

1.1.0 (current, released 2023-08-15)

• added initial support for OpenSSH config-file support to CnOpts

1.0.9 (released 2023-05-08)

• added drivedrop to bypass _adjust_cwd’s lack of Windows drive support

• added file_size logic and default remotepath fallback to putfo

• moved Connection.compress to CnOpts.compress

• regression in put_d again

• removed SKIP_IF_CI from all but one test in response to the above

• switched to public key auth for all tests !¿macOS?¡

• switched from get_fingerprint() using md5 to helpers.hash using sha3_256

• test clean-up and major refactor

1.0.7 (released 2023-02-27)

• fix regression in put_d

1.0.6 (released 2023-01-15)

• allow CnOpts knownhost to be set to None directly

• standardize on using is for None checks

1.0.5 (released 2022-11-29)

• added log_level to connection options

• added compression security option for Transport

• code optimizations in _start_transport() and _set_authentication()

• moved compression on/off switch to Connection object

• sprinkled debug messaging throughout

• switched to using native logging module instead of paramiko util

1.0.4 (released 2022-09-24)

• added Windows Pure Path logic in put_d() and put_r() through localtree()

• fix for regression in _sftp_channel() causing UnboundLocalError

• improved support for dot notation in known_hosts and private key file

• removed basicConfig() call for improved embedded behavior

1.0.3 (released 2022-09-13)

• added disabled algorithms option for Transport

1.0.2 (released 2022-09-09)

• added sort to localtree() for test continuity

• bug fix for typo in put_d()

1.0.1 (released 2022-07-22)

• added key types security option for Transport

• bug fixes for close()

• default to private key authentication

• enabled timeout setting for channel and transport

• improved host key logging

• localtree & remotetree functions Windows compatible

• started hosting on PyPi

• updated tests and CI pipeline

1.0.0 (released 2021-06-06)

• added ECDSA and ED25519 key support for authentication

• added digest and kex security options for Transport

• added tests for additional functionality

• default callback function for progress notifications

• hash function added to helpers for file verification option

• improved local and remote directory mapping

• improved logging capabilities

• replaced _sftp_connect with context aware channel manager

• retry decorator for automated recovery from failure

• switched to using pathlib for all local filepath operations

• updated documentation and README with advanced examples