feat: support keyset pagination globally

docs/api-usage.rst

@@ -219,6 +219,18 @@ You can define the ``per_page`` value globally to avoid passing it to every
 
    gl = gitlab.Gitlab(url, token, per_page=50)
 
+Gitlab allows to also use keyset pagination. You can supply it to your project listing,
+but you can also do so globally. Be aware that GitLab then also requires you to only use supported
+order options. At the time of writing, only ``order_by="id"`` works.
+
+.. code-block:: python
+
+   gl = gitlab.Gitlab(url, token, pagination="keyset", per_page=100)
+   gl.projects.list(order_by="id")
+
+Reference:
+https://docs.gitlab.com/ce/api/README.html#keyset-based-pagination
+
 ``list()`` methods can also return a generator object which will handle the
 next calls to the API when required. This is the recommended way to iterate
 through a large number of items:

gitlab/__init__.py

@@ -69,6 +69,7 @@ class Gitlab(object):
         http_username (str): Username for HTTP authentication
         http_password (str): Password for HTTP authentication
         api_version (str): Gitlab API version to use (support for 4 only)
+        pagination (str): Can be set to 'keyset' to use keyset pagination
     """
 
     def __init__(
@@ -84,6 +85,7 @@ def __init__(
         api_version="4",
         session=None,
         per_page=None,
+        pagination=None,
     ):
 
         self._api_version = str(api_version)
@@ -109,6 +111,7 @@ def __init__(
         self.session = session or requests.Session()
 
         self.per_page = per_page
+        self.pagination = pagination
 
         objects = importlib.import_module("gitlab.v%s.objects" % self._api_version)
         self._objects = objects
@@ -200,6 +203,7 @@ def from_config(cls, gitlab_id=None, config_files=None):
             http_password=config.http_password,
             api_version=config.api_version,
             per_page=config.per_page,
+            pagination=config.pagination,
         )
 
     def auth(self):

gitlab/config.py

@@ -163,3 +163,9 @@ def __init__(self, gitlab_id=None, config_files=None):
                 pass
         if self.per_page is not None and not 0 <= self.per_page <= 100:
             raise GitlabDataError("Unsupported per_page number: %s" % self.per_page)
+
+        self.pagination = None
+        try:
+            self.pagination = self._config.get(self.gitlab_id, "pagination")
+        except Exception:
+            pass

gitlab/mixins.py

@@ -120,6 +120,10 @@ def list(self, **kwargs):
         if self.gitlab.per_page:
             data.setdefault("per_page", self.gitlab.per_page)
 
+        # global keyset pagination
+        if self.gitlab.pagination:
+            data.setdefault("pagination", self.gitlab.pagination)
+
         # We get the attributes that need some special transformation
         types = getattr(self, "_types", {})
         if types: