Merge pull request #222 from opentok/auto-archive-improvements

add auto archive improvements

Author: maxkahan

README.rst

@@ -62,6 +62,15 @@ keyword parameters for this method:
 * ``archive_mode`` which specifies whether the session will be automatically archived (``always``)
   or not (``manual``).
 
+* ``archive_name`` which indicates the archive name for all the archives in auto archived session. 
+  A session that begins with archive mode 'always' will be using this archive name for all archives of that session.
+  Passing 'archive_name' with archive mode 'manual' will cause an error response.
+
+* ``archive_resolution`` which indicates the archive resolution for all the archives in auto archived session.
+  Valid values are '640x480', '480x640', '1280x720', '720x1280', '1920x1080' and '1080x1920'.
+  A session that begins with archive mode 'always' will be using this resolution for all archives of that session.
+  Passing 'archive_resolution' with archive mode 'manual' will cause an error response.
+
 * ``e2ee`` which is a boolean. This specifies whether to enable
   `end-to-end encryption <https://tokbox.com/developer/guides/end-to-end-encryption/>`_
   for the OpenTok session.
@@ -82,6 +91,14 @@ store (such as a database).
   # An automatically archived session:
   session = opentok.create_session(media_mode=MediaModes.routed, archive_mode=ArchiveModes.always)
 
+  # An automatically archived session with the archive name and resolution specified:
+  session = opentok.create_session(
+    media_mode=MediaModes.routed,
+    archive_mode=ArchiveModes.always,
+    archive_name='my_archive',
+    archive_resolution='1920x1080'
+  )
+
   # A session with a location hint
   session = opentok.create_session(location=u'12.34.56.78')
 

opentok/opentok.py

@@ -90,6 +90,15 @@ class ArchiveModes(Enum):
     """The session will be automatically archived."""
 
 
+valid_archive_resolutions = {
+    "640x480",
+    "480x640",
+    "1280x720",
+    "720x1280",
+    "1920x1080",
+    "1080x1920",
+}
+
 logger = logging.getLogger("opentok")
 
 
@@ -312,6 +321,8 @@ def create_session(
         location=None,
         media_mode=MediaModes.relayed,
         archive_mode=ArchiveModes.manual,
+        archive_name=None,
+        archive_resolution=None,
         e2ee=False,
     ):
         """
@@ -367,6 +378,16 @@ def create_session(
             (either automatically or not), you must set the media_mode parameter to
             MediaModes.routed.
 
+        :param String archive_name: Indicates the archive name for all the archives in auto archived session.
+            A session that begins with archive mode 'always' will be using this archive name for all archives of that session.
+            Passing 'archive_name' with archive mode 'manual' will cause an error response.
+
+        :param String archive_resolution:
+            Indicates the archive resolution for all the archives in auto archived session.
+            Valid values are '640x480', '480x640', '1280x720', '720x1280', '1920x1080' and '1080x1920'.
+            A session that begins with archive mode 'always' will be using this resolution for all archives of that session.
+            Passing 'archive_resolution' with archive mode 'manual' will cause an error response.
+
         :param String location: An IP address that the OpenTok servers will use to
             situate the session in its global network. If you do not set a location hint,
             the OpenTok servers will be based on the first client connecting to the session.
@@ -397,8 +418,34 @@ def create_session(
                     "A session with always archive mode must also have the routed media mode."
                 )
             )
+
+        if archive_name is not None:
+            if archive_mode == ArchiveModes.manual:
+                raise OpenTokException(
+                    "You cannot specify a value for archive_name with archive mode: manual."
+                )
+            if not 1 <= len(archive_name) <= 80:
+                raise OpenTokException(
+                    "archive_name must be between 1 and 80 characters in length."
+                )
+
+        if archive_resolution is not None:
+            if archive_mode == ArchiveModes.manual:
+                raise OpenTokException(
+                    "You cannot specify a value for archive_resolution with archive mode: manual."
+                )
+            if archive_resolution not in valid_archive_resolutions:
+                raise OpenTokException(
+                    f"archive_resolution must be one of the allowed values: {valid_archive_resolutions}."
+                )
+
         options[u("p2p.preference")] = media_mode.value
         options[u("archiveMode")] = archive_mode.value
+        if archive_name is not None:
+            options[("archiveName")] = archive_name
+        if archive_resolution is not None:
+            options[("archiveResolution")] = archive_resolution
+
         if location:
             # validate IP address
             try:
@@ -452,7 +499,7 @@ def create_session(
 
             session_id = (
                 dom.getElementsByTagName("session_id")[0].childNodes[0].nodeValue
-            )            
+            )
             return Session(
                 self,
                 session_id,

tests/test_session_creation.py

@@ -229,7 +229,10 @@ def test_create_always_archive_mode_session(self):
         )
 
         session = self.opentok.create_session(
-            media_mode=MediaModes.routed, archive_mode=ArchiveModes.always
+            media_mode=MediaModes.routed,
+            archive_mode=ArchiveModes.always,
+            archive_name="test_opentok_archive",
+            archive_resolution="1920x1080",
         )
 
         validate_jwt_header(self, httpretty.last_request().headers[u("x-opentok-auth")])
@@ -239,6 +242,8 @@ def test_create_always_archive_mode_session(self):
         body = parse_qs(httpretty.last_request().body)
         expect(body).to(have_key(b("p2p.preference"), [b("disabled")]))
         expect(body).to(have_key(b("archiveMode"), [b("always")]))
+        expect(body).to(have_key(b("archiveName"), [b("test_opentok_archive")]))
+        expect(body).to(have_key(b("archiveResolution"), [b("1920x1080")]))
         expect(session).to(be_a(Session))
         expect(session).to(
             have_property(
@@ -252,24 +257,44 @@ def test_create_always_archive_mode_session(self):
         expect(session).to(have_property(u("archive_mode"), ArchiveModes.always))
         expect(session).to(have_property(u("e2ee"), False))
 
-    @httpretty.activate
     def test_complains_about_always_archive_mode_and_relayed_session(self):
-        httpretty.register_uri(
-            httpretty.POST,
-            u("https://api.opentok.com/session/create"),
-            body=u(
-                '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><sessions><Session><session_id>1_MX4xMjM0NTZ-fk1vbiBNYXIgMTcgMDA6NDE6MzEgUERUIDIwMTR-MC42ODM3ODk1MzQ0OTQyODA4fg</session_id><partner_id>123456</partner_id><create_dt>Mon Mar 17 00:41:31 PDT 2014</create_dt></Session></sessions>'
-            ),
-            status=200,
-            content_type=u("text/xml"),
-        )
         self.assertRaises(
             OpenTokException,
             self.opentok.create_session,
             media_mode=MediaModes.relayed,
             archive_mode=ArchiveModes.always,
         )
 
+    def test_auto_archive_errors(self):
+        self.assertRaises(
+            OpenTokException,
+            self.opentok.create_session,
+            media_mode=MediaModes.routed,
+            archive_mode=ArchiveModes.manual,
+            archive_name="my_archive",
+        )
+        self.assertRaises(
+            OpenTokException,
+            self.opentok.create_session,
+            media_mode=MediaModes.routed,
+            archive_mode=ArchiveModes.manual,
+            archive_resolution="640x480",
+        )
+        self.assertRaises(
+            OpenTokException,
+            self.opentok.create_session,
+            media_mode=MediaModes.routed,
+            archive_mode=ArchiveModes.always,
+            archive_name="my_incredibly_long_name_that_is_definitely_going_to_be_over_the_80_character_limit_we_currently_impose",
+        )
+        self.assertRaises(
+            OpenTokException,
+            self.opentok.create_session,
+            media_mode=MediaModes.routed,
+            archive_mode=ArchiveModes.always,
+            archive_resolution="10x10",
+        )
+
     @httpretty.activate
     def test_create_session_with_e2ee(self):
         httpretty.register_uri(
@@ -285,7 +310,7 @@ def test_create_session_with_e2ee(self):
         session = self.opentok.create_session(e2ee=True)
 
         body = parse_qs(httpretty.last_request().body)
-        expect(body).to(have_key(b("e2ee"), [b'True']))
+        expect(body).to(have_key(b("e2ee"), [b"True"]))
         expect(session).to(be_a(Session))
         expect(session).to(
             have_property(