Add first group support

matrix_client/api.py

@@ -744,3 +744,144 @@ def get_room_members(self, room_id):
             room_id (str): The room to get the member events for.
         """
         return self._send("GET", "/rooms/{}/members".format(quote(room_id)))
+
+    def create_group(self, localpart):
+        """Create a new group.
+
+        Args:
+            localpart (str): The local part (the thing before the ':') of the
+            new group to be created.
+        """
+        body = {
+            "localpart": localpart
+        }
+        return self._send("POST", "/create_group", body)
+
+    def invite_user_to_group(self, group_id, user_id):
+        """Invite a user to a group.
+
+        Args:
+            group_id (str): The group ID
+            user_id (str): The user ID of the invitee
+        """
+        return self._send("PUT", "/groups/{}/admin/users/invite/{}".format(
+            quote(group_id), quote(user_id)))
+
+    def kick_user_from_group(self, group_id, user_id):
+        """Kick a user from a group.
+
+        Args:
+            group_id (str): The group ID
+            user_id (str): The user ID of the user to be kicked
+        """
+        return self._send("PUT", "/groups/{}/admin/users/remove/{}".format(
+            quote(group_id), quote(user_id)))
+
+    def add_room_to_group(self, group_id, room_id):
+        """Add a room to a group.
+
+        Args:
+            group_id (str): The group ID
+            room_id (str): The room ID of the room to be added
+        """
+        return self._send("PUT", "/groups/{}/admin/rooms/{}".format(
+            quote(group_id), quote(room_id)))
+
+    def remove_room_from_group(self, group_id, room_id):
+        """Removes a room from a group.
+
+        Args:
+            group_id (str): The group ID
+            room_id (str): The room ID of the room to be removed
+        """
+        return self._send("DELETE", "/groups/{}/admin/rooms/{}".format(
+                                    quote(group_id), quote(room_id)))
+
+    def update_group_profile(self, group_id, profile_data):
+        """Update the profile of a group.
+
+        Args:
+            profile_data (dict): The request payload.
+
+                | Includes all the data to be updated in the group profile.
+
+                | name (string): The new name of the group
+
+                | avatar_url (URL): A URL pointing to the new URL for the
+                | group's avatar.
+
+                | short_description (string): The new short description of the
+                | group.
+
+                | long_description (string): The new long description of the
+                | group.
+            group_id (str): The group ID
+        """
+        return self._send("POST", "/groups/{}/profile".format(quote(group_id)),
+                          profile_data)
+
+    def get_group_profile(self, group_id):
+        """Retrieve the profile of a group.
+
+        Args:
+            group_id (str): The group ID
+        """
+        return self._send("GET", "/groups/{}/profile".format(quote(group_id)))
+
+    def get_users_in_group(self, group_id):
+        """Retrieve the users in a group.
+
+        Args:
+            group_id (str): The group ID
+        """
+        return self._send("GET", "/groups/{}/users".format(quote(group_id)))
+
+    def get_invited_users_in_group(self, group_id):
+        """Retrieve invitations in a group.
+
+        Args:
+            group_id (str): The group ID
+        """
+        return self._send("GET", "/groups/{}/invited_users".format(
+                          quote(group_id)))
+
+    def get_rooms_in_group(self, group_id):
+        """Retrieve rooms in a group.
+
+        Args:
+            group_id (str): The group ID
+        """
+        return self._send("GET", "/groups/{}/rooms".format(quote(group_id)))
+
+    def accept_group_invitation(self, group_id):
+        """Accept an invitation to a group.
+
+        Args:
+            group_id (str): The group ID
+        """
+        return self._send("PUT", "/groups/{}/self/accept_invite".format(
+            quote(group_id)))
+
+    def leave_group(self, group_id):
+        """Leave a group.
+
+        Args:
+            group_id (str): The group ID
+        """
+        return self._send("PUT", "/groups/{}/self/leave".format(
+            quote(group_id)))
+
+    def publicise_group(self, group_id, make_public):
+        """Publicise or depublicise a group in your profile.
+
+        Args:
+            group_id (str): The group ID
+            make_public (bool): Set to True to show this group in your profile
+        """
+        return self._send("PUT", "/groups/{}/self/update_publicity".format(
+            quote(group_id)), {'publicise': make_public})
+
+    def get_joined_groups(self):
+        """Get the groups that the user has joined.
+        """
+        return self._send("GET", "/joined_groups")

matrix_client/client.py

@@ -15,6 +15,7 @@
 from .api import MatrixHttpApi
 from .errors import MatrixRequestError, MatrixUnexpectedResponse
 from .room import Room
+from .group import Group
 from .user import User
 from enum import Enum
 from threading import Thread
@@ -140,6 +141,9 @@ def __init__(self, base_url, token=None, user_id=None,
         self.rooms = {
             # room_id: Room
         }
+        self.groups = {
+            # group_id: Group
+        }
         if token:
             self.user_id = user_id
             self._sync()
@@ -263,6 +267,21 @@ def create_room(self, alias=None, is_public=False, invitees=()):
         response = self.api.create_room(alias, is_public, invitees)
         return self._mkroom(response["room_id"])
 
+    def create_group(self, localpart):
+        """ Create a new group on the homeserver.
+
+        Args:
+            localpart (str): The part before the ':' of the new room ID.
+
+        Returns:
+            Group
+
+        Raises:
+            MatrixRequestError
+        """
+        response = self.api.create_group(localpart)
+        return self._mkgroup(response["group_id"])
+
     def join_room(self, room_id_or_alias):
         """ Join a room.
 
@@ -290,6 +309,21 @@ def get_rooms(self):
         """
         return self.rooms
 
+    def get_groups(self):
+        """ Return a dict of {group_id: Group object} that the user has joined.
+
+        TODO: As soon as group joins / leaves come down the event stream,
+        polling is not necessary here anymore.
+
+        Returns:
+            Group{}: Groups the user has joined.
+        """
+        response = self.api.get_joined_groups()
+        for group_id in response["groups"]:
+            if group_id not in self.groups:
+                self._mkgroup(group_id)
+        return self.groups
+
     def add_listener(self, callback, event_type=None):
         """ Add a listener that will send a callback when the client recieves
         an event.
@@ -487,6 +521,10 @@ def upload(self, content, content_type):
                 content="Upload failed: %s" % e
             )
 
+    def _mkgroup(self, group_id):
+        self.groups[group_id] = Group(self, group_id)
+        return self.groups[group_id]
+
     def _mkroom(self, room_id):
         self.rooms[room_id] = Room(self, room_id)
         return self.rooms[room_id]