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

‎docs/gl_objects/clusters.rst

Lines changed: 2 additions & 2 deletions
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

Lines changed: 6 additions & 6 deletions
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

Lines changed: 3 additions & 3 deletions
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

Lines changed: 3 additions & 3 deletions
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 1 addition & 1 deletion
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

Lines changed: 1 addition & 1 deletion
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

Lines changed: 1 addition & 1 deletion
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

Lines changed: 1 addition & 1 deletion
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 5 additions & 5 deletions
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

Lines changed: 1 addition & 1 deletion
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

Lines changed: 1 addition & 1 deletion
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

Lines changed: 1 addition & 1 deletion
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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy