Add support for the notification settings API

Gauvain Pocentek · Gauvain Pocentek · commit b15f17b6d200 · 2016-10-23T21:46:28.000+02:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -7,6 +7,7 @@ API objects manipulation
 
    gl_objects/access_requests
    gl_objects/branches
+   gl_objects/messages
    gl_objects/builds
    gl_objects/commits
    gl_objects/deploy_keys
@@ -16,7 +17,7 @@ API objects manipulation
    gl_objects/issues
    gl_objects/labels
    gl_objects/licenses
-   gl_objects/messages
+   gl_objects/notifications
    gl_objects/mrs
    gl_objects/namespaces
    gl_objects/milestones
diff --git a/docs/gl_objects/notifications.py b/docs/gl_objects/notifications.py
@@ -0,0 +1,21 @@
+# get
+# global settings
+settings = gl.notificationsettings.get()
+# for a group
+settings = gl.groups.get(group_id).notificationsettings.get()
+# for a project
+settings = gl.projects.get(project_id).notificationsettings.get()
+# end get
+
+# update
+# use a predefined level
+settings.level = gitlab.NOTIFICATION_LEVEL_WATCH
+# create a custom setup
+settings.level = gitlab.NOTIFICATION_LEVEL_CUSTOM
+settings.save()  # will create additional attributes, but not mandatory
+
+settings.new_merge_request = True
+settings.new_issue = True
+settings.new_note = True
+settings.save()
+# end update
diff --git a/docs/gl_objects/notifications.rst b/docs/gl_objects/notifications.rst
@@ -0,0 +1,38 @@
+#####################
+Notification settings
+#####################
+
+You can define notification settings globally, for groups and for projects.
+Valid levels are defined as constants:
+
+* ``NOTIFICATION_LEVEL_DISABLED``
+* ``NOTIFICATION_LEVEL_PARTICIPATING``
+* ``NOTIFICATION_LEVEL_WATCH``
+* ``NOTIFICATION_LEVEL_GLOBAL``
+* ``NOTIFICATION_LEVEL_MENTION``
+* ``NOTIFICATION_LEVEL_CUSTOM``
+
+You get access to fine-grained settings if you use the
+``NOTIFICATION_LEVEL_CUSTOM`` level.
+
+* Object classes: :class:`gitlab.objects.NotificationSettings` (global),
+  :class:`gitlab.objects.GroupNotificationSettings` (groups) and
+  :class:`gitlab.objects.ProjectNotificationSettings` (projects)
+* Manager objects: :attr:`gitlab.Gitlab.notificationsettings` (global),
+  :attr:`gitlab.objects.Group.notificationsettings` (groups) and
+  :attr:`gitlab.objects.Project.notificationsettings` (projects)
+
+Examples
+--------
+
+Get the settings:
+
+.. literalinclude:: notifications.py
+   :start-after: # get
+   :end-before: # end get
+
+Update the settings:
+
+.. literalinclude:: notifications.py
+   :start-after: # update
+   :end-before: # end update
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
@@ -82,6 +82,8 @@ class Gitlab(object):
         issues (IssueManager): Manager for GitLab issues
         licenses (LicenseManager): Manager for licenses
         namespaces (NamespaceManager): Manager for namespaces
+        notificationsettings (NotificationSettingsManager): Manager for global
+            notification settings
         project_accessrequests (ProjectAccessRequestManager): Manager for
             GitLab projects access requests
         project_boards (ProjectBoardManager): Manager for GitLab projects
@@ -181,6 +183,7 @@ def __init__(self, url, private_token=None, email=None, password=None,
         self.issues = IssueManager(self)
         self.licenses = LicenseManager(self)
         self.namespaces = NamespaceManager(self)
+        self.notificationsettings = NotificationSettingsManager(self)
         self.project_accessrequests = ProjectAccessRequestManager(self)
         self.project_boards = ProjectBoardManager(self)
         self.project_board_listss = ProjectBoardListManager(self)
diff --git a/gitlab/const.py b/gitlab/const.py
@@ -24,3 +24,10 @@
 VISIBILITY_PRIVATE = 0
 VISIBILITY_INTERNAL = 10
 VISIBILITY_PUBLIC = 20
+
+NOTIFICATION_LEVEL_DISABLED = 'disabled'
+NOTIFICATION_LEVEL_PARTICIPATING = 'participating'
+NOTIFICATION_LEVEL_WATCH = 'watch'
+NOTIFICATION_LEVEL_GLOBAL = 'global'
+NOTIFICATION_LEVEL_MENTION = 'mention'
+NOTIFICATION_LEVEL_CUSTOM = 'custom'
diff --git a/gitlab/objects.py b/gitlab/objects.py
@@ -752,6 +752,30 @@ class KeyManager(BaseManager):
     obj_cls = Key
 
 
+class NotificationSettings(GitlabObject):
+    _url = '/notification_settings'
+    _id_in_update_url = False
+    optionalUpdateAttrs = ['level',
+                           'notification_email',
+                           'new_note',
+                           'new_issue',
+                           'reopen_issue',
+                           'close_issue',
+                           'reassign_issue',
+                           'new_merge_request',
+                           'reopen_merge_request',
+                           'close_merge_request',
+                           'reassign_merge_request',
+                           'merge_merge_request']
+    canList = False
+    canCreate = False
+    canDelete = False
+
+
+class NotificationSettingsManager(BaseManager):
+    obj_cls = NotificationSettings
+
+
 class GroupIssue(GitlabObject):
     _url = '/groups/%(group_id)s/issues'
     canGet = 'from_list'
@@ -783,6 +807,15 @@ class GroupMemberManager(BaseManager):
     obj_cls = GroupMember
 
 
+class GroupNotificationSettings(NotificationSettings):
+    _url = '/groups/%(group_id)s/notification_settings'
+    requiredUrlAttrs = ['group_id']
+
+
+class GroupNotificationSettingsManager(BaseManager):
+    obj_cls = GroupNotificationSettings
+
+
 class GroupProject(GitlabObject):
     _url = '/groups/%(group_id)s/projects'
     canGet = 'from_list'
@@ -835,6 +868,8 @@ class Group(GitlabObject):
     managers = [
         ('accessrequests', GroupAccessRequestManager, [('group_id', 'id')]),
         ('members', GroupMemberManager, [('group_id', 'id')]),
+        ('notificationsettings', GroupNotificationSettingsManager,
+         [('group_id', 'id')]),
         ('projects', GroupProjectManager, [('group_id', 'id')]),
         ('issues', GroupIssueManager, [('group_id', 'id')])
     ]
@@ -1385,6 +1420,15 @@ class ProjectNoteManager(BaseManager):
     obj_cls = ProjectNote
 
 
+class ProjectNotificationSettings(NotificationSettings):
+    _url = '/projects/%(project_id)s/notification_settings'
+    requiredUrlAttrs = ['project_id']
+
+
+class ProjectNotificationSettingsManager(BaseManager):
+    obj_cls = ProjectNotificationSettings
+
+
 class ProjectTagRelease(GitlabObject):
     _url = '/projects/%(project_id)s/repository/tags/%(tag_name)/release'
     canDelete = False
@@ -1987,6 +2031,8 @@ class Project(GitlabObject):
         ('mergerequests', ProjectMergeRequestManager, [('project_id', 'id')]),
         ('milestones', ProjectMilestoneManager, [('project_id', 'id')]),
         ('notes', ProjectNoteManager, [('project_id', 'id')]),
+        ('notificationsettings', ProjectNotificationSettingsManager,
+         [('project_id', 'id')]),
         ('pipelines', ProjectPipelineManager, [('project_id', 'id')]),
         ('services', ProjectServiceManager, [('project_id', 'id')]),
         ('snippets', ProjectSnippetManager, [('project_id', 'id')]),
diff --git a/tools/python_test.py b/tools/python_test.py
@@ -282,3 +282,10 @@
 assert(msg.color == '#444444')
 msg.delete()
 assert(len(gl.broadcastmessages.list()) == 0)
+
+# notification settings
+settings = gl.notificationsettings.get()
+settings.level = gitlab.NOTIFICATION_LEVEL_WATCH
+settings.save()
+settings = gl.notificationsettings.get()
+assert(settings.level == gitlab.NOTIFICATION_LEVEL_WATCH)
