chore: add a UserWarning if both iterator=True and page=X are used (

#2462)

If a caller calls a `list()` method with both `iterator=True` (or
`as_list=False`) and `page=X` then emit a `UserWarning` as the options
are mutually exclusive.

gitlab/client.py

@@ -929,6 +929,19 @@ def http_list(
 
         page = kwargs.get("page")
 
+        if iterator and page is not None:
+            arg_used_message = f"iterator={iterator}"
+            if as_list is not None:
+                arg_used_message = f"as_list={as_list}"
+            utils.warn(
+                message=(
+                    f"`{arg_used_message}` and `page={page}` were both specified. "
+                    f"`{arg_used_message}` will be ignored and a `list` will be "
+                    f"returned."
+                ),
+                category=UserWarning,
+            )
+
         if iterator and page is None:
             # Generator requested
             return GitlabList(self, url, query_data, **kwargs)

tests/unit/test_gitlab_http_methods.py

@@ -548,11 +548,22 @@ def test_list_request_page_and_iterator(gl):
     response_dict["match"] = [responses.matchers.query_param_matcher({"page": "1"})]
     responses.add(**response_dict)
 
-    result = gl.http_list("/projects", iterator=True, page=1)
+    with pytest.warns(
+        UserWarning, match="`iterator=True` and `page=1` were both specified"
+    ):
+        result = gl.http_list("/projects", iterator=True, page=1)
     assert isinstance(result, list)
     assert len(result) == 20
     assert len(responses.calls) == 1
 
+    with pytest.warns(
+        UserWarning, match="`as_list=False` and `page=1` were both specified"
+    ):
+        result = gl.http_list("/projects", as_list=False, page=1)
+    assert isinstance(result, list)
+    assert len(result) == 20
+    assert len(responses.calls) == 2
+
 
 large_list_response = {
     "method": responses.GET,