Update client API interface with groups and notes (#184)

Author: satterly

alertaclient/api.py

@@ -13,6 +13,8 @@
 from alertaclient.models.alert import Alert
 from alertaclient.models.blackout import Blackout
 from alertaclient.models.customer import Customer
+from alertaclient.models.enums import Scope
+from alertaclient.models.group import Group
 from alertaclient.models.heartbeat import Heartbeat
 from alertaclient.models.history import RichHistory
 from alertaclient.models.key import ApiKey
@@ -92,6 +94,12 @@ def update_attributes(self, id, attributes):
         }
         return self.http.put('/alert/%s/attributes' % id, data)
 
+    def add_note(self, id, note):
+        data = {
+            'note': note
+        }
+        return self.http.put('/alert/%s/note' % id, data)
+
     def delete_alert(self, id):
         return self.http.delete('/alert/%s' % id)
 
@@ -118,13 +126,25 @@ def get_top10_flapping(self, query=None):
         counts = self.http.get('/alerts/top10/flapping', query)
         return counts['top10']
 
+    def get_top10_standing(self, query=None):
+        counts = self.http.get('/alerts/top10/standing', query)
+        return counts['top10']
+
     def get_environments(self, query=None):
-        counts = self.http.get('/environments', query)
-        return counts['environments']
+        r = self.http.get('/environments', query)
+        return r['environments']
 
     def get_services(self, query=None):
-        counts = self.http.get('/services', query)
-        return counts['services']
+        r = self.http.get('/services', query)
+        return r['services']
+
+    def get_groups(self, query=None):
+        r = self.http.get('/alerts/groups', query)
+        return r['groups']
+
+    def get_tags(self, query=None):
+        r = self.http.get('/alerts/tags', query)
+        return r['tags']
 
     # Blackouts
     def create_blackout(self, environment, service=None, resource=None, event=None, group=None, tags=None, customer=None, start=None, duration=None, text=None):
@@ -143,10 +163,16 @@ def create_blackout(self, environment, service=None, resource=None, event=None,
         r = self.http.post('/blackout', data)
         return Blackout.parse(r['blackout'])
 
+    def get_blackout(self, id):
+        return Blackout.parse(self.http.get('/blackout/%s' % id)['blackout'])
+
     def get_blackouts(self, query=None):
         r = self.http.get('/blackouts', query)
         return [Blackout.parse(b) for b in r['blackouts']]
 
+    def update_blackout(self, id, blackout):
+        self.http.put('/blackout/%s' % id, blackout)
+
     def delete_blackout(self, id):
         return self.http.delete('/blackout/%s' % id)
 
@@ -159,10 +185,16 @@ def create_customer(self, customer, match):
         r = self.http.post('/customer', data)
         return Customer.parse(r['customer'])
 
+    def get_customer(self):
+        return Customer.parse(self.http.get('/customer/%s' % id)['customer'])
+
     def get_customers(self, query=None):
         r = self.http.get('/customers', query)
         return [Customer.parse(c) for c in r['customers']]
 
+    def update_customer(self, id, customer):
+        self.http.put('/customer/%s' % id, customer)
+
     def delete_customer(self, id):
         return self.http.delete('/customer/%s' % id)
 
@@ -201,10 +233,22 @@ def create_key(self, username, scopes=None, expires=None, text='', customer=None
         r = self.http.post('/key', data)
         return ApiKey.parse(r['data'])
 
+    def get_key(self):
+        return ApiKey.parse(self.http.get('/key/%s' % id)['key'])
+
     def get_keys(self, query=None):
         r = self.http.get('/keys', query)
         return [ApiKey.parse(k) for k in r['keys']]
 
+    def update_key(self, id, **kwargs):
+        data = {
+            'scopes': kwargs.get('scopes'),
+            'text': kwargs.get('text'),
+            'expireTime': kwargs.get('expireTime'),
+            'customer': kwargs.get('customer')
+        }
+        return self.http.put('/key/{}'.format(id), data)
+
     def delete_key(self, id):
         return self.http.delete('/key/%s' % id)
 
@@ -217,13 +261,27 @@ def create_perm(self, role, scopes=None):
         r = self.http.post('/perm', data)
         return Permission.parse(r['permission'])
 
+    def get_perm(self):
+        return Permission.parse(self.http.get('/perm/%s' % id)['perm'])
+
     def get_perms(self, query=None):
         r = self.http.get('/perms', query)
         return [Permission.parse(p) for p in r['permissions']]
 
+    def update_perm(self, id, **kwargs):
+        data = {
+            'match': kwargs.get('match'),  # role
+            'scopes': kwargs.get('scopes')
+        }
+        return self.http.put('/perm/{}'.format(id), data)
+
     def delete_perm(self, id):
         return self.http.delete('/perm/%s' % id)
 
+    def get_scopes(self):
+        r = self.http.get('/scopes')
+        return [Scope(s) for s in r['scopes']]
+
     # Users
     def signup(self, name, email, password, status, attributes=None, text=''):
         data = {
@@ -250,6 +308,19 @@ def create_user(self, name, email, password, status, roles=None, attributes=None
         r = self.http.post('/user', data)
         return User.parse(r['user'])
 
+    def get_user(self):
+        return Permission.parse(self.http.get('/user/%s' % id)['user'])
+
+    def get_user_groups(self, id):
+        r = self.http.get('/user/{}/groups'.format(id))
+        return [Group.parse(g) for g in r['groups']]
+
+    def get_me(self):
+        return User.parse(self.http.get('/user/me')['user'])
+
+    def get_me_attributes(self):
+        return self.http.get('/user/me/attributes')['attributes']
+
     def get_users(self, query=None):
         r = self.http.get('/users', query)
         return [User.parse(u) for u in r['users']]
@@ -293,6 +364,7 @@ def update_me_attributes(self, attributes):
     def delete_user(self, id):
         return self.http.delete('/user/%s' % id)
 
+    # Auth
     def login(self, username, password):
         data = {
             'username': username,
@@ -318,6 +390,42 @@ def userinfo(self):
     def config(self):
         return self.http.get('/config')
 
+    # Groups
+    def create_group(self, name, text):
+        data = {
+            'name': name,
+            'text': text
+        }
+        r = self.http.post('/group', data)
+        return Group.parse(r['group'])
+
+    def get_group(self):
+        return Group.parse(self.http.get('/group/%s' % id)['group'])
+
+    def get_group_users(self, id):
+        r = self.http.get('/group/{}/users'.format(id))
+        return [User.parse(u) for u in r['users']]
+
+    def get_users_groups(self, query=None):
+        r = self.http.get('/groups', query)
+        return [Group.parse(g) for g in r['groups']]
+
+    def update_group(self, id, kwargs):
+        data = {
+            'name': kwargs.get('name'),
+            'text': kwargs.get('text')
+        }
+        return self.http.put('/group/{}'.format(id), data)
+
+    def add_user_to_group(self, group_id, user_id):
+        return self.http.put('/group/{}/user/{}'.format(group_id, user_id))
+
+    def remove_user_from_group(self, group_id, user_id):
+        return self.http.delete('/group/{}/user/{}'.format(group_id, user_id))
+
+    def delete_group(self, id):
+        return self.http.delete('/group/%s' % id)
+
     # Management
     def mgmt_status(self):
         return self.http.get('/management/status')

alertaclient/models/enums.py

@@ -0,0 +1,59 @@
+from enum import Enum
+
+
+class Scope(str, Enum):
+
+    read = 'read'
+    write = 'write'
+    admin = 'admin'
+    read_alerts = 'read:alerts'
+    write_alerts = 'write:alerts'
+    admin_alerts = 'admin:alerts'
+    read_blackouts = 'read:blackouts'
+    write_blackouts = 'write:blackouts'
+    admin_blackouts = 'admin:blackouts'
+    read_heartbeats = 'read:heartbeats'
+    write_heartbeats = 'write:heartbeats'
+    admin_heartbeats = 'admin:heartbeats'
+    write_users = 'write:users'
+    admin_users = 'admin:users'
+    read_groups = 'read:groups'
+    admin_groups = 'admin:groups'
+    read_perms = 'read:perms'
+    admin_perms = 'admin:perms'
+    read_customers = 'read:customers'
+    admin_customers = 'admin:customers'
+    read_keys = 'read:keys'
+    write_keys = 'write:keys'
+    admin_keys = 'admin:keys'
+    write_webhooks = 'write:webhooks'
+    read_oembed = 'read:oembed'
+    read_management = 'read:management'
+    admin_management = 'admin:management'
+    read_userinfo = 'read:userinfo'
+
+    @property
+    def action(self):
+        return self.split(':')[0]
+
+    @property
+    def resource(self):
+        try:
+            return self.split(':')[1]
+        except IndexError:
+            return None
+
+    @staticmethod
+    def from_str(action: str, resource: str=None):
+        """Return a scope based on the supplied action and resource.
+
+        :param action: the scope action eg. read, write or admin
+        :param resource: the specific resource of the scope, if any eg. alerts,
+            blackouts, heartbeats, users, perms, customers, keys, webhooks,
+            oembed, management or userinfo or None
+        :return: Scope
+        """
+        if resource:
+            return Scope('{}:{}'.format(action, resource))
+        else:
+            return Scope(action)

alertaclient/models/group.py

@@ -0,0 +1,47 @@
+
+from typing import Any, Dict, List, Optional, Tuple, Union
+from uuid import uuid4
+
+JSON = Dict[str, Any]
+
+
+# class GroupUser:
+#
+#     def __init__(self, id: str, login: str, name: str, status: str) -> None:
+#         self.id = id
+#         self.login = login
+#         self.name = name
+#         self.status = status
+#
+
+# class GroupUsers:
+#
+#     def __init__(self, id: str, users: List[GroupUser]) -> None:
+#         self.id = id
+#         self.users = users
+
+
+class Group:
+    """
+    Group model.
+    """
+
+    def __init__(self, name: str, text: str, **kwargs) -> None:
+        if not name:
+            raise ValueError('Missing mandatory value for name')
+
+        self.id = kwargs.get('id', str(uuid4()))
+        self.name = name
+        self.text = text or ''
+        self.count = kwargs.get('count')
+
+    def __repr__(self) -> str:
+        return 'Group(id={!r}, name={!r}, text={!r}, count={!r})'.format(
+            self.id, self.name, self.text, self.count)
+
+    @classmethod
+    def parse(cls, json: JSON) -> 'Group':
+        return Group(
+            name=json.get('name', None),
+            text=json.get('text', None)
+        )

tests/test_groups.py

@@ -0,0 +1,33 @@
+
+import unittest
+
+import requests_mock
+
+from alertaclient.api import Client
+
+
+class GroupTestCase(unittest.TestCase):
+
+    def setUp(self):
+        self.client = Client()
+
+        self.key = """
+            {
+                "group": {
+                    "count": 0,
+                    "href": "http://localhost:8080/group/8ed5d256-4205-4dfc-b25d-185bd019cb21",
+                    "id": "8ed5d256-4205-4dfc-b25d-185bd019cb21",
+                    "name": "myGroup",
+                    "text": "test group"
+                },
+                "id": "8ed5d256-4205-4dfc-b25d-185bd019cb21",
+                "status": "ok"
+            }
+        """
+
+    @requests_mock.mock()
+    def test_key(self, m):
+        m.post('http://localhost:8080/group', text=self.key)
+        group = self.client.create_group(name='myGroup', text='test group')
+        self.assertEqual(group.name, 'myGroup')
+        self.assertEqual(group.text, 'test group')

tests/test_notes.py

@@ -0,0 +1,24 @@
+
+import unittest
+
+import requests_mock
+
+from alertaclient.api import Client
+
+
+class NotesTestCase(unittest.TestCase):
+
+    def setUp(self):
+        self.client = Client()
+
+        self.key = """
+            {
+              "status": "ok"
+            }
+        """
+
+    @requests_mock.mock()
+    def test_add_note(self, m):
+        m.put('http://localhost:8080/alert/e7020428-5dad-4a41-9bfe-78e9d55cda06/note', text=self.key)
+        r = self.client.add_note(id='e7020428-5dad-4a41-9bfe-78e9d55cda06', note='this is a test note')
+        self.assertEqual(r['status'], 'ok')