Adding "get_stream()" method (#130)

Adds get_stream API

Author: normanargueta

README.rst

@@ -231,6 +231,33 @@ Once a Session is created, you can send signals to everyone in the session or to
   # To send a signal to a specific connection in the session:
   opentok.signal(session_id, payload, connection_id)
 
+Get Stream
+~~~~~~~~~~~~~~~~~~~~~
+
+Use this method to get information on an OpenTok stream (or all streams in a session).
+
+You can get information about a stream by calling the `get_stream(session_id, stream_id)` method of the `OpenTok` class, or by calling the `get_stream(stream_id)` method on the `Session` class.
+
+The method return a 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)
+* ``layoutClassList``: It's an array of the layout classes for the stream
+
+.. code:: python
+
+  session_id = 'SESSIONID'
+  stream_id = '8b732909-0a06-46a2-8ea8-074e64d43422'
+
+  # To get stream info:
+  stream = opentok.get_stream(session_id, stream_id)
+
+  # Stream properties:
+  print stream.id #8b732909-0a06-46a2-8ea8-074e64d43422
+  print stream.videoType #camera
+  print stream.name #stream name
+  print stream.layoutClassList #['full']
 
 Samples
 -------

opentok/__init__.py

@@ -3,3 +3,4 @@
 from .archives import Archive, ArchiveList, OutputModes
 from .exceptions import OpenTokException
 from .version import __version__
+from .stream import Stream

opentok/endpoints.py

@@ -0,0 +1,32 @@
+class Endpoints(object):
+    """
+    For internal use.
+    Class that provides the endpoint urls
+    """
+    def __init__(self, api_url, api_key):
+        self.api_url = api_url
+        self.api_key = api_key
+
+    def session_url(self):
+        url = self.api_url + '/session/create'
+        return url
+
+    def archive_url(self, archive_id=None):
+        url = self.api_url + '/v2/project/' + self.api_key + '/archive'
+        if archive_id:
+            url = url + '/' + archive_id
+        return url
+
+    def signaling_url(self, session_id, connection_id=None):
+        url = self.api_url + '/v2/project/' + self.api_key + '/session/' + session_id
+
+        if connection_id:
+            url += '/connection/' + connection_id
+
+        url += '/signal'
+        return url
+
+    def get_stream_url(self, session_id, stream_id):
+        url = self.api_url + '/v2/project/' + self.api_key + '/session/' + session_id + '/stream/' + stream_id
+        return url
+

opentok/exceptions.py

@@ -34,4 +34,9 @@ class ArchiveError(OpenTokException):
 class SignalingError(OpenTokException):
     """Indicates that there was a signaling specific problem, one of the parameter
     is invalid or the type|data string doesn't have a correct size"""
-    pass
+    pass
+
+class GetStreamError(OpenTokException):
+    """Indicates that the data in the request is invalid, or the session_id or stream_id
+    are invalid"""
+    pass

opentok/opentok.py

@@ -19,9 +19,19 @@
 from enum import Enum
 
 from .version import __version__
+from .endpoints import Endpoints
 from .session import Session
 from .archives import Archive, ArchiveList, OutputModes
-from .exceptions import OpenTokException, RequestError, AuthError, NotFoundError, ArchiveError, SignalingError
+from .stream import Stream
+from .exceptions import (
+    OpenTokException,
+    RequestError,
+    AuthError,
+    NotFoundError,
+    ArchiveError,
+    SignalingError,
+    GetStreamError
+)
 
 class Roles(Enum):
     """List of valid roles for a token."""
@@ -62,9 +72,9 @@ class OpenTok(object):
     def __init__(self, api_key, api_secret, api_url='https://api.opentok.com', timeout=None):
         self.api_key = str(api_key)
         self.api_secret = api_secret
-        self.api_url = api_url
         self.timeout = timeout
         self._proxies = None
+        self.endpoints = Endpoints(api_url, self.api_key)
 
     @property
     def proxies(self):
@@ -264,7 +274,7 @@ def create_session(self, location=None, media_mode=MediaModes.relayed, archive_m
             options[u('location')] = location
 
         try:
-            response = requests.post(self.session_url(), data=options, headers=self.headers(), proxies=self.proxies, timeout=self.timeout)
+            response = requests.post(self.endpoints.session_url(), data=options, headers=self.headers(), proxies=self.proxies, timeout=self.timeout)
             response.encoding = 'utf-8'
 
             if response.status_code == 403:
@@ -299,29 +309,6 @@ def json_headers(self):
         result['Content-Type'] = 'application/json'
         return result
 
-    def session_url(self):
-        """For internal use."""
-        url = self.api_url + '/session/create'
-        return url
-
-    def archive_url(self, archive_id=None):
-        """For internal use."""
-        url = self.api_url + '/v2/project/' + self.api_key + '/archive'
-        if archive_id:
-            url = url + '/' + archive_id
-        return url
-
-    def signaling_url(self, session_id, connection_id=None):
-        """For internal use."""
-        url = self.api_url + '/v2/project/' + self.api_key + '/session/' + session_id
-
-        if connection_id:
-            url += '/connection/' + connection_id
-
-        url += '/signal'
-
-        return url
-
     def start_archive(self, session_id, has_audio=True, has_video=True, name=None, output_mode=OutputModes.composed, resolution=None):
         """
         Starts archiving an OpenTok session.
@@ -372,7 +359,7 @@ def start_archive(self, session_id, has_audio=True, has_video=True, name=None, o
                    'resolution': resolution,
         }
 
-        response = requests.post(self.archive_url(), data=json.dumps(payload), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.post(self.endpoints.archive_url(), data=json.dumps(payload), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             return Archive(self, response.json())
@@ -405,7 +392,7 @@ def stop_archive(self, archive_id):
 
         :rtype: The Archive object corresponding to the archive being stopped.
         """
-        response = requests.post(self.archive_url(archive_id) + '/stop', headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.post(self.endpoints.archive_url(archive_id) + '/stop', headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             return Archive(self, response.json())
@@ -428,7 +415,7 @@ def delete_archive(self, archive_id):
 
         :param String archive_id: The archive ID of the archive to be deleted.
         """
-        response = requests.delete(self.archive_url(archive_id), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.delete(self.endpoints.archive_url(archive_id), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             pass
@@ -446,7 +433,7 @@ def get_archive(self, archive_id):
 
         :rtype: The Archive object.
         """
-        response = requests.get(self.archive_url(archive_id), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.get(self.endpoints.archive_url(archive_id), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             return Archive(self, response.json())
@@ -475,7 +462,7 @@ def get_archives(self, offset=None, count=None):
         if count is not None:
             params['count'] = count
 
-        response = requests.get(self.archive_url() + "?" + urlencode(params), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
+        response = requests.get(self.endpoints.archive_url() + "?" + urlencode(params), headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout)
 
         if response.status_code < 300:
             return ArchiveList(self, response.json())
@@ -502,7 +489,7 @@ def signal(self, session_id, payload, connection_id=None):
         connected to the session
         """
         response = requests.post(
-            self.signaling_url(session_id, connection_id),
+            self.endpoints.signaling_url(session_id, connection_id),
             data=json.dumps(payload),
             headers=self.json_headers(),
             proxies=self.proxies,
@@ -522,6 +509,31 @@ def signal(self, session_id, payload, connection_id=None):
         else:
             raise RequestError("An unexpected error occurred", response.status_code)
 
+    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)
+        -layoutClassList: It's an array of the layout classes for the stream
+        """
+        endpoint = self.endpoints.get_stream_url(session_id, stream_id)
+        response = requests.get(
+            endpoint, headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout
+        )
+
+        if response.status_code == 200:
+            return Stream(response.json())
+        elif response.status_code == 400:
+            raise GetStreamError('Invalid request. This response may indicate that data in your request data is invalid JSON. Or it may indicate that you do not pass in a session ID or you passed in an invalid stream ID.')
+        elif response.status_code == 403:
+            raise AuthError('You passed in an invalid OpenTok API key or JWT token.')
+        elif response.status_code == 408:
+            raise GetStreamError('You passed in an invalid stream ID.')
+        else:
+            raise RequestError('An unexpected error occurred', response.status_code)
+
     def _sign_string(self, string, secret):
         return hmac.new(secret.encode('utf-8'), string.encode('utf-8'), hashlib.sha1).hexdigest()
 

opentok/stream.py

@@ -0,0 +1,8 @@
+class Stream(object):
+	"""
+	Represents an OpenTok stream
+	"""
+
+	def __init__(self, kwargs):
+		for key, value in kwargs.items():
+			setattr(self, key, value)

tests/test_get_stream.py

@@ -0,0 +1,85 @@
+import unittest
+from six import text_type, u, b, PY2, PY3
+from opentok import OpenTok, Stream, __version__
+import httpretty
+import json
+import textwrap
+from expects import *
+
+from .validate_jwt import validate_jwt_header
+
+class OpenTokGetStreamTest(unittest.TestCase):
+    def setUp(self):
+        self.api_key = u('123456')
+        self.api_secret = u('1234567890abcdef1234567890abcdef1234567890')
+        self.opentok = OpenTok(self.api_key, self.api_secret)
+        self.session_id = u('SESSIONID')
+        self.stream_id = u('8b732909-0a06-46a2-8ea8-074e64d43422')
+
+    @httpretty.activate
+    def test_get_stream(self):
+        stream = Stream({
+            u('id'): u('8b732909-0a06-46a2-8ea8-074e64d43422'),
+            u('videoType'): u('camera'),
+            u('name'): u(''),
+            u('layoutClassList'): ['full']
+        })
+
+        httpretty.register_uri(
+            httpretty.GET,
+            u('https://api.opentok.com/v2/project/{0}/session/{1}/stream/{2}').format(self.api_key, self.session_id, self.stream_id),
+            body=textwrap.dedent(u("""\
+                   {
+                      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
+                      "videoType": "camera",
+                      "name": "",
+                      "layoutClassList": ["full"]
+                    }""")),
+            status=200,
+            content_type=u('application/json')
+        )
+
+        stream_response = self.opentok.get_stream(self.session_id, self.stream_id)
+        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')))
+        expect(stream_response).to(be_an(Stream))
+        expect(stream_response).to(have_property(u('id'), stream.id))
+        expect(stream_response).to(have_property(u('videoType'), stream.videoType))
+        expect(stream_response).to(have_property(u('name'), stream.name))
+        expect(stream_response).to(have_property(u('layoutClassList'), stream.layoutClassList))
+        expect(list(stream_response.layoutClassList)).to(have_length(1))
+
+    @httpretty.activate
+    def test_get_stream_with_name(self):
+        stream = Stream({
+            u('id'): u('8b732909-0a06-46a2-8ea8-074e64d43422'),
+            u('videoType'): u('camera'),
+            u('name'): u('stream name'),
+            u('layoutClassList'): ['full']
+        })
+
+        httpretty.register_uri(
+            httpretty.GET,
+            u('https://api.opentok.com/v2/project/{0}/session/{1}/stream/{2}').format(self.api_key, self.session_id, self.stream_id),
+            body=textwrap.dedent(u("""\
+                   {
+                      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
+                      "videoType": "camera",
+                      "name": "stream name",
+                      "layoutClassList": ["full"]
+                    }""")),
+            status=200,
+            content_type=u('application/json')
+        )
+
+        stream_response = self.opentok.get_stream(self.session_id, self.stream_id)
+        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')))
+        expect(stream_response).to(be_an(Stream))
+        expect(stream_response).to(have_property(u('id'), stream.id))
+        expect(stream_response).to(have_property(u('videoType'), stream.videoType))
+        expect(stream_response).to(have_property(u('name'), stream.name))
+        expect(stream_response).to(have_property(u('layoutClassList'), stream.layoutClassList))
+        expect(list(stream_response.layoutClassList)).to(have_length(1))