Added get_streams method to get the list of streams in a session (#135)

* Add list_streams API

Author: normanargueta

README.rst

@@ -231,14 +231,12 @@ 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
+Working with Streams
 ~~~~~~~~~~~~~~~~~~~~~
 
-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.
 
-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:
+The method returns a Stream object that contains information of an OpenTok stream:
 
 * ``id``: The stream ID
 * ``videoType``: "camera" or "screen"
@@ -259,6 +257,24 @@ The method return a Stream object that contains information of an OpenTok stream
   print stream.name #stream name
   print stream.layoutClassList #['full']
 
+Also, you can get information about all the streams in a session by calling the `list_streams(session_id)` method of the `OpenTok` class.
+
+The method returns a StreamList object that contains a list of all the streams
+
+.. code:: python
+
+  # To get all streams in a session:
+  stream_list = opentok.list_streams(session_id)
+
+  # Getting the first stream of the list
+  stream = stream_list.items[0]
+
+  # Stream properties:
+  print stream.id #8b732909-0a06-46a2-8ea8-074e64d43422
+  print stream.videoType #camera
+  print stream.name #stream name
+  print stream.layoutClassList #['full']
+
 Force Disconnect
 ~~~~~~~~~~~~~~~~~~~~~
 

opentok/__init__.py

@@ -3,4 +3,5 @@
 from .archives import Archive, ArchiveList, OutputModes
 from .exceptions import OpenTokException, AuthError, ForceDisconnectError
 from .version import __version__
-from .stream import Stream
+from .stream import Stream
+from .streamlist import StreamList

opentok/endpoints.py

@@ -26,8 +26,11 @@ def signaling_url(self, session_id, connection_id=None):
         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
+    def get_stream_url(self, session_id, stream_id=None):
+        """ this method returns the url to get streams information """
+        url = self.api_url + '/v2/project/' + self.api_key + '/session/' + session_id + '/stream'
+        if stream_id:
+            url = url + '/' + stream_id
         return url
 
     def force_disconnect_url(self, session_id, connection_id):

opentok/opentok.py

@@ -23,6 +23,7 @@
 from .session import Session
 from .archives import Archive, ArchiveList, OutputModes
 from .stream import Stream
+from .streamlist import StreamList
 from .exceptions import (
     OpenTokException,
     RequestError,
@@ -508,7 +509,7 @@ def signal(self, session_id, payload, connection_id=None):
         elif response.status_code == 413:
             raise SignalingError('The type string exceeds the maximum length (128 bytes), or the data string exceeds the maximum size (8 kB).')
         else:
-            raise RequestError("An unexpected error occurred", response.status_code)
+            raise RequestError('An unexpected error occurred', response.status_code)
 
     def get_stream(self, session_id, stream_id):
         """
@@ -535,6 +536,29 @@ def get_stream(self, session_id, stream_id):
         else:
             raise RequestError('An unexpected error occurred', response.status_code)
 
+    def list_streams(self, session_id):
+        """
+        Returns a list of Stream objects that contains information of all
+        the streams in a OpenTok session, with the following attributes:
+
+        -count: An integer that indicates the number of streams in the session
+        -items: List of the Stream objects
+        """
+        endpoint = self.endpoints.get_stream_url(session_id)
+
+        response = requests.get(
+            endpoint, headers=self.json_headers(), proxies=self.proxies, timeout=self.timeout
+        )
+
+        if response.status_code == 200:
+            return StreamList(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.')
+        else:
+            raise RequestError('An unexpected error occurred', response.status_code)
+
     def force_disconnect(self, session_id, connection_id):
         """
         Sends a request to disconnect a client from an OpenTok session

opentok/stream.py

@@ -1,8 +1,30 @@
+from datetime import datetime, date
+from six import iteritems, PY2, PY3, u
+import json
+from six.moves import map
+dthandler = lambda obj: obj.isoformat() if isinstance(obj, datetime)  or isinstance(obj, date) else None
+
+from .exceptions import GetStreamError
+
 class Stream(object):
-	"""
-	Represents an OpenTok stream
-	"""
+    """
+    Represents an OpenTok stream
+    """
+
+    def __init__(self, kwargs):
+        self.id = kwargs.get('id')
+        self.videoType = kwargs.get('videoType')
+        self.name = kwargs.get('name')
+        self.layoutClassList = kwargs.get('layoutClassList')
+
+    def attrs(self):
+        """
+        Returns a dictionary of the Stream's attributes.
+        """
+        return dict((k, v) for k, v in iteritems(self.__dict__))
 
-	def __init__(self, kwargs):
-		for key, value in kwargs.items():
-			setattr(self, key, value)
+    def json(self):
+        """
+        Returns a JSON representation of the Stream.
+        """
+        return json.dumps(self.attrs(), default=dthandler, indent=4)

opentok/streamlist.py

@@ -0,0 +1,29 @@
+from six import u
+import json
+from .opentok import Stream
+from .exceptions import GetStreamError
+
+class StreamList(object):
+    """
+    Represents a list of OpenTok stream objects
+    """
+
+    def __init__(self, values):
+        self.count = values.get('count')
+        self.items = list(map(lambda x: Stream(x), values.get('items', [])))
+
+    def __iter__(self):
+        for x in self.items:
+            yield x
+
+    def json(self):
+        return json.dumps(self, default=lambda o: o.__dict__, sort_keys=True, indent=4)
+
+    def __getitem__(self, key):
+        return self.items.get(key)
+
+    def __setitem__(self, key, item):
+        raise GetStreamError(u('Cannot set item {0} for key {1} in Archive object').format(item, key))
+
+    def __len__(self):
+        return len(self.items)

tests/test_get_stream.py

@@ -1,6 +1,6 @@
 import unittest
 from six import text_type, u, b, PY2, PY3
-from opentok import OpenTok, Stream, __version__
+from opentok import OpenTok, Stream, StreamList, __version__
 import httpretty
 import json
 import textwrap
@@ -83,3 +83,38 @@ def test_get_stream_with_name(self):
         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_list(self):
+        httpretty.register_uri(
+            httpretty.GET,
+            u('https://api.opentok.com/v2/project/{0}/session/{1}/stream').format(self.api_key, self.session_id),
+            body=textwrap.dedent(u("""\
+                   {
+                      "count": 2,
+                      "items": [
+                        {
+                          "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
+                          "videoType": "camera",
+                          "name": "stream1",
+                          "layoutClassList": ["full"]
+                        },
+                        {
+                          "id": "7b732909-0a06-46a2-8ea8-074e64d43423",
+                          "videoType": "camera",
+                          "name": "stream2",
+                          "layoutClassList": ["full"]
+                        }
+                      ]
+                    }""")),
+            status=200,
+            content_type=u('application/json')
+        )
+
+        stream_list = self.opentok.list_streams(self.session_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_list).to(be_an(StreamList))
+        expect(stream_list).to(have_property(u('count'), 2))
+        expect(list(stream_list.items)).to(have_length(2))