diff options
| author | John L. Villalovos <john@sodarock.com> | 2022-05-29 09:52:24 -0700 |
|---|---|---|
| committer | John L. Villalovos <john@sodarock.com> | 2022-05-29 09:52:24 -0700 |
| commit | de8c6e80af218d93ca167f8b5ff30319a2781d91 (patch) | |
| tree | 926f3b0b35d4b1a87f215af0751b68f21203f79c /docs | |
| parent | 09b3b2225361722f2439952d2dbee6a48a9f9fd9 (diff) | |
| download | gitlab-de8c6e80af218d93ca167f8b5ff30319a2781d91.tar.gz | |
docs: use `as_list=False` or `all=True` in Getting started
In the "Getting started with the API" section of the documentation,
use either `as_list=False` or `all=True` in the example usages of the
`list()` method.
Also add a warning about the fact that `list()` by default does not
return all items.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api-usage.rst | 18 |
1 files changed, 13 insertions, 5 deletions
diff --git a/docs/api-usage.rst b/docs/api-usage.rst index 06c186c..b072d29 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -93,13 +93,13 @@ Examples: .. code-block:: python # list all the projects - projects = gl.projects.list() + projects = gl.projects.list(as_list=False) for project in projects: print(project) # get the group with id == 2 group = gl.groups.get(2) - for project in group.projects.list(): + for project in group.projects.list(as_list=False): print(project) # create a new user @@ -107,6 +107,12 @@ Examples: user = gl.users.create(user_data) print(user) +.. warning:: + Calling ``list()`` without any arguments will by default not return the complete list + of items. Use either the ``all=True`` or ``as_list=False`` parameters to get all the + items when using listing methods. See the :ref:`pagination` section for more + information. + You can list the mandatory and optional attributes for object creation and update with the manager's ``get_create_attrs()`` and ``get_update_attrs()`` methods. They return 2 tuples, the first one is the list of mandatory @@ -133,7 +139,7 @@ Some objects also provide managers to access related GitLab resources: # list the issues for a project project = gl.projects.get(1) - issues = project.issues.list() + issues = project.issues.list(all=True) python-gitlab allows to send any data to the GitLab server when making queries. In case of invalid or missing arguments python-gitlab will raise an exception @@ -150,9 +156,9 @@ conflict with python or python-gitlab when using them as kwargs: .. code-block:: python - gl.user_activities.list(from='2019-01-01') ## invalid + gl.user_activities.list(from='2019-01-01', as_list=False) ## invalid - gl.user_activities.list(query_parameters={'from': '2019-01-01'}) # OK + gl.user_activities.list(query_parameters={'from': '2019-01-01'}, as_list=False) # OK Gitlab Objects ============== @@ -233,6 +239,8 @@ a project (the previous example used 2 API calls): project = gl.projects.get(1, lazy=True) # no API call project.star() # API call +.. _pagination: + Pagination ========== |