Document, expand, and fix sudo usage

Fix bugs with add and find functions.
Add 'with' statement usage.

Author: alexvh

README.md

@@ -38,6 +38,16 @@ for event in gl.project(1).events(limit=10):  # 10 most recent events
 for project in gl.projects(page=1, per_page=10):  # pagination
     print project.issues(limit=1)[0].title  # (assume issue[0] exists...)
 
+#
+# Sudo usage examples (GitLab v6.1+)
+# All functions accept an optional, undocumented, 'sudo' argument
+# specifiying a username or user id to act as.
+#
+gl.get_current_user(sudo='other_user')  # => 'other_user' CurrentUser object
+gl.projects(sudo=2)  # => list of user 2's projects
+with gl.sudo('other_user'):
+    gl.get_current_user()  # => 'other_user' CurrentUser object
+    gl.projects()  # => list of 'other_users's projects
 
 #
 # Example usage involving users

gitlab3/__init__.py

@@ -133,8 +133,14 @@ def fn(**kwargs):
             del kwargs['find_all']
         except KeyError:
             find_all = False
+        try:
+            query_data = {}
+            query_data['sudo'] = kwargs['sudo']
+            del kwargs['sudo']
+        except KeyError:
+            pass
         if not objects:
-            objects = _query_list(api, parent, {})
+            objects = _query_list(api, parent, query_data)
 
         return _find_matches(objects, kwargs, find_all)
     setattr(parent, 'find_' + name, fn)
@@ -256,6 +262,8 @@ def _add_api(definition, parent):
     else:
         uq_url = parent._uq_url
     uq_url += re.sub(r'/\:.*', '', url)  # "unqualify" the url
+    # 'sudo' is an optional parameter for all functions
+    definition.optional_params.append('sudo')
 
     cls_attrs = {
         '_key_name': definition.key_name,
@@ -466,3 +474,14 @@ def login(self, login_or_email, password):
         headers = {'PRIVATE-TOKEN': ret['private_token']}
         setattr(_GitLabAPI, '_headers', headers)
         return True
+
+    class sudo:
+        """Alternative sudo usage. To be used with the 'with' statement"""
+        def __init__(self, username_or_id):
+            self.user = username_or_id
+        def __enter__(self):
+            headers = getattr(_GitLabAPI, '_headers')
+            headers['SUDO'] = self.user
+        def __exit__(self, type, value, traceback):
+            headers = getattr(_GitLabAPI, '_headers')
+            del headers['SUDO']