Add type annotations

Add missing type annotations in download.py, fetcher.py
and requests_fetcher.py
Update docstrings to match the new style.

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

Author: sechkova

tuf/ngclient/_internal/download.py

@@ -1,61 +1,37 @@
-#!/usr/bin/env python
-
 # Copyright 2012 - 2017, New York University and the TUF contributors
 # SPDX-License-Identifier: MIT OR Apache-2.0
 
+"""Handles the download of URL contents to a file"
 """
-<Program Name>
-  download.py
-
-<Started>
-  February 21, 2012.  Based on previous version by Geremy Condra.
-
-<Author>
-  Konstantin Andrianov
-  Vladimir Diaz <vladimir.v.diaz@gmail.com>
-
-<Copyright>
-  See LICENSE-MIT OR LICENSE for licensing information.
 
-<Purpose>
-  Download metadata and target files and check their validity.  The hash and
-  length of a downloaded file has to match the hash and length supplied by the
-  metadata of that file.
-"""
 import logging
 import tempfile
 from contextlib import contextmanager
+from typing import IO, Iterator
 from urllib import parse
 
 from tuf import exceptions
 
 logger = logging.getLogger(__name__)
 
-@contextmanager
-def download_file(url, required_length, fetcher):
-    """
-    <Purpose>
-      Given the url and length of the desired file, this function opens a
-      connection to 'url' and downloads the file up to 'required_length'.
 
-    <Arguments>
-      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.
-
-    <Side Effects>
-      A file object is created on disk to store the contents of 'url'.
-
-    <Exceptions>
-      exceptions.DownloadLengthMismatchError, if there was a
-      mismatch of observed vs expected lengths while downloading the file.
-
-      Any other unforeseen runtime exception.
-
-    <Returns>
+@contextmanager
+def download_file(
+    url: str, required_length: int, fetcher: "FetcherInterface"
+) -> Iterator[IO]:
+    """Opens a connection to 'url' and downloads the content
+    up to 'required_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.
+
+    Raises:
+      DownloadLengthMismatchError: a mismatch of observed vs expected
+          lengths while downloading the file.
+
+    Returns:
       A file object that points to the contents of 'url'.
     """
     # 'url.replace('\\', '/')' is needed for compatibility with Windows-based
@@ -82,7 +58,9 @@ def download_file(url, required_length, fetcher):
         yield temp_file
 
 
-def download_bytes(url, required_length, fetcher):
+def download_bytes(
+    url: str, required_length: int, fetcher: "FetcherInterface"
+) -> bytes:
     """Download bytes from given url
 
     Returns the downloaded bytes, otherwise like download_file()

tuf/ngclient/_internal/requests_fetcher.py

@@ -7,6 +7,7 @@
 
 import logging
 import time
+from typing import Iterator
 from urllib import parse
 
 # Imports
@@ -47,7 +48,7 @@ def __init__(self):
         # Some cookies may not be HTTP-safe.
         self._sessions = {}
 
-    def fetch(self, url, required_length):
+    def fetch(self, url: str, required_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'.
@@ -89,7 +90,9 @@ def fetch(self, url, required_length):
         return self._chunks(response, required_length)
 
     @staticmethod
-    def _chunks(response, required_length):
+    def _chunks(
+        response: "requests.Response", required_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
         download."""

tuf/ngclient/fetcher.py

@@ -6,6 +6,7 @@
 
 # Imports
 import abc
+from typing import Iterator
 
 
 # Classes
@@ -20,7 +21,7 @@ class FetcherInterface:
     __metaclass__ = abc.ABCMeta
 
     @abc.abstractmethod
-    def fetch(self, url, required_length):
+    def fetch(self, url: str, required_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'.