Commit d509da60 authored by John L. Villalovos's avatar John L. Villalovos Committed by Nejc Habjan
Browse files

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
parent 6b37811c

docs/api-usage.rst

+21 −0
Original line number Diff line number Diff line
@@ -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

=======