Skip to main content

Pretty secure file transfer made easy.

Project description

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

  • Transfer Resumption

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

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.1 (current, released 2023-08-28)

  • added initial support for resuming existing transfers get() & put()

  • added max_concurrent_prefetch_requests parameter to get() family

  • added prefetch parameter to get() family

1.1.0 (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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sftpretty-1.1.1.tar.gz (45.5 kB view hashes)

Uploaded Source

Built Distribution

sftpretty-1.1.1-py3-none-any.whl (19.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page