borgapi 0.6.1__tar.gz → 0.7.1__tar.gz

{borgapi-0.6.1 → borgapi-0.7.1}/PKG-INFO

@@ -1,25 +1,30 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: borgapi
-Version: 0.6.1
+Version: 0.7.1
 Summary: Wrapper for borgbackup to easily use in code
-Home-page: https://github.com/spslater/borgapi
-Author: Sean Slater
-Author-email: seanslater@whatno.io
-License: MIT License
-Keywords: borgbackup backup api
+Author-email: Sean Slater <seanslater@whatno.io>
+Project-URL: homepage, https://github.com/spslater/borgapi
+Project-URL: documentation, https://github.com/spslater/borgapi/blob/master/README.md
+Project-URL: repository, https://github.com/spslater/borgapi.git
+Project-URL: issues, https://github.com/spslater/borgapi/issues
+Project-URL: changelog, https://github.com/spslater/borgapi/blob/master/CHANGELOG.md
+Keywords: borgbackup,backup,api
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Operating System :: OS Independent
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Topic :: Utilities
 Classifier: Topic :: System :: Archiving :: Backup
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: borgbackup[llfuse]~=1.4.0
+Requires-Dist: python-dotenv~=1.0.0
+Dynamic: license-file
 
 # BorgAPI
 
@@ -34,10 +39,10 @@ pip install borgapi
 ```
 
 Requires:
-* `borgbackup`: 1.2.4
-* `python-dotenv`: 1.0.0
+* `borgbackup`: 1.4.0
+* `python-dotenv`: 1.0.1
 
-Supports Python 3.8 to 3.11
+Supports Python 3.9 to 3.13
 
 ## Usage
 ```python
@@ -46,12 +51,12 @@ import borgapi
 api = borgapi.BorgAPI(defaults={}, options={})
 
 # Initalize new repository
-api.init("/foo/bar", make_parent_dirs=True)
+api.init("foo/bar", make_parent_dirs=True)
 
 # Create backup 
-result = api.create("/foo/bar::backup", "/home", "/mnt/baz", json=True)
+result = api.create("foo/bar::backup", "/home", "/mnt/baz", json=True)
 print(result['archive']["name"]) # backup
-print(result["repository"]["location"]) # /foo/bar
+print(result["repository"]["location"]) # foo/bar
 ```
 
 ### BorgAPI Init arguments
@@ -60,7 +65,8 @@ class BorgAPI(
     defaults: dict = None,
     options: dict = None,
     log_level: str = "warning",
-    log_json: bool = False
+    log_json: bool = False,
+    environ: dict = None,
 )
 ```
 * __defaults__: dictionary that has command names as keys and value that is a dict of
@@ -94,12 +100,35 @@ class BorgAPI(
   level as and keyword argument
 * __log_json__: log lines written by logger are formatted as json lines, passed into the
   logging setup
+* __environ__: dictionary that contains environmental variables that should be set before running
+  any commands. Useful for setting the passphrase or passcommand for the repository or other
+  settings like that. See [Environment Variables](#Setting-Environment-Variables) section for
+  how to set environmental variables after initalization or what the defaults are.
+```python
+{
+  "BORG_CHECK_I_KNOW_WHAT_I_AM_DOING": "YES",
+  "BORG_PASSCOMMAND": "cat ~/.borg/password",
+}
+```
 
 ### 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:
+When initialzing the `BorgAPI` object, you can include a dictionary with the `environ` argument.
+
+The following are the defaults that BorgAPI will always load so that user input does not hold up
+the app from progressing.
+```ini
+BORG_EXIT_CODES=modern,
+BORG_PASSPHRASE="",
+BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no,
+BORG_RELOCATED_REPO_ACCESS_IS_OK=no,
+BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO,
+BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO,
+```
+
+There are 3 ways you can set the variables after initialization:
 1. `filename`: Path to a file that contains the variables and their values. See the
    [python-dotenv README](https://github.com/theskumar/python-dotenv/blob/master/README.md#file-format)
    for more information.
@@ -122,14 +151,6 @@ will be used, which is searching for a ".env" file somewhere above in the curren
 [Environment Variables](https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables)
 used by `borgbackup`.
 
-#### IMPORTANT
-For commands that borg requires a confirmation on if no environment variable is given, the api will
-become stuck as it waits for a `yes` or `no` answer.
-* BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK
-* BORG_RELOCATED_REPO_ACCESS_IS_OK
-* BORG_CHECK_I_KNOW_WHAT_I_AM_DOING
-* BORG_DELETE_I_KNOW_WHAT_I_AM_DOING
-
 ### 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.
@@ -156,7 +177,7 @@ So the `--storage-quota` argument in `init` gets turned into the keyword argumen
 
 ```python
 api.init(
-    repository="/foor/bar",
+    repository="foor/bar",
     encryption="repokey",
     append_only=True,
     storage_quota="5G",
@@ -173,9 +194,9 @@ diff_args = {
 }
 
 api.diff(
-    "/foo/bar::tuesday",
+    "foo/bar::tuesday",
     "friday",
-    "/foo/bar",
+    "foo/bar",
     "/baz",
     **diff_args,
 )
@@ -195,20 +216,18 @@ api.diff(
 * info
 * mount
 * umount
-* key_change_passphrase (key change-passphrase)
-* key_export (key export)
-* key_import (key import)
+* key change-passphrase (key_change_passphrase)
+* key export (key_export)
+* key import (key_import)
 * upgrade
-* export_tar
+* recreate
+* immport-tar (immport_tar)
+* export-tar (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.
+* with-lock (with_lock)
+* break-lock (break_lock)
+* benchmark crud (benchmark_crud)
 
 ### Command Quirks
 Things that were changed from the way the default borg commands work to make things a bit
@@ -233,7 +252,8 @@ which outputs the stats info as a json object, it gets written to stdout.
 
 If either `json` or `log_json` is 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 returns `None`.
+If no output is captured, it returns `None` if expecting a string or `{}` (an empty
+dictionary) if expection some kind of JSON output.
 
 If multiple outputs are requested at the same time (like `--stats` and `--list`) the command
 will return a dictionary with aptly named keys (`--list` key is "list"). If only one output
@@ -265,6 +285,12 @@ Commands not listed return no output (None)
   - info: `--info`
 - info
   - always returns bare value
+- recreate:
+  - list: `--list`, `--log-json`
+  - stats: `--stats`
+- import tar
+  - list: `--list`
+  - stats: `--stats`, `--json`
 - export tar
   - list: `--list`, `--log-json`
   - tar: filename == "-"
@@ -275,7 +301,7 @@ Commands not listed return no output (None)
   - always returns bare value
 
 ## Roadmap
-- Start work on Borg's beta branch chagnes and keeping up with those
+- Start work on Borg's beta branch again and keeping up with those
 
 ## Links
 * [PyPi Project](https://pypi.org/project/borgapi)

{borgapi-0.6.1 → borgapi-0.7.1}/README.md

@@ -11,10 +11,10 @@ pip install borgapi
 ```
 
 Requires:
-* `borgbackup`: 1.2.4
-* `python-dotenv`: 1.0.0
+* `borgbackup`: 1.4.0
+* `python-dotenv`: 1.0.1
 
-Supports Python 3.8 to 3.11
+Supports Python 3.9 to 3.13
 
 ## Usage
 ```python
@@ -23,12 +23,12 @@ import borgapi
 api = borgapi.BorgAPI(defaults={}, options={})
 
 # Initalize new repository
-api.init("/foo/bar", make_parent_dirs=True)
+api.init("foo/bar", make_parent_dirs=True)
 
 # Create backup 
-result = api.create("/foo/bar::backup", "/home", "/mnt/baz", json=True)
+result = api.create("foo/bar::backup", "/home", "/mnt/baz", json=True)
 print(result['archive']["name"]) # backup
-print(result["repository"]["location"]) # /foo/bar
+print(result["repository"]["location"]) # foo/bar
 ```
 
 ### BorgAPI Init arguments
@@ -37,7 +37,8 @@ class BorgAPI(
     defaults: dict = None,
     options: dict = None,
     log_level: str = "warning",
-    log_json: bool = False
+    log_json: bool = False,
+    environ: dict = None,
 )
 ```
 * __defaults__: dictionary that has command names as keys and value that is a dict of
@@ -71,12 +72,35 @@ class BorgAPI(
   level as and keyword argument
 * __log_json__: log lines written by logger are formatted as json lines, passed into the
   logging setup
+* __environ__: dictionary that contains environmental variables that should be set before running
+  any commands. Useful for setting the passphrase or passcommand for the repository or other
+  settings like that. See [Environment Variables](#Setting-Environment-Variables) section for
+  how to set environmental variables after initalization or what the defaults are.
+```python
+{
+  "BORG_CHECK_I_KNOW_WHAT_I_AM_DOING": "YES",
+  "BORG_PASSCOMMAND": "cat ~/.borg/password",
+}
+```
 
 ### 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:
+When initialzing the `BorgAPI` object, you can include a dictionary with the `environ` argument.
+
+The following are the defaults that BorgAPI will always load so that user input does not hold up
+the app from progressing.
+```ini
+BORG_EXIT_CODES=modern,
+BORG_PASSPHRASE="",
+BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no,
+BORG_RELOCATED_REPO_ACCESS_IS_OK=no,
+BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO,
+BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO,
+```
+
+There are 3 ways you can set the variables after initialization:
 1. `filename`: Path to a file that contains the variables and their values. See the
    [python-dotenv README](https://github.com/theskumar/python-dotenv/blob/master/README.md#file-format)
    for more information.
@@ -99,14 +123,6 @@ will be used, which is searching for a ".env" file somewhere above in the curren
 [Environment Variables](https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables)
 used by `borgbackup`.
 
-#### IMPORTANT
-For commands that borg requires a confirmation on if no environment variable is given, the api will
-become stuck as it waits for a `yes` or `no` answer.
-* BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK
-* BORG_RELOCATED_REPO_ACCESS_IS_OK
-* BORG_CHECK_I_KNOW_WHAT_I_AM_DOING
-* BORG_DELETE_I_KNOW_WHAT_I_AM_DOING
-
 ### 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.
@@ -133,7 +149,7 @@ So the `--storage-quota` argument in `init` gets turned into the keyword argumen
 
 ```python
 api.init(
-    repository="/foor/bar",
+    repository="foor/bar",
     encryption="repokey",
     append_only=True,
     storage_quota="5G",
@@ -150,9 +166,9 @@ diff_args = {
 }
 
 api.diff(
-    "/foo/bar::tuesday",
+    "foo/bar::tuesday",
     "friday",
-    "/foo/bar",
+    "foo/bar",
     "/baz",
     **diff_args,
 )
@@ -172,20 +188,18 @@ api.diff(
 * info
 * mount
 * umount
-* key_change_passphrase (key change-passphrase)
-* key_export (key export)
-* key_import (key import)
+* key change-passphrase (key_change_passphrase)
+* key export (key_export)
+* key import (key_import)
 * upgrade
-* export_tar
+* recreate
+* immport-tar (immport_tar)
+* export-tar (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.
+* with-lock (with_lock)
+* break-lock (break_lock)
+* benchmark crud (benchmark_crud)
 
 ### Command Quirks
 Things that were changed from the way the default borg commands work to make things a bit
@@ -210,7 +224,8 @@ which outputs the stats info as a json object, it gets written to stdout.
 
 If either `json` or `log_json` is 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 returns `None`.
+If no output is captured, it returns `None` if expecting a string or `{}` (an empty
+dictionary) if expection some kind of JSON output.
 
 If multiple outputs are requested at the same time (like `--stats` and `--list`) the command
 will return a dictionary with aptly named keys (`--list` key is "list"). If only one output
@@ -242,6 +257,12 @@ Commands not listed return no output (None)
   - info: `--info`
 - info
   - always returns bare value
+- recreate:
+  - list: `--list`, `--log-json`
+  - stats: `--stats`
+- import tar
+  - list: `--list`
+  - stats: `--stats`, `--json`
 - export tar
   - list: `--list`, `--log-json`
   - tar: filename == "-"
@@ -252,7 +273,7 @@ Commands not listed return no output (None)
   - always returns bare value
 
 ## Roadmap
-- Start work on Borg's beta branch chagnes and keeping up with those
+- Start work on Borg's beta branch again and keeping up with those
 
 ## Links
 * [PyPi Project](https://pypi.org/project/borgapi)

borgapi-0.7.1/borgapi/__init__.py

@@ -0,0 +1,45 @@
+"""Interface for BorgBackup."""
+
+__all__ = [
+    "BorgAPI",
+    "BorgAPIAsync",
+    "CommonOptions",
+    "ExclusionOptions",
+    "ExclusionInput",
+    "ExclusionOutput",
+    "FilesystemOptions",
+    "ArchiveOptions",
+    "ArchiveInput",
+    "ArchivePattern",
+    "ArchiveOutput",
+    "CommandOptions",
+    "Json",
+    "Output",
+    "Options",
+    "OutputOptions",
+    "ListStringIO",
+    "PersistantHandler",
+    "BorgLogCapture",
+    "OutputCapture",
+]
+
+from .borgapi import BorgAPI as BorgAPI
+from .borgapi import BorgAPIAsync as BorgAPIAsync
+from .capture import BorgLogCapture as BorgLogCapture
+from .capture import ListStringIO as ListStringIO
+from .capture import OutputCapture as OutputCapture
+from .capture import OutputOptions as OutputOptions
+from .capture import PersistantHandler as PersistantHandler
+from .helpers import Json as Json
+from .helpers import Options as Options
+from .helpers import Output as Output
+from .options import ArchiveInput as ArchiveInput
+from .options import ArchiveOptions as ArchiveOptions
+from .options import ArchiveOutput as ArchiveOutput
+from .options import ArchivePattern as ArchivePattern
+from .options import CommandOptions as CommandOptions
+from .options import CommonOptions as CommonOptions
+from .options import ExclusionInput as ExclusionInput
+from .options import ExclusionOptions as ExclusionOptions
+from .options import ExclusionOutput as ExclusionOutput
+from .options import FilesystemOptions as FilesystemOptions