borgapi 0.6.1__py3-none-any.whl → 0.7.1__py3-none-any.whl

borgapi/borgapi.py

@@ -1,16 +1,19 @@
-"""Run Borg Backups"""
+"""Run Borg backups."""
 
+import functools
 import logging
 import os
-import sys
-from io import BytesIO, StringIO, TextIOWrapper
+from asyncio import wrap_future
+from concurrent.futures import ThreadPoolExecutor
+from io import StringIO
 from json import decoder, loads
-from typing import Callable, List, Optional, Tuple, Union
+from typing import Callable, Optional, Union
 
 import borg.archiver
-from borg.logger import JsonFormatter
 from dotenv import dotenv_values, load_dotenv
 
+from .capture import LOG_LVL, OutputCapture, OutputOptions
+from .helpers import ENVIRONMENT_DEFAULTS, Options, Output
 from .options import (
     ArchiveInput,
     ArchiveOutput,
@@ -24,194 +27,116 @@ from .options import (
     OptionsBase,
 )
 
-__all__ = ["BorgAPI"]
+__all__ = ["BorgAPI", "BorgAPIAsync"]
 
-Json = Union[list, dict]
-Output = Union[str, Json, None]
-Options = Union[bool, str, int]
 
-LOG_LVL = "warning"
+class BorgAPIBase:
+    """Automate borg in code.
 
-
-class OutputCapture:
-    """Capture stdout and stderr by redirecting to inmemory streams
-
-    :param raw: Expecting raw bytes from stdout and stderr
-    :type raw: bool
+    Base class for the wrapper. Contains all the non-Borg command calls.
+    Should not be called by itself. Only really here for readability purposes.
     """
 
-    def __init__(
-        self,
-        raw: bool = False,
-        log_json: bool = False,
-        log_level: str = LOG_LVL,
-    ):
-        self.raw = raw
-        fmt = "%(message)s"
-        self.formatter = JsonFormatter(fmt) if log_json else logging.Formatter(fmt)
-        self.level = log_level.upper()
-        self._init_stdout(raw)
-        self._init_stderr()
-
-        self._init_list_capture()
-        self._init_stats_capture()
-        self._init_repo_capture()
-
-    def _init_stdout(self, raw: bool):
-        self.stdout = TextIOWrapper(BytesIO()) if raw else StringIO()
-        self.stdout_original = sys.stdout
-        sys.stdout = self.stdout
-
-    def _init_stderr(self):
-        self.stderr = StringIO()
-        self.stderr_original = sys.stderr
-        sys.stderr = self.stderr
-
-    def _init_list_capture(self):
-        self.list_handler = logging.StreamHandler(StringIO())
-        self.list_handler.setFormatter(self.formatter)
-        # self.list_handler.setLevel(self.level)
-        self.list_handler.setLevel("INFO")
-
-        self.list_logger = logging.getLogger("borg.output.list")
-        self.list_logger.addHandler(self.list_handler)
-
-    def _init_stats_capture(self):
-        self.stats_handler = logging.StreamHandler(StringIO())
-        self.stats_handler.setFormatter(self.formatter)
-        # self.stats_handler.setLevel(self.level)
-        self.stats_handler.setLevel("INFO")
-
-        self.stats_logger = logging.getLogger("borg.output.stats")
-        self.stats_logger.addHandler(self.stats_handler)
-
-    def _init_repo_capture(self):
-        self.repo_handler = logging.StreamHandler(StringIO())
-        self.repo_handler.setFormatter(self.formatter)
-        self.repo_handler.setLevel(self.level)
-
-        self.repo_logger = logging.getLogger("borg.repository")
-        self.repo_logger.addHandler(self.repo_handler)
-
-    # pylint: disable=no-member
-    def getvalues(self) -> Union[str, bytes]:
-        """Get the captured values from the redirected stdout and stderr
-
-        :return: Redirected values from stdout and stderr
-        :rtype: Union[str, bytes]
-        """
-        stdout_value = stderr_value = None
-        if self.raw:
-            stdout_value = self.stdout.buffer.getvalue()
-        else:
-            stdout_value = self.stdout.getvalue().strip()
-        stderr_value = self.stderr.getvalue().strip()
-
-        list_value = self.list_handler.stream.getvalue()
-        stats_value = self.stats_handler.stream.getvalue()
-        repo_value = self.repo_handler.stream.getvalue()
-
-        return {
-            "stdout": stdout_value,
-            "stderr": stderr_value,
-            "list": list_value,
-            "stats": stats_value,
-            "repo": repo_value,
-        }
-
-    def close(self):
-        """Close the underlying IO streams and reset stdout and stderr"""
-        try:
-            self.stdout.close()
-            self.stderr.close()
-            self.list_handler.stream.close()
-            self.list_logger.removeHandler(self.list_handler)
-            self.stats_handler.stream.close()
-            self.stats_logger.removeHandler(self.stats_handler)
-        finally:
-            sys.stdout = self.stdout_original
-            sys.stderr = self.stderr_original
-
-
-# pylint: disable=too-many-public-methods
-class BorgAPI:
-    """Automate borg in code"""
-
-    # pylint: disable=too-many-arguments,not-callable
     def __init__(
         self,
         defaults: dict = None,
         options: dict = None,
         log_level: str = LOG_LVL,
         log_json: bool = False,
+        environ: dict = None,
     ):
+        """Set the options to be used across the different command call.
+
+        :param defaults: options for specific commands to always use, defaults to None
+        :type defaults: dict, optional
+        :param options: common flags for all commands, defaults to None
+        :type options: dict, optional
+        :param log_level: level to record logged messages at, defaults to LOG_LVL
+        :type log_level: str, optional
+        :param log_json: if the output should be in json or string format, defaults to False
+        :type log_json: bool, optional
+        :param environ: envirnmental variables to set for borg to use (ie BORG_PASSCOMMAND),
+            defaults to None
+        :type environ: dict, optional
+        """
         self.options = options or {}
         self.optionals = CommandOptions(defaults)
         self.archiver = borg.archiver.Archiver()
         self._previous_dotenv = []
-        self._setup_logging(log_level, log_json)
+        self._set_environ_defaults()
+        if environ is not None:
+            self.set_environ(**environ)
         self.log_level = log_level
+        if log_json:
+            self.options.set("log_json", log_json)
 
-    def _setup_logging(self, log_level: str = LOG_LVL, log_json: bool = False):
-        self.logger_setup = False
-        self.archiver.log_json = log_json or self.options.get("log_json", False)
-        borg.archiver.setup_logging(level=log_level, is_serve=False, json=log_json)
-        self.original_stdout = sys.stdout
+        self.archiver.log_json = log_json
+        borg.archiver.setup_logging(level=self.log_level, is_serve=False, json=log_json)
         logging.getLogger("borgapi")
         self._logger = logging.getLogger(__name__)
 
+        self.output = OutputCapture()
+
     @staticmethod
-    def _loads_json_lines(string: str) -> Union[dict, str, None]:
+    def _loads_json_lines(string: Union[str, list]) -> Union[dict, str, None]:
         result = None
         try:
-            result = loads(string)
+            if type(string) is str:
+                result = loads(string)
+            elif type(string) is list:
+                result = loads(f"[{','.join(string)}]")
         except decoder.JSONDecodeError:
-            clean = f'[{",".join(string.splitlines())}]'
+            if type(string) is str:
+                clean = f"[{','.join(string.splitlines())}]"
+            elif type(string) is str:
+                clean = str(string)
             try:
                 result = loads(clean)
             except decoder.JSONDecodeError:
-                result = string or None
+                try:
+                    multiline = "[" + string.replace("}{", "},{") + "]"
+                    result = loads(multiline)
+                except decoder.JSONDecodeError:
+                    result = string or None
         return result
 
     @staticmethod
-    def _build_result(*results: Tuple[str, Output]) -> Output:
+    def _build_result(*results: tuple[str, Output], log_json: bool = False) -> Output:
         if not results:
             return None
         if len(results) == 1:
-            return results[0][1] or None
+            result = results[0][1]
+            if len(result) == 1:
+                return result[0]
+            return result
         result = {}
         for name, value in results:
-            if value:
-                result[name] = value
-        return result or None
+            result[name] = value
+        return result
 
-    # pylint: disable=no-member
     def _run(
         self,
-        arg_list: List,
+        arg_list: list,
         func: Callable,
-        raw_bytes: bool = False,
-        log_level: str = LOG_LVL,
+        output_options: OutputOptions,
     ) -> dict:
         self._logger.debug("%s: %s", func.__name__, arg_list)
         arg_list.insert(0, "borgapi")
         arg_list = [str(arg) for arg in arg_list]
-        args = self.archiver.get_args(arg_list, os.environ.get("SSH_ORIGINAL_COMMAND"))
+        args = self.archiver.get_args(arg_list, os.getenv("SSH_ORIGINAL_COMMAND", None))
 
         prev_json = self.archiver.log_json
         log_json = getattr(args, "log_json", prev_json)
         self.archiver.log_json = log_json
 
-        capture = OutputCapture(raw_bytes, log_json, log_level)
-        try:
-            func(args)
-        except Exception as e:
-            self._logger.error(e)
-            raise e
-        else:
-            capture_result = capture.getvalues()
-        finally:
-            capture.close()
+        with self.output(output_options):
+            try:
+                func(args)
+            except Exception as e:
+                self._logger.error(e)
+                raise e
+            else:
+                capture_result = self.output.getvalues()
 
         self.archiver.log_json = prev_json
 
@@ -221,7 +146,7 @@ class BorgAPI:
         args = {**self.options, **(value or {})}
         return options_class(**args)
 
-    def _get_option_list(self, value: dict, options_class: OptionsBase) -> List:
+    def _get_option_list(self, value: dict, options_class: OptionsBase) -> list:
         option = self._get_option(value, options_class)
         return option.parse()
 
@@ -251,13 +176,65 @@ class BorgAPI:
 
         return lvl
 
+    def _get_basic_results(self, output: dict, opts: OutputOptions) -> dict:
+        result_list = []
+        if opts.stats_show:
+            if opts.stats_json:
+                result_list.append(("stats", self._loads_json_lines(output["stdout"])))
+            else:
+                result_list.append(("stats", output["stats"]))
+
+        if opts.list_show:
+            if opts.list_json:
+                result_list.append(("list", self._loads_json_lines(output["list"])))
+            else:
+                result_list.append(("list", output["list"]))
+
+        if opts.prog_show:
+            if opts.prog_json:
+                result_list.append(("prog", self._loads_json_lines(output["stderr"])))
+            else:
+                result_list.append(("prog", output["stderr"]))
+
+        return result_list
+
+    def _set_environ_defaults(self):
+        for key, value in ENVIRONMENT_DEFAULTS.items():
+            if os.getenv(key) is None:
+                os.environ[key] = value
+
+
+class BorgAPI(BorgAPIBase):
+    """Automate borg in code."""
+
+    def __init__(
+        self,
+        defaults: dict = None,
+        options: dict = None,
+        log_level: str = LOG_LVL,
+        log_json: bool = False,
+        environ: dict = None,
+    ):
+        """Set the options to be used across the different command call.
+
+        :param defaults: options for specific commands to always use, defaults to None
+        :type defaults: dict, optional
+        :param options: common flags for all commands, defaults to None
+        :type options: dict, optional
+        :param log_level: level to record logged messages at, defaults to LOG_LVL
+        :type log_level: str, optional
+        :param log_json: if the output should be in json or string format, defaults to False
+        :type log_json: bool, optional
+        """
+        super().__init__(defaults, options, log_level, log_json, environ)
+
     def set_environ(
         self,
         filename: str = None,
         dictionary: dict = None,
         **kwargs: Options,
     ) -> None:
-        """Load environment variables from file
+        """Load environment variables from file.
 
         If nothing is provided, load_dotenv's default value will be used.
 
@@ -281,15 +258,15 @@ class BorgAPI:
 
         self._previous_dotenv = variables.keys()
 
-        config = StringIO()
-        for key, value in variables.items():
-            config.write(f"{key}={value}\n")
-        config.seek(0)
-        load_dotenv(stream=config, override=True)
-        config.close()
+        with StringIO() as config:
+            for key, value in variables.items():
+                config.write(f"{key}={value}\n")
+            config.seek(0)
+            load_dotenv(stream=config, override=True)
+            config.close()
 
     def unset_environ(self, *variable: Optional[str]) -> None:
-        """Remove variables from the environment
+        """Remove variables from the environment.
 
         If no variable is provided the values set from the previous call to `set_environ`
             will be removed.
@@ -309,8 +286,10 @@ class BorgAPI:
         encryption: str = "repokey",
         **options: Options,
     ) -> Output:
-        """Initialize an empty repository. A repository is a filesystem directory
-        containing the deduplicated data from zero or more archives.
+        """Initialize an empty repository.
+
+        A repository is a filesystem directory containing the deduplicated data
+        from zero or more archives.
 
         :param repository: repository to create
         :type repository: str
@@ -322,15 +301,26 @@ class BorgAPI:
             json dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+        init_options = self.optionals.get("init", options)
+
         arg_list = []
         arg_list.extend(self._get_option_list(options, CommonOptions))
         arg_list.append("init")
         arg_list.extend(["--encryption", encryption])
-        arg_list.extend(self.optionals.to_list("init", options))
+        arg_list.extend(init_options.parse())
         arg_list.append(repository)
 
-        lvl = self._get_log_level(options)
-        return self._run(arg_list, self.archiver.do_init, log_level=lvl)
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_init, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def create(
         self,
@@ -338,8 +328,7 @@ class BorgAPI:
         *paths: str,
         **options: Options,
     ) -> Output:
-        """Create a backup archive containing all files found while recursively
-        traversing all paths specified.
+        """Create a backup archive of all files found while recursively traversing specified paths.
 
         :param archive: name of archive to create (must be also a valid directory name)
         :type archive: str
@@ -365,21 +354,24 @@ class BorgAPI:
         arg_list.append(archive)
         arg_list.extend(paths)
 
-        lvl = self._get_log_level(options)
-        output = self._run(arg_list, self.archiver.do_create, log_level=lvl)
-
-        result_list = []
-        if create_options.stats and not create_options.json:
-            result_list.append(("stats", output["stats"]))
-        elif create_options.json:
-            result_list.append(("stats", self._loads_json_lines(output["stdout"])))
-
-        if create_options.list and not common_options.log_json:
-            result_list.append(("list", output["list"]))
-        elif create_options.list and common_options.log_json:
-            result_list.append(("list", self._loads_json_lines(output["stderr"])))
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            stats_show=create_options.stats or create_options.json,
+            stats_json=create_options.json,
+            list_show=create_options.list,
+            list_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_create, output_options=opts)
 
-        return self._build_result(*result_list)
+        result_list = self._get_basic_results(output, opts)
+        if opts.list_show:
+            if opts.list_json:
+                result_list.remove(("list", []))
+                result_list.append(("list", self._loads_json_lines(output["stderr"])))
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def extract(
         self,
@@ -411,25 +403,26 @@ class BorgAPI:
         arg_list.append(archive)
         arg_list.extend(paths)
 
-        raw_bytes = options.get("stdout", False)
-        lvl = self._get_log_level(options)
+        opts = OutputOptions(
+            raw_bytes=extract_options.stdout,
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            list_show=extract_options.list,
+            list_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
         output = self._run(
             arg_list,
             self.archiver.do_extract,
-            raw_bytes=raw_bytes,
-            log_level=lvl,
+            output_options=opts,
         )
 
-        result_list = []
-        if extract_options.list and not common_options.log_json:
-            result_list.append(("list", output["list"]))
-        elif extract_options.list and common_options.log_json:
-            result_list.append(("list", self._loads_json_lines(output["list"])))
-
-        if extract_options.stdout:
+        result_list = self._get_basic_results(output, opts)
+        if opts.raw_bytes:
             result_list.append(("extract", output["stdout"]))
 
-        return self._build_result(*result_list)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def check(self, *repository_or_archive: str, **options: Options) -> Output:
         """Verify the consistency of a repository and the corresponding archives.
@@ -443,16 +436,26 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+        check_options = self.optionals.get("check", options)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.append("check")
-        arg_list.extend(self.optionals.to_list("check", options))
+        arg_list.extend(check_options.parse())
         arg_list.extend(self._get_option_list(options, ArchiveOutput))
         arg_list.extend(repository_or_archive)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_check, log_level=lvl)
-        return self._build_result()
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_check, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def rename(
         self,
@@ -473,17 +476,25 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.append("rename")
         arg_list.append(archive)
         arg_list.append(newname)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_rename, log_level=lvl)
-        return self._build_result()
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_rename, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
-    # pylint: disable=redefined-builtin
     def list(
         self,
         repository_or_archive: str,
@@ -515,16 +526,26 @@ class BorgAPI:
         arg_list.append(repository_or_archive)
         arg_list.extend(paths)
 
-        lvl = self._get_log_level(options)
-        output = self._run(arg_list, self.archiver.do_list, log_level=lvl)
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            list_show=True,
+            list_json=list_options.json_lines or list_options.json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_list, output_options=opts)
 
-        result_list = []
-        if common_options.log_json or list_options.json or list_options.json_lines:
-            result_list.append(("list", self._loads_json_lines(output["stdout"])))
-        else:
-            result_list.append(("list", output["stdout"]))
+        result_list = self._get_basic_results(output, opts)
+        if opts.list_show:
+            if opts.list_json:
+                result_list.remove(("list", []))
+                result_list.append(("list", self._loads_json_lines(output["stdout"])))
+            else:
+                result_list.remove(("list", ""))
+                result_list.append(("list", output["stdout"]))
 
-        return self._build_result(*result_list)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def diff(
         self,
@@ -560,16 +581,21 @@ class BorgAPI:
         arg_list.append(archive_2)
         arg_list.extend(paths)
 
-        lvl = self._get_log_level(options)
-        output = self._run(arg_list, self.archiver.do_diff, log_level=lvl)
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=diff_options.json_lines or common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_diff, output_options=opts)
 
-        result_list = []
-        if common_options.log_json or diff_options.json_lines:
+        result_list = self._get_basic_results(output, opts)
+        if opts.log_json:
             result_list.append(("diff", self._loads_json_lines(output["stdout"])))
         else:
             result_list.append(("diff", output["stdout"]))
 
-        return self._build_result(*result_list)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def delete(
         self,
@@ -577,7 +603,7 @@ class BorgAPI:
         *archives: Optional[str],
         **options: Options,
     ) -> Output:
-        """Delete an archive from the repository or the complete repository
+        """Delete an archive from the repository or the complete repository.
 
         :param repository_or_archive: repository or archive to delete
         :type repository_or_archive: str
@@ -601,20 +627,24 @@ class BorgAPI:
         arg_list.append(repository_or_archive)
         arg_list.extend(archives)
 
-        lvl = self._get_log_level(options)
-        output = self._run(arg_list, self.archiver.do_delete, log_level=lvl)
-
-        result_list = []
-        if delete_options.stats and common_options.log_json:
-            result_list.append(("stats", self._loads_json_lines(output["stats"])))
-        elif delete_options.stats:
-            result_list.append(("stats", output["stats"]))
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            # no json option in this command
+            stats_show=delete_options.stats,  # or delete_options.json,
+            # stats_json = delete_options.json,
+            list_show=delete_options.list,
+            list_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_delete, output_options=opts)
 
-        return self._build_result(*result_list)
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def prune(self, repository: str, **options: Options) -> Output:
-        """Prune a repository by deleting all archives not matching any of the specified
-        retention options.
+        """Prune a repository by deleting all archives not matching the specified retention options.
 
         :param repository: repository to prune
         :type repository: str
@@ -635,20 +665,21 @@ class BorgAPI:
         arg_list.extend(self._get_option_list(options, ArchivePattern))
         arg_list.append(repository)
 
-        lvl = self._get_log_level(options)
-        output = self._run(arg_list, self.archiver.do_prune, log_level=lvl)
-
-        result_list = []
-        if prune_options.list and not common_options.log_json:
-            result_list.append(("list", output["list"]))
-        elif prune_options.list and common_options.log_json:
-            result_list.append(("list", self._loads_json_lines(output["list"])))
-        if prune_options.stats and not common_options.log_json:
-            result_list.append(("stats", output["stats"]))
-        elif prune_options.stats and common_options.log_json:
-            result_list.append(("stats", self._loads_json_lines(output["stats"])))
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            # no json option for stats
+            stats_show=prune_options.stats,  # or prune_options.json,
+            # stats_json = prune_options.json,
+            list_show=prune_options.list,
+            list_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_prune, output_options=opts)
 
-        return self._build_result(*result_list)
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def compact(self, repository: str, **options: Options) -> Output:
         """Compact frees repository space by compacting segments.
@@ -671,16 +702,23 @@ class BorgAPI:
         arg_list.extend(compact_options.parse())
         arg_list.append(repository)
 
-        lvl = self._get_log_level(options)
-        output = self._run(arg_list, self.archiver.do_compact, log_level=lvl)
-
-        result_list = []
-        if common_options.log_json:
-            result_list.append(("compact", self._loads_json_lines(output["repo"])))
-        else:
-            result_list.append(("compact", output["repo"]))
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            repo_show=common_options.verbose,
+            repo_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_compact, output_options=opts)
 
-        return self._build_result(*result_list)
+        result_list = self._get_basic_results(output, opts)
+        if opts.repo_show:
+            if opts.repo_json:
+                result_list.append(("compact", self._loads_json_lines(output["repo"])))
+            else:
+                result_list.append(("compact", output["repo"]))
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def info(self, repository_or_archive: str, **options: Options) -> Output:
         """Display detailed information about the specified archive or repository.
@@ -704,16 +742,21 @@ class BorgAPI:
         arg_list.extend(self._get_option_list(options, ArchiveOutput))
         arg_list.append(repository_or_archive)
 
-        lvl = self._get_log_level(options)
-        output = self._run(arg_list, self.archiver.do_info, log_level=lvl)
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=info_options.json or common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_info, output_options=opts)
 
-        result_list = []
-        if info_options.json:
+        result_list = self._get_basic_results(output, opts)
+        if opts.log_json:
             result_list.append(("info", self._loads_json_lines(output["stdout"])))
         else:
             result_list.append(("info", output["stdout"]))
 
-        return self._build_result(*result_list)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def mount(
         self,
@@ -737,23 +780,37 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+        mount_options = self.optionals.get("mount", options)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.append("mount")
-        arg_list.extend(self.optionals.to_list("mount", options))
+        arg_list.extend(mount_options.parse())
         arg_list.extend(self._get_option_list(options, ArchiveOutput))
         arg_list.extend(self._get_option_list(options, ExclusionOutput))
         arg_list.append(repository_or_archive)
         arg_list.append(mountpoint)
         arg_list.extend(paths)
 
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+
         pid = os.fork()
         # child process, this one does the actual mount (in the foreground)
         if pid == 0:
-            lvl = self._get_log_level(options)
-            self._run(arg_list, self.archiver.do_mount, log_level=lvl)
-            return self._build_result()
-        return self._build_result(("mount", {"pid": pid, "cid": os.getpid()}))
+            output = self._run(arg_list, self.archiver.do_mount, output_options=opts)
+
+            result_list = self._get_basic_results(output, opts)
+            return self._build_result(*result_list, log_json=opts.log_json)
+
+        result_list = self._get_basic_results({}, opts)
+        result_list.append(("mount", {"pid": pid, "cid": os.getpid()}))
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def umount(self, mountpoint: str, **options: Options) -> Output:
         """Un-mount a FUSE filesystem that was mounted with `mount`.
@@ -767,14 +824,23 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.append("umount")
         arg_list.append(mountpoint)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_umount, log_level=lvl)
-        return self._build_result()
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_umount, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def key_change_passphrase(self, repository: str, **options: Options) -> Output:
         """Change the passphrase protecting the repository encryption.
@@ -788,14 +854,23 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.extend(["key", "change-passphrase"])
         arg_list.append(repository)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_change_passphrase, log_level=lvl)
-        return self._build_result()
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_change_passphrase, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def key_export(
         self,
@@ -816,16 +891,26 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+        key_export_options = self.optionals.get("key_export", options)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.extend(["key", "export"])
-        arg_list.extend(self.optionals.to_list("key_export", options))
+        arg_list.extend(key_export_options.parse())
         arg_list.append(repository)
         arg_list.append(path)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_key_export, log_level=lvl)
-        return self._build_result()
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_key_export, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def key_import(
         self,
@@ -846,16 +931,26 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+        key_import_options = self.optionals.get("key_import", options)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.extend(["key", "import"])
-        arg_list.extend(self.optionals.to_list("key_import", options))
+        arg_list.extend(key_import_options.parse())
         arg_list.append(repository)
         arg_list.append(path)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_key_import, log_level=lvl)
-        return self._build_result()
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_key_import, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def upgrade(self, repository: str, **options: Options) -> Output:
         """Upgrade an existing, local Borg repository.
@@ -869,15 +964,115 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+        upgrade_options = self.optionals.to_list("upgrade", options)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.append("upgrade")
-        arg_list.extend(self.optionals.to_list("upgrade", options))
+        arg_list.extend(upgrade_options.parse())
         arg_list.append(repository)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_upgrade, log_level=lvl)
-        return self._build_result()
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_upgrade, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
+
+    def recreate(
+        self,
+        repository_or_archive: str,
+        *paths: Optional[str],
+        **options: Options,
+    ):
+        """Recreate the contents of existing archives.
+
+        :param repository_or_archive: repository or archive to recreate
+        :type repository_or_archive: str
+        :param *paths: paths to recreate; patterns are supported
+        :type *paths: Optional[str]
+        :param **options: optional arguments specific to `recreate` as well as exclusion and
+            common options; defaults to {}
+        :type **options: Options
+        :return: Output of command, None if no output created,
+            dict if json flag used, str otherwise
+        :rtype: Output
+        """
+        common_options = self._get_option(options, CommonOptions)
+        recreate_options = self.optionals.get("recreate", options)
+
+        arg_list = []
+        arg_list.extend(common_options.parse())
+        arg_list.append("recreate")
+        arg_list.extend(recreate_options.parse())
+        arg_list.extend(self._get_option_list(options, ExclusionInput))
+        arg_list.extend(self._get_option_list(options, ArchiveInput))
+        arg_list.append(repository_or_archive)
+        arg_list.extend(paths)
+
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            stats_show=recreate_options.stats,
+            stats_json=False,  # No json flag
+            list_show=recreate_options.list,
+            list_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_recreate, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
+
+    def import_tar(
+        self,
+        archive: str,
+        tarfile: str,
+        **options: Options,
+    ):
+        """Create a backup archive from a tarball.
+
+        :param archive: name of archive to create (must be also a valid directory name)
+        :type archive: str
+        :param tarfile: input tar file. “-” to read from stdin instead.
+        :type tarfile: str
+        :param **options: optional arguments specific to `import_tar` as well as exclusion and
+            common options; defaults to {}
+        :type **options: Options
+        :return: Output of command, None if no output created,
+            dict if json flag used, str otherwise
+        :rtype: Output
+        """
+        common_options = self._get_option(options, CommonOptions)
+        import_tar_options = self.optionals.get("import_tar", options)
+
+        arg_list = []
+        arg_list.extend(common_options.parse())
+        arg_list.append("import-tar")
+        arg_list.extend(import_tar_options.parse())
+        arg_list.append(archive)
+        arg_list.append(tarfile)
+
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            stats_show=import_tar_options.stats or import_tar_options.json,
+            stats_json=import_tar_options.json,
+            list_show=import_tar_options.list,
+            list_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_import_tar, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def export_tar(
         self,
@@ -913,21 +1108,26 @@ class BorgAPI:
         arg_list.append(file)
         arg_list.extend(paths)
 
-        lvl = self._get_log_level(options)
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            raw_bytes=(file == "-"),
+            list_show=export_tar_options.list,
+            list_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
         output = self._run(
             arg_list,
             self.archiver.do_export_tar,
-            raw_bytes=(file == "-"),
-            log_level=lvl,
+            output_options=opts,
         )
 
-        result_list = []
-        if export_tar_options.list:
-            result_list.append(("list", output["list"]))
-        if file == "-":
+        result_list = self._get_basic_results(output, opts)
+        if opts.raw_bytes:
             result_list.append(("tar", output["stdout"]))
 
-        return self._build_result(*result_list)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def serve(self, **options: Options) -> Output:
         """Start a repository server process. This command is usually not used manually.
@@ -936,19 +1136,29 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+        serve_options = self.optionals.to_list("serve", options)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.append("serve")
-        arg_list.extend(self.optionals.to_list("serve", options))
+        arg_list.extend(serve_options.parse())
+
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_serve, output_options=opts)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_serve, log_level=lvl)
-        return self._build_result()
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def config(
         self,
         repository: str,
-        *changes: Union[str, Tuple[str, str]],
+        *changes: Union[str, tuple[str, str]],
         **options: Options,
     ) -> Output:
         """Get and set options in a local repository or cache config file.
@@ -956,7 +1166,7 @@ class BorgAPI:
         :param repository: repository to configure
         :type repository: str
         :param *changes: config key, new value
-        :type *changes: Union[str, Tuple[str, str]]
+        :type *changes: Union[str, tuple[str, str]]
         :param **options: optional arguments specific to `config` as well as
             common options; defaults to {}
         :type **options: Options
@@ -974,25 +1184,36 @@ class BorgAPI:
         arg_list.extend(self._get_option_list(options, ExclusionOutput))
         arg_list.append(repository)
 
-        lvl = self._get_log_level(options)
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            list_show=config_options.list,
+            list_json=False,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+
         result_list = []
         if not changes:
-            output = self._run(arg_list, self.archiver.do_config, log_level=lvl)
-            if config_options.list:
+            output = self._run(arg_list, self.archiver.do_config, output_options=opts)
+            result_list.extend(self._get_basic_results(output, opts))
+            if opts.list_show:
+                result_list.remove(("list", ""))
                 result_list.append(("list", output["stdout"]))
 
         change_result = []
         for change in changes:
+            new_args = arg_list
             if isinstance(change, tuple):
-                change = arg_list + [change[0], change[1]]
-                self._run(change, self.archiver.do_config, log_level=lvl)
+                new_args.extend([change[0], change[1]])
             else:
-                change = arg_list + [change]
-                output = self._run(change, self.archiver.do_config, log_level=lvl)
-                change_result.append(output["stdout"])
+                new_args.extend([change])
+            output = self._run(new_args, self.archiver.do_config, output_options=opts)
+            change_result.append(output["stdout"].strip())
+        if change_result:
             result_list.append(("changes", change_result))
 
-        return self._build_result(*result_list)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def with_lock(
         self,
@@ -1016,16 +1237,25 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.append("with-lock")
         arg_list.append(repository)
         arg_list.append(command)
         arg_list.extend(args)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_with_lock, log_level=lvl)
-        return self._build_result()
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_with_lock, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def break_lock(self, repository: str, **options: Options) -> Output:
         """Break the repository and cache locks.
@@ -1039,14 +1269,23 @@ class BorgAPI:
             dict if json flag used, str otherwise
         :rtype: Output
         """
+        common_options = self._get_option(options, CommonOptions)
+
         arg_list = []
-        arg_list.extend(self._get_option_list(options, CommonOptions))
+        arg_list.extend(common_options.parse())
         arg_list.append("break-lock")
         arg_list.append(repository)
 
-        lvl = self._get_log_level(options)
-        self._run(arg_list, self.archiver.do_break_lock, log_level=lvl)
-        return self._build_result()
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_break_lock, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        return self._build_result(*result_list, log_json=opts.log_json)
 
     def benchmark_crud(
         self,
@@ -1075,8 +1314,72 @@ class BorgAPI:
         arg_list.append(repository)
         arg_list.append(path)
 
-        lvl = self._get_log_level(options)
-        output = self._run(arg_list, self.archiver.do_benchmark_crud, log_level=lvl)
+        opts = OutputOptions(
+            log_lvl=self._get_log_level(options),
+            log_json=common_options.log_json,
+            prog_show=common_options.progress,
+            prog_json=common_options.log_json,
+        )
+        output = self._run(arg_list, self.archiver.do_benchmark_crud, output_options=opts)
+
+        result_list = self._get_basic_results(output, opts)
+        result_list.append(("benchmark", output["stdout"]))
+        return self._build_result(*result_list, log_json=opts.log_json)
+
+
+class BorgAPIAsync(BorgAPI):
+    """Async version of the :class:`BorgAPI`."""
+
+    CMDS = [
+        "set_environ",
+        "unset_environ",
+        "init",
+        "create",
+        "extract",
+        "check",
+        "rename",
+        "list",
+        "diff",
+        "delete",
+        "prune",
+        "compact",
+        "info",
+        "mount",
+        "umount",
+        "key_change_passphrase",
+        "key_export",
+        "key_import",
+        "upgrade",
+        "recreate",
+        "import_tar",
+        "export_tar",
+        "serve",
+        "config",
+        "with_lock",
+        "break_lock",
+        "benchmark_crud",
+    ]
+
+    def __init__(self, *args, **kwargs):
+        """Turn the commands in `:class:`BorgAPI` into async methods.
+
+        View the `:class:`BorgAPI` for init arguments.
+        """
+        super().__init__(*args, **kwargs)
+
+        for cmd in self.CMDS:
+            synced = getattr(super(), cmd)
+            wrapped = self._force_async(synced)
+            setattr(self, cmd, wrapped)
+
+        self.pool = ThreadPoolExecutor()
+
+    def _force_async(self, fn):
+        """Turn a sync function to async function using threads."""
+
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            future = self.pool.submit(fn, *args, **kwargs)
+            return wrap_future(future)  # make it awaitable
 
-        result_list = [("benchmark", output["stdout"])]
-        return self._build_result(*result_list)
+        return wrapper