Skip to content

Latest commit

 

History

History
167 lines (123 loc) · 6.35 KB

README.md

File metadata and controls

167 lines (123 loc) · 6.35 KB

sysrsync

All Contributors

Simple and safe native rsync wrapper for Python 3

Quality Gate Status

Requirements

  • rsync
  • python 3.6+

development:

  • poetry (be sure to have both poetry and pip upgraded to the latest version)

Installation

pip install sysrsync

Basic rules

  • Syncs source contents by default, so it adds a trailing slash to the end of source, unless sync_source_contents=False is specified
  • Removes trailing slash from destination
  • Extra arguments are put right after rsync
  • Breaks if source_ssh and destination_ssh are both set

Usage

  • Basic file sync
import sysrsync

sysrsync.run(source='/home/user/foo.txt',
             destination='/home/server/bar')
# runs 'rsync /home/users/foo.txt /home/server/files'
  • sync whole folder
import sysrsync

sysrsync.run(source='/home/user/files',
             destination='/home/server/',
             sync_source_contents=False)
# runs 'rsync /home/user/files /home/server'
  • sync folder contents
import sysrsync

sysrsync.run(source='/home/user/files',
             destination='/home/server/',
             sync_source_contents=True)
# runs 'rsync /home/user/files/ /home/server'
  • ssh with options
import sysrsync

sysrsync.run(source='/home/user/files',
             destination='/home/server/files',
             destination_ssh='myserver',
             options=['-a'])
# runs 'rsync -a /home/users/files/ myserver:/home/server/files'
  • exclusions
import sysrsync

sysrsync.run(source='/home/user/files',
             destination='/home/server/files',
             destination_ssh='myserver',
             options=['-a'],
             exclusions=['file_to_exclude', 'unwanted_file'])
# runs 'rsync -a /home/user/files/ myserver:/home/server/files --exclude file_to_exclude --exclude unwanted_file'
  • Private key
import sysrsync

sysrsync.run(source='/home/user/files',
             destination='/home/server/files',
             destination_ssh='myserver',
             private_key="totally_secure_key")
# runs 'rsync --rsh='ssh -i totally_secure_key' /home/user/files/ myserver:/home/server/files'

API

sysrsync.run

argument type default description
cwd str os.getcwd() working directory in which subprocess will run the rsync command
strict bool True raises RsyncError when rsync return code is different than 0
verbose bool False verbose mode: currently prints rsync command before executing
**kwargs dict Not Applicable arguments that will be forwarded to call to sysrsync.get_rsync_command

returns: subprocess.CompletedProcess

raises:

  • RsyncError when strict = True and rsync return code is different than 0 (Success)

sysrsync.get_rsync_command

argument type default description
source str - Source folder or file
destination str - Destination folder
source_ssh Optional[str] None Remote ssh client where source is located
destination_ssh Optional[str] None Remote ssh client where destination is located
exclusions Optional[Iterable[str]] None List of excluded patterns as in rsync's --exclude
sync_source_contents bool True Abstracts the elusive trailing slash behaviour that source normally has when using rsync directly, i.e. when a trailing slash is present in source, the folder's content is synchronized with destination. When no trailing slash is present, the folder itself is synchronized with destination.
options Optional[Iterable[str]] None List of options to be used right after rsync call, e.g. ['-a', '-v'] translates to rsync -a -v
private_key Optional[str] None Configures an explicit key to be used with rsync --rsh command
rsh_port  Optional[int] None Specify port to be used for --rsh command
strict_host_key_checking Optional[bool] None set StrictHostKeyChecking property for rsh #cf. https://superuser.com/questions/125324/how-can-i-avoid-sshs-host-verification-for-known-hosts

returns: List[str] -> the compiled list of commands to be used directly in subprocess.run

raises:

  • RemotesError when both source_ssh and destination_ssh are set. Normally linux rsync distribution disallows source and destination to be both remotes.
  • PrivateKeyError when private_key doesn't exist

Contributing

  • Fork project
  • Install dependencies with poetry install
  • Make changes
  • Lint with poetry run pylint ./sysrsync
  • Test with poetry run python -m unittest
  • Run end-to-end tests with bash end-to-end-tests/run-tests.sh
  • Submit changes with a pull request

Contributors ✨

Thanks goes to these wonderful people (emoji key):

plazmakeks
plazmakeks

💻
Steve Henderson
Steve Henderson

💻

This project follows the all-contributors specification. Contributions of any kind welcome!