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.

8 files changed, 39 insertions, 36 deletions

diff --git a/gitlab/client.py b/gitlab/client.py
index b8ac222..2ac5158 100644
--- a/gitlab/client.py
+++ b/gitlab/client.py
@@ -807,7 +807,9 @@ class Gitlab:
         self,
         path: str,
         query_data: Optional[Dict[str, Any]] = None,
-        as_list: Optional[bool] = None,
+        *,
+        as_list: Optional[bool] = None,  # Deprecated in favor of `iterator`
+        iterator: Optional[bool] = None,
         **kwargs: Any,
     ) -> Union["GitlabList", List[Dict[str, Any]]]:
         """Make a GET request to the Gitlab server for list-oriented queries.
@@ -816,12 +818,13 @@ class Gitlab:
             path: Path or full URL to query ('/projects' or
                         'http://whatever/v4/api/projects')
             query_data: Data to send as query parameters
+            iterator: Indicate if should return a generator (True)
             **kwargs: Extra options to send to the server (e.g. sudo, page,
                       per_page)
 
         Returns:
-            A list of the objects returned by the server. If `as_list` is
-            False and no pagination-related arguments (`page`, `per_page`,
+            A list of the objects returned by the server. If `iterator` is
+            True and no pagination-related arguments (`page`, `per_page`,
             `all`) are defined then a GitlabList object (generator) is returned
             instead. This object will make API calls when needed to fetch the
             next items from the server.
@@ -832,15 +835,29 @@ class Gitlab:
         """
         query_data = query_data or {}
 
-        # In case we want to change the default behavior at some point
-        as_list = True if as_list is None else as_list
+        # Don't allow both `as_list` and `iterator` to be set.
+        if as_list is not None and iterator is not None:
+            raise ValueError(
+                "Only one of `as_list` or `iterator` can be used. "
+                "Use `iterator` instead of `as_list`. `as_list` is deprecated."
+            )
+
+        if as_list is not None:
+            iterator = not as_list
+            utils.warn(
+                message=(
+                    f"`as_list={as_list}` is deprecated and will be removed in a "
+                    f"future version. Use `iterator={iterator}` instead."
+                ),
+                category=DeprecationWarning,
+            )
 
         get_all = kwargs.pop("all", None)
         url = self._build_url(path)
 
         page = kwargs.get("page")
 
-        if as_list is False:
+        if iterator:
             # Generator requested
             return GitlabList(self, url, query_data, **kwargs)
 
@@ -879,7 +896,7 @@ class Gitlab:
         utils.warn(
             message=(
                 f"Calling a `list()` method without specifying `all=True` or "
-                f"`as_list=False` will return a maximum of {gl_list.per_page} items. "
+                f"`iterator=True` will return a maximum of {gl_list.per_page} items. "
                 f"Your query returned {len(items)} of {total_items} items. See "
                 f"{_PAGINATION_URL} for more details. If this was done intentionally, "
                 f"then this warning can be supressed by adding the argument "
diff --git a/gitlab/mixins.py b/gitlab/mixins.py
index a29c7a7..850ce81 100644
--- a/gitlab/mixins.py
+++ b/gitlab/mixins.py
@@ -201,12 +201,12 @@ class ListMixin(_RestManagerBase):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
+            iterator: If set to True and no pagination option is
                 defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Returns:
-            The list of objects, or a generator if `as_list` is False
+            The list of objects, or a generator if `iterator` is True
 
         Raises:
             GitlabAuthenticationError: If authentication is not correct
@@ -846,8 +846,6 @@ class ParticipantsMixin(_RestObjectBase):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
-                defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
diff --git a/gitlab/v4/objects/ldap.py b/gitlab/v4/objects/ldap.py
index 10667b4..4a01061 100644
--- a/gitlab/v4/objects/ldap.py
+++ b/gitlab/v4/objects/ldap.py
@@ -26,12 +26,12 @@ class LDAPGroupManager(RESTManager):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
+            iterator: If set to True and no pagination option is
                 defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Returns:
-            The list of objects, or a generator if `as_list` is False
+            The list of objects, or a generator if `iterator` is True
 
         Raises:
             GitlabAuthenticationError: If authentication is not correct
diff --git a/gitlab/v4/objects/merge_requests.py b/gitlab/v4/objects/merge_requests.py
index edd7d01..a3c583b 100644
--- a/gitlab/v4/objects/merge_requests.py
+++ b/gitlab/v4/objects/merge_requests.py
@@ -199,8 +199,6 @@ class ProjectMergeRequest(
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
-                defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
@@ -211,7 +209,7 @@ class ProjectMergeRequest(
             List of issues
         """
         path = f"{self.manager.path}/{self.encoded_id}/closes_issues"
-        data_list = self.manager.gitlab.http_list(path, as_list=False, **kwargs)
+        data_list = self.manager.gitlab.http_list(path, iterator=True, **kwargs)
         if TYPE_CHECKING:
             assert isinstance(data_list, gitlab.GitlabList)
         manager = ProjectIssueManager(self.manager.gitlab, parent=self.manager._parent)
@@ -226,8 +224,6 @@ class ProjectMergeRequest(
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
-                defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
@@ -239,7 +235,7 @@ class ProjectMergeRequest(
         """
 
         path = f"{self.manager.path}/{self.encoded_id}/commits"
-        data_list = self.manager.gitlab.http_list(path, as_list=False, **kwargs)
+        data_list = self.manager.gitlab.http_list(path, iterator=True, **kwargs)
         if TYPE_CHECKING:
             assert isinstance(data_list, gitlab.GitlabList)
         manager = ProjectCommitManager(self.manager.gitlab, parent=self.manager._parent)
diff --git a/gitlab/v4/objects/milestones.py b/gitlab/v4/objects/milestones.py
index e415330..0c4d74b 100644
--- a/gitlab/v4/objects/milestones.py
+++ b/gitlab/v4/objects/milestones.py
@@ -33,8 +33,6 @@ class GroupMilestone(SaveMixin, ObjectDeleteMixin, RESTObject):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
-                defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
@@ -46,7 +44,7 @@ class GroupMilestone(SaveMixin, ObjectDeleteMixin, RESTObject):
         """
 
         path = f"{self.manager.path}/{self.encoded_id}/issues"
-        data_list = self.manager.gitlab.http_list(path, as_list=False, **kwargs)
+        data_list = self.manager.gitlab.http_list(path, iterator=True, **kwargs)
         if TYPE_CHECKING:
             assert isinstance(data_list, RESTObjectList)
         manager = GroupIssueManager(self.manager.gitlab, parent=self.manager._parent)
@@ -62,8 +60,6 @@ class GroupMilestone(SaveMixin, ObjectDeleteMixin, RESTObject):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
-                defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
@@ -74,7 +70,7 @@ class GroupMilestone(SaveMixin, ObjectDeleteMixin, RESTObject):
             The list of merge requests
         """
         path = f"{self.manager.path}/{self.encoded_id}/merge_requests"
-        data_list = self.manager.gitlab.http_list(path, as_list=False, **kwargs)
+        data_list = self.manager.gitlab.http_list(path, iterator=True, **kwargs)
         if TYPE_CHECKING:
             assert isinstance(data_list, RESTObjectList)
         manager = GroupIssueManager(self.manager.gitlab, parent=self.manager._parent)
@@ -114,8 +110,6 @@ class ProjectMilestone(PromoteMixin, SaveMixin, ObjectDeleteMixin, RESTObject):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
-                defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
@@ -127,7 +121,7 @@ class ProjectMilestone(PromoteMixin, SaveMixin, ObjectDeleteMixin, RESTObject):
         """
 
         path = f"{self.manager.path}/{self.encoded_id}/issues"
-        data_list = self.manager.gitlab.http_list(path, as_list=False, **kwargs)
+        data_list = self.manager.gitlab.http_list(path, iterator=True, **kwargs)
         if TYPE_CHECKING:
             assert isinstance(data_list, RESTObjectList)
         manager = ProjectIssueManager(self.manager.gitlab, parent=self.manager._parent)
@@ -143,8 +137,6 @@ class ProjectMilestone(PromoteMixin, SaveMixin, ObjectDeleteMixin, RESTObject):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
-                defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
@@ -155,7 +147,7 @@ class ProjectMilestone(PromoteMixin, SaveMixin, ObjectDeleteMixin, RESTObject):
             The list of merge requests
         """
         path = f"{self.manager.path}/{self.encoded_id}/merge_requests"
-        data_list = self.manager.gitlab.http_list(path, as_list=False, **kwargs)
+        data_list = self.manager.gitlab.http_list(path, iterator=True, **kwargs)
         if TYPE_CHECKING:
             assert isinstance(data_list, RESTObjectList)
         manager = ProjectMergeRequestManager(
diff --git a/gitlab/v4/objects/repositories.py b/gitlab/v4/objects/repositories.py
index f2792b1..5826d9d 100644
--- a/gitlab/v4/objects/repositories.py
+++ b/gitlab/v4/objects/repositories.py
@@ -60,7 +60,7 @@ class RepositoryMixin(_RestObjectBase):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
+            iterator: If set to True and no pagination option is
                 defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
@@ -172,7 +172,7 @@ class RepositoryMixin(_RestObjectBase):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
+            iterator: If set to True and no pagination option is
                 defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
diff --git a/gitlab/v4/objects/runners.py b/gitlab/v4/objects/runners.py
index 665e743..51f6861 100644
--- a/gitlab/v4/objects/runners.py
+++ b/gitlab/v4/objects/runners.py
@@ -81,7 +81,7 @@ class RunnerManager(CRUDMixin, RESTManager):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
+            iterator: If set to True and no pagination option is
                 defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
diff --git a/gitlab/v4/objects/users.py b/gitlab/v4/objects/users.py
index 09964b1..39c243a 100644
--- a/gitlab/v4/objects/users.py
+++ b/gitlab/v4/objects/users.py
@@ -542,12 +542,12 @@ class UserProjectManager(ListMixin, CreateMixin, RESTManager):
             all: If True, return all the items, without pagination
             per_page: Number of items to retrieve per request
             page: ID of the page to return (starts with page 1)
-            as_list: If set to False and no pagination option is
+            iterator: If set to True and no pagination option is
                 defined, return a generator instead of a list
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Returns:
-            The list of objects, or a generator if `as_list` is False
+            The list of objects, or a generator if `iterator` is True
 
         Raises:
             GitlabAuthenticationError: If authentication is not correct