Wrapper for borgbackup to easily use in code
Project description
BorgAPI
A helpful wrapper for borgbackup
to be able to easily use it in python scripts.
This is not supported use case by the borg
developers. They only intend for it's use via a CLI.
Keeping parity with borg
is the main goal of this api.
Installation
pip install borgapi
Requires:
borgbackup
: 1.1.16python-dotenv
: 0.17.1
Usage
import borgapi
api = borgapi.BorgAPI(defaults={}, options={})
# Initalize new repository
api.init("/foo/bar", make_parent_dirs=True)
# Create backup
output = api.create("/foo/bar::backup", "/home", "/mnt/baz", json=True)
print(output["name"]) # backup
print(output["repository"]["location"]) # /foo/bar
BorgAPI Init arguments
class BorgAPI(
defaults: dict = None,
options: dict = None,
log_level: str = 'info',
log_json: bool = False
)
- defaults: dictionary that has command names as keys and value that is a dict of command specific optional arguments
{
"init": {
"encryption": "repokey-blake2",
"make_parent_dirs": True,
},
"create": {
"json": True,
},
}
- options: dictionary that contain the optional arguments (common, exclusion, filesystem, and
archive) used for every command (when valid). Options that aren't valid for a command will get
filterd out. For example,
strip_components
will be passed into theextract
command but not thediff
command.
{
"debug": True,
"log_json": True,
"exclue_from": "baz/spam.txt",
"strip_components": 2,
"sort": True,
"json_lines": True,
}
- log_level: defualt log level, can be overriden for a specific comand by passing in another level as and keyword argument
- log_json: log lines written by logger are formatted as json lines, passed into the logging setup
Setting Environment Variables
You are able to manage the environment variables used by borg to be able to use different settings for different repositories.
There are 3 ways you can set the variables:
filename
: Path to a file that contains the variables and their values. See the python-dotenv README for more information.dictionary
: Dictionary that contains the variable names as keys with their corresponding values set.**kwargs
: Argument names are the variable names and the values are what will be set.
api.set_environ(filename="foo/bar/.env")
api.set_environ(dictionary={"FOO":"BAR", "SPAM":False})
api.set_environ(FOO="BAR", SPAM=False)
Only one value will be used if multiple set, filename
has highest precedence,
followed by dictionary
, and fallback to **kwargs
.
If no values are given for any of the three things (ie. calling with no arguments), then the
default behavior for load_dotenv
from python-dotenv
will be used, which is searching for a ".env" file somewhere above in the current file path.
Environment Variables
used by borgbackup
.
Removing Environment Variables
If you want to unset a variable so it doesn't get used for another command you can use the
unset_environ
method. It'll remove any variables passed in from the current environment.
If no variables are passed in, it'll remove the variables set from the last call to set_environ
.
# Enironment = {}
api.set_environ(dictionary={"FOO":"BAR", "SPAM":False})
# Enironment = {"FOO": "BAR", "SPAM": "False"}
api.unset_environ("FOO")
# Enironment = {"SPAM": "False"}
api.set_environ(BAZ="HAM")
# Enironment = {"SPAM": "False", "BAZ": "HAM"}
api.unset_environ("OTHER")
# Enironment = {"SPAM": "False", "BAZ": "HAM"}
api.unset_environ()
# Enironment = {"SPAM": "False"}
Borg Commands
When using a borg command any of the arguments can be set as keyword arguments.
The argument names are the long option names with dashes turned into underscores.
So the --storage-quota
argument in init
gets turned into the keyword argument storage_quota
.
api.init(
repository="/foor/bar",
encryption="repokey",
append_only=True,
storage_quota="5G",
make_parent_dirs=True,
debug=True,
log_json=True,
)
diff_args = {
sort: True,
json_lines: True,
debug: True,
exclude_from: "./exclude_patterns.txt",
}
api.diff(
"/foo/bar::tuesday",
"friday",
"/foo/bar",
"/baz",
**diff_args,
)
Available Borg Commands
- init
- create
- extract
- check
- rename
- list
- diff
- delete
- prune
- info
- mount
- umount
- key_change_passphrase (key change-passphrase)
- key_export (key export)
- key_import (key import)
- upgrade
- export_tar
- serve
- config
- with-lock
- break-lock
- benchmark crud
Unavailable Borg Commands
- recreate
- Since this is an experimental feature there are no current plans to implament this.
Command Quirks
Things that were changed from the way the default borg commands work to make things a bit more manageable.
- init
encryption
is an optional argument that defaults torepokey
- config
borg config
can only change one key at a timechanges
is a list of(NAME, VALUE)
tuples so multiple changes can be made at once to the same repository
Roadmap
- Make compatible with same version of Python that Borg uses (currently 3.5)
- Start work on Borg's beta branch chagnes and keeping up with those
Links
Contributing
Help is greatly appreciated. First check if there are any issues open that relate to what you want to help with. Also feel free to make a pull request with changes / fixes you make.
License
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.