Add specific methods for interface to groups

Hide 'verbs' from users.

HISTORY.rst

@@ -3,6 +3,11 @@
 Release history
 ===============
 
+0.4.0
+-----
+
+* Adds initial groups functionality
+
 0.3.2
 -----
 

docs/conf.py

@@ -51,9 +51,9 @@ copyright = u'2014, Marc Sibson'
 # built documents.
 #
 # The short X.Y version.
-version = '0.3'
+version = '0.4'
 # The full version, including alpha/beta/rc tags.
-release = '0.3.2'
+release = '0.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

pydiscourse/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
 
-__version__ = '0.3.2'
+__version__ = '0.4.0'
 
 from pydiscourse.client import DiscourseClient

pydiscourse/client.py

@@ -13,6 +13,12 @@ from pydiscourse.sso import sso_payload
 
 log = logging.getLogger('pydiscourse.client')
 
+# HTTP verbs to be used as non string literals
+DELETE = "DELETE"
+GET = "GET"
+POST = "POST"
+PUT = "PUT"
+
 
 class DiscourseClient(object):
     """Discourse API client"""
@@ -611,7 +617,117 @@ class DiscourseClient(object):
         """
         for setting, value in kwargs.items():
             setting = setting.replace(' ', '_')
-            self._request('PUT', '/admin/site_settings/{0}'.format(setting), {setting: value})
+            self._request(PUT, '/admin/site_settings/{0}'.format(setting), {setting: value})
+
+    def groups(self, **kwargs):
+        """
+        Returns a list of all groups.
+
+        Returns:
+            List of dictionaries of groups
+
+                [
+                  {
+                    'alias_level': 0,
+                    'automatic': True,
+                    'automatic_membership_email_domains': None,
+                    'automatic_membership_retroactive': False,
+                    'grant_trust_level': None,
+                    'has_messages': True,
+                    'id': 1,
+                    'incoming_email': None,
+                    'mentionable': False,
+                    'name': 'admins',
+                    'notification_level': 2,
+                    'primary_group': False,
+                    'title': None,
+                    'user_count': 9,
+                    'visible': True
+                  },
+                  {
+                    'alias_level': 0,
+                    'automatic': True,
+                    'automatic_membership_email_domains': None,
+                    'automatic_membership_retroactive': False,
+                    'grant_trust_level': None,
+                    'has_messages': False,
+                    'id': 0,
+                    'incoming_email': None,
+                    'mentionable': False,
+                    'name': 'everyone',
+                    'notification_level': None,
+                    'primary_group': False,
+                    'title': None,
+                    'user_count': 0,
+                    'visible': True
+                  }
+                ]
+
+        """
+        return self._get("/admin/groups.json", **kwargs)
+
+    def add_group_owner(self, groupid, username):
+        """
+        Add an owner to a group by username
+
+        Args:
+            groupid: the ID of the group
+            username: the new owner usernmae
+
+        Returns:
+            JSON API response
+
+        """
+        return self._put("/admin/groups/{0}/owners.json".format(groupid), usernames=username)
+
+    def delete_group_owner(self, groupid, userid):
+        """
+        Deletes an owner from a group by user ID
+
+        Does not delete the user from Discourse.
+
+        Args:
+            groupid: the ID of the group
+            userid: the ID of the user
+
+        Returns:
+            JSON API response
+
+        """
+        return self._delete("/admin/groups/{0}/owners.json".format(groupid), user_id=userid)
+
+    def add_group_member(self, groupid, username):
+        """
+        Add a member to a group by username
+
+        Args:
+            groupid: the ID of the group
+            username: the new member usernmae
+
+        Returns:
+            JSON API response
+
+        Raises:
+            DiscourseError if user is already member of group
+
+        """
+        return self._put("/admin/groups/{0}/members.json".format(groupid), usernames=username)
+
+    def delete_group_member(self, groupid, userid):
+        """
+        Deletes a member from a group by user ID
+
+        Does not delete the user from Discourse.
+
+        Args:
+            groupid: the ID of the group
+            userid: the ID of the user
+
+        Returns:
+            JSON API response
+
+        """
+        return self._delete("/admin/groups/{0}/members.json".format(groupid), user_id=userid)
 
     def _get(self, path, **kwargs):
         """
@@ -623,7 +739,7 @@ class DiscourseClient(object):
         Returns:
 
         """
-        return self._request('GET', path, kwargs)
+        return self._request(GET, path, kwargs)
 
     def _put(self, path, **kwargs):
         """
@@ -635,7 +751,7 @@ class DiscourseClient(object):
         Returns:
 
         """
-        return self._request('PUT', path, kwargs)
+        return self._request(PUT, path, kwargs)
 
     def _post(self, path, **kwargs):
         """
@@ -647,7 +763,7 @@ class DiscourseClient(object):
         Returns:
 
         """
-        return self._request('POST', path, kwargs)
+        return self._request(POST, path, kwargs)
 
     def _delete(self, path, **kwargs):
         """
@@ -659,15 +775,16 @@ class DiscourseClient(object):
         Returns:
 
         """
-        return self._request('DELETE', path, kwargs)
+        return self._request(DELETE, path, kwargs)
 
     def _request(self, verb, path, params):
         """
+        Executes HTTP request to API and handles response
 
         Args:
-            verb:
-            path:
-            params:
+            verb: HTTP verb as string: GET, DELETE, PUT, POST
+            path: the path on the Discourse API
+            params: dictionary of parameters to include to the API
 
         Returns: