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

+1-1
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

+3-3
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

+2-2
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

+2-2
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

+1-1
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

+1-1
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

+2-2
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

+1-1
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

+3-3
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

+1-1
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

‎docs/gl_objects/clusters.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Examples
2727

2828
List clusters for a project::
2929

30-
clusters = project.clusters.list()
30+
clusters = project.clusters.list(get_all=True)
3131

3232
Create an cluster for a project::
3333

@@ -58,7 +58,7 @@ Delete an cluster for a project::
5858

5959
List clusters for a group::
6060

61-
clusters = group.clusters.list()
61+
clusters = group.clusters.list(get_all=True)
6262

6363
Create an cluster for a group::
6464

‎docs/gl_objects/commits.rst

+6-6
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,17 @@ Examples
1919

2020
List the commits for a project::
2121

22-
commits = project.commits.list()
22+
commits = project.commits.list(get_all=True)
2323

2424
You can use the ``ref_name``, ``since`` and ``until`` filters to limit the
2525
results::
2626

27-
commits = project.commits.list(ref_name='my_branch')
28-
commits = project.commits.list(since='2016-01-01T00:00:00Z')
27+
commits = project.commits.list(ref_name='my_branch', get_all=True)
28+
commits = project.commits.list(since='2016-01-01T00:00:00Z', get_all=True)
2929

3030
List all commits for a project (see :ref:`pagination`) on all branches:
3131

32-
commits = project.commits.list(get_all=True, all=True)
32+
commits = project.commits.list(get_all=True)
3333

3434
Create a commit::
3535

@@ -105,7 +105,7 @@ Examples
105105

106106
Get the comments for a commit::
107107

108-
comments = commit.comments.list()
108+
comments = commit.comments.list(get_all=True)
109109

110110
Add a comment on a commit::
111111

@@ -136,7 +136,7 @@ Examples
136136

137137
List the statuses for a commit::
138138

139-
statuses = commit.statuses.list()
139+
statuses = commit.statuses.list(get_all=True)
140140

141141
Change the status of a commit::
142142

‎docs/gl_objects/deploy_keys.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Add an instance-wide deploy key (requires admin access)::
2525

2626
List all deploy keys::
2727

28-
keys = gl.deploykeys.list()
28+
keys = gl.deploykeys.list(get_all=True)
2929

3030
Deploy keys for projects
3131
========================
@@ -48,7 +48,7 @@ Examples
4848

4949
List keys for a project::
5050

51-
keys = project.keys.list()
51+
keys = project.keys.list(get_all=True)
5252

5353
Get a single deploy key::
5454

@@ -61,7 +61,7 @@ Create a deploy key for a project::
6161

6262
Delete a deploy key for a project::
6363

64-
key = project.keys.list(key_id)
64+
key = project.keys.list(key_id, get_all=True)
6565
# or
6666
key.delete()
6767

‎docs/gl_objects/deploy_tokens.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Use the ``list()`` method to list all deploy tokens across the GitLab instance.
2929
::
3030

3131
# List deploy tokens
32-
deploy_tokens = gl.deploytokens.list()
32+
deploy_tokens = gl.deploytokens.list(get_all=True)
3333

3434
Project deploy tokens
3535
=====================
@@ -52,7 +52,7 @@ Examples
5252

5353
List the deploy tokens for a project::
5454

55-
deploy_tokens = project.deploytokens.list()
55+
deploy_tokens = project.deploytokens.list(get_all=True)
5656

5757
Get a deploy token for a project by id::
5858

@@ -109,7 +109,7 @@ Examples
109109

110110
List the deploy tokens for a group::
111111

112-
deploy_tokens = group.deploytokens.list()
112+
deploy_tokens = group.deploytokens.list(get_all=True)
113113

114114
Get a deploy token for a group by id::
115115

‎docs/gl_objects/deployments.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Examples
1818

1919
List deployments for a project::
2020

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

2323
Get a single deployment::
2424

@@ -72,4 +72,4 @@ Examples
7272
List the merge requests associated with a deployment::
7373

7474
deployment = project.deployments.get(42, lazy=True)
75-
mrs = deployment.mergerequests.list()
75+
mrs = deployment.mergerequests.list(get_all=True)

‎docs/gl_objects/discussions.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Examples
4444

4545
List the discussions for a resource (issue, merge request, snippet or commit)::
4646

47-
discussions = resource.discussions.list()
47+
discussions = resource.discussions.list(get_all=True)
4848

4949
Get a single discussion::
5050

‎docs/gl_objects/draft_notes.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Examples
2525

2626
List all draft notes for a merge request::
2727

28-
draft_notes = merge_request.draft_notes.list()
28+
draft_notes = merge_request.draft_notes.list(get_all=True)
2929

3030
Get a draft note for a merge request by ID::
3131

‎docs/gl_objects/emojis.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Examples
2828

2929
List emojis for a resource::
3030

31-
emojis = obj.awardemojis.list()
31+
emojis = obj.awardemojis.list(get_all=True)
3232

3333
Get a single emoji::
3434

‎docs/gl_objects/environments.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Examples
1818

1919
List environments for a project::
2020

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

2323
Create an environment for a project::
2424

‎docs/gl_objects/epics.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Examples
2121

2222
List the epics for a group::
2323

24-
epics = groups.epics.list()
24+
epics = groups.epics.list(get_all=True)
2525

2626
Get a single epic for a group::
2727

@@ -60,7 +60,7 @@ Examples
6060

6161
List the issues associated with an issue::
6262

63-
ei = epic.issues.list()
63+
ei = epic.issues.list(get_all=True)
6464

6565
Associate an issue with an epic::
6666

‎docs/gl_objects/events.rst

+5-5
Original file line numberDiff line numberDiff line change
@@ -33,15 +33,15 @@ available on `the gitlab documentation
3333

3434
List all the events (paginated)::
3535

36-
events = gl.events.list()
36+
events = gl.events.list(get_all=True)
3737

3838
List the issue events on a project::
3939

40-
events = project.events.list(target_type='issue')
40+
events = project.events.list(target_type='issue', get_all=True)
4141

4242
List the user events::
4343

44-
events = project.events.list()
44+
events = project.events.list(get_all=True)
4545

4646
Resource state events
4747
=====================
@@ -68,15 +68,15 @@ and project merge requests.
6868

6969
List the state events of a project issue (paginated)::
7070

71-
state_events = issue.resourcestateevents.list()
71+
state_events = issue.resourcestateevents.list(get_all=True)
7272

7373
Get a specific state event of a project issue by its id::
7474

7575
state_event = issue.resourcestateevents.get(1)
7676

7777
List the state events of a project merge request (paginated)::
7878

79-
state_events = mr.resourcestateevents.list()
79+
state_events = mr.resourcestateevents.list(get_all=True)
8080

8181
Get a specific state event of a project merge request by its id::
8282

‎docs/gl_objects/features.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Examples
1818

1919
List features::
2020

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

2323
Create or set a feature::
2424

‎docs/gl_objects/geo_nodes.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Examples
1818

1919
List the geo nodes::
2020

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

2323
Get the status of all the nodes::
2424

‎docs/gl_objects/group_access_tokens.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Examples
2020

2121
List group access tokens::
2222

23-
access_tokens = gl.groups.get(1, lazy=True).access_tokens.list()
23+
access_tokens = gl.groups.get(1, lazy=True).access_tokens.list(get_all=True)
2424
print(access_tokens[0].name)
2525

2626
Get a group access token by id::

0 commit comments

Comments
 (0)