feat(client): introduce `iterator=True` and deprecate `as_list=False` in `list()`

`as_list=False` is confusing as it doesn't explain what is being
returned. Replace it with `iterator=True` which more clearly explains
to the user that an iterator/generator will be returned.

This maintains backward compatibility with `as_list` but does issue a
DeprecationWarning if `as_list` is set.

2 files changed, 15 insertions, 4 deletions

diff --git a/tests/functional/api/test_gitlab.py b/tests/functional/api/test_gitlab.py
index 4684e43..c9a24a0 100644
--- a/tests/functional/api/test_gitlab.py
+++ b/tests/functional/api/test_gitlab.py
@@ -220,9 +220,20 @@ def test_list_all_true_nowarning(gl):
     assert len(items) > 20
 
 
-def test_list_as_list_false_nowarning(gl):
-    """Using `as_list=False` will disable the warning"""
+def test_list_iterator_true_nowarning(gl):
+    """Using `iterator=True` will disable the warning"""
     with warnings.catch_warnings(record=True) as caught_warnings:
-        items = gl.gitlabciymls.list(as_list=False)
+        items = gl.gitlabciymls.list(iterator=True)
     assert len(caught_warnings) == 0
     assert len(list(items)) > 20
+
+
+def test_list_as_list_false_warnings(gl):
+    """Using `as_list=False` will disable the UserWarning but cause a
+    DeprecationWarning"""
+    with warnings.catch_warnings(record=True) as caught_warnings:
+        items = gl.gitlabciymls.list(as_list=False)
+    assert len(caught_warnings) == 1
+    for warning in caught_warnings:
+        assert isinstance(warning.message, DeprecationWarning)
+    assert len(list(items)) > 20
diff --git a/tests/functional/api/test_projects.py b/tests/functional/api/test_projects.py
index 50cc554..8d367de 100644
--- a/tests/functional/api/test_projects.py
+++ b/tests/functional/api/test_projects.py
@@ -15,7 +15,7 @@ def test_create_project(gl, user):
     sudo_project = gl.projects.create({"name": "sudo_project"}, sudo=user.id)
 
     created = gl.projects.list()
-    created_gen = gl.projects.list(as_list=False)
+    created_gen = gl.projects.list(iterator=True)
     owned = gl.projects.list(owned=True)
 
     assert admin_project in created and sudo_project in created