From 5168a97782134699fb31ff7bdf74c6f053bf85f0 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   |  4 ++++
 3 files changed, 47 insertions(+), 11 deletions(-)

diff --git a/docs/internals/frontends.rst b/docs/internals/frontends.rst
index fd2b5b0f4..b054331a5 100644
--- a/docs/internals/frontends.rst
+++ b/docs/internals/frontends.rst
@@ -707,9 +707,20 @@ Errors
 
 
 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 735f11257..dba19aae0 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 931d6daf2..10012ef4b 100644
--- a/src/borg/helpers/errors.py
+++ b/src/borg/helpers/errors.py
@@ -135,10 +135,14 @@ def exit_code(self):
 
 
 class PermissionWarning(BorgWarning):
+    """{}: {}"""
+
     exit_mcode = 105
 
 
 class IOWarning(BorgWarning):
+    """{}: {}"""
+
     exit_mcode = 106