feat(downloads): allow streaming downloads access to response iterator (#1956)

* feat(downloads): allow streaming downloads access to response iterator

Allow access to the underlying response iterator when downloading in
streaming mode by specifying `iterator=True`.

Update type annotations to support this change.

* docs(api-docs): add iterator example to artifact download

Document the usage of the `iterator=True` option when downloading
artifacts

* test(packages): add tests for streaming downloads

1 files changed, 38 insertions, 0 deletions

diff --git a/tests/functional/api/test_packages.py b/tests/functional/api/test_packages.py
index 64b57b8..9f06439 100644
--- a/tests/functional/api/test_packages.py
+++ b/tests/functional/api/test_packages.py
@@ -3,6 +3,8 @@ GitLab API:
 https://docs.gitlab.com/ce/api/packages.html
 https://docs.gitlab.com/ee/user/packages/generic_packages
 """
+from collections.abc import Iterator
+
 from gitlab.v4.objects import GenericPackage
 
 package_name = "hello-world"
@@ -46,6 +48,24 @@ def test_download_generic_package(project):
     assert package.decode("utf-8") == file_content
 
 
+def test_stream_generic_package(project):
+    bytes_iterator = project.generic_packages.download(
+        package_name=package_name,
+        package_version=package_version,
+        file_name=file_name,
+        iterator=True,
+    )
+
+    assert isinstance(bytes_iterator, Iterator)
+
+    package = bytes()
+    for chunk in bytes_iterator:
+        package += chunk
+
+    assert isinstance(package, bytes)
+    assert package.decode("utf-8") == file_content
+
+
 def test_download_generic_package_to_file(tmp_path, project):
     path = tmp_path / file_name
 
@@ -60,3 +80,21 @@ def test_download_generic_package_to_file(tmp_path, project):
 
     with open(path, "r") as f:
         assert f.read() == file_content
+
+
+def test_stream_generic_package_to_file(tmp_path, project):
+    path = tmp_path / file_name
+
+    bytes_iterator = project.generic_packages.download(
+        package_name=package_name,
+        package_version=package_version,
+        file_name=file_name,
+        iterator=True,
+    )
+
+    with open(path, "wb") as f:
+        for chunk in bytes_iterator:
+            f.write(chunk)
+
+    with open(path, "r") as f:
+        assert f.read() == file_content