Adding set_stream_class_list() method (#141)

* Add set_stream_class_lists API

Author: normanargueta

README.rst

@@ -294,6 +294,27 @@ The method returns a StreamList object that contains a list of all the streams
   print stream.name #stream name
   print stream.layoutClassList #['full']
 
+You can change the layout classes for streams in a session by calling the `set_stream_class_lists(session_id, stream_list)` method of the `OpenTok` class.
+
+The layout classes define how the stream is displayed in the layout of a composed OpenTok archive.
+
+.. code:: python
+
+  # This list contains the information of the streams that will be updated. Each element
+  # in the list is a dictionary with two properties: 'id' and 'layoutClassList'. The 'id'
+  # property is the stream ID (a String), and the 'layoutClassList' is an array of class
+  # names (Strings) to apply to the stream.
+  payload = [
+      {'id': '7b09ec3c-26f9-43d7-8197-f608f13d4fb6', 'layoutClassList': ['focus']},
+      {'id': '567bc941-6ea0-4c69-97fc-70a740b68976', 'layoutClassList': ['top']},
+      {'id': '307dc941-0450-4c09-975c-705740d08970', 'layoutClassList': ['bottom']}
+  ]
+
+  opentok.set_stream_class_lists('SESSIONID', payload)
+
+For more information see
+`Changing the composed archive layout classes for an OpenTok stream <https://tokbox.com/developer/rest/#change-stream-layout-classes-composed>`_.
+
 Force Disconnect
 ~~~~~~~~~~~~~~~~~~~~~
 

opentok/__init__.py

@@ -1,7 +1,13 @@
 from .opentok import OpenTok, Roles, MediaModes, ArchiveModes
 from .session import Session
 from .archives import Archive, ArchiveList, OutputModes
-from .exceptions import OpenTokException, AuthError, ForceDisconnectError, ArchiveError
+from .exceptions import (
+    OpenTokException,
+    AuthError,
+    ForceDisconnectError,
+    ArchiveError,
+    SetStreamClassError
+)
 from .version import __version__
 from .stream import Stream
 from .streamlist import StreamList

opentok/endpoints.py

@@ -50,3 +50,8 @@ def dial_url(self):
         """ this method returns the url to initialize a SIP call """
         url = self.api_url + '/v2/project/' + self.api_key + '/dial'
         return url
+
+    def set_stream_class_lists_url(self, session_id):
+        """ this method returns the url to set the stream class list """
+        url = self.api_url + '/v2/project/' + self.api_key + '/session/' + session_id + '/stream'
+        return url

opentok/exceptions.py

@@ -56,3 +56,10 @@ class SipDialError(OpenTokException):
     that does not use the OpenTok Media Router.
     """
     pass
+
+class SetStreamClassError(OpenTokException):
+    """
+    Indicates that there is invalid data in the JSON request.
+    It may also indicate that invalid layout options have been passed
+    """
+    pass

opentok/opentok.py

@@ -34,7 +34,8 @@
     SignalingError,
     GetStreamError,
     ForceDisconnectError,
-    SipDialError
+    SipDialError,
+    SetStreamClassError
 )
 
 class Roles(Enum):
@@ -530,7 +531,7 @@ def signal(self, session_id, payload, connection_id=None):
     def get_stream(self, session_id, stream_id):
         """
         Returns an Stream object that contains information of an OpenTok stream:
-        
+
         -id: The stream ID
         -videoType: "camera" or "screen"
         -name: The stream name (if one was set when the client published the stream)
@@ -638,7 +639,6 @@ def set_archive_layout(self, archive_id, layout_type, stylesheet=None):
         else:
             raise RequestError('OpenTok server error.', response.status_code)
 
-
     def dial(self, session_id, token, sip_uri, options=[]):
         """
         Use this method to connect a SIP platform to an OpenTok session. The audio from the end
@@ -720,6 +720,47 @@ def dial(self, session_id, token, sip_uri, options=[]):
         else:
             raise RequestError('OpenTok server error.', response.status_code)
 
+    def set_stream_class_lists(self, session_id, payload):
+        """
+        Use this method to change layout classes for OpenTok streams. The layout classes
+        define how the streams are displayed in the layout of a composed OpenTok archive
+
+        :param String session_id: The ID of the session of the streams that will be updated
+
+        :param List payload: A list defining the class lists to apply to the streams.
+        Each element in the list is a dictionary with two properties: 'id' and 'layoutClassList'.
+        The 'id' property is the stream ID (a String), and the 'layoutClassList' is an array of
+        class names (Strings) to apply to the stream. For example:
+
+            payload = [
+                {'id': '7b09ec3c-26f9-43d7-8197-f608f13d4fb6', 'layoutClassList': ['focus']},
+                {'id': '567bc941-6ea0-4c69-97fc-70a740b68976', 'layoutClassList': ['top']},
+                {'id': '307dc941-0450-4c09-975c-705740d08970', 'layoutClassList': ['bottom']}
+            ]
+        """
+        items_payload = {'items': payload}
+
+        endpoint = self.endpoints.set_stream_class_lists_url(session_id)
+        response = requests.put(
+            endpoint,
+            data=json.dumps(items_payload),
+            headers=self.json_headers(),
+            proxies=self.proxies,
+            timeout=self.timeout
+        )
+
+        if response.status_code == 200:
+            pass
+        elif response.status_code == 400:
+            raise SetStreamClassError(
+                'Invalid request. This response may indicate that data in your request data '
+                'is invalid JSON. It may also indicate that you passed in invalid layout options.'
+            )
+        elif response.status_code == 403:
+            raise AuthError('Authentication error.')
+        else:
+            raise RequestError('OpenTok server error.', response.status_code)
+
     def _sign_string(self, string, secret):
         return hmac.new(secret.encode('utf-8'), string.encode('utf-8'), hashlib.sha1).hexdigest()
 

tests/test_get_stream.py tests/test_stream.pytests/test_get_stream.py renamed to tests/test_stream.py

@@ -1,14 +1,14 @@
 import unittest
 from six import text_type, u, b, PY2, PY3
-from opentok import OpenTok, Stream, StreamList, __version__
+from opentok import OpenTok, Stream, StreamList, __version__, SetStreamClassError
 import httpretty
 import json
 import textwrap
 from expects import *
 
 from .validate_jwt import validate_jwt_header
 
-class OpenTokGetStreamTest(unittest.TestCase):
+class OpenTokStreamTest(unittest.TestCase):
     def setUp(self):
         self.api_key = u('123456')
         self.api_secret = u('1234567890abcdef1234567890abcdef1234567890')
@@ -118,3 +118,55 @@ def test_get_stream_list(self):
         expect(stream_list).to(be_an(StreamList))
         expect(stream_list).to(have_property(u('count'), 2))
         expect(list(stream_list.items)).to(have_length(2))
+
+    @httpretty.activate
+    def test_set_stream_class_lists(self):
+        """ Test set stream class functionality """
+        payload = [
+            {'id': '7b09ec3c-26f9-43d7-8197-f608f13d4fb6', 'layoutClassList': ['focus']},
+            {'id': '567bc941-6ea0-4c69-97fc-70a740b68976', 'layoutClassList': ['top']},
+            {'id': '307dc941-0450-4c09-975c-705740d08970', 'layoutClassList': ['bottom']}
+        ]
+
+        httpretty.register_uri(
+            httpretty.PUT,
+            u('https://api.opentok.com/v2/project/{0}/session/{1}/stream').format(
+                self.api_key,
+                self.session_id
+            ),
+            status=200,
+            content_type=u('application/json')
+        )
+
+        self.opentok.set_stream_class_lists(self.session_id, payload)
+
+        validate_jwt_header(self, httpretty.last_request().headers[u('x-opentok-auth')])
+        expect(httpretty.last_request().headers[u('user-agent')]).to(contain(
+            u('OpenTok-Python-SDK/')+__version__))
+        expect(httpretty.last_request().headers[u('content-type')]).to(equal(u('application/json')))
+
+    @httpretty.activate
+    def test_set_stream_class_lists_throws_exception(self):
+        """ Test invalid request in set stream class list """
+        
+        #invalid payload
+        payload = [
+            {'id': '7b09ec3c-26f9-43d7-8197-f608f13d4fb6'}
+        ]
+
+        httpretty.register_uri(
+            httpretty.PUT,
+            u('https://api.opentok.com/v2/project/{0}/session/{1}/stream').format(
+                self.api_key,
+                self.session_id
+            ),
+            status=400,
+            content_type=u('application/json')
+        )
+
+        self.assertRaises(
+            SetStreamClassError,
+            self.opentok.set_stream_class_lists,
+            self.session_id,
+            payload
+        )