declarative-data-backup 0.4.1__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/PKG-INFO +3 -1
  2. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/README.md +2 -0
  3. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/pyproject.toml +1 -1
  4. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/backup.py +19 -0
  5. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/environment.py +13 -0
  6. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup.egg-info/PKG-INFO +3 -1
  7. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/tests/test_backup.py +17 -3
  8. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/setup.cfg +0 -0
  9. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/__init__.py +0 -0
  10. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/__main__.py +0 -0
  11. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/borg/__init__.py +0 -0
  12. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/borg/archive_naming.py +0 -0
  13. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/borg/borg.py +0 -0
  14. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/borg/borg_cli.py +0 -0
  15. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/config/__init__.py +0 -0
  16. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/config/backup_config/__init__.py +0 -0
  17. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/config/backup_config/models.py +0 -0
  18. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/config/backup_config/utils.py +0 -0
  19. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/config/backup_config/yaml_parser.py +0 -0
  20. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/config/backup_config/yaml_raw_loader.py +0 -0
  21. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/config/logging.py +0 -0
  22. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup/errors.py +0 -0
  23. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup.egg-info/SOURCES.txt +0 -0
  24. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup.egg-info/dependency_links.txt +0 -0
  25. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup.egg-info/requires.txt +0 -0
  26. {declarative_data_backup-0.4.1 → declarative_data_backup-0.5.0}/src/declarative_data_backup.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: declarative-data-backup
3
- Version: 0.4.1
3
+ Version: 0.5.0
4
4
  Summary: Declarative Borg-based data backups
5
5
  Requires-Python: >=3.11
6
6
  Description-Content-Type: text/markdown
@@ -149,6 +149,8 @@ Optional variables:
149
149
  | --- | --- |
150
150
  | `BORG_REMOTE_PATH` | Remote Borg executable path, passed as Borg's `--remote-path`. Leave unset to use Borg's default. |
151
151
  | `BORG_EXIT_CODES` | Borg exit-code mode: `legacy` or `modern`. |
152
+ | `BORG_FILES_CACHE_TTL` | How many archive creations can pass without a file appearing before Borg forgets its cached metadata. The default is `20`; raise it if more than 20 archives are created between backups of the same source, so unchanged files can still be recognized. |
153
+ | `BACKUP_FAILURES_PATH` | Optional absolute path where failed backup group names are written as JSON. |
152
154
  | `BACKUP_PROGRESS` | Set to `true` to log the latest Borg progress every 30 seconds during archive creation. Defaults to `false`. |
153
155
  | `BACKUP_VERBOSE` | Set to `true` to show Borg's per-file create and per-archive prune output. Defaults to `false` for concise logs. |
154
156
 
@@ -141,6 +141,8 @@ Optional variables:
141
141
  | --- | --- |
142
142
  | `BORG_REMOTE_PATH` | Remote Borg executable path, passed as Borg's `--remote-path`. Leave unset to use Borg's default. |
143
143
  | `BORG_EXIT_CODES` | Borg exit-code mode: `legacy` or `modern`. |
144
+ | `BORG_FILES_CACHE_TTL` | How many archive creations can pass without a file appearing before Borg forgets its cached metadata. The default is `20`; raise it if more than 20 archives are created between backups of the same source, so unchanged files can still be recognized. |
145
+ | `BACKUP_FAILURES_PATH` | Optional absolute path where failed backup group names are written as JSON. |
144
146
  | `BACKUP_PROGRESS` | Set to `true` to log the latest Borg progress every 30 seconds during archive creation. Defaults to `false`. |
145
147
  | `BACKUP_VERBOSE` | Set to `true` to show Borg's per-file create and per-archive prune output. Defaults to `false` for concise logs. |
146
148
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "declarative-data-backup"
7
- version = "0.4.1"
7
+ version = "0.5.0"
8
8
  description = "Declarative Borg-based data backups"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -1,3 +1,4 @@
1
+ import json
1
2
  import logging
2
3
  import os
3
4
  import signal
@@ -21,6 +22,20 @@ from .errors import BackupError, BackupInterrupted, BorgWarningError
21
22
  logger = logging.getLogger(__name__)
22
23
 
23
24
 
25
+ def write_failed_groups(settings: Environment, groups: set[str]) -> None:
26
+ path = settings.failure_groups_path
27
+ if path is None or not groups:
28
+ return
29
+ try:
30
+ path.write_text(json.dumps(sorted(groups)), encoding="utf-8")
31
+ except OSError as exc:
32
+ logger.warning(
33
+ "Unable to write failed backup group summary to %s: %s",
34
+ path,
35
+ exc.strerror or "I/O error",
36
+ )
37
+
38
+
24
39
  def check_settings(settings: Environment) -> None:
25
40
  ensure_borg_binary()
26
41
  if not settings.borg_base_dir.is_dir():
@@ -58,6 +73,7 @@ def run_backup(
58
73
  created_at = datetime.now(UTC)
59
74
  successful_definitions = []
60
75
  failures: list[BackupError] = []
76
+ failed_groups: set[str] = set()
61
77
  for definition in definitions:
62
78
  logger.info(
63
79
  "Starting backup group '%s' (%d sources).",
@@ -83,6 +99,7 @@ def run_backup(
83
99
  exc,
84
100
  )
85
101
  failures.append(exc)
102
+ failed_groups.add(definition.name)
86
103
  continue
87
104
 
88
105
  logger.info("Backup group '%s' completed.", definition.name)
@@ -111,6 +128,7 @@ def run_backup(
111
128
  exc,
112
129
  )
113
130
  failures.append(exc)
131
+ failed_groups.add(definition.name)
114
132
  pruning_succeeded = False
115
133
 
116
134
  if pruning_succeeded:
@@ -119,6 +137,7 @@ def run_backup(
119
137
  )
120
138
 
121
139
  if failures:
140
+ write_failed_groups(settings, failed_groups)
122
141
  message = "; ".join(str(failure) for failure in failures)
123
142
  if any(isinstance(failure, BorgWarningError) for failure in failures):
124
143
  raise BorgWarningError(message)
@@ -19,6 +19,7 @@ class Environment:
19
19
  borg_exit_codes: str | None
20
20
  backup_progress: bool
21
21
  backup_verbose: bool
22
+ failure_groups_path: Path | None = None
22
23
 
23
24
  @classmethod
24
25
  def from_env(
@@ -42,6 +43,17 @@ class Environment:
42
43
  fail(f"{name} must be an absolute path.")
43
44
  return value
44
45
 
46
+ def optional_path(name: str) -> Path | None:
47
+ raw_value = source.get(name)
48
+ if raw_value is None:
49
+ return None
50
+ if "\0" in raw_value:
51
+ fail(f"{name} must be a valid absolute path.")
52
+ value = Path(raw_value)
53
+ if not value.is_absolute():
54
+ fail(f"{name} must be an absolute path.")
55
+ return value
56
+
45
57
  repo = required("BORG_REPO")
46
58
  if "\0" in repo:
47
59
  fail("BORG_REPO must be a valid repository location.")
@@ -72,6 +84,7 @@ class Environment:
72
84
  borg_exit_codes=borg_exit_codes,
73
85
  backup_progress=backup_progress_value == "true",
74
86
  backup_verbose=backup_verbose_value == "true",
87
+ failure_groups_path=optional_path("BACKUP_FAILURES_PATH"),
75
88
  )
76
89
 
77
90
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: declarative-data-backup
3
- Version: 0.4.1
3
+ Version: 0.5.0
4
4
  Summary: Declarative Borg-based data backups
5
5
  Requires-Python: >=3.11
6
6
  Description-Content-Type: text/markdown
@@ -149,6 +149,8 @@ Optional variables:
149
149
  | --- | --- |
150
150
  | `BORG_REMOTE_PATH` | Remote Borg executable path, passed as Borg's `--remote-path`. Leave unset to use Borg's default. |
151
151
  | `BORG_EXIT_CODES` | Borg exit-code mode: `legacy` or `modern`. |
152
+ | `BORG_FILES_CACHE_TTL` | How many archive creations can pass without a file appearing before Borg forgets its cached metadata. The default is `20`; raise it if more than 20 archives are created between backups of the same source, so unchanged files can still be recognized. |
153
+ | `BACKUP_FAILURES_PATH` | Optional absolute path where failed backup group names are written as JSON. |
152
154
  | `BACKUP_PROGRESS` | Set to `true` to log the latest Borg progress every 30 seconds during archive creation. Defaults to `false`. |
153
155
  | `BACKUP_VERBOSE` | Set to `true` to show Borg's per-file create and per-archive prune output. Defaults to `false` for concise logs. |
154
156
 
@@ -1,3 +1,4 @@
1
+ import json
1
2
  import logging
2
3
 
3
4
  import declarative_data_backup.backup as backup
@@ -6,7 +7,7 @@ from declarative_data_backup.errors import BackupError, BorgWarningError
6
7
 
7
8
 
8
9
  def _settings_environment(settings: Environment) -> dict[str, str]:
9
- return {
10
+ environment = {
10
11
  "BACKUP_CONFIG_PATH": str(settings.config_path),
11
12
  "BORG_KEY_FILE": str(settings.key_file),
12
13
  "BORG_REPO": settings.borg_repo,
@@ -15,6 +16,9 @@ def _settings_environment(settings: Environment) -> dict[str, str]:
15
16
  "BORG_RSH": settings.borg_rsh,
16
17
  "BORG_PASSCOMMAND": settings.borg_passcommand,
17
18
  }
19
+ if settings.failure_groups_path is not None:
20
+ environment["BACKUP_FAILURES_PATH"] = str(settings.failure_groups_path)
21
+ return environment
18
22
 
19
23
 
20
24
  def _write_config(settings, contents: str) -> None:
@@ -83,8 +87,12 @@ def test_main_warning_skips_failed_group_but_prunes_successful_groups(
83
87
  settings_factory,
84
88
  monkeypatch,
85
89
  caplog,
90
+ tmp_path,
86
91
  ):
87
- settings = settings_factory()
92
+ failure_groups_path = tmp_path / "failed-groups.json"
93
+ settings = settings_factory(
94
+ environment={"BACKUP_FAILURES_PATH": str(failure_groups_path)}
95
+ )
88
96
  first = settings.server_root / "first"
89
97
  second = settings.server_root / "second"
90
98
  first.mkdir()
@@ -117,6 +125,7 @@ def test_main_warning_skips_failed_group_but_prunes_successful_groups(
117
125
  ]
118
126
  assert "warnings" in caplog.text
119
127
  assert str(first) in caplog.text
128
+ assert json.loads(failure_groups_path.read_text(encoding="utf-8")) == ["failed"]
120
129
 
121
130
 
122
131
  def test_main_interruption_returns_130_without_pruning(
@@ -245,8 +254,12 @@ def test_main_missing_borg_binary_returns_nonzero(
245
254
  def test_main_prune_failure_is_nonzero_and_scoped(
246
255
  settings_factory,
247
256
  monkeypatch,
257
+ tmp_path,
248
258
  ):
249
- settings = settings_factory()
259
+ failure_groups_path = tmp_path / "failed-groups.json"
260
+ settings = settings_factory(
261
+ environment={"BACKUP_FAILURES_PATH": str(failure_groups_path)}
262
+ )
250
263
  first = settings.server_root / "first"
251
264
  second = settings.server_root / "second"
252
265
  first.mkdir()
@@ -276,6 +289,7 @@ def test_main_prune_failure_is_nonzero_and_scoped(
276
289
  ("prune", first),
277
290
  ("prune", second),
278
291
  ]
292
+ assert json.loads(failure_groups_path.read_text(encoding="utf-8")) == ["media"]
279
293
 
280
294
 
281
295
  def test_exclusions_are_passed_only_to_their_backup_group(