From 775b9f5560e87b329d0bea27d9cdb43fa79bb5e3 Mon Sep 17 00:00:00 2001
From: Thomas Waldmann <tw@waldmann-edv.de>
Date: Wed, 15 Nov 2023 23:01:26 +0100
Subject: [PATCH] extend errorlist script to warnings, update docs

---
 docs/internals/frontends.rst | 13 +++++++++++-
 scripts/errorlist.py         | 41 +++++++++++++++++++++++++++---------
 src/borg/helpers/errors.py   |  2 ++
 3 files changed, 45 insertions(+), 11 deletions(-)

diff --git a/docs/internals/frontends.rst b/docs/internals/frontends.rst
index dff1ca1c8..20e5f7edb 100644
--- a/docs/internals/frontends.rst
+++ b/docs/internals/frontends.rst
@@ -689,9 +689,20 @@ Errors
         Could not verify manifest: Unsupported suite {!r}; a newer version is needed.
 
 Warnings
+    BorgWarning rc: 1
+        Warning: {}
     FileChangedWarning rc: 100
+        {}: file changed while we backed it up
     IncludePatternNeverMatchedWarning rc: 101
-    BackupExcWarning rc: 102 (needs more work!)
+        Include pattern '{}' never matched.
+    BackupWarning rc: 102
+        {}: {}
+    BackupOSWarning rc: 104
+        {}: {}
+    PermissionWarning rc: 105
+        {}: {}
+    IOWarning rc: 106
+        {}: {}
 
 Operations
     - cache.begin_transaction
diff --git a/scripts/errorlist.py b/scripts/errorlist.py
index 204c9fc6c..ba9f675ad 100755
--- a/scripts/errorlist.py
+++ b/scripts/errorlist.py
@@ -5,7 +5,8 @@
 from textwrap import indent
 
 import borg.archiver  # noqa: F401 - need import to get Error subclasses.
-from borg.helpers import Error
+from borg.constants import *  # NOQA
+from borg.helpers import Error, BorgWarning
 
 
 def subclasses(cls):
@@ -17,26 +18,46 @@ def subclasses(cls):
 # 3..99 are available for specific errors
 # 100..127 are available for specific warnings
 # 128+ are reserved for signals
-free_rcs = set(range(3, 99+1))  # 3 .. 99 (we only deal with errors here)
+free_error_rcs = set(range(EXIT_ERROR_BASE, EXIT_WARNING_BASE))  # 3 .. 99
+free_warning_rcs = set(range(EXIT_WARNING_BASE, EXIT_SIGNAL_BASE))  # 100 .. 127
 
 # these classes map to rc 2
-generic_rc_classes = set()
+generic_error_rc_classes = set()
+generic_warning_rc_classes = set()
 
-classes = {Error}.union(subclasses(Error))
+error_classes = {Error}.union(subclasses(Error))
 
-for cls in sorted(classes, key=lambda cls: (cls.__module__, cls.__qualname__)):
+for cls in sorted(error_classes, key=lambda cls: (cls.__module__, cls.__qualname__)):
     traceback = "yes" if cls.traceback else "no"
     rc = cls.exit_mcode
     print('   ', cls.__qualname__, 'rc:', rc, 'traceback:', traceback)
     print(indent(cls.__doc__, ' ' * 8))
-    if rc in free_rcs:
-        free_rcs.remove(rc)
+    if rc in free_error_rcs:
+        free_error_rcs.remove(rc)
     elif rc == 2:
-        generic_rc_classes.add(cls.__qualname__)
+        generic_error_rc_classes.add(cls.__qualname__)
     else:  # rc != 2
         # if we did not intentionally map this to the generic error rc, this might be an issue:
         print(f'ERROR: {rc} is not a free/available RC, but either duplicate or invalid')
 
 print()
-print('free RCs:', sorted(free_rcs))
-print('generic errors:', sorted(generic_rc_classes))
+print('free error RCs:', sorted(free_error_rcs))
+print('generic errors:', sorted(generic_error_rc_classes))
+
+warning_classes = {BorgWarning}.union(subclasses(BorgWarning))
+
+for cls in sorted(warning_classes, key=lambda cls: (cls.__module__, cls.__qualname__)):
+    rc = cls.exit_mcode
+    print('   ', cls.__qualname__, 'rc:', rc)
+    print(indent(cls.__doc__, ' ' * 8))
+    if rc in free_warning_rcs:
+        free_warning_rcs.remove(rc)
+    elif rc == 1:
+        generic_warning_rc_classes.add(cls.__qualname__)
+    else:  # rc != 1
+        # if we did not intentionally map this to the generic warning rc, this might be an issue:
+        print(f'ERROR: {rc} is not a free/available RC, but either duplicate or invalid')
+
+print("\n")
+print('free warning RCs:', sorted(free_warning_rcs))
+print('generic warnings:', sorted(generic_warning_rc_classes))
diff --git a/src/borg/helpers/errors.py b/src/borg/helpers/errors.py
index 6d34b60d3..6c5232c4c 100644
--- a/src/borg/helpers/errors.py
+++ b/src/borg/helpers/errors.py
@@ -124,10 +124,12 @@ def exit_code(self):
 
 
 class PermissionWarning(BorgWarning):
+    """{}: {}"""
     exit_mcode = 105
 
 
 class IOWarning(BorgWarning):
+    """{}: {}"""
     exit_mcode = 106