Skip to content

Commit 4057644

Browse files
author
Gauvain Pocentek
committed
Update the objects doc/examples for v4
1 parent 80eab7b commit 4057644

36 files changed

Lines changed: 991 additions & 464 deletions

‎docs/gl_objects/access_requests.py‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,14 @@
11
# list
2-
p_ars = gl.project_accessrequests.list(project_id=1)
3-
g_ars = gl.group_accessrequests.list(group_id=1)
4-
# or
52
p_ars = project.accessrequests.list()
63
g_ars = group.accessrequests.list()
74
# end list
85

96
# get
10-
p_ar = gl.project_accessrequests.get(user_id, project_id=1)
11-
g_ar = gl.group_accessrequests.get(user_id, group_id=1)
12-
# or
137
p_ar = project.accessrequests.get(user_id)
148
g_ar = group.accessrequests.get(user_id)
159
# end get
1610

1711
# create
18-
p_ar = gl.project_accessrequests.create({}, project_id=1)
19-
g_ar = gl.group_accessrequests.create({}, group_id=1)
20-
# or
2112
p_ar = project.accessrequests.create({})
2213
g_ar = group.accessrequests.create({})
2314
# end create
@@ -28,9 +19,6 @@
2819
# end approve
2920

3021
# delete
31-
gl.project_accessrequests.delete(user_id, project_id=1)
32-
gl.group_accessrequests.delete(user_id, group_id=1)
33-
# or
3422
project.accessrequests.delete(user_id)
3523
group.accessrequests.delete(user_id)
3624
# or

‎docs/gl_objects/access_requests.rst‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,41 @@
22
Access requests
33
###############
44

5-
Use :class:`~gitlab.objects.ProjectAccessRequest` and
6-
:class:`~gitlab.objects.GroupAccessRequest` objects to manipulate access
7-
requests for projects and groups. The
8-
:attr:`gitlab.Gitlab.project_accessrequests`,
9-
:attr:`gitlab.Gitlab.group_accessrequests`, :attr:`Project.accessrequests
10-
<gitlab.objects.Project.accessrequests>` and :attr:`Group.accessrequests
11-
<gitlab.objects.Group.accessrequests>` manager objects provide helper
12-
functions.
5+
Users can request access to groups and projects.
6+
7+
When access is granted the user should be given a numerical access level. The
8+
following constants are provided to represent the access levels:
9+
10+
* ``gitlab.GUEST_ACCESS``: ``10``
11+
* ``gitlab.REPORTER_ACCESS``: ``20``
12+
* ``gitlab.DEVELOPER_ACCESS``: ``30``
13+
* ``gitlab.MASTER_ACCESS``: ``40``
14+
* ``gitlab.OWNER_ACCESS``: ``50``
15+
16+
References
17+
----------
18+
19+
* v4 API:
20+
21+
+ :class:`gitlab.v4.objects.ProjectAccessRequest`
22+
+ :class:`gitlab.v4.objects.ProjectAccessRequestManager`
23+
+ :attr:`gitlab.v4.objects.Project.accessrequests`
24+
+ :class:`gitlab.v4.objects.GroupAccessRequest`
25+
+ :class:`gitlab.v4.objects.GroupAccessRequestManager`
26+
+ :attr:`gitlab.v4.objects.Group.accessrequests`
27+
28+
* v3 API:
29+
30+
+ :class:`gitlab.v3.objects.ProjectAccessRequest`
31+
+ :class:`gitlab.v3.objects.ProjectAccessRequestManager`
32+
+ :attr:`gitlab.v3.objects.Project.accessrequests`
33+
+ :attr:`gitlab.Gitlab.project_accessrequests`
34+
+ :class:`gitlab.v3.objects.GroupAccessRequest`
35+
+ :class:`gitlab.v3.objects.GroupAccessRequestManager`
36+
+ :attr:`gitlab.v3.objects.Group.accessrequests`
37+
+ :attr:`gitlab.Gitlab.group_accessrequests`
38+
39+
* GitLab API: https://docs.gitlab.com/ce/api/access_requests.html
1340

1441
Examples
1542
--------

‎docs/gl_objects/branches.py‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,22 @@
11
# list
2-
branches = gl.project_branches.list(project_id=1)
3-
# or
42
branches = project.branches.list()
53
# end list
64

75
# get
8-
branch = gl.project_branches.get(project_id=1, id='master')
9-
# or
106
branch = project.branches.get('master')
117
# end get
128

139
# create
14-
branch = gl.project_branches.create({'branch_name': 'feature1',
15-
'ref': 'master'},
16-
project_id=1)
17-
# or
10+
# v4
11+
branch = project.branches.create({'branch': 'feature1',
12+
'ref': 'master'})
13+
14+
#v3
1815
branch = project.branches.create({'branch_name': 'feature1',
1916
'ref': 'master'})
2017
# end create
2118

2219
# delete
23-
gl.project_branches.delete(project_id=1, id='feature1')
24-
# or
2520
project.branches.delete('feature1')
2621
# or
2722
branch.delete()

‎docs/gl_objects/branches.rst‎

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,25 @@
22
Branches
33
########
44

5-
Use :class:`~gitlab.objects.ProjectBranch` objects to manipulate repository
6-
branches.
5+
References
6+
----------
77

8-
To create :class:`~gitlab.objects.ProjectBranch` objects use the
9-
:attr:`gitlab.Gitlab.project_branches` or :attr:`Project.branches
10-
<gitlab.objects.Project.branches>` managers.
8+
* v4 API:
9+
10+
+ :class:`gitlab.v4.objects.ProjectBranch`
11+
+ :class:`gitlab.v4.objects.ProjectBranchManager`
12+
+ :attr:`gitlab.v4.objects.Project.branches`
13+
14+
* v3 API:
15+
16+
+ :class:`gitlab.v3.objects.ProjectBranch`
17+
+ :class:`gitlab.v3.objects.ProjectBranchManager`
18+
+ :attr:`gitlab.v3.objects.Project.branches`
19+
20+
* GitLab API: https://docs.gitlab.com/ce/api/branches.html
1121

1222
Examples
13-
========
23+
--------
1424

1525
Get the list of branches for a repository:
1626

@@ -41,10 +51,13 @@ Protect/unprotect a repository branch:
4151
.. literalinclude:: branches.py
4252
:start-after: # protect
4353
:end-before: # end protect
44-
54+
4555
.. note::
46-
47-
By default, developers will not be able to push or merge into
48-
protected branches. This can be changed by passing ``developers_can_push``
49-
or ``developers_can_merge`` like so:
50-
``branch.protect(developers_can_push=False, developers_can_merge=True)``
56+
57+
By default, developers are not authorized to push or merge into protected
58+
branches. This can be changed by passing ``developers_can_push`` or
59+
``developers_can_merge``:
60+
61+
.. code-block:: python
62+
63+
branch.protect(developers_can_push=True, developers_can_merge=True)

‎docs/gl_objects/builds.py‎

Lines changed: 17 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,12 @@
11
# var list
2-
variables = gl.project_variables.list(project_id=1)
3-
# or
42
variables = project.variables.list()
53
# end var list
64

75
# var get
8-
var = gl.project_variables.get(var_key, project_id=1)
9-
# or
106
var = project.variables.get(var_key)
117
# end var get
128

139
# var create
14-
var = gl.project_variables.create({'key': 'key1', 'value': 'value1'},
15-
project_id=1)
16-
# or
1710
var = project.variables.create({'key': 'key1', 'value': 'value1'})
1811
# end var create
1912

@@ -23,58 +16,47 @@
2316
# end var update
2417

2518
# var delete
26-
gl.project_variables.delete(var_key)
27-
# or
28-
project.variables.delete()
19+
project.variables.delete(var_key)
2920
# or
3021
var.delete()
3122
# end var delete
3223

3324
# trigger list
34-
triggers = gl.project_triggers.list(project_id=1)
35-
# or
3625
triggers = project.triggers.list()
3726
# end trigger list
3827

3928
# trigger get
40-
trigger = gl.project_triggers.get(trigger_token, project_id=1)
41-
# or
4229
trigger = project.triggers.get(trigger_token)
4330
# end trigger get
4431

4532
# trigger create
46-
trigger = gl.project_triggers.create({}, project_id=1)
47-
# or
4833
trigger = project.triggers.create({})
4934
# end trigger create
5035

5136
# trigger delete
52-
gl.project_triggers.delete(trigger_token)
53-
# or
54-
project.triggers.delete()
37+
project.triggers.delete(trigger_token)
5538
# or
5639
trigger.delete()
5740
# end trigger delete
5841

5942
# list
60-
builds = gl.project_builds.list(project_id=1)
61-
# or
62-
builds = project.builds.list()
43+
builds = project.builds.list() # v3
44+
jobs = project.jobs.list() # v4
6345
# end list
6446

6547
# commit list
48+
# v3 only
6649
commit = gl.project_commits.get(commit_sha, project_id=1)
6750
builds = commit.builds()
6851
# end commit list
6952

7053
# get
71-
build = gl.project_builds.get(build_id, project_id=1)
72-
# or
73-
project.builds.get(build_id)
54+
project.builds.get(build_id) # v3
55+
project.jobs.get(job_id) # v4
7456
# end get
7557

7658
# artifacts
77-
build.artifacts()
59+
build_or_job.artifacts()
7860
# end artifacts
7961

8062
# stream artifacts
@@ -86,33 +68,32 @@ def __call__(self, chunk):
8668
self._fd.write(chunk)
8769

8870
target = Foo()
89-
build.artifacts(streamed=True, action=target)
71+
build_or_job.artifacts(streamed=True, action=target)
9072
del(target) # flushes data on disk
9173
# end stream artifacts
9274

9375
# keep artifacts
94-
build.keep_artifacts()
76+
build_or_job.keep_artifacts()
9577
# end keep artifacts
9678

9779
# trace
98-
build.trace()
80+
build_or_job.trace()
9981
# end trace
10082

10183
# retry
102-
build.cancel()
103-
build.retry()
84+
build_or_job.cancel()
85+
build_or_job.retry()
10486
# end retry
10587

10688
# erase
107-
build.erase()
89+
build_or_job.erase()
10890
# end erase
10991

11092
# play
111-
build.play()
93+
build_or_job.play()
11294
# end play
11395

11496
# trigger run
115-
p = gl.projects.get(project_id)
116-
p.trigger_build('master', trigger_token,
117-
{'extra_var1': 'foo', 'extra_var2': 'bar'})
97+
project.trigger_build('master', trigger_token,
98+
{'extra_var1': 'foo', 'extra_var2': 'bar'})
11899
# end trigger run

0 commit comments

Comments
 (0)