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
-------
.. code-block:: python
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 Connection('hostname', private_key='~/.ssh/id_ed25519') as sftp:
# Resume the download of a bigfile and save it to /mnt locally.
sftp.get('bigfile', '/mnt', preserve_mtime=True, resume=True)
# 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. Limit the thread pool connections to the server.
sftp.get_r('remote_directory', '/tmp', confirm=False,
preserve_mtime=True, workers=6)
# 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.3 (current, released 2023-12-11)
------------------------------------
* adding merge between ssh security options and paramiko compatibility
* changing default logger behavior from hooking into __main__
1.1.2 (released 2023-10-24)
---------------------------
* added support for setting max_workers on ThreadPool functions
1.1.1 (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
Raw data
{
"_id": null,
"home_page": "https://github.com/byteskeptical/sftpretty",
"name": "sftpretty",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "ftp scp sftp ssh",
"author": "byteskeptical",
"author_email": "40208858+byteskeptical@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/f9/51/671c80a4c0d59709e9b9fc9e1df519133848f4790d644e2e2558f02fa5a6/sftpretty-1.1.3.tar.gz",
"platform": "any",
"description": "sftpretty\n=========\n\nA pretty quick and simple interface to paramiko SFTP. Provides multi-threaded\nroutines with progress notifications for reliable, asynchronous transfers. A\nPython3 optimized fork of pysftp with additional features & improvements.\n\n* Built-in retry decorator\n* Hash function for integrity checking\n* Improved local & remote directory mapping\n* Improved logging mechanism\n* More tests\n* Multi-threaded directory transfers\n* OpenSSH config file support\n* Progress notifications\n* Support for ciphers, compression, digests, kex & key type options\n* Support for disabled algorithms\n* Support for ED25519 & ECDSA keys\n* Support for private key passwords\n* Thread-safe connection manager\n* Transfer Resumption\n\n\nExample\n-------\n.. code-block:: python\n\n from sftpretty import CnOpts, Connection\n\n\n # Basic\n\n with Connection('hostname', username='me', password='secret') as sftp:\n # Temporarily chdir to public/.\n with sftp.cd('public'):\n # Upload file to public/ on remote.\n sftp.put('/my/local/filename')\n # Download a remote file from public/.\n sftp.get('remote_file')\n\n\n with Connection('hostname', private_key='~/.ssh/id_ed25519',\n private_key_pass='secret') as sftp:\n # Upload local directory to remote_directory.\n sftp.put_d('/my/local', '/remote_directory')\n\n # Recursively download a remote_directory and save it to /tmp locally.\n sftp.get_r('remote_directory', '/tmp')\n\n\n # Advanced\n\n # Use password authentication\n with Connection('hostname', username='me', password='secret') as sftp:\n # Upload local directory to remote_directory. On occurance of any\n # exception or child of, passed in the tuple, retry the operation.\n # Between each attempt increment a pause equal to backoff * delay.\n # Run a total of tries (six) times including the first attempt.\n sftp.put_d('/my/local', '/remote_directory', backoff=2, delay=1,\n exceptions=(NoValidConnectionsError, socket.timeout,\n SSHException), tries=6)\n\n\n # Use public key authentication\n with Connection('hostname', private_key='~/.ssh/id_ed25519') as sftp:\n # Resume the download of a bigfile and save it to /mnt locally.\n sftp.get('bigfile', '/mnt', preserve_mtime=True, resume=True)\n\n\n # Use public key authentication with optional private key password\n with Connection('hostname', private_key='~/.ssh/id_ed25519',\n private_key_pass='secret') as sftp:\n # Recursively download a remote_directory and save it to /tmp locally.\n # Don't confirm files, useful in a scenario where the server removes\n # the remote file immediately after download. Preserve remote mtime on\n # local copy. Limit the thread pool connections to the server.\n sftp.get_r('remote_directory', '/tmp', confirm=False,\n preserve_mtime=True, workers=6)\n\n\n # Use OpenSSH format config for public key authentication. Configuration\n # connection values are prioritized when available. Credentials still need\n # to be provided. There may be a significant delta between your ssh program\n # and support for newer security option algorithms due to lagging support\n # in paramiko.\n cnopts = CnOpts(config='~/.ssh/config', knownhosts='server.pub')\n with Connection('alias', cnopts=cnopts, private_key_pass='secret') as sftp:\n # Rename existing file on remote server\n sftp.rename('/remote/old_name', '/remote/new_name')\n\n\n # Pass custom host key file for verification \n cnopts = CnOpts(knownhosts='sftpserver.pub')\n # Use connection options to set preferred encryption standards\n cnopts.ciphers= ('aes256-ctr', 'aes128-ctr')\n cnopts.digests = ('hmac-sha2-512', 'hmac-sha2-256')\n cnopts.kex = ('ecdh-sha2-nistp521', 'ecdh-sha2-nistp384')\n cnopts.key_types = ('ssh-ed25519', 'ecdsa-sha2-nistp521')\n # Turn on verbose logging and set custom log file\n cnopts.log = '/var/log/backups/daily.log'\n cnopts.log_level = 'debug'\n # Pass options object directly to connection object\n with Connection('hostname', cnopts=cnopts, private_key='~/.ssh/id_backup',\n private_key_pass='secret') as sftp:\n # Aggressively retry important operation\n sftp.put_r('/local_backup', '/remote_backup', backoff=2, delay=1,\n exceptions=socket.timeout, preserve_mtime=True, tries=11)\n\n\nAdditional Information\n----------------------\n* Project: https://github.com/byteskeptical/sftpretty\n* Download: https://pypi.python.org/pypi/sftpretty\n* Documentation: https://docs.sftpretty.com\n* License: BSD\n\nRequirements\n------------\nparamiko >= 1.17.0\n\nSupports\n--------\nTested on Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11\n\n\nChange Log\n==========\n\n1.1.3 (current, released 2023-12-11)\n------------------------------------\n * adding merge between ssh security options and paramiko compatibility\n * changing default logger behavior from hooking into __main__\n\n1.1.2 (released 2023-10-24)\n---------------------------\n * added support for setting max_workers on ThreadPool functions\n\n1.1.1 (released 2023-08-28)\n---------------------------\n * added initial support for resuming existing transfers get() & put()\n * added max_concurrent_prefetch_requests parameter to get() family\n * added prefetch parameter to get() family\n\n1.1.0 (released 2023-08-15)\n---------------------------\n * added initial support for OpenSSH config-file support to CnOpts\n\n1.0.9 (released 2023-05-08)\n---------------------------\n * added drivedrop to bypass _adjust_cwd's lack of Windows drive support\n * added file_size logic and default remotepath fallback to putfo\n * moved Connection.compress to CnOpts.compress\n * regression in put_d *again*\n * removed SKIP_IF_CI from all but one test in response to the above\n * switched to public key auth for all tests !\u00bfmacOS?\u00a1\n * switched from get_fingerprint() using md5 to helpers.hash using sha3_256\n * test clean-up and major refactor\n\n1.0.7 (released 2023-02-27)\n------------------------------------\n * fix regression in put_d\n\n1.0.6 (released 2023-01-15)\n------------------------------------\n * allow CnOpts knownhost to be set to None directly\n * standardize on using is for None checks \n\n1.0.5 (released 2022-11-29)\n------------------------------------\n * added log_level to connection options\n * added compression security option for Transport\n * code optimizations in _start_transport() and _set_authentication()\n * moved compression on/off switch to Connection object\n * sprinkled debug messaging throughout\n * switched to using native logging module instead of paramiko util\n\n1.0.4 (released 2022-09-24)\n------------------------------------\n * added Windows Pure Path logic in put_d() and put_r() through localtree()\n * fix for regression in _sftp_channel() causing UnboundLocalError\n * improved support for dot notation in known_hosts and private key file\n * removed basicConfig() call for improved embedded behavior\n\n1.0.3 (released 2022-09-13)\n---------------------------\n * added disabled algorithms option for Transport\n\n1.0.2 (released 2022-09-09)\n---------------------------\n * added sort to localtree() for test continuity\n * bug fix for typo in put_d()\n\n1.0.1 (released 2022-07-22)\n---------------------------\n * added key types security option for Transport\n * bug fixes for close()\n * default to private key authentication\n * enabled timeout setting for channel and transport\n * improved host key logging\n * localtree & remotetree functions Windows compatible\n * started hosting on PyPi\n * updated tests and CI pipeline \n\n1.0.0 (released 2021-06-06)\n---------------------------\n * added ECDSA and ED25519 key support for authentication\n * added digest and kex security options for Transport\n * added tests for additional functionality\n * default callback function for progress notifications\n * hash function added to helpers for file verification option\n * improved local and remote directory mapping\n * improved logging capabilities\n * replaced _sftp_connect with context aware channel manager\n * retry decorator for automated recovery from failure\n * switched to using pathlib for all local filepath operations\n * updated documentation and README with advanced examples\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Pretty secure file transfer made easy.",
"version": "1.1.3",
"project_urls": {
"Download": "https://pypi.python.org/pypi/sftpretty",
"Homepage": "https://github.com/byteskeptical/sftpretty"
},
"split_keywords": [
"ftp",
"scp",
"sftp",
"ssh"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "51c58ef4d5ce278943970c85f9b9cfd840fab941ac4378bc0d557a84471644c0",
"md5": "d408173c6c8623ee2d07272a1d2ff7d5",
"sha256": "446ebdade5b29181fbcc02e78de851c906b6024525a9fd00bebc2f97eac6a173"
},
"downloads": -1,
"filename": "sftpretty-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d408173c6c8623ee2d07272a1d2ff7d5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20046,
"upload_time": "2023-12-11T06:17:12",
"upload_time_iso_8601": "2023-12-11T06:17:12.933359Z",
"url": "https://files.pythonhosted.org/packages/51/c5/8ef4d5ce278943970c85f9b9cfd840fab941ac4378bc0d557a84471644c0/sftpretty-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f951671c80a4c0d59709e9b9fc9e1df519133848f4790d644e2e2558f02fa5a6",
"md5": "8f9a09e7ad21c047cd316dc6f5b74189",
"sha256": "504dc7703873d9f905338403bd58b8a10514a4007871aab2fd87fc1c8d6de947"
},
"downloads": -1,
"filename": "sftpretty-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "8f9a09e7ad21c047cd316dc6f5b74189",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 46446,
"upload_time": "2023-12-11T06:17:14",
"upload_time_iso_8601": "2023-12-11T06:17:14.740248Z",
"url": "https://files.pythonhosted.org/packages/f9/51/671c80a4c0d59709e9b9fc9e1df519133848f4790d644e2e2558f02fa5a6/sftpretty-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-11 06:17:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "byteskeptical",
"github_project": "sftpretty",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sftpretty"
}
JSON
