refactor: avoid possible breaking change in iterator (#2107)

Commit b6447211754e126f64e12fc735ad74fe557b7fb4 inadvertently
introduced a possible breaking change as it added a new argument
`iterator` and added it in between existing (potentially positional) arguments.

This moves the `iterator` argument to the end of the argument list and
requires it to be a keyword-only argument.

10 files changed, 66 insertions, 28 deletions

diff --git a/gitlab/mixins.py b/gitlab/mixins.py
index 3c897d4..519e83f 100644
--- a/gitlab/mixins.py
+++ b/gitlab/mixins.py
@@ -613,9 +613,10 @@ class DownloadMixin(_RestObjectBase):
     def download(
         self,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Download the archive of a resource export.
@@ -644,7 +645,9 @@ class DownloadMixin(_RestObjectBase):
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
 
 class SubscribableMixin(_RestObjectBase):
diff --git a/gitlab/utils.py b/gitlab/utils.py
index 6acb861..4d2ec8d 100644
--- a/gitlab/utils.py
+++ b/gitlab/utils.py
@@ -34,9 +34,10 @@ class _StdoutStream:
 def response_content(
     response: requests.Response,
     streamed: bool,
-    iterator: bool,
     action: Optional[Callable],
     chunk_size: int,
+    *,
+    iterator: bool,
 ) -> Optional[Union[bytes, Iterator[Any]]]:
     if iterator:
         return response.iter_content(chunk_size=chunk_size)
diff --git a/gitlab/v4/objects/artifacts.py b/gitlab/v4/objects/artifacts.py
index f5f106d..b4a4c0e 100644
--- a/gitlab/v4/objects/artifacts.py
+++ b/gitlab/v4/objects/artifacts.py
@@ -75,9 +75,10 @@ class ProjectArtifactManager(RESTManager):
         ref_name: str,
         job: str,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Get the job artifacts archive from a specific tag or branch.
@@ -110,7 +111,9 @@ class ProjectArtifactManager(RESTManager):
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
     @cli.register_custom_action(
         "ProjectArtifactManager", ("ref_name", "artifact_path", "job")
@@ -122,9 +125,10 @@ class ProjectArtifactManager(RESTManager):
         artifact_path: str,
         job: str,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Download a single artifact file from a specific tag or branch from
@@ -158,4 +162,6 @@ class ProjectArtifactManager(RESTManager):
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
diff --git a/gitlab/v4/objects/files.py b/gitlab/v4/objects/files.py
index 2fd79fd..d81b711 100644
--- a/gitlab/v4/objects/files.py
+++ b/gitlab/v4/objects/files.py
@@ -230,9 +230,10 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa
         file_path: str,
         ref: str,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable[..., Any]] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Return the content of a file for a commit.
@@ -265,7 +266,9 @@ class ProjectFileManager(GetMixin, CreateMixin, UpdateMixin, DeleteMixin, RESTMa
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
     @cli.register_custom_action("ProjectFileManager", ("file_path", "ref"))
     @exc.on_http_error(exc.GitlabListError)
diff --git a/gitlab/v4/objects/jobs.py b/gitlab/v4/objects/jobs.py
index 3fcd667..54c4f33 100644
--- a/gitlab/v4/objects/jobs.py
+++ b/gitlab/v4/objects/jobs.py
@@ -116,9 +116,10 @@ class ProjectJob(RefreshMixin, RESTObject):
     def artifacts(
         self,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable[..., Any]] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Get the job artifacts.
@@ -147,7 +148,9 @@ class ProjectJob(RefreshMixin, RESTObject):
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
     @cli.register_custom_action("ProjectJob")
     @exc.on_http_error(exc.GitlabGetError)
@@ -155,9 +158,10 @@ class ProjectJob(RefreshMixin, RESTObject):
         self,
         path: str,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable[..., Any]] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Get a single artifact file from within the job's artifacts archive.
@@ -187,16 +191,19 @@ class ProjectJob(RefreshMixin, RESTObject):
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
     @cli.register_custom_action("ProjectJob")
     @exc.on_http_error(exc.GitlabGetError)
     def trace(
         self,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable[..., Any]] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Dict[str, Any]:
         """Get the job trace.
@@ -226,7 +233,7 @@ class ProjectJob(RefreshMixin, RESTObject):
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
         return_value = utils.response_content(
-            result, streamed, iterator, action, chunk_size
+            result, streamed, action, chunk_size, iterator=iterator
         )
         if TYPE_CHECKING:
             assert isinstance(return_value, dict)
diff --git a/gitlab/v4/objects/packages.py b/gitlab/v4/objects/packages.py
index a820801..50295e0 100644
--- a/gitlab/v4/objects/packages.py
+++ b/gitlab/v4/objects/packages.py
@@ -103,9 +103,10 @@ class GenericPackageManager(RESTManager):
         package_version: str,
         file_name: str,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Download a generic package.
@@ -135,7 +136,9 @@ class GenericPackageManager(RESTManager):
         result = self.gitlab.http_get(path, streamed=streamed, raw=True, **kwargs)
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
 
 class GroupPackage(RESTObject):
diff --git a/gitlab/v4/objects/projects.py b/gitlab/v4/objects/projects.py
index b21ea3a..e912a28 100644
--- a/gitlab/v4/objects/projects.py
+++ b/gitlab/v4/objects/projects.py
@@ -476,9 +476,10 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO
         self,
         wiki: bool = False,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Return a snapshot of the repository.
@@ -508,7 +509,9 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
     @cli.register_custom_action("Project", ("scope", "search"))
     @exc.on_http_error(exc.GitlabSearchError)
diff --git a/gitlab/v4/objects/repositories.py b/gitlab/v4/objects/repositories.py
index 1f10473..e968a6a 100644
--- a/gitlab/v4/objects/repositories.py
+++ b/gitlab/v4/objects/repositories.py
@@ -107,9 +107,10 @@ class RepositoryMixin(_RestObjectBase):
         self,
         sha: str,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable[..., Any]] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Return the raw file contents for a blob.
@@ -139,7 +140,9 @@ class RepositoryMixin(_RestObjectBase):
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
     @cli.register_custom_action("Project", ("from_", "to"))
     @exc.on_http_error(exc.GitlabGetError)
@@ -195,10 +198,11 @@ class RepositoryMixin(_RestObjectBase):
         self,
         sha: str = None,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable[..., Any]] = None,
         chunk_size: int = 1024,
         format: Optional[str] = None,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Return an archive of the repository.
@@ -234,7 +238,9 @@ class RepositoryMixin(_RestObjectBase):
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
     @cli.register_custom_action("Project")
     @exc.on_http_error(exc.GitlabDeleteError)
diff --git a/gitlab/v4/objects/snippets.py b/gitlab/v4/objects/snippets.py
index aa46c77..648def2 100644
--- a/gitlab/v4/objects/snippets.py
+++ b/gitlab/v4/objects/snippets.py
@@ -29,9 +29,10 @@ class Snippet(UserAgentDetailMixin, SaveMixin, ObjectDeleteMixin, RESTObject):
     def content(
         self,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable[..., Any]] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Return the content of a snippet.
@@ -60,7 +61,9 @@ class Snippet(UserAgentDetailMixin, SaveMixin, ObjectDeleteMixin, RESTObject):
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
 
 class SnippetManager(CRUDMixin, RESTManager):
@@ -106,9 +109,10 @@ class ProjectSnippet(UserAgentDetailMixin, SaveMixin, ObjectDeleteMixin, RESTObj
     def content(
         self,
         streamed: bool = False,
-        iterator: bool = False,
         action: Optional[Callable[..., Any]] = None,
         chunk_size: int = 1024,
+        *,
+        iterator: bool = False,
         **kwargs: Any,
     ) -> Optional[Union[bytes, Iterator[Any]]]:
         """Return the content of a snippet.
@@ -137,7 +141,9 @@ class ProjectSnippet(UserAgentDetailMixin, SaveMixin, ObjectDeleteMixin, RESTObj
         )
         if TYPE_CHECKING:
             assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, iterator, action, chunk_size)
+        return utils.response_content(
+            result, streamed, action, chunk_size, iterator=iterator
+        )
 
 
 class ProjectSnippetManager(CRUDMixin, RESTManager):
diff --git a/tests/unit/test_utils.py b/tests/unit/test_utils.py
index 74b48ae..ce2e776 100644
--- a/tests/unit/test_utils.py
+++ b/tests/unit/test_utils.py
@@ -37,7 +37,7 @@ def test_response_content(capsys):
 
     resp = requests.get("https://example.com", stream=True)
     utils.response_content(
-        resp, streamed=True, iterator=False, action=None, chunk_size=1024
+        resp, streamed=True, action=None, chunk_size=1024, iterator=False
     )
 
     captured = capsys.readouterr()