##// END OF EJS Templates
docs: updated API docs
marcink -
r4523:53d2eca7 stable
parent child Browse files
Show More
@@ -1,448 +1,465 b''
1 1 .. _pull-request-methods-ref:
2 2
3 3 pull_request methods
4 4 ====================
5 5
6 6 close_pull_request
7 7 ------------------
8 8
9 9 .. py:function:: close_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>, message=<Optional:''>)
10 10
11 11 Close the pull request specified by `pullrequestid`.
12 12
13 13 :param apiuser: This is filled automatically from the |authtoken|.
14 14 :type apiuser: AuthUser
15 15 :param repoid: Repository name or repository ID to which the pull
16 16 request belongs.
17 17 :type repoid: str or int
18 18 :param pullrequestid: ID of the pull request to be closed.
19 19 :type pullrequestid: int
20 20 :param userid: Close the pull request as this user.
21 21 :type userid: Optional(str or int)
22 22 :param message: Optional message to close the Pull Request with. If not
23 23 specified it will be generated automatically.
24 24 :type message: Optional(str)
25 25
26 26 Example output:
27 27
28 28 .. code-block:: bash
29 29
30 30 "id": <id_given_in_input>,
31 31 "result": {
32 32 "pull_request_id": "<int>",
33 33 "close_status": "<str:status_lbl>,
34 34 "closed": "<bool>"
35 35 },
36 36 "error": null
37 37
38 38
39 39 comment_pull_request
40 40 --------------------
41 41
42 42 .. py:function:: comment_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, message=<Optional:None>, commit_id=<Optional:None>, status=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, extra_recipients=<Optional:[]>, userid=<Optional:<OptionalAttr:apiuser>>, send_email=<Optional:True>)
43 43
44 44 Comment on the pull request specified with the `pullrequestid`,
45 45 in the |repo| specified by the `repoid`, and optionally change the
46 46 review status.
47 47
48 48 :param apiuser: This is filled automatically from the |authtoken|.
49 49 :type apiuser: AuthUser
50 50 :param repoid: Optional repository name or repository ID.
51 51 :type repoid: str or int
52 52 :param pullrequestid: The pull request ID.
53 53 :type pullrequestid: int
54 54 :param commit_id: Specify the commit_id for which to set a comment. If
55 55 given commit_id is different than latest in the PR status
56 56 change won't be performed.
57 57 :type commit_id: str
58 58 :param message: The text content of the comment.
59 59 :type message: str
60 60 :param status: (**Optional**) Set the approval status of the pull
61 61 request. One of: 'not_reviewed', 'approved', 'rejected',
62 62 'under_review'
63 63 :type status: str
64 64 :param comment_type: Comment type, one of: 'note', 'todo'
65 65 :type comment_type: Optional(str), default: 'note'
66 66 :param resolves_comment_id: id of comment which this one will resolve
67 67 :type resolves_comment_id: Optional(int)
68 68 :param extra_recipients: list of user ids or usernames to add
69 69 notifications for this comment. Acts like a CC for notification
70 70 :type extra_recipients: Optional(list)
71 71 :param userid: Comment on the pull request as this user
72 72 :type userid: Optional(str or int)
73 73 :param send_email: Define if this comment should also send email notification
74 74 :type send_email: Optional(bool)
75 75
76 76 Example output:
77 77
78 78 .. code-block:: bash
79 79
80 80 id : <id_given_in_input>
81 81 result : {
82 82 "pull_request_id": "<Integer>",
83 83 "comment_id": "<Integer>",
84 84 "status": {"given": <given_status>,
85 85 "was_changed": <bool status_was_actually_changed> },
86 86 },
87 87 error : null
88 88
89 89
90 90 create_pull_request
91 91 -------------------
92 92
93 .. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, owner=<Optional:<OptionalAttr:apiuser>>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>)
93 .. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, owner=<Optional:<OptionalAttr:apiuser>>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>, observers=<Optional:None>)
94 94
95 95 Creates a new pull request.
96 96
97 97 Accepts refs in the following formats:
98 98
99 99 * branch:<branch_name>:<sha>
100 100 * branch:<branch_name>
101 101 * bookmark:<bookmark_name>:<sha> (Mercurial only)
102 102 * bookmark:<bookmark_name> (Mercurial only)
103 103
104 104 :param apiuser: This is filled automatically from the |authtoken|.
105 105 :type apiuser: AuthUser
106 106 :param source_repo: Set the source repository name.
107 107 :type source_repo: str
108 108 :param target_repo: Set the target repository name.
109 109 :type target_repo: str
110 110 :param source_ref: Set the source ref name.
111 111 :type source_ref: str
112 112 :param target_ref: Set the target ref name.
113 113 :type target_ref: str
114 114 :param owner: user_id or username
115 115 :type owner: Optional(str)
116 116 :param title: Optionally Set the pull request title, it's generated otherwise
117 117 :type title: str
118 118 :param description: Set the pull request description.
119 119 :type description: Optional(str)
120 120 :type description_renderer: Optional(str)
121 121 :param description_renderer: Set pull request renderer for the description.
122 122 It should be 'rst', 'markdown' or 'plain'. If not give default
123 123 system renderer will be used
124 124 :param reviewers: Set the new pull request reviewers list.
125 125 Reviewer defined by review rules will be added automatically to the
126 126 defined list.
127 127 :type reviewers: Optional(list)
128 128 Accepts username strings or objects of the format:
129 129
130 130 [{'username': 'nick', 'reasons': ['original author'], 'mandatory': <bool>}]
131 :param observers: Set the new pull request observers list.
132 Reviewer defined by review rules will be added automatically to the
133 defined list. This feature is only available in RhodeCode EE
134 :type observers: Optional(list)
135 Accepts username strings or objects of the format:
136
137 [{'username': 'nick', 'reasons': ['original author']}]
131 138
132 139
133 140 get_pull_request
134 141 ----------------
135 142
136 143 .. py:function:: get_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, merge_state=<Optional:False>)
137 144
138 145 Get a pull request based on the given ID.
139 146
140 147 :param apiuser: This is filled automatically from the |authtoken|.
141 148 :type apiuser: AuthUser
142 149 :param repoid: Optional, repository name or repository ID from where
143 150 the pull request was opened.
144 151 :type repoid: str or int
145 152 :param pullrequestid: ID of the requested pull request.
146 153 :type pullrequestid: int
147 154 :param merge_state: Optional calculate merge state for each repository.
148 155 This could result in longer time to fetch the data
149 156 :type merge_state: bool
150 157
151 158 Example output:
152 159
153 160 .. code-block:: bash
154 161
155 162 "id": <id_given_in_input>,
156 163 "result":
157 164 {
158 165 "pull_request_id": "<pull_request_id>",
159 166 "url": "<url>",
160 167 "title": "<title>",
161 168 "description": "<description>",
162 169 "status" : "<status>",
163 170 "created_on": "<date_time_created>",
164 171 "updated_on": "<date_time_updated>",
165 172 "versions": "<number_or_versions_of_pr>",
166 173 "commit_ids": [
167 174 ...
168 175 "<commit_id>",
169 176 "<commit_id>",
170 177 ...
171 178 ],
172 179 "review_status": "<review_status>",
173 180 "mergeable": {
174 181 "status": "<bool>",
175 182 "message": "<message>",
176 183 },
177 184 "source": {
178 185 "clone_url": "<clone_url>",
179 186 "repository": "<repository_name>",
180 187 "reference":
181 188 {
182 189 "name": "<name>",
183 190 "type": "<type>",
184 191 "commit_id": "<commit_id>",
185 192 }
186 193 },
187 194 "target": {
188 195 "clone_url": "<clone_url>",
189 196 "repository": "<repository_name>",
190 197 "reference":
191 198 {
192 199 "name": "<name>",
193 200 "type": "<type>",
194 201 "commit_id": "<commit_id>",
195 202 }
196 203 },
197 204 "merge": {
198 205 "clone_url": "<clone_url>",
199 206 "reference":
200 207 {
201 208 "name": "<name>",
202 209 "type": "<type>",
203 210 "commit_id": "<commit_id>",
204 211 }
205 212 },
206 213 "author": <user_obj>,
207 214 "reviewers": [
208 215 ...
209 216 {
210 217 "user": "<user_obj>",
211 218 "review_status": "<review_status>",
212 219 }
213 220 ...
214 221 ]
215 222 },
216 223 "error": null
217 224
218 225
219 226 get_pull_request_comments
220 227 -------------------------
221 228
222 229 .. py:function:: get_pull_request_comments(apiuser, pullrequestid, repoid=<Optional:None>)
223 230
224 231 Get all comments of pull request specified with the `pullrequestid`
225 232
226 233 :param apiuser: This is filled automatically from the |authtoken|.
227 234 :type apiuser: AuthUser
228 235 :param repoid: Optional repository name or repository ID.
229 236 :type repoid: str or int
230 237 :param pullrequestid: The pull request ID.
231 238 :type pullrequestid: int
232 239
233 240 Example output:
234 241
235 242 .. code-block:: bash
236 243
237 244 id : <id_given_in_input>
238 245 result : [
239 246 {
240 247 "comment_author": {
241 248 "active": true,
242 249 "full_name_or_username": "Tom Gore",
243 250 "username": "admin"
244 251 },
245 252 "comment_created_on": "2017-01-02T18:43:45.533",
246 253 "comment_f_path": null,
247 254 "comment_id": 25,
248 255 "comment_lineno": null,
249 256 "comment_status": {
250 257 "status": "under_review",
251 258 "status_lbl": "Under Review"
252 259 },
253 260 "comment_text": "Example text",
254 261 "comment_type": null,
255 262 "comment_last_version: 0,
256 263 "pull_request_version": null,
257 264 "comment_commit_id": None,
258 265 "comment_pull_request_id": <pull_request_id>
259 266 }
260 267 ],
261 268 error : null
262 269
263 270
264 271 get_pull_requests
265 272 -----------------
266 273
267 274 .. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>, merge_state=<Optional:False>)
268 275
269 276 Get all pull requests from the repository specified in `repoid`.
270 277
271 278 :param apiuser: This is filled automatically from the |authtoken|.
272 279 :type apiuser: AuthUser
273 280 :param repoid: Optional repository name or repository ID.
274 281 :type repoid: str or int
275 282 :param status: Only return pull requests with the specified status.
276 283 Valid options are.
277 284 * ``new`` (default)
278 285 * ``open``
279 286 * ``closed``
280 287 :type status: str
281 288 :param merge_state: Optional calculate merge state for each repository.
282 289 This could result in longer time to fetch the data
283 290 :type merge_state: bool
284 291
285 292 Example output:
286 293
287 294 .. code-block:: bash
288 295
289 296 "id": <id_given_in_input>,
290 297 "result":
291 298 [
292 299 ...
293 300 {
294 301 "pull_request_id": "<pull_request_id>",
295 302 "url": "<url>",
296 303 "title" : "<title>",
297 304 "description": "<description>",
298 305 "status": "<status>",
299 306 "created_on": "<date_time_created>",
300 307 "updated_on": "<date_time_updated>",
301 308 "commit_ids": [
302 309 ...
303 310 "<commit_id>",
304 311 "<commit_id>",
305 312 ...
306 313 ],
307 314 "review_status": "<review_status>",
308 315 "mergeable": {
309 316 "status": "<bool>",
310 317 "message: "<message>",
311 318 },
312 319 "source": {
313 320 "clone_url": "<clone_url>",
314 321 "reference":
315 322 {
316 323 "name": "<name>",
317 324 "type": "<type>",
318 325 "commit_id": "<commit_id>",
319 326 }
320 327 },
321 328 "target": {
322 329 "clone_url": "<clone_url>",
323 330 "reference":
324 331 {
325 332 "name": "<name>",
326 333 "type": "<type>",
327 334 "commit_id": "<commit_id>",
328 335 }
329 336 },
330 337 "merge": {
331 338 "clone_url": "<clone_url>",
332 339 "reference":
333 340 {
334 341 "name": "<name>",
335 342 "type": "<type>",
336 343 "commit_id": "<commit_id>",
337 344 }
338 345 },
339 346 "author": <user_obj>,
340 347 "reviewers": [
341 348 ...
342 349 {
343 350 "user": "<user_obj>",
344 351 "review_status": "<review_status>",
345 352 }
346 353 ...
347 354 ]
348 355 }
349 356 ...
350 357 ],
351 358 "error": null
352 359
353 360
354 361 merge_pull_request
355 362 ------------------
356 363
357 364 .. py:function:: merge_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
358 365
359 366 Merge the pull request specified by `pullrequestid` into its target
360 367 repository.
361 368
362 369 :param apiuser: This is filled automatically from the |authtoken|.
363 370 :type apiuser: AuthUser
364 371 :param repoid: Optional, repository name or repository ID of the
365 372 target repository to which the |pr| is to be merged.
366 373 :type repoid: str or int
367 374 :param pullrequestid: ID of the pull request which shall be merged.
368 375 :type pullrequestid: int
369 376 :param userid: Merge the pull request as this user.
370 377 :type userid: Optional(str or int)
371 378
372 379 Example output:
373 380
374 381 .. code-block:: bash
375 382
376 383 "id": <id_given_in_input>,
377 384 "result": {
378 385 "executed": "<bool>",
379 386 "failure_reason": "<int>",
380 387 "merge_status_message": "<str>",
381 388 "merge_commit_id": "<merge_commit_id>",
382 389 "possible": "<bool>",
383 390 "merge_ref": {
384 391 "commit_id": "<commit_id>",
385 392 "type": "<type>",
386 393 "name": "<name>"
387 394 }
388 395 },
389 396 "error": null
390 397
391 398
392 399 update_pull_request
393 400 -------------------
394 401
395 .. py:function:: update_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>, update_commits=<Optional:None>)
402 .. py:function:: update_pull_request(apiuser, pullrequestid, repoid=<Optional:None>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>, observers=<Optional:None>, update_commits=<Optional:None>)
396 403
397 404 Updates a pull request.
398 405
399 406 :param apiuser: This is filled automatically from the |authtoken|.
400 407 :type apiuser: AuthUser
401 408 :param repoid: Optional repository name or repository ID.
402 409 :type repoid: str or int
403 410 :param pullrequestid: The pull request ID.
404 411 :type pullrequestid: int
405 412 :param title: Set the pull request title.
406 413 :type title: str
407 414 :param description: Update pull request description.
408 415 :type description: Optional(str)
409 416 :type description_renderer: Optional(str)
410 417 :param description_renderer: Update pull request renderer for the description.
411 418 It should be 'rst', 'markdown' or 'plain'
412 419 :param reviewers: Update pull request reviewers list with new value.
413 420 :type reviewers: Optional(list)
414 421 Accepts username strings or objects of the format:
415 422
416 423 [{'username': 'nick', 'reasons': ['original author'], 'mandatory': <bool>}]
424 :param observers: Update pull request observers list with new value.
425 :type observers: Optional(list)
426 Accepts username strings or objects of the format:
417 427
428 [{'username': 'nick', 'reasons': ['should be aware about this PR']}]
418 429 :param update_commits: Trigger update of commits for this pull request
419 430 :type: update_commits: Optional(bool)
420 431
421 432 Example output:
422 433
423 434 .. code-block:: bash
424 435
425 436 id : <id_given_in_input>
426 437 result : {
427 438 "msg": "Updated pull request `63`",
428 439 "pull_request": <pull_request_object>,
429 440 "updated_reviewers": {
430 441 "added": [
431 442 "username"
432 443 ],
433 444 "removed": []
434 445 },
446 "updated_observers": {
447 "added": [
448 "username"
449 ],
450 "removed": []
451 },
435 452 "updated_commits": {
436 453 "added": [
437 454 "<sha1_hash>"
438 455 ],
439 456 "common": [
440 457 "<sha1_hash>",
441 458 "<sha1_hash>",
442 459 ],
443 460 "removed": []
444 461 }
445 462 }
446 463 error : null
447 464
448 465
General Comments 0
You need to be logged in to leave comments. Login now