Additions to the client exceptions

I made a review on all files inside tuf/ngclient to see which of them
needs additions or changes in their function docstrings regarding
exceptions.

I didn't find any changes required inside the request_fetcher.py
and of course inside the config module.
Other than that multiple additions had to be made.

For trusted_metadata_set we had a discussion with Jussi that there is
no need to list each of the specific RepositoryErrors one by one as
this is an internal module and this will only create a bigger
maintenance burden.

For updater.py we had discussions with Jussi and Lukas that we want to
document only those exceptions that could be potentially handled.
This means there is no point in documenting each of the RepositoryErrors
or DownloadErrors separately.

Finally, I added a little documentation for download_bytes() inside
fetcher.py, as it's naming, suggests it's not an internal function.

Signed-off-by: Martin Vrachev <mvrachev@vmware.com>

tuf/ngclient/_internal/trusted_metadata_set.py

@@ -150,6 +150,7 @@ def update_root(self, data: bytes) -> Metadata[Root]:
             data: unverified new root metadata as bytes
 
         Raises:
+            RuntimeError: This function is called after updating timestamp.
             RepositoryError: Metadata failed to load or verify. The actual
                 error type and content will contain more details.
 
@@ -198,6 +199,7 @@ def update_timestamp(self, data: bytes) -> Metadata[Timestamp]:
             data: unverified new timestamp metadata as bytes
 
         Raises:
+            RuntimeError: This function is called after updating snapshot.
             RepositoryError: Metadata failed to load or verify as final
                 timestamp. The actual error type and content will contain
                 more details.
@@ -281,6 +283,8 @@ def update_snapshot(
                 match data. Default is False.
 
         Raises:
+            RuntimeError: This function is called before updating timestamp
+                or after updating targets.
             RepositoryError: data failed to load or verify as final snapshot.
                 The actual error type and content will contain more details.
 
@@ -385,6 +389,7 @@ def update_delegated_targets(
             delegator_name: The name of the role delegating to the new metadata
 
         Raises:
+            RuntimeError: This function is called before updating snapshot.
             RepositoryError: Metadata failed to load or verify. The actual
                 error type and content will contain more details.
 

tuf/ngclient/fetcher.py

@@ -90,6 +90,17 @@ def download_bytes(self, url: str, max_length: int) -> bytes:
         """Download bytes from given url
 
         Returns the downloaded bytes, otherwise like download_file()
+
+        Args:
+            url: a URL string that represents the location of the file.
+            max_length: upper bound of data size in bytes.
+
+        Raises:
+            exceptions.DownloadLengthMismatchError: downloaded bytes exceed
+                'max_length'.
+
+        Returns:
+            The content of the file in bytes.
         """
         with self.download_file(url, max_length) as dl_file:
             return dl_file.read()

tuf/ngclient/updater.py

@@ -39,6 +39,7 @@
 from typing import Optional, Set
 from urllib import parse
 
+from securesystemslib import exceptions as sslib_exceptions
 from securesystemslib import util as sslib_util
 
 from tuf.api import exceptions
@@ -121,7 +122,7 @@ def refresh(self) -> None:
         Raises:
             OSError: New metadata could not be written to disk
             RepositoryError: Metadata failed to verify in some way
-            TODO: download-related errors
+            DownloadError: Download of a metadata file failed in some way
         """
 
         self._load_root()
@@ -157,7 +158,7 @@ def get_targetinfo(self, target_path: str) -> Optional[TargetFile]:
         Raises:
             OSError: New metadata could not be written to disk
             RepositoryError: Metadata failed to verify in some way
-            TODO: download-related errors
+            DownloadError: Download of a metadata file failed in some way
 
         Returns:
             A TargetFile instance or None.
@@ -216,8 +217,9 @@ def download_target(
 
         Raises:
             ValueError: Invalid arguments
-            TODO: download-related errors
-            TODO: file write errors
+            DownloadError: Download of the target file failed in some way
+            RepositoryError: Downloaded target failed to be verified in some way
+            OSError: Downloaded target could not be written to disk
 
         Returns:
             Local path to downloaded file
@@ -250,7 +252,10 @@ def download_target(
         ) as target_file:
             targetinfo.verify_length_and_hashes(target_file)
 
-            sslib_util.persist_temp_file(target_file, filepath)
+            try:
+                sslib_util.persist_temp_file(target_file, filepath)
+            except sslib_exceptions.StorageError as e:
+                raise OSError() from e
 
         logger.info("Downloaded target %s", targetinfo.path)
         return filepath