Restore correct exceptions

Match the exceptions raised in v3 for v4.

Also update the doc strings with correct information.

1 files changed, 111 insertions, 44 deletions

diff --git a/gitlab/mixins.py b/gitlab/mixins.py
index 6b5475c..cc9eb51 100644
--- a/gitlab/mixins.py
+++ b/gitlab/mixins.py
@@ -17,10 +17,11 @@
 
 import gitlab
 from gitlab import base
-from gitlab import exceptions
+from gitlab import exceptions as exc
 
 
 class GetMixin(object):
+    @exc.on_http_error(exc.GitlabGetError)
     def get(self, id, lazy=False, **kwargs):
         """Retrieve a single object.
 
@@ -29,45 +30,48 @@ class GetMixin(object):
             lazy (bool): If True, don't request the server, but create a
                          shallow object giving access to the managers. This is
                          useful if you want to avoid useless calls to the API.
-            **kwargs: Extra data to send to the Gitlab server (e.g. sudo)
+            **kwargs: Extra options to send to the Gitlab server (e.g. sudo)
 
         Returns:
             object: The generated RESTObject.
 
         Raises:
-            GitlabGetError: If the server cannot perform the request.
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabGetError: If the server cannot perform the request
         """
         path = '%s/%s' % (self.path, id)
         if lazy is True:
             return self._obj_cls(self, {self._obj_cls._id_attr: id})
-
         server_data = self.gitlab.http_get(path, **kwargs)
         return self._obj_cls(self, server_data)
 
 
 class GetWithoutIdMixin(object):
+    @exc.on_http_error(exc.GitlabGetError)
     def get(self, **kwargs):
         """Retrieve a single object.
 
         Args:
-            **kwargs: Extra data to send to the Gitlab server (e.g. sudo)
+            **kwargs: Extra options to send to the Gitlab server (e.g. sudo)
 
         Returns:
-            object: The generated RESTObject.
+            object: The generated RESTObject
 
         Raises:
-            GitlabGetError: If the server cannot perform the request.
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabGetError: If the server cannot perform the request
         """
         server_data = self.gitlab.http_get(self.path, **kwargs)
         return self._obj_cls(self, server_data)
 
 
 class ListMixin(object):
+    @exc.on_http_error(exc.GitlabListError)
     def list(self, **kwargs):
-        """Retrieves a list of objects.
+        """Retrieve a list of objects.
 
         Args:
-            **kwargs: Extra data to send to the Gitlab server (e.g. sudo).
+            **kwargs: Extra options to send to the Gitlab server (e.g. sudo).
                       If ``all`` is passed and set to True, the entire list of
                       objects will be returned.
 
@@ -76,11 +80,14 @@ class ListMixin(object):
                             queries to the server when required.
                             If ``all=True`` is passed as argument, returns
                             list(RESTObjectList).
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabListError: If the server cannot perform the request
         """
 
         # Allow to overwrite the path, handy for custom listings
         path = kwargs.pop('path', self.path)
-
         obj = self.gitlab.http_list(path, **kwargs)
         if isinstance(obj, list):
             return [self._obj_cls(self, item) for item in obj]
@@ -94,20 +101,21 @@ class GetFromListMixin(ListMixin):
 
         Args:
             id (int or str): ID of the object to retrieve
-            **kwargs: Extra data to send to the Gitlab server (e.g. sudo)
+            **kwargs: Extra options to send to the Gitlab server (e.g. sudo)
 
         Returns:
-            object: The generated RESTObject.
+            object: The generated RESTObject
 
         Raises:
-            AttributeError: If the object could not be found in the list
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabGetError: If the server cannot perform the request
         """
         gen = self.list()
         for obj in gen:
             if str(obj.get_id()) == str(id):
                 return obj
 
-        raise exceptions.GitlabHttpError(404, "Not found")
+        raise exc.GitlabGetError(response_code=404, error_message="Not found")
 
 
 class RetrieveMixin(ListMixin, GetMixin):
@@ -126,7 +134,7 @@ class CreateMixin(object):
             raise AttributeError("Missing attributes: %s" % ", ".join(missing))
 
     def get_create_attrs(self):
-        """Returns the required and optional arguments.
+        """Return the required and optional arguments.
 
         Returns:
             tuple: 2 items: list of required arguments and list of optional
@@ -134,17 +142,22 @@ class CreateMixin(object):
         """
         return getattr(self, '_create_attrs', (tuple(), tuple()))
 
+    @exc.on_http_error(exc.GitlabCreateError)
     def create(self, data, **kwargs):
-        """Creates a new object.
+        """Create a new object.
 
         Args:
             data (dict): parameters to send to the server to create the
                          resource
-            **kwargs: Extra data to send to the Gitlab server (e.g. sudo)
+            **kwargs: Extra options to send to the Gitlab server (e.g. sudo)
 
         Returns:
-            RESTObject: a new instance of the manage object class build with
-                        the data sent by the server
+            RESTObject: a new instance of the managed object class build with
+                the data sent by the server
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabCreateError: If the server cannot perform the request
         """
         self._check_missing_create_attrs(data)
         if hasattr(self, '_sanitize_data'):
@@ -167,7 +180,7 @@ class UpdateMixin(object):
             raise AttributeError("Missing attributes: %s" % ", ".join(missing))
 
     def get_update_attrs(self):
-        """Returns the required and optional arguments.
+        """Return the required and optional arguments.
 
         Returns:
             tuple: 2 items: list of required arguments and list of optional
@@ -175,16 +188,21 @@ class UpdateMixin(object):
         """
         return getattr(self, '_update_attrs', (tuple(), tuple()))
 
+    @exc.on_http_error(exc.GitlabUpdateError)
     def update(self, id=None, new_data={}, **kwargs):
         """Update an object on the server.
 
         Args:
             id: ID of the object to update (can be None if not required)
             new_data: the update data for the object
-            **kwargs: Extra data to send to the Gitlab server (e.g. sudo)
+            **kwargs: Extra options to send to the Gitlab server (e.g. sudo)
 
         Returns:
             dict: The new object data (*not* a RESTObject)
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabUpdateError: If the server cannot perform the request
         """
 
         if id is None:
@@ -197,17 +215,22 @@ class UpdateMixin(object):
             data = self._sanitize_data(new_data, 'update')
         else:
             data = new_data
-        server_data = self.gitlab.http_put(path, post_data=data, **kwargs)
-        return server_data
+
+        return self.gitlab.http_put(path, post_data=data, **kwargs)
 
 
 class DeleteMixin(object):
+    @exc.on_http_error(exc.GitlabDeleteError)
     def delete(self, id, **kwargs):
-        """Deletes an object on the server.
+        """Delete an object on the server.
 
         Args:
             id: ID of the object to delete
-            **kwargs: Extra data to send to the Gitlab server (e.g. sudo)
+            **kwargs: Extra options to send to the Gitlab server (e.g. sudo)
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabDeleteError: If the server cannot perform the request
         """
         path = '%s/%s' % (self.path, id)
         self.gitlab.http_delete(path, **kwargs)
@@ -235,12 +258,16 @@ class SaveMixin(object):
         return updated_data
 
     def save(self, **kwargs):
-        """Saves the changes made to the object to the server.
+        """Save the changes made to the object to the server.
+
+        The object is updated to match what the server returns.
 
         Args:
-            **kwargs: Extra option to send to the server (e.g. sudo)
+            **kwargs: Extra options to send to the server (e.g. sudo)
 
-        The object is updated to match what the server returns.
+        Raise:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabUpdateError: If the server cannot perform the request
         """
         updated_data = self._get_updated_data()
 
@@ -256,21 +283,27 @@ class ObjectDeleteMixin(object):
         """Delete the object from the server.
 
         Args:
-            **kwargs: Extra option to send to the server (e.g. sudo)
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabDeleteError: If the server cannot perform the request
         """
         self.manager.delete(self.get_id())
 
 
 class AccessRequestMixin(object):
+    @exc.on_http_error(exc.GitlabUpdateError)
     def approve(self, access_level=gitlab.DEVELOPER_ACCESS, **kwargs):
         """Approve an access request.
 
         Attrs:
-            access_level (int): The access level for the user.
+            access_level (int): The access level for the user
+            **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
-            GitlabConnectionError: If the server cannot be reached.
-            GitlabUpdateError: If the server fails to perform the request.
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabUpdateError: If the server fails to perform the request
         """
 
         path = '%s/%s/approve' % (self.manager.path, self.id)
@@ -281,23 +314,31 @@ class AccessRequestMixin(object):
 
 
 class SubscribableMixin(object):
+    @exc.on_http_error(exc.GitlabSubscribeError)
     def subscribe(self, **kwargs):
         """Subscribe to the object notifications.
 
+        Args:
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
         raises:
-            gitlabconnectionerror: if the server cannot be reached.
-            gitlabsubscribeerror: if the subscription cannot be done
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabSubscribeError: If the subscription cannot be done
         """
         path = '%s/%s/subscribe' % (self.manager.path, self.get_id())
         server_data = self.manager.gitlab.http_post(path, **kwargs)
         self._update_attrs(server_data)
 
+    @exc.on_http_error(exc.GitlabUnsubscribeError)
     def unsubscribe(self, **kwargs):
         """Unsubscribe from the object notifications.
 
+        Args:
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
         raises:
-            gitlabconnectionerror: if the server cannot be reached.
-            gitlabunsubscribeerror: if the unsubscription cannot be done
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabUnsubscribeError: If the unsubscription cannot be done
         """
         path = '%s/%s/unsubscribe' % (self.manager.path, self.get_id())
         server_data = self.manager.gitlab.http_post(path, **kwargs)
@@ -305,66 +346,92 @@ class SubscribableMixin(object):
 
 
 class TodoMixin(object):
+    @exc.on_http_error(exc.GitlabHttpError)
     def todo(self, **kwargs):
         """Create a todo associated to the object.
 
+        Args:
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
         Raises:
-            GitlabConnectionError: If the server cannot be reached.
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabTodoError: If the todo cannot be set
         """
         path = '%s/%s/todo' % (self.manager.path, self.get_id())
         self.manager.gitlab.http_post(path, **kwargs)
 
 
 class TimeTrackingMixin(object):
+    @exc.on_http_error(exc.GitlabTimeTrackingError)
     def time_stats(self, **kwargs):
         """Get time stats for the object.
 
+        Args:
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
         Raises:
-            GitlabConnectionError: If the server cannot be reached.
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabTimeTrackingError: If the time tracking update cannot be done
         """
         path = '%s/%s/time_stats' % (self.manager.path, self.get_id())
         return self.manager.gitlab.http_get(path, **kwargs)
 
+    @exc.on_http_error(exc.GitlabTimeTrackingError)
     def time_estimate(self, duration, **kwargs):
         """Set an estimated time of work for the object.
 
         Args:
-            duration (str): duration in human format (e.g. 3h30)
+            duration (str): Duration in human format (e.g. 3h30)
+            **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
-            GitlabConnectionError: If the server cannot be reached.
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabTimeTrackingError: If the time tracking update cannot be done
         """
         path = '%s/%s/time_estimate' % (self.manager.path, self.get_id())
         data = {'duration': duration}
         return self.manager.gitlab.http_post(path, post_data=data, **kwargs)
 
+    @exc.on_http_error(exc.GitlabTimeTrackingError)
     def reset_time_estimate(self, **kwargs):
         """Resets estimated time for the object to 0 seconds.
 
+        Args:
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
         Raises:
-            GitlabConnectionError: If the server cannot be reached.
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabTimeTrackingError: If the time tracking update cannot be done
         """
         path = '%s/%s/rest_time_estimate' % (self.manager.path, self.get_id())
         return self.manager.gitlab.http_post(path, **kwargs)
 
+    @exc.on_http_error(exc.GitlabTimeTrackingError)
     def add_spent_time(self, duration, **kwargs):
         """Add time spent working on the object.
 
         Args:
-            duration (str): duration in human format (e.g. 3h30)
+            duration (str): Duration in human format (e.g. 3h30)
+            **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
-            GitlabConnectionError: If the server cannot be reached.
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabTimeTrackingError: If the time tracking update cannot be done
         """
         path = '%s/%s/add_spent_time' % (self.manager.path, self.get_id())
         data = {'duration': duration}
         return self.manager.gitlab.http_post(path, post_data=data, **kwargs)
 
+    @exc.on_http_error(exc.GitlabTimeTrackingError)
     def reset_spent_time(self, **kwargs):
         """Resets the time spent working on the object.
 
+        Args:
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
         Raises:
-            GitlabConnectionError: If the server cannot be reached.
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabTimeTrackingError: If the time tracking update cannot be done
         """
         path = '%s/%s/reset_spent_time' % (self.manager.path, self.get_id())
         return self.manager.gitlab.http_post(path, **kwargs)