1.. _issues_examples:
2
3######
4Issues
5######
6
7Reported issues
8===============
9
10Reference
11---------
12
13* v4 API:
14
15  + :class:`gitlab.v4.objects.Issue`
16  + :class:`gitlab.v4.objects.IssueManager`
17  + :attr:`gitlab.Gitlab.issues`
18
19* GitLab API: https://docs.gitlab.com/ce/api/issues.html
20
21Examples
22--------
23
24List the issues::
25
26    issues = gl.issues.list()
27
28Use the ``state`` and ``label`` parameters to filter the results. Use the
29``order_by`` and ``sort`` attributes to sort the results::
30
31    open_issues = gl.issues.list(state='opened')
32    closed_issues = gl.issues.list(state='closed')
33    tagged_issues = gl.issues.list(labels=['foo', 'bar'])
34
35.. note::
36
37   It is not possible to edit or delete Issue objects. You need to create a
38   ProjectIssue object to perform changes::
39
40       issue = gl.issues.list()[0]
41       project = gl.projects.get(issue.project_id, lazy=True)
42       editable_issue = project.issues.get(issue.iid, lazy=True)
43       editable_issue.title = updated_title
44       editable_issue.save()
45
46Group issues
47============
48
49Reference
50---------
51
52* v4 API:
53
54  + :class:`gitlab.v4.objects.GroupIssue`
55  + :class:`gitlab.v4.objects.GroupIssueManager`
56  + :attr:`gitlab.v4.objects.Group.issues`
57
58* GitLab API: https://docs.gitlab.com/ce/api/issues.html
59
60Examples
61--------
62
63List the group issues::
64
65    issues = group.issues.list()
66    # Filter using the state, labels and milestone parameters
67    issues = group.issues.list(milestone='1.0', state='opened')
68    # Order using the order_by and sort parameters
69    issues = group.issues.list(order_by='created_at', sort='desc')
70
71.. note::
72
73   It is not possible to edit or delete GroupIssue objects. You need to create
74   a ProjectIssue object to perform changes::
75
76       issue = group.issues.list()[0]
77       project = gl.projects.get(issue.project_id, lazy=True)
78       editable_issue = project.issues.get(issue.iid, lazy=True)
79       editable_issue.title = updated_title
80       editable_issue.save()
81
82Project issues
83==============
84
85Reference
86---------
87
88* v4 API:
89
90  + :class:`gitlab.v4.objects.ProjectIssue`
91  + :class:`gitlab.v4.objects.ProjectIssueManager`
92  + :attr:`gitlab.v4.objects.Project.issues`
93
94* GitLab API: https://docs.gitlab.com/ce/api/issues.html
95
96Examples
97--------
98
99List the project issues::
100
101    issues = project.issues.list()
102    # Filter using the state, labels and milestone parameters
103    issues = project.issues.list(milestone='1.0', state='opened')
104    # Order using the order_by and sort parameters
105    issues = project.issues.list(order_by='created_at', sort='desc')
106
107Get a project issue::
108
109    issue = project.issues.get(issue_iid)
110
111Create a new issue::
112
113    issue = project.issues.create({'title': 'I have a bug',
114                                   'description': 'Something useful here.'})
115
116Update an issue::
117
118    issue.labels = ['foo', 'bar']
119    issue.save()
120
121Close / reopen an issue::
122
123    # close an issue
124    issue.state_event = 'close'
125    issue.save()
126    # reopen it
127    issue.state_event = 'reopen'
128    issue.save()
129
130Delete an issue (admin or project owner only)::
131
132    project.issues.delete(issue_id)
133    # pr
134    issue.delete()
135
136Subscribe / unsubscribe from an issue::
137
138    issue.subscribe()
139    issue.unsubscribe()
140
141Move an issue to another project::
142
143    issue.move(other_project_id)
144
145Make an issue as todo::
146
147    issue.todo()
148
149Get time tracking stats::
150
151    issue.time_stats()
152
153On recent versions of Gitlab the time stats are also returned as an issue
154object attribute::
155
156    issue = project.issue.get(iid)
157    print(issue.attributes['time_stats'])
158
159Set a time estimate for an issue::
160
161    issue.time_estimate('3h30m')
162
163Reset a time estimate for an issue::
164
165    issue.reset_time_estimate()
166
167Add spent time for an issue::
168
169    issue.add_spent_time('3h30m')
170
171Reset spent time for an issue::
172
173    issue.reset_spent_time()
174
175Get user agent detail for the issue (admin only)::
176
177    detail = issue.user_agent_detail()
178
179Get the list of merge requests that will close an issue when merged::
180
181    mrs = issue.closed_by()
182
183Get the merge requests related to an issue::
184
185    mrs = issue.related_merge_requests()
186
187Get the list of participants::
188
189    users = issue.participants()
190
191Issue links
192===========
193
194Reference
195---------
196
197* v4 API:
198
199  + :class:`gitlab.v4.objects.ProjectIssueLink`
200  + :class:`gitlab.v4.objects.ProjectIssueLinkManager`
201  + :attr:`gitlab.v4.objects.ProjectIssue.links`
202
203* GitLab API: https://docs.gitlab.com/ee/api/issue_links.html (EE feature)
204
205Examples
206--------
207
208List the issues linked to ``i1``::
209
210    links = i1.links.list()
211
212Link issue ``i1`` to issue ``i2``::
213
214    data = {
215        'target_project_id': i2.project_id,
216        'target_issue_iid': i2.iid
217    }
218    src_issue, dest_issue = i1.links.create(data)
219
220.. note::
221
222   The ``create()`` method returns the source and destination ``ProjectIssue``
223   objects, not a ``ProjectIssueLink`` object.
224
225Delete a link::
226
227    i1.links.delete(issue_link_id)
228
229Issues statistics
230=========================
231
232Reference
233---------
234
235* v4 API:
236
237  + :class:`gitlab.v4.objects.IssuesStatistics`
238  + :class:`gitlab.v4.objects.IssuesStatisticsManager`
239  + :attr:`gitlab.issues_statistics`
240  + :class:`gitlab.v4.objects.GroupIssuesStatistics`
241  + :class:`gitlab.v4.objects.GroupIssuesStatisticsManager`
242  + :attr:`gitlab.v4.objects.Group.issues_statistics`
243  + :class:`gitlab.v4.objects.ProjectIssuesStatistics`
244  + :class:`gitlab.v4.objects.ProjectIssuesStatisticsManager`
245  + :attr:`gitlab.v4.objects.Project.issues_statistics`
246
247
248* GitLab API: https://docs.gitlab.com/ce/api/issues_statistics.htm
249
250Examples
251---------
252
253Get statistics of all issues created by the current user::
254
255    statistics = gl.issues_statistics.get()
256
257Get statistics of all issues the user has access to::
258
259    statistics = gl.issues_statistics.get(scope='all')
260
261Get statistics of issues for the user with ``foobar`` in the ``title`` or the ``description``::
262
263    statistics = gl.issues_statistics.get(search='foobar')
264
265Get statistics of all issues in a group::
266
267    statistics = group.issues_statistics.get()
268
269Get statistics of issues in a group with ``foobar`` in the ``title`` or the ``description``::
270
271    statistics = group.issues_statistics.get(search='foobar')
272
273Get statistics of all issues in a project::
274
275    statistics = project.issues_statistics.get()
276
277Get statistics of issues in a project with ``foobar`` in the ``title`` or the ``description``::
278
279    statistics = project.issues_statistics.get(search='foobar')
280