From 9fe6b9f1d798811b76a21ff7ef87944af86b3077 Mon Sep 17 00:00:00 2001 From: "John L. Villalovos" Date: Mon, 15 Jul 2024 08:07:32 -0700 Subject: [PATCH] docs: document how to use `sudo` if modifying an object Add a warning about using `sudo` when saving. Give an example of how to `get` an object, modify it, and then `save` it using `sudo` Closes: #532 --- docs/api-usage.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/api-usage.rst b/docs/api-usage.rst index 09d9239bf..61be295ed 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -411,6 +411,27 @@ user. For example: p = gl.projects.create({'name': 'awesome_project'}, sudo='user1') +.. warning:: + When using ``sudo``, its usage is not remembered. If you use ``sudo`` to + retrieve an object and then later use ``save()`` to modify the object, it + will not use ``sudo``. You should use ``save(sudo='user1')`` if you want to + perform subsequent actions as the user. + +Updating with ``sudo`` +---------------------- + +An example of how to ``get`` an object (using ``sudo``), modify the object, and +then ``save`` the object (using ``sudo``): + +.. code-block:: python + + group = gl.groups.get('example-group') + notification_setting = group.notificationsettings.get(sudo='user1') + notification_setting.level = gitlab.const.NOTIFICATION_LEVEL_GLOBAL + # Must use `sudo` again when doing the save. + notification_setting.save(sudo='user1') + + Logging =======