Add missing exceptions documentation

The missing exceptions documentation that was added is related to the
code for the "storage_backend" and its API calls.

Signed-off-by: Martin Vrachev <[email protected]>

Author: MVrachev

securesystemslib/hash.py

@@ -343,6 +343,8 @@ def digest_filename(filename, algorithm=DEFAULT_HASH_ALGORITHM,
     securesystemslib.exceptions.UnsupportedLibraryError, if the given
     'hash_library' is unsupported.
 
+    securesystemslib.exceptions.StorageError, if the file cannot be opened.
+
   <Side Effects>
     None.
 

securesystemslib/util.py

@@ -59,7 +59,8 @@ def get_file_details(
     securesystemslib.exceptions.FormatError: If hash of the file does not match
     HASHDICT_SCHEMA.
 
-    securesystemslib.exceptions.Error: If 'filepath' does not exist.
+    securesystemslib.exceptions.StorageError: The file at "filepath" cannot be
+    opened or found.
 
   <Returns>
     A tuple (length, hashes) describing 'filepath'.
@@ -107,7 +108,8 @@ def get_file_hashes(
     securesystemslib.exceptions.FormatError: If hash of the file does not match
     HASHDICT_SCHEMA.
 
-    securesystemslib.exceptions.Error: If 'filepath' does not exist.
+    securesystemslib.exceptions.StorageError: The file at "filepath" cannot be
+    opened or found.
 
   <Returns>
     A dictionary conforming to securesystemslib.formats.HASHDICT_SCHEMA
@@ -156,7 +158,8 @@ def get_file_length(
       passed a FilesystemBackend will be instantiated and used.
 
   <Exceptions>
-    securesystemslib.exceptions.Error: If 'filepath' does not exist.
+    securesystemslib.exceptions.StorageError: The file at "filepath" cannot be
+    opened or found.
 
   <Returns>
     The length, in bytes, of the file at 'filepath'.
@@ -240,6 +243,7 @@ def ensure_parent_dir(
   <Exceptions>
     securesystemslib.exceptions.FormatError: If 'filename' is improperly
     formatted.
+    securesystemslib.exceptions.StorageError: When folder cannot be created.
 
   <Side Effects>
     A directory is created whenever the parent directory of 'filename' does not
@@ -378,6 +382,8 @@ def load_json_file(
     securesystemslib.exceptions.Error: If 'filepath' cannot be deserialized to
     a Python object.
 
+    securesystemslib.exceptions.StorageError: If file cannot be loaded.
+
     IOError in case of runtime IO exceptions.
 
   <Side Effects>

tests/test_util.py

@@ -68,7 +68,7 @@ def test_B1_get_file_details(self):
 
     for bogus_input in bogus_inputs:
       if isinstance(bogus_input, str):
-        self.assertRaises(securesystemslib.exceptions.Error,
+        self.assertRaises(securesystemslib.exceptions.StorageError,
             securesystemslib.util.get_file_details, bogus_input)
       else:
         self.assertRaises(securesystemslib.exceptions.FormatError,
@@ -96,7 +96,7 @@ def test_B2_get_file_hashes(self):
 
     for bogus_input in bogus_inputs:
       if isinstance(bogus_input, str):
-        self.assertRaises(securesystemslib.exceptions.Error,
+        self.assertRaises(securesystemslib.exceptions.StorageError,
             securesystemslib.util.get_file_hashes, bogus_input)
       else:
         self.assertRaises(securesystemslib.exceptions.FormatError,
@@ -123,7 +123,7 @@ def test_B3_get_file_length(self):
 
     for bogus_input in bogus_inputs:
       if isinstance(bogus_input, str):
-        self.assertRaises(securesystemslib.exceptions.Error,
+        self.assertRaises(securesystemslib.exceptions.StorageError,
             securesystemslib.util.get_file_length, bogus_input)
       else:
         self.assertRaises(securesystemslib.exceptions.FormatError,
@@ -144,6 +144,10 @@ def  test_B4_ensure_parent_dir(self):
         self.assertRaises(securesystemslib.exceptions.FormatError,
             securesystemslib.util.ensure_parent_dir, parent_dir)
 
+    # Check that when a folder cannot be created a StorageError is thrown
+    with self.assertRaises(securesystemslib.exceptions.StorageError):
+      securesystemslib.util.ensure_parent_dir("/a/file.txt")
+
     # When we call ensure_parent_dir with filepath arg like "a.txt",
     # then the directory of that filepath will be an empty string.
     # We want to make sure that securesyslib.storage.create_folder()