Keep the byte counts on NotEnoughFreeSpaceError

changes/426.changed

@@ -0,0 +1 @@
+Kept the byte counts on `NotEnoughFreeSpaceError` as attributes (`required`, `available`, `file_system`, `shortfall`) so callers no longer have to parse the message, and its message now reports those counts with thousands separators along with the remaining shortfall.

pyntc/errors.py

@@ -210,17 +210,39 @@ def __init__(self, hostname, min_space=None, *, required=None, available=None, f
         """
         Error for not having enough free space to transfer a file.
 
+        The byte counts are kept as attributes so callers can render their own message
+        (or compute the shortfall) without parsing ``message``. They are ``None`` when the
+        error is raised in the legacy ``min_space`` form.
+
         Args:
             hostname (str): The hostname of the device being checked.
             min_space (str, optional): The minimum amount of space required. Retained for
                 backward compatibility with callers that only know the required value.
             required (int, optional): Required bytes for the pending transfer.
             available (int, optional): Free bytes currently available on the target filesystem.
             file_system (str, optional): The target filesystem that was checked.
+
+        Attributes:
+            hostname (str): The hostname of the device being checked.
+            min_space (str, optional): The minimum amount of space required, legacy form only.
+            required (int, optional): Required bytes for the pending transfer.
+            available (int, optional): Free bytes currently available on the target filesystem.
+            file_system (str, optional): The target filesystem that was checked.
+            shortfall (int, optional): Bytes still needed for the transfer to succeed.
         """
-        if required is not None and available is not None:
+        self.hostname = hostname
+        self.min_space = min_space
+        self.required = required
+        self.available = available
+        self.file_system = file_system
+        self.shortfall = required - available if required is not None and available is not None else None
+
+        if self.shortfall is not None:
             location = f"{file_system} " if file_system else ""
-            message = f"{hostname}: {location}has {available} bytes free; {required} bytes required for transfer"
+            message = (
+                f"{hostname}: {location}has {available:,} bytes free; {required:,} bytes required for transfer "
+                f"({self.shortfall:,} more bytes required to succeed)"
+            )
         else:
             message = f"{hostname} does not meet the minimum disk space requirements of {min_space}"
         super().__init__(message)

tests/unit/test_errors.py

@@ -138,6 +138,47 @@ def test_not_enough_free_space_error():
     assert err.value.message == error_message
 
 
+def test_not_enough_free_space_error_legacy_form_leaves_byte_counts_unset():
+    error = ntc_errors.NotEnoughFreeSpaceError("host1", 1000)
+
+    assert error.min_space == 1000
+    assert error.required is None
+    assert error.available is None
+    assert error.file_system is None
+    assert error.shortfall is None
+
+
+def test_not_enough_free_space_error_keeps_byte_counts_as_attributes():
+    error = ntc_errors.NotEnoughFreeSpaceError(
+        hostname="host1", required=313456789, available=13456789, file_system="bootflash:"
+    )
+
+    assert error.hostname == "host1"
+    assert error.required == 313456789
+    assert error.available == 13456789
+    assert error.file_system == "bootflash:"
+    assert error.shortfall == 300000000
+
+
+def test_not_enough_free_space_error_message_reports_counts_and_shortfall():
+    error = ntc_errors.NotEnoughFreeSpaceError(
+        hostname="host1", required=313456789, available=13456789, file_system="bootflash:"
+    )
+
+    assert error.message == (
+        "host1: bootflash: has 13,456,789 bytes free; 313,456,789 bytes required for transfer "
+        "(300,000,000 more bytes required to succeed)"
+    )
+
+
+def test_not_enough_free_space_error_message_omits_file_system_when_unknown():
+    error = ntc_errors.NotEnoughFreeSpaceError(hostname="host1", required=2500, available=500)
+
+    assert error.message == (
+        "host1: has 500 bytes free; 2,500 bytes required for transfer (2,000 more bytes required to succeed)"
+    )
+
+
 def test_os_install_error():
     error_message = "host1 was unable to boot into v1.2.3"
     error_class = ntc_errors.OSInstallError