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, 6 insertions, 2 deletions

diff --git a/gitlab/utils.py b/gitlab/utils.py
index bab6705..6acb861 100644
--- a/gitlab/utils.py
+++ b/gitlab/utils.py
@@ -19,7 +19,7 @@ import pathlib
 import traceback
 import urllib.parse
 import warnings
-from typing import Any, Callable, Dict, Optional, Tuple, Type, Union
+from typing import Any, Callable, Dict, Iterator, Optional, Tuple, Type, Union
 
 import requests
 
@@ -34,9 +34,13 @@ class _StdoutStream:
 def response_content(
     response: requests.Response,
     streamed: bool,
+    iterator: bool,
     action: Optional[Callable],
     chunk_size: int,
-) -> Optional[bytes]:
+) -> Optional[Union[bytes, Iterator[Any]]]:
+    if iterator:
+        return response.iter_content(chunk_size=chunk_size)
+
     if streamed is False:
         return response.content