summaryrefslogtreecommitdiff
path: root/docs/api-usage.rst
diff options
context:
space:
mode:
authorGauvain Pocentek <gauvain@pocentek.net>2016-08-30 08:45:42 +0200
committerGauvain Pocentek <gauvain@pocentek.net>2016-08-30 08:45:42 +0200
commit29e2efeae22ce5fa82e3541360b234e0053a65c2 (patch)
treefe838000a2088c099a60bede717651361122f174 /docs/api-usage.rst
parent47cb27824d2e1b3d056817c45cbb2d5dca1df904 (diff)
downloadgitlab-29e2efeae22ce5fa82e3541360b234e0053a65c2.tar.gz
docs: improve the pagination section
Diffstat (limited to 'docs/api-usage.rst')
-rw-r--r--docs/api-usage.rst13
1 files changed, 11 insertions, 2 deletions
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index 976a3a0..b33913d 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -106,19 +106,28 @@ actions on the GitLab resources. For example:
Pagination
==========
-You can use pagination to go throught long lists:
+You can use pagination to iterate over long lists. All the Gitlab objects
+listing methods support the ``page`` and ``per_page`` parameters:
.. code-block:: python
ten_first_groups = gl.groups.list(page=0, per_page=10)
-Use the ``all`` parameter to get all the items when using listing methods:
+By default GitLab does not return the complete list of items. Use the ``all``
+parameter to get all the items when using listing methods:
.. code-block:: python
all_groups = gl.groups.list(all=True)
all_owned_projects = gl.projects.owned(all=True)
+.. note::
+
+ python-gitlab will iterate over the list by calling the correspnding API
+ multiple times. This might take some time if you have a lot of items to
+ retrieve. This might also consume a lot of memory as all the items will be
+ stored in RAM.
+
Sudo
====