diff options
Diffstat (limited to 'gitlab/mixins.py')
| -rw-r--r-- | gitlab/mixins.py | 155 |
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) |