Skip to content

Commit f36614f

Browse files
igorp-collaboranejch
igorp-collabora
authored and
nejch
committed
docs: Use list(get_all=True) in documentation examples
The plain `list()` produces warnings to alert users that they might miss certain entities if pagination is not enabled using `get_all=True` to get a list of objects or `iterator=True` to have an iterator over all objects. Use `get_all=False` where the list would me immediately indexed `[0]` and `iterator=True` where iteration is used. Signed-off-by: Igor Ponomarev <igor.ponomarev@collabora.com>
1 parent 22be96c commit f36614f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+226
-227
lines changed

‎docs/api-usage-advanced.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ properly closed when you exit a ``with`` block:
3434
.. code-block:: python
3535
3636
with gitlab.Gitlab(host, token) as gl:
37-
gl.projects.list()
37+
gl.statistics.get()
3838
3939
.. warning::
4040

‎docs/api-usage.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,7 @@ with the GitLab server error message:
158158

159159
.. code-block:: python
160160
161-
>>> gl.projects.list(sort='invalid value')
161+
>>> gl.projects.list(get_all=True, sort='invalid value')
162162
...
163163
GitlabListError: 400: sort does not have a valid value
164164
@@ -222,7 +222,7 @@ the value on the object is accepted:
222222

223223
.. code-block:: python
224224
225-
issues = project.issues.list(state='opened')
225+
issues = project.issues.list(get_all=True, state='opened')
226226
for issue in issues:
227227
issue.my_super_awesome_feature_flag = "random_value"
228228
issue.save()
@@ -361,7 +361,7 @@ order options. At the time of writing, only ``order_by="id"`` works.
361361
.. code-block:: python
362362
363363
gl = gitlab.Gitlab(url, token, pagination="keyset", order_by="id", per_page=100)
364-
gl.projects.list()
364+
gl.projects.list(get_all=True)
365365
366366
Reference:
367367
https://docs.gitlab.com/ce/api/README.html#keyset-based-pagination

‎docs/faq.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ It is likely that you used a ``MergeRequest``, ``GroupMergeRequest``,
1313
can create a new ``ProjectMergeRequest`` or ``ProjectIssue`` object to
1414
apply changes. For example::
1515

16-
issue = gl.issues.list()[0]
16+
issue = gl.issues.list(get_all=False)[0]
1717
project = gl.projects.get(issue.project_id, lazy=True)
1818
editable_issue = project.issues.get(issue.iid, lazy=True)
1919
# you can now edit the object
@@ -58,7 +58,7 @@ To retrieve an object with all attributes, use a ``get()`` call.
5858

5959
Example with projects::
6060

61-
for project in gl.projects.list():
61+
for project in gl.projects.list(iterator=True):
6262
# Retrieve project object with all attributes
6363
project = gl.projects.get(project.id)
6464

‎docs/gl_objects/access_requests.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ Examples
3232

3333
List access requests from projects and groups::
3434

35-
p_ars = project.accessrequests.list()
36-
g_ars = group.accessrequests.list()
35+
p_ars = project.accessrequests.list(get_all=True)
36+
g_ars = group.accessrequests.list(get_all=True)
3737

3838
Create an access request::
3939

‎docs/gl_objects/applications.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Examples
1818

1919
List all OAuth applications::
2020

21-
applications = gl.applications.list()
21+
applications = gl.applications.list(get_all=True)
2222

2323
Create an application::
2424

‎docs/gl_objects/badges.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Examples
2626

2727
List badges::
2828

29-
badges = group_or_project.badges.list()
29+
badges = group_or_project.badges.list(get_all=True)
3030

3131
Get a badge::
3232

‎docs/gl_objects/boards.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Examples
3232
Get the list of existing boards for a project or a group::
3333

3434
# item is a Project or a Group
35-
boards = project_or_group.boards.list()
35+
boards = project_or_group.boards.list(get_all=True)
3636

3737
Get a single board for a project or a group::
3838

@@ -80,7 +80,7 @@ Examples
8080

8181
List the issue lists for a board::
8282

83-
b_lists = board.lists.list()
83+
b_lists = board.lists.list(get_all=True)
8484

8585
Get a single list::
8686

‎docs/gl_objects/branches.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Examples
1818

1919
Get the list of branches for a repository::
2020

21-
branches = project.branches.list()
21+
branches = project.branches.list(get_all=True)
2222

2323
Get a single repository branch::
2424

‎docs/gl_objects/bulk_imports.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,19 +55,19 @@ Start a bulk import/migration of a group and wait for completion::
5555

5656
List all migrations::
5757

58-
gl.bulk_imports.list()
58+
gl.bulk_imports.list(get_all=True)
5959

6060
List the entities of all migrations::
6161

62-
gl.bulk_import_entities.list()
62+
gl.bulk_import_entities.list(get_all=True)
6363

6464
Get a single migration by ID::
6565

6666
migration = gl.bulk_imports.get(123)
6767

6868
List the entities of a single migration::
6969

70-
entities = migration.entities.list()
70+
entities = migration.entities.list(get_all=True)
7171

7272
Get a single entity of a migration by ID::
7373

‎docs/gl_objects/cluster_agents.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Examples
2424

2525
List cluster agents for a project::
2626

27-
cluster_agents = project.cluster_agents.list()
27+
cluster_agents = project.cluster_agents.list(get_all=True)
2828

2929
Register a cluster agent with a project::
3030

0 commit comments

Comments
 (0)