Simple and safe python wrapper for calling system rsync
Project description
sysrsync
Simple and safe native rsync wrapper for Python 3
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
anddestination_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
whenstrict = 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 bothsource_ssh
anddestination_ssh
are set. Normally linux rsync distribution disallows source and destination to be both remotes.PrivateKeyError
whenprivate_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 💻 |
Steve Henderson 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
sysrsync-1.1.1.tar.gz
(6.9 kB
view hashes)