Time tracking (python-gitlab#222)

savenger · Gauvain Pocentek · commit 92151b22b5b0 · 2017-03-03T13:57:46.000+01:00
* Added gitlab time tracking features

- get/set/remove estimated time per issue
- get/set/remove time spent per issue

* Added documentation for time tracking functions
diff --git a/docs/gl_objects/issues.py b/docs/gl_objects/issues.py
@@ -77,3 +77,23 @@
 # project issue todo
 issue.todo()
 # end project issue todo
+
+# project issue time tracking stats
+issue.time_stats()
+# end project issue time tracking stats
+
+# project issue set time estimate
+issue.set_time_estimate({'duration': '3h30m'})
+# end project issue set time estimate
+
+# project issue reset time estimate
+issue.reset_time_estimate()
+# end project issue reset time estimate
+
+# project issue set time spent
+issue.add_time_spent({'duration': '3h30m'})
+# end project issue set time spent
+
+# project issue reset time spent
+issue.reset_time_spent()
+# end project issue reset time spent
diff --git a/docs/gl_objects/issues.rst b/docs/gl_objects/issues.rst
@@ -104,3 +104,34 @@ Make an issue as todo:
 .. literalinclude:: issues.py
    :start-after: # project issue todo
    :end-before: # end project issue todo
+
+Get time tracking stats:
+
+.. literalinclude:: issues.py
+   :start-after: # project issue time tracking stats
+   :end-before: # end project time tracking stats
+
+Set a time estimate for an issue:
+
+.. literalinclude:: issues.py
+   :start-after: # project issue set time estimate
+   :end-before: # end project set time estimate
+
+Reset a time estimate for an issue:
+
+.. literalinclude:: issues.py
+   :start-after: # project issue reset time estimate
+   :end-before: # end project reset time estimate
+
+Add spent time for an issue:
+
+.. literalinclude:: issues.py
+   :start-after: # project issue set time spent
+   :end-before: # end project set time spent
+
+Reset spent time for an issue:
+
+.. literalinclude:: issues.py
+   :start-after: # project issue reset time spent
+   :end-before: # end project reset time spent
+
diff --git a/gitlab/exceptions.py b/gitlab/exceptions.py
@@ -143,6 +143,10 @@ class GitlabTodoError(GitlabOperationError):
     pass
 
 
+class GitlabTimeTrackingError(GitlabOperationError):
+    pass
+
+
 def raise_error_from_response(response, error, expected_code=200):
     """Tries to parse gitlab error message from response and raises error.
 
diff --git a/gitlab/objects.py b/gitlab/objects.py
@@ -1523,6 +1523,69 @@ def todo(self, **kwargs):
         r = self.gitlab._raw_post(url, **kwargs)
         raise_error_from_response(r, GitlabTodoError, [201, 304])
 
+    def time_stats(self, **kwargs):
+        """Get time stats for the issue.
+
+        Raises:
+            GitlabConnectionError: If the server cannot be reached.
+        """
+        url = ('/projects/%(project_id)s/issues/%(issue_id)s/time_stats' %
+               {'project_id': self.project_id, 'issue_id': self.id})
+        r = self.gitlab._raw_get(url, **kwargs)
+        raise_error_from_response(r, GitlabGetError)
+        return r.json()
+
+    def time_estimate(self, **kwargs):
+        """Set an estimated time of work for the issue.
+
+        Raises:
+            GitlabConnectionError: If the server cannot be reached.
+        """
+        url = ('/projects/%(project_id)s/issues/%(issue_id)s/time_estimate' %
+               {'project_id': self.project_id, 'issue_id': self.id})
+        r = self.gitlab._raw_post(url, **kwargs)
+        raise_error_from_response(r, GitlabTimeTrackingError, 201)
+        return r.json()
+
+    def reset_time_estimate(self, **kwargs):
+        """Resets estimated time for the issue to 0 seconds.
+
+        Raises:
+            GitlabConnectionError: If the server cannot be reached.
+        """
+        url = ('/projects/%(project_id)s/issues/%(issue_id)s/'
+               'reset_time_estimate' %
+               {'project_id': self.project_id, 'issue_id': self.id})
+        r = self.gitlab._raw_post(url, **kwargs)
+        raise_error_from_response(r, GitlabTimeTrackingError, 200)
+        return r.json()
+
+    def add_spent_time(self, **kwargs):
+        """Set an estimated time of work for the issue.
+
+        Raises:
+            GitlabConnectionError: If the server cannot be reached.
+        """
+        url = ('/projects/%(project_id)s/issues/%(issue_id)s/'
+               'reset_spent_time' %
+               {'project_id': self.project_id, 'issue_id': self.id})
+        r = self.gitlab._raw_post(url, **kwargs)
+        raise_error_from_response(r, GitlabTimeTrackingError, 200)
+        return r.json()
+
+    def reset_spent_time(self, **kwargs):
+        """Set an estimated time of work for the issue.
+
+        Raises:
+            GitlabConnectionError: If the server cannot be reached.
+        """
+        url = ('/projects/%(project_id)s/issues/%(issue_id)s/'
+               'add_spent_time' %
+               {'project_id': self.project_id, 'issue_id': self.id})
+        r = self.gitlab._raw_post(url, **kwargs)
+        raise_error_from_response(r, GitlabTimeTrackingError, 200)
+        return r.json()
+
 
 class ProjectIssueManager(BaseManager):
     obj_cls = ProjectIssue
