borg-space 2.3__tar.gz → 2.5__tar.gz

{borg_space-2.3 → borg_space-2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: borg_space
-Version: 2.3
+Version: 2.5
 Summary: Accessory for Emborg used to report and track the size of your Borg repositories
 Keywords: emborg,borg,backups
 Author-email: Ken Kundert <borg-space@nurdletech.com>
@@ -39,11 +39,12 @@ Borg-Space — Report and track the size of your Emborg repositories
     :target: https://pypi.python.org/pypi/borg-space/
 
 :Author: Ken Kundert
-:Version: 2.3
-:Released: 2025-05-11
+:Version: 2.5
+:Released: 2026-06-28
 
-*Borg-Space* is an accessory for Emborg_.  It reports on the space consumed by 
-your *BorgBackup* repositories.  You can get this information using the
+*Borg-Space* is an accessory for Emborg_ and Assimilate_.  It reports on the 
+space consumed by your *BorgBackup* repositories.  You can get this information 
+using the
 ``emborg info`` command, but there are several reasons to prefer *Borg-Space*.
 
 #. *Borg-Space* is capable of reporting on many repositories at once.
@@ -131,6 +132,7 @@ You can create a NestedText_ settings file to specify default behaviors and
 define composite repositories.  For example::
 
     default repository: home
+    default path: ~{user}/.local/share/assimilate/{config}.latest.nt
     report style: tree
     compact format: {name}: {size:{fmt}}.  Last back up: {last_create:ddd, MMM DD}.  Last squeeze: {last_squeeze:ddd, MMM DD}.
     table format: {host:<8} {user:<5} {config:<9} {size:<8.2b} {last_create:ddd, MMM DD}
@@ -146,7 +148,11 @@ define composite repositories.  For example::
         dev: root@dev~root
         mail: root@mail~root
         files: root@files~root
-        bastion: root@bastion~root
+        bastion:
+            config: root
+            host: bastion
+            user: root
+            path: /root/.local/share/emborg/root.latest.nt
         media: root@media~root
         web: root@web~root
         cluster: home@cluster
@@ -166,7 +172,17 @@ define composite repositories.  For example::
             children: home servers root
 
 default repository:
-    The name of the repository to be used if none are given on the command line.
+    The name (or names) of the repository to be used if none are given on the 
+    command line.
+
+default path:
+    The path to the *Emborg* or *Assimilate* generated latest.nt files.  If not 
+    give, it defaults to::
+
+      ~{user}/.local/share/emborg/{config}.latest.nt
+
+    ``{config}`` and ``{user}`` are placeholders that are replaced by the 
+    corresponding component of the repository specification.
 
 report style:
     The report style to be used if none is specified on the command line.  
@@ -262,6 +278,7 @@ repositories:
                 config: home
                 host: host
                 user: user
+                path: ~user/.local/share/emborg/home.latest.nt
 
         repositiories:
             all: home@host~user work@host~user
@@ -280,6 +297,7 @@ repositories:
                     config: home
                     host: host
                     user: user
+                    path: ~user/.local/share/emborg/home.latest.nt
                 -
                     config: work
                     host: host
@@ -342,30 +360,25 @@ scaled nicely on the same graph::
 Installation
 ------------
 
-*Borg-Space* requires *Emborg* version 1.37 or newer.
+*Borg-Space* requires *Emborg* version 1.37 or newer or *Assimilate*.
 
 Install with::
 
     > pip3 install borg-space
 
 
-Borg 2
-------
+Assimilate and Borg 2
+---------------------
 
 Borg_ 2 will be released soon, and with it will come Assimilate_, the next 
 generation of Emborg_.  *Assimilate* is intended to be used with *Borg 2.0* and 
-beyond while *Emborg* would be used with older versions of *Borg*.  Currently 
-*Borg-Space* does not support *Assimilate* directly, but the *latest.nt* files 
-produced by *Assimilate* are compatible with *Borg-Space*, only their location 
-differs.  You can get the current version of *Borg-Space* to read *Assimilate* 
-*latest.nt* files by simply creating a symbolic link from the expected location 
-to the actual location.  For example, if you convert your *home* repository from 
-*Emborg* to *Assimilate*, you can use the following commands to get *Borg-Space* 
-to use the *latest.nt* file produced by *Assimilate*::
-
-    cd ~/.local/share/emborg
-    rm home.latest.nt
-    ln -s ../assimilate/home.latest.nt .
+beyond while *Emborg* would be used with older versions of *Borg*.  To use 
+*Assimilate* you should set the *default path* accordingly.  To support both 
+*Emborg* and *Assimilate* simultaneously, you should set *default path* for one 
+and then use *path* overrides for individual repositories.
+
+*Assimilate* only saves the space used by the repository when running 
+a *compact* command and only if the *get_repo_size* is set to ``'yes``.
 
 .. _assimilate: https://assimilate.readthedocs.io
 .. _borg: https://borgbackup.readthedocs.io

{borg_space-2.3 → borg_space-2.5}/README.rst

@@ -11,11 +11,12 @@ Borg-Space — Report and track the size of your Emborg repositories
     :target: https://pypi.python.org/pypi/borg-space/
 
 :Author: Ken Kundert
-:Version: 2.3
-:Released: 2025-05-11
+:Version: 2.5
+:Released: 2026-06-28
 
-*Borg-Space* is an accessory for Emborg_.  It reports on the space consumed by 
-your *BorgBackup* repositories.  You can get this information using the
+*Borg-Space* is an accessory for Emborg_ and Assimilate_.  It reports on the 
+space consumed by your *BorgBackup* repositories.  You can get this information 
+using the
 ``emborg info`` command, but there are several reasons to prefer *Borg-Space*.
 
 #. *Borg-Space* is capable of reporting on many repositories at once.
@@ -103,6 +104,7 @@ You can create a NestedText_ settings file to specify default behaviors and
 define composite repositories.  For example::
 
     default repository: home
+    default path: ~{user}/.local/share/assimilate/{config}.latest.nt
     report style: tree
     compact format: {name}: {size:{fmt}}.  Last back up: {last_create:ddd, MMM DD}.  Last squeeze: {last_squeeze:ddd, MMM DD}.
     table format: {host:<8} {user:<5} {config:<9} {size:<8.2b} {last_create:ddd, MMM DD}
@@ -118,7 +120,11 @@ define composite repositories.  For example::
         dev: root@dev~root
         mail: root@mail~root
         files: root@files~root
-        bastion: root@bastion~root
+        bastion:
+            config: root
+            host: bastion
+            user: root
+            path: /root/.local/share/emborg/root.latest.nt
         media: root@media~root
         web: root@web~root
         cluster: home@cluster
@@ -138,7 +144,17 @@ define composite repositories.  For example::
             children: home servers root
 
 default repository:
-    The name of the repository to be used if none are given on the command line.
+    The name (or names) of the repository to be used if none are given on the 
+    command line.
+
+default path:
+    The path to the *Emborg* or *Assimilate* generated latest.nt files.  If not 
+    give, it defaults to::
+
+      ~{user}/.local/share/emborg/{config}.latest.nt
+
+    ``{config}`` and ``{user}`` are placeholders that are replaced by the 
+    corresponding component of the repository specification.
 
 report style:
     The report style to be used if none is specified on the command line.  
@@ -234,6 +250,7 @@ repositories:
                 config: home
                 host: host
                 user: user
+                path: ~user/.local/share/emborg/home.latest.nt
 
         repositiories:
             all: home@host~user work@host~user
@@ -252,6 +269,7 @@ repositories:
                     config: home
                     host: host
                     user: user
+                    path: ~user/.local/share/emborg/home.latest.nt
                 -
                     config: work
                     host: host
@@ -314,30 +332,25 @@ scaled nicely on the same graph::
 Installation
 ------------
 
-*Borg-Space* requires *Emborg* version 1.37 or newer.
+*Borg-Space* requires *Emborg* version 1.37 or newer or *Assimilate*.
 
 Install with::
 
     > pip3 install borg-space
 
 
-Borg 2
-------
+Assimilate and Borg 2
+---------------------
 
 Borg_ 2 will be released soon, and with it will come Assimilate_, the next 
 generation of Emborg_.  *Assimilate* is intended to be used with *Borg 2.0* and 
-beyond while *Emborg* would be used with older versions of *Borg*.  Currently 
-*Borg-Space* does not support *Assimilate* directly, but the *latest.nt* files 
-produced by *Assimilate* are compatible with *Borg-Space*, only their location 
-differs.  You can get the current version of *Borg-Space* to read *Assimilate* 
-*latest.nt* files by simply creating a symbolic link from the expected location 
-to the actual location.  For example, if you convert your *home* repository from 
-*Emborg* to *Assimilate*, you can use the following commands to get *Borg-Space* 
-to use the *latest.nt* file produced by *Assimilate*::
-
-    cd ~/.local/share/emborg
-    rm home.latest.nt
-    ln -s ../assimilate/home.latest.nt .
+beyond while *Emborg* would be used with older versions of *Borg*.  To use 
+*Assimilate* you should set the *default path* accordingly.  To support both 
+*Emborg* and *Assimilate* simultaneously, you should set *default path* for one 
+and then use *path* overrides for individual repositories.
+
+*Assimilate* only saves the space used by the repository when running 
+a *compact* command and only if the *get_repo_size* is set to ``'yes``.
 
 .. _assimilate: https://assimilate.readthedocs.io
 .. _borg: https://borgbackup.readthedocs.io

{borg_space-2.3 → borg_space-2.5}/borg_space/config.py

@@ -32,7 +32,6 @@ if new_home:  # pragma: no cover
 
 # GLOBALS {{{1
 set_prefs(use_inform=True)
-settings_file = to_path(user_config_dir('borg-space')) / 'settings.nt'
 voluptuous_error_msg_mappings = {
     "extra keys not allowed": ("unknown key", "key"),
     "expected a dictionary": ("expected key:value pair", "value"),
@@ -41,24 +40,43 @@ voluptuous_key_prefix = "key contains"
 hostname = socket.gethostname().split('.')[0]
     # version of the hostname (the hostname without any domain name)
 username = pwd.getpwuid(os.getuid()).pw_name
+program_name = 'borg-space'
+if 'XDG_CONFIG_HOME' in os.environ:
+    config_dir = os.sep.join([os.environ['XDG_CONFIG_HOME'], program_name])
+else:
+    config_dir = user_config_dir(program_name)
+settings_file = to_path(config_dir) / 'settings.nt'
 
 
 # REPOSITORY {{{1
 # Repository class {{{2
 class Repository:
     def __init__(self, spec, name=None):
-        prefix, _, user = spec.partition('~')
-        config, _, host = prefix.partition('@')
+        if is_str(spec):
+            prefix, _, user = spec.partition('~')
+            config, _, host = prefix.partition('@')
+            path = None
+        else:
+            user = spec.get('user')
+            config = spec.get('config')
+            host = spec.get('host')
+            path = spec.get('path')
+            spec = spec.get('spec')
+
         if not config:
             raise Error("spec is missing Emborg config name.", culprit=spec)
         if not name:
             name = spec
 
-        self.spec = spec
-        self.name = name
-        self.config = a_name(config)
-        self.host = a_name(host) or hostname
-        self.user = a_name(user) or username
+        try:
+            self.spec = spec
+            self.name = name
+            self.config = a_name(config)
+            self.host = a_name(host) or hostname
+            self.user = a_name(user) or username
+            self.path = path
+        except Invalid as e:
+            raise Error(e, culprit=spec)
         self.latest = None
 
     def __str__(self):
@@ -87,14 +105,21 @@ class Repository:
             user = self.user,
             full_spec = str(self)
         )
-        info.update(self.latest)
+        if self.latest:
+            info.update(self.latest)
         return info
 
     def get_path(self):
         user = self.user if self.user else getpass.getuser()
         config = self.config
         assert config
-        path = f"~{user}/.local/share/emborg/{config}.latest.nt"
+        path = self.path
+        if not path:
+            path = settings.get(
+                'default_path',
+                "~{user}/.local/share/emborg/{config}.latest.nt"
+            )
+        path = path.format(user=user, config=config)
         return (self.host, path)
 
     def get_latest(self):
@@ -109,7 +134,7 @@ class Repository:
             try:
                 content = to_path(path).read_text()
             except FileNotFoundError:
-                raise Error('unknown repository.', culprit=str(self))
+                raise Error(f'repository not found: {path}', culprit=str(self))
         raw_data = nt.loads(content)
         self.latest = data = {}
         if 'repository size' in raw_data:
@@ -128,27 +153,27 @@ class Repository:
 def get_repos(spec):
     if not spec:
         spec = settings.get('default_repository')
-    if not spec:
-        raise Error('there is no default repository.')
 
-    try:
-        children = repositories[spec]
-    except (TypeError, KeyError):
-        # not found in repositories specified in settings file.
-        # see if it exists on local machine
-        children = [Repository(spec)]
-
-    results = {}
-    for child in children:
-        host, path = child.get_path()
-        name = str(child)
+    specs = spec.split()
+    for spec in specs:
         try:
-            child.get_latest()
-            results[name] = child
-        except Error as e:
-            e.report(culprit=name)
-        except OSError as e:
-            error(os_error(e), culprit=name)
+            children = repositories[spec]
+        except (TypeError, KeyError):
+            # not found in repositories specified in settings file.
+            # see if it exists on local machine
+            children = [Repository(spec)]
+
+        results = {}
+        for child in children:
+            # host, path = child.get_path()
+            name = str(child)
+            try:
+                child.get_latest()
+                results[name] = child
+            except Error as e:
+                e.report(culprit=name)
+            except OSError as e:
+                error(os_error(e), culprit=name)
     return results
 
 
@@ -168,7 +193,7 @@ def to_list(args):
     if is_str(args):
         args = args.split()
     if is_mapping(args):
-        raise Invalid(f"expected a list or string")
+        raise Invalid("expected a list or string")
     return args
 
 # a_name() {{{2
@@ -200,7 +225,7 @@ def a_spec(arg):
     if is_str(arg):
         return arg
     if is_mapping(arg):
-        unknown_keys = arg.keys() - set(['config', 'host', 'user'])
+        unknown_keys = arg.keys() - set(['config', 'host', 'user', 'path'])
         if unknown_keys:
             raise Invalid(f"unknown {plural(unknown_keys):key}: {conjoin(unknown_keys)}.")
         if 'config' not in arg:
@@ -210,7 +235,8 @@ def a_spec(arg):
             spec = f"{spec}@{arg.get('host')}"
         if arg.get('user'):
             spec = f"{spec}~{arg.get('user')}"
-        return spec
+        arg['spec'] = spec
+        return arg
     raise Invalid("expected a specification")
 
 # to_specs() {{{2
@@ -218,7 +244,7 @@ def to_specs(arg):
     if is_str(arg):
         return [a_spec(r) for r in arg.split()]
     if is_mapping(arg):
-        unknown_keys = arg.keys() - set(['config', 'host', 'user'])
+        unknown_keys = arg.keys() - set(['config', 'host', 'user', 'path'])
         if unknown_keys:
             raise Invalid(f"unknown {plural(unknown_keys):key}: {conjoin(unknown_keys)}.")
         return [a_spec(arg)]
@@ -230,6 +256,7 @@ def to_specs(arg):
 validate_settings = Schema({
     'repositories': {key_as_name: to_specs},
     'default_repository': str,
+    'default_path': str,
     'report_style': str,
     'compact_format': str,
     'table_format': str,
@@ -264,9 +291,12 @@ try:
                 repositories[name] = []
                 alias = name if len(specs) <= 1 else None
                 for spec in specs:
-                    if spec in repositories and spec != name:
+                    specname = spec
+                    if is_mapping(spec):
+                        specname = spec['spec']
+                    if specname in repositories and specname != name:
                         # this is a known (previously defined) repository
-                        repositories[name].extend(repositories[spec])
+                        repositories[name].extend(repositories[specname])
                     else:
                         repositories[name].append(Repository(spec, alias))
             else:
@@ -292,7 +322,7 @@ except MultipleInvalid as e:  # report schema violations
             flag = 'key'
         loc = keymap.get(tuple(err.path))
         codicil = loc.as_line(flag) if loc else None
-        keys = nt.join_keys(err.path, keymap=keymap)
+        keys = nt.get_keys(err.path, keymap=keymap, sep=', ')
         error(
             full_stop(msg),
             culprit = (settings_file, keys),

{borg_space-2.3 → borg_space-2.5}/borg_space/main.py

@@ -31,7 +31,7 @@ Settings are held in ~/.config/borg-space/settings.nt.
 """
 
 # imports {{{1
-from .config import settings, get_repos
+from .config import settings, get_repos, program_name
 import arrow
 from appdirs import user_data_dir
 from docopt import docopt
@@ -45,14 +45,18 @@ import matplotlib.pyplot as plt
 from matplotlib.dates import AutoDateFormatter, AutoDateLocator
 from matplotlib.ticker import FuncFormatter
 # from labellines import labelLines
+import os
 
 
 # globals {{{1
-data_dir = Path(user_data_dir('borg-space'))
+if 'XDG_DATA_HOME' in os.environ:
+    data_dir = Path(os.sep.join([os.environ['XDG_DATA_HOME'], program_name]))
+else:
+    data_dir = Path(user_data_dir(program_name))
 now = str(arrow.now())
 Quantity.set_prefs(prec='full')
-__version__ = "2.3"
-__released__ = "2025-05-11"
+__version__ = "2.5"
+__released__ = "2026-06-28"
 date_format = settings.get('date_format', 'D MMMM YYYY')
 size_format = settings.get('size_format', '.2b')
 nestedtext_size_format = settings.get('nestedtext_size_format', size_format)
@@ -65,6 +69,8 @@ not_available = "⟪not available⟫"
 # collect_repos() {{{1
 def collect_repos(requests, record_size):
     repos = {}
+    if not requests:
+        raise Error('there is no default repository.')
     for request in requests:
         new_repos = get_repos(request)
         repos.update(new_repos)
@@ -74,7 +80,7 @@ def collect_repos(requests, record_size):
         for name, repo in repos.items():
 
             # read previously recorded sizes
-            data_path = Path(data_dir / f'{name}.nt')
+            data_path = data_dir / f'{name}.nt'
             try:
                 data = nt.load(data_path, top=dict)
             except FileNotFoundError:
@@ -330,7 +336,7 @@ def main():
 
     requests = cmdline['<spec>']
     if not requests:
-        requests = ['']  # this gets the default config
+        requests = settings.get('default_repository', '').split()
 
     try:
         repos = collect_repos(requests, cmdline['--record'])

{borg_space-2.3 → borg_space-2.5}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "borg_space"
 dist-name = "borg-space"
-version = "2.3"
+version = "2.5"
 description = "Accessory for Emborg used to report and track the size of your Borg repositories"
 readme = "README.rst"
 requires-python = ">=3.6"
@@ -38,5 +38,18 @@ changelog = "https://github.com/KenKundert/ntlog/blob/master/CHANGELOG.rst"
 borg-space = "borg_space.main:main"
 
 [build-system]
-requires = ["flit_core >=2,<4"]
+requires = ["flit_core >=2"]
 build-backend = "flit_core.buildapi"
+
+[tool.pytest.ini_options]
+addopts = "--tb=short"
+
+[tool.ruff]
+exclude = [".tox", "doc", "Diffs"]
+
+[tool.ruff.lint]
+select = ["F"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"borg_space/__init__.py" = ["F401"]