Update download_target docstring

sechkova · sechkova · commit aa3a635f62c1 · 2020-10-23T17:35:55.000+03:00
Add a detailed documentation of custom_download_handler.

Signed-off-by: Teodora Sechkova &lt;tsechkova@vmware.com&gt;
diff --git a/tuf/client/updater.py b/tuf/client/updater.py
@@ -3249,25 +3249,36 @@ def download_target(self, target, destination_directory,
 
      custom_download_handler:
         A user provided function performing the actual target file download.
-        In order to comply with the TUF specification, the function signature
-        should have the form:
+        In order to comply with the TUF specification, the function implementation
+        should match the following description:
 
-        'def download_handler_func(url, required_length)'
+        def download_handler_func(url, required_length)
+          <Purpose>
+            Given the 'url' and 'required_length' of the desired file, open a connection
+            to 'url', download it, and return the contents of the file.  Also ensure
+            the length of the downloaded file matches 'required_length' exactly.
 
-        The function implementation should provide the following functionality:
+          <Arguments>
+            url:
+              A URL string that represents the location of the file.
 
-        'Given the 'url' and 'required_length' of the desired file, open a
-        connection to 'url', download it, and return the contents of the file.
-        Also ensure the length of the downloaded file matches 'required_length'
-        exactly'
+            required_length:
+              An integer value representing the length of the file.  This is an exact
+              limit.
 
-        Raise 'securesystemslib.exceptions.DownloadLengthMismatchError', if
-        STRICT_REQUIRED_LENGTH is True and total_downloaded is not equal
-        required_length.
+          <Side Effects>
+            A temprorary file object is created to store the contents of 'url'.
 
-        Raise 'tuf.exceptions.SlowRetrievalError', if the total downloaded was
-        done in less than the acceptable download speed (as set in
-        tuf.settings.py).
+          <Exceptions>
+            DownloadLengthMismatchError, if there was a
+            mismatch of observed vs expected lengths while downloading the file.
+
+            SlowRetrievalError, if the total downloaded was
+            done in less than the acceptable download speed (as set in
+             tuf.settings.py).
+
+          <Returns>
+            A temporay file object that points to the contents of 'url'.
 
         If None, tuf.download.safe_download is used.
 
