Replace required_length with max_length

Rename required_length argument in fetcher to
max_length to better match its purpose.
Docstring improvements.

Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>

Author: sechkova

tuf/ngclient/_internal/requests_fetcher.py

@@ -53,15 +53,15 @@ def __init__(self):
         self.chunk_size: int = 400000  # bytes
         self.sleep_before_round: Optional[int] = None
 
-    def fetch(self, url: str, required_length: int) -> Iterator[bytes]:
+    def fetch(self, url: str, max_length: int) -> Iterator[bytes]:
         """Fetches the contents of HTTP/HTTPS url from a remote server.
 
-        Ensures the length of the downloaded data is up to 'required_length'.
+        Ensures the length of the downloaded data is up to 'max_length'.
 
         Arguments:
             url: A URL string that represents a file location.
-            required_length: An integer value representing the file length in
-                bytes.
+            max_length: An integer value representing the maximum
+                number of bytes to be downloaded.
 
         Raises:
             exceptions.SlowRetrievalError: A timeout occurs while receiving
@@ -90,10 +90,10 @@ def fetch(self, url: str, required_length: int) -> Iterator[bytes]:
             status = e.response.status_code
             raise exceptions.FetcherHTTPError(str(e), status)
 
-        return self._chunks(response, required_length)
+        return self._chunks(response, max_length)
 
     def _chunks(
-        self, response: "requests.Response", required_length: int
+        self, response: "requests.Response", max_length: int
     ) -> Iterator[bytes]:
         """A generator function to be returned by fetch. This way the
         caller of fetch can differentiate between connection and actual data
@@ -113,7 +113,7 @@ def _chunks(
 
                 read_amount = min(
                     self.chunk_size,
-                    required_length - bytes_received,
+                    max_length - bytes_received,
                 )
 
                 # NOTE: This may not handle some servers adding a
@@ -131,13 +131,13 @@ def _chunks(
 
                 yield data
 
-                if bytes_received >= required_length:
+                if bytes_received >= max_length:
                     break
 
             logger.debug(
                 "Downloaded %d out of %d bytes",
                 bytes_received,
-                required_length,
+                max_length,
             )
 
         except urllib3.exceptions.ReadTimeoutError as e:

tuf/ngclient/fetcher.py

@@ -29,15 +29,15 @@ class FetcherInterface:
     __metaclass__ = abc.ABCMeta
 
     @abc.abstractmethod
-    def fetch(self, url: str, required_length: int) -> Iterator[bytes]:
+    def fetch(self, url: str, max_length: int) -> Iterator[bytes]:
         """Fetches the contents of HTTP/HTTPS url from a remote server.
 
-        Ensures the length of the downloaded data is up to 'required_length'.
+        Ensures the length of the downloaded data is up to 'max_length'.
 
         Arguments:
             url: A URL string that represents a file location.
-            required_length: An integer value representing the file length in
-                bytes.
+            max_length: An integer value representing the maximum
+                number of bytes to be downloaded.
 
         Raises:
             tuf.exceptions.SlowRetrievalError: A timeout occurs while receiving
@@ -50,21 +50,20 @@ def fetch(self, url: str, required_length: int) -> Iterator[bytes]:
         raise NotImplementedError  # pragma: no cover
 
     @contextmanager
-    def download_file(self, url: str, required_length: int) -> Iterator[IO]:
+    def download_file(self, url: str, max_length: int) -> Iterator[IO]:
         """Opens a connection to 'url' and downloads the content
-        up to 'required_length'.
+        up to 'max_length'.
 
         Args:
           url: a URL string that represents the location of the file.
-          required_length: an integer value representing the length of
-              the file or an upper boundary.
+          max_length: an integer value representing the length of
+              the file or an upper bound.
 
         Raises:
-          DownloadLengthMismatchError: a mismatch of observed vs expected
-              lengths while downloading the file.
+          DownloadLengthMismatchError: downloaded bytes exceed 'max_length'.
 
         Yields:
-          A file object that points to the contents of 'url'.
+          A TemporaryFile object that points to the contents of 'url'.
         """
         # 'url.replace('\\', '/')' is needed for compatibility with
         # Windows-based systems, because they might use back-slashes in place
@@ -78,21 +77,21 @@ def download_file(self, url: str, required_length: int) -> Iterator[IO]:
         number_of_bytes_received = 0
 
         with tempfile.TemporaryFile() as temp_file:
-            chunks = self.fetch(url, required_length)
+            chunks = self.fetch(url, max_length)
             for chunk in chunks:
                 temp_file.write(chunk)
                 number_of_bytes_received += len(chunk)
-            if number_of_bytes_received > required_length:
+            if number_of_bytes_received > max_length:
                 raise exceptions.DownloadLengthMismatchError(
-                    required_length, number_of_bytes_received
+                    max_length, number_of_bytes_received
                 )
             temp_file.seek(0)
             yield temp_file
 
-    def download_bytes(self, url: str, required_length: int) -> bytes:
+    def download_bytes(self, url: str, max_length: int) -> bytes:
         """Download bytes from given url
 
         Returns the downloaded bytes, otherwise like download_file()
         """
-        with self.download_file(url, required_length) as dl_file:
+        with self.download_file(url, max_length) as dl_file:
             return dl_file.read()