Adding set_archive_layout() method (#139)

* Adding set_archive_layout() method

Author: normanargueta

README.rst

@@ -207,6 +207,25 @@ Note that you can also create an automatically archived session, by passing in
 ``ArchiveModes.always`` as the ``archive_mode`` parameter when you call the
 ``opentok.create_session()`` method (see "Creating Sessions," above).
 
+For composed archives, you can change the layout dynamically, using the `opentok.set_archive_layout(archive_id, type, stylesheet)` method:
+
+.. code:: python
+
+  opentok.set_archive_layout('ARCHIVEID', 'horizontalPresentation')
+
+Setting the layout of composed archives is optional. By default, composed archives use the `best fit` layout.  Other valid values are: `custom`, `horizontalPresentation`, `pip` and `verticalPresentation`. If you specify a `custom` layout type, set the stylesheet parameter:
+
+.. code:: python
+
+  opentok.set_archive_layout(
+      'ARCHIVEID',
+      'custom',
+      'stream.instructor {position: absolute; width: 100%;  height:50%;}'
+  )
+
+For other layout types, do not set the stylesheet property. For more information see
+`Customizing the video layout for composed archives <https://tokbox.com/developer/guides/archiving/layout-control.html>`_.
+
 For more information on archiving, see the
 `OpenTok archiving <https://tokbox.com/opentok/tutorials/archiving/>`_ programming guide.
 

opentok/__init__.py

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

opentok/endpoints.py

@@ -40,3 +40,8 @@ def force_disconnect_url(self, session_id, connection_id):
             session_id + '/connection/' + connection_id
         )
         return url
+
+    def set_archive_layout_url(self, archive_id):
+        """ this method returns the url to set the archive layout """
+        url = self.api_url + '/v2/project/' + self.api_key + '/archive/' + archive_id + '/layout'
+        return url

opentok/opentok.py

@@ -598,6 +598,44 @@ def force_disconnect(self, session_id, connection_id):
         else:
             raise RequestError('An unexpected error occurred', response.status_code)
 
+    def set_archive_layout(self, archive_id, layout_type, stylesheet=None):
+        """
+        Use this method to change the layout of videos in an OpenTok archive
+
+        :param String archive_id: The ID of the archive that will be updated
+
+        :param String layout_type: The layout type for the archive. Valid values are:
+        'bestFit', 'custom', 'horizontalPresentation', 'pip' and 'verticalPresentation'
+
+        :param String stylesheet optional: CSS used to style the custom layout.
+        Specify this only if you set the type property to 'custom'
+        """
+        payload = {
+            'type':  layout_type,
+        }
+
+        if layout_type == 'custom':
+            if stylesheet is not None:
+                payload['stylesheet'] = stylesheet
+
+        endpoint = self.endpoints.set_archive_layout_url(archive_id)
+        response = requests.put(
+            endpoint,
+            data=json.dumps(payload),
+            headers=self.json_headers(),
+            proxies=self.proxies,
+            timeout=self.timeout
+        )
+
+        if response.status_code == 200:
+            pass
+        elif response.status_code == 400:
+            raise ArchiveError('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_archive_api.py

@@ -9,7 +9,15 @@
 import pytz
 from .validate_jwt import validate_jwt_header
 
-from opentok import OpenTok, Archive, ArchiveList, OutputModes, OpenTokException, __version__
+from opentok import (
+    OpenTok,
+    Archive,
+    ArchiveList,
+    OutputModes,
+    OpenTokException,
+    __version__,
+    ArchiveError
+)
 
 class OpenTokArchiveApiTest(unittest.TestCase):
     def setUp(self):
@@ -1049,3 +1057,73 @@ def test_find_archive_with_unknown_properties(self):
         archive = self.opentok.get_archive(archive_id)
 
         expect(archive).to(be_an(Archive))
+
+    @httpretty.activate
+    def test_set_archive_layout(self):
+        """ Test set archive layout functionality """
+        archive_id = u('f6e7ee58-d6cf-4a59-896b-6d56b158ec71')
+
+        httpretty.register_uri(
+            httpretty.PUT,
+            u('https://api.opentok.com/v2/project/{0}/archive/{1}/layout').format(
+                self.api_key,
+                archive_id
+            ),
+            status=200,
+            content_type=u('application/json')
+        )
+
+        self.opentok.set_archive_layout(archive_id, 'horizontalPresentation')
+
+        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_custom_archive_layout(self):
+        """ Test set a custom archive layout specifying the 'stylesheet' parameter """
+        archive_id = u('f6e7ee58-d6cf-4a59-896b-6d56b158ec71')
+
+        httpretty.register_uri(
+            httpretty.PUT,
+            u('https://api.opentok.com/v2/project/{0}/archive/{1}/layout').format(
+                self.api_key,
+                archive_id
+            ),
+            status=200,
+            content_type=u('application/json')
+        )
+
+        self.opentok.set_archive_layout(
+            archive_id,
+            'custom',
+            'stream.instructor {position: absolute; width: 100%;  height:50%;}'
+        )
+
+        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_archive_layout_throws_exception(self):
+        """ Test invalid request in set archive layout """
+        archive_id = u('f6e7ee58-d6cf-4a59-896b-6d56b158ec71')
+
+        httpretty.register_uri(
+            httpretty.PUT,
+            u('https://api.opentok.com/v2/project/{0}/archive/{1}/layout').format(
+                self.api_key,
+                archive_id
+            ),
+            status=400,
+            content_type=u('application/json')
+        )
+
+        self.assertRaises(
+            ArchiveError,
+            self.opentok.set_archive_layout,
+            archive_id,
+            'horizontalPresentation'
+        )