Pagination generators: expose more information

Gauvain Pocentek · Gauvain Pocentek · commit 38d446737f45 · 2017-11-01T17:07:30.000+01:00
Expose the X-* pagination attributes returned by the Gitlab server when requesting lists. Closes python-gitlab#304
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -225,6 +225,15 @@ handle the next calls to the API when required:
    for item in items:
        print(item.attributes)
 
+The generator exposes extra listing information as received by the server:
+
+* ``current_page``: current page number (first page is 1)
+* ``prev_page``: if ``None`` the current page is the first one
+* ``next_page``: if ``None`` the current page is the last one
+* ``per_page``: number of items per page
+* ``total_pages``: total number of pages available
+* ``total``: total number of items in the list
+
 Sudo
 ====
 
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
@@ -864,6 +864,7 @@ def _query(self, url, query_data={}, **kwargs):
         except KeyError:
             self._next_url = None
         self._current_page = result.headers.get('X-Page')
+        self._prev_page = result.headers.get('X-Prev-Page')
         self._next_page = result.headers.get('X-Next-Page')
         self._per_page = result.headers.get('X-Per-Page')
         self._total_pages = result.headers.get('X-Total-Pages')
@@ -877,6 +878,42 @@ def _query(self, url, query_data={}, **kwargs):
 
         self._current = 0
 
+    @property
+    def current_page(self):
+        """The current page number."""
+        return int(self._current_page)
+
+    @property
+    def prev_page(self):
+        """The next page number.
+
+        If None, the current page is the last.
+        """
+        return int(self._prev_page) if self._prev_page else None
+
+    @property
+    def next_page(self):
+        """The next page number.
+
+        If None, the current page is the last.
+        """
+        return int(self._next_page) if self._next_page else None
+
+    @property
+    def per_page(self):
+        """The number of items per page."""
+        return int(self._per_page)
+
+    @property
+    def total_pages(self):
+        """The total number of pages."""
+        return int(self._total_pages)
+
+    @property
+    def total(self):
+        """The total number of items."""
+        return int(self._total)
+
     def __iter__(self):
         return self
 
diff --git a/gitlab/base.py b/gitlab/base.py
@@ -670,6 +670,42 @@ def next(self):
         data = self._list.next()
         return self._obj_cls(self.manager, data)
 
+    @property
+    def current_page(self):
+        """The current page number."""
+        return self._list.current_page
+
+    @property
+    def prev_page(self):
+        """The next page number.
+
+        If None, the current page is the last.
+        """
+        return self._list.prev_page
+
+    @property
+    def next_page(self):
+        """The next page number.
+
+        If None, the current page is the last.
+        """
+        return self._list.next_page
+
+    @property
+    def per_page(self):
+        """The number of items per page."""
+        return self._list.per_page
+
+    @property
+    def total_pages(self):
+        """The total number of pages."""
+        return self._list.total_pages
+
+    @property
+    def total(self):
+        """The total number of items."""
+        return self._list.total
+
 
 class RESTManager(object):
     """Base class for CRUD operations on objects.
diff --git a/gitlab/tests/test_gitlab.py b/gitlab/tests/test_gitlab.py
@@ -209,6 +209,12 @@ def resp_2(url, request):
             self.assertEqual(len(obj), 2)
             self.assertEqual(obj._next_url,
                              'http://localhost/api/v4/tests?per_page=1&page=2')
+            self.assertEqual(obj.current_page, 1)
+            self.assertEqual(obj.prev_page, None)
+            self.assertEqual(obj.next_page, 2)
+            self.assertEqual(obj.per_page, 1)
+            self.assertEqual(obj.total_pages, 2)
+            self.assertEqual(obj.total, 2)
 
             with HTTMock(resp_2):
                 l = list(obj)
