Skip to content

docs: use as_list=False or all=True in Getting started #1884

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 29, 2022
Merged

docs: use as_list=False or all=True in Getting started #1884

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions docs/api-usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,20 +93,26 @@ 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
user_data = {'email': 'jen@foo.com', 'username': 'jen', 'name': 'Jen'}
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
Expand All @@ -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
Expand All @@ -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
==============
Expand Down Expand Up @@ -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
==========

Expand Down