Package: borgapi
BorgAPIA helpful wrapper forborgbackupto be able to easily use it in python scripts.This is not supported use case by theborgdevelopers. They only intend for it's use via a CLI.Keeping parity withborgis the main goal of this api.Installationpip install borgapiRequires:borgbackup: 1.2.4python-dotenv: 1.0.0Supports Python 3.8 to 3.11Usageimportborgapiapi=borgapi.BorgAPI(defaults={},options={})# Initalize new repositoryapi.init("/foo/bar",make_parent_dirs=True)# Create backupresult=api.create("/foo/bar::backup","/home","/mnt/baz",json=True)print(result['archive']["name"])# backupprint(result["repository"]["location"])# /foo/barBorgAPI Init argumentsclassBorgAPI(defaults:dict=None,options:dict=None,log_level:str="warning",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_componentswill be passed into theextractcommand but not
thediffcommand.{"debug":True,"log_json":True,"exclue_from":"baz/spam.txt","strip_components":2,"sort":True,"json_lines":True,}log_level: default log level, can be overriden for a specific comand by passing in another
level as and keyword argumentlog_json: log lines written by logger are formatted as json lines, passed into the
logging setupSetting Environment VariablesYou 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 thepython-dotenv READMEfor 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,filenamehas highest precedence,
followed bydictionary, and fallback to**kwargs.If no values are given for any of the three things (ie. calling with no arguments), then the
default behavior forload_dotenvfrompython-dotenvwill be used, which is searching for a ".env" file somewhere above in the current file path.Environment Variablesused byborgbackup.IMPORTANTFor commands that borg requires a confirmation on if no environment variable is given, the api will
become stuck as it waits for ayesornoanswer.BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OKBORG_RELOCATED_REPO_ACCESS_IS_OKBORG_CHECK_I_KNOW_WHAT_I_AM_DOINGBORG_DELETE_I_KNOW_WHAT_I_AM_DOINGRemoving Environment VariablesIf you want to unset a variable so it doesn't get used for another command you can use theunset_environmethod. 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 toset_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 CommandsWhen 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-quotaargument ininitgets turned into the keyword argumentstorage_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 Commandsinitcreateextractcheckrenamelistdiffdeleteprunecompactinfomountumountkey_change_passphrase (key change-passphrase)key_export (key export)key_import (key import)upgradeexport_tarserveconfigwith-lockbreak-lockbenchmark crudUnavailable Borg CommandsrecreateSince this is an experimental feature there are no current plans to implament this.Command QuirksThings that were changed from the way the default borg commands work to make things a bit
more manageable.initencryptionis an optional argument that defaults torepokeyconfigborg configcan only change one key at a time*changescan either be:NAMEto get the current value of the key(NAME, VALUE)which will change they keyAny single stringNAMEvalues passed to*changewill be returned as a list with their
values in the order they were passed, tuple changes will not appear in that listCapturing Outputborgcommands display information different depending on what is asked for.
For example,createwith the--listoption writes the file list to the logger.
When the--log-jsoncommon flag is included it writes it to stderr. The--statsoption writes to the logger, like the--listoption does, but when--jsonis used,
which outputs the stats info as a json object, it gets written to stdout.If eitherjsonorlog_jsonis set, it'll try to convert the tuple output to json.
If it is unable and there is output that is captured it'll return the plaintext value.
If no output is captured, it returnsNone.If multiple outputs are requested at the same time (like--statsand--list) the command
will return a dictionary with aptly named keys (--listkey is "list"). If only one output
is requested than the bare value will be returned, not in a dictionary.Command ReturnsCommands not listed return no output (None)createlist:--list,--log-jsonstats:--stats,--jsonextractlist:--list,--log-jsonextract:--stdoutlist:list: always returns bare value--log-json,--json,--json-linesdiff:diff: always returns bare value--log-json,--json-linesdelete:stats: always returns bare value--statsprune:list:--list,--log-jsonstats:--stats,--log-jsoncompact:returns bare value, when verbose or info is setverbose:--verbose,-vinfo:--infoinfoalways returns bare valueexport tarlist:--list,--log-jsontar: filename == "-"configlist:--list,--log-jsonchanges: single values passed into*changesbenchmark crudalways returns bare valueRoadmapStart work on Borg's beta branch chagnes and keeping up with thoseLinksPyPi ProjectGithubContributingHelp 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.LicenseMIT License