From 438b22f57175afe5d694b25c589708f4ea9648ee Mon Sep 17 00:00:00 2001 From: Michael Sweikata Date: Mon, 23 May 2022 17:41:38 -0400 Subject: [PATCH] doc: API Doc Updates Updates the API docs to provide examples Clarifies https://github.com/python-gitlab/python-gitlab/discussions/2021 --- docs/api-usage.rst | 10 ++++++++++ docs/gl_objects/issues.rst | 11 +++++++++++ 2 files changed, 21 insertions(+) diff --git a/docs/api-usage.rst b/docs/api-usage.rst index e39082d2b..4dfa21e1f 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -192,6 +192,16 @@ You can print a Gitlab Object. For example: # Or explicitly via `pformat()`. This is equivalent to the above. print(project.pformat()) +You can also extend the object if the parameter isn't explicitly listed. For example, +if you want to update a field that has been newly introduced to the Gitlab API, setting +the value on the object is accepted: + +.. code-block:: python + + issues = project.issues.list(state='opened') + for issue in issues: + issue.my_super_awesome_feature_flag = "random_value" + issue.save() Base types ========== diff --git a/docs/gl_objects/issues.rst b/docs/gl_objects/issues.rst index dfb1ff7b5..0c89246db 100644 --- a/docs/gl_objects/issues.rst +++ b/docs/gl_objects/issues.rst @@ -133,6 +133,17 @@ Delete an issue (admin or project owner only):: # pr issue.delete() +Assign the issues:: + + issue = gl.issues.list()[0] + issue.assignee_ids = [25, 10, 31, 12] + issue.save() + +.. note:: + The Gitlab API explicitly references that the `assignee_id` field is deprecated, + so using a list of user IDs for `assignee_ids` is how to assign an issue to a user(s). + + Subscribe / unsubscribe from an issue:: issue.subscribe()