Merge branch 'modernization' of github.com:aoberoi/Opentok-Python-SDK into v2.2-docs

Author: jeffswartz

opentok/archives.py

@@ -1,5 +1,5 @@
 from datetime import datetime, date
-from six import iteritems, PY2, PY3
+from six import iteritems, PY2, PY3, u
 import json
 import pytz
 if PY3:
@@ -75,7 +75,7 @@ def __init__(self, sdk, values):
     def stop(self):
         """
         Stops an OpenTok archive that is being recorded.
-       
+
         Archives automatically stop recording after 90 minutes or when all clients have disconnected
         from the session being archived.
         """
@@ -86,7 +86,7 @@ def stop(self):
     def delete(self):
         """
         Deletes an OpenTok archive.
-       
+
         You can only delete an archive which has a status of "available" or "uploaded". Deleting an
         archive removes its record from the list of archives. For an "available" archive, it also
         removes the archive file, making it unavailable for download.
@@ -108,9 +108,9 @@ def json(self):
 
 class ArchiveList(object):
 
-    def __init__(self, values):
+    def __init__(self, sdk, values):
         self.count = values.get('count')
-        self.items = map(lambda x: Archive(self, x), values.get('items', []))
+        self.items = list(map(lambda x: Archive(sdk, x), values.get('items', [])))
 
     def __iter__(self):
         for x in self.items:
@@ -125,4 +125,11 @@ def attrs(self):
     def json(self):
         return json.dumps(self.attrs(), default=dthandler, indent=4)
 
+    def __getitem__(self, key):
+        return self.items.get(key)
+
+    def __setitem__(self, key, item):
+        raise ArchiveError(u('Cannot set item {0} for key {1} in Archive object').format(item, key))
 
+    def __len__(self):
+        return len(self.items)

opentok/opentok.py

@@ -386,7 +386,7 @@ def get_archives(self, offset=None, count=None):
         response = requests.get(self.archive_url() + "?" + urlencode(params), headers=self.archive_headers())
 
         if response.status_code < 300:
-            return ArchiveList(response.json())
+            return ArchiveList(self, response.json())
         elif response.status_code == 403:
             raise AuthError()
         elif response.status_code == 404:

sample/Archiving/README.md

@@ -0,0 +1,129 @@
+# OpenTok Hello World Python
+
+This is a simple demo app that shows how you can use the OpenTok-Python-SDK to create Sessions,
+generate Tokens with those Sessions, and then pass these values to a JavaScript client that can
+connect and conduct a group chat.
+
+## Running the App
+
+First, we highly recommend setting up a [virtualenv](http://www.virtualenv.org/en/latest/).
+
+```
+$ virtualenv venv
+$ source venv/bin/activate
+```
+
+Next, download the dependencies using [Pip](http://www.pip-installer.org/en/latest/), from the
+current directory:
+
+```
+(venv)$ pip install -r requirements.txt
+```
+
+Then add your own API Key and API Secret to the environment variables. There are a few ways to do
+this but the simplest would be to do it right in your shell.
+
+```
+(venv)$ export API_KEY=0000000
+(venv)$ export API_SECRET=abcdef1234567890abcdef01234567890abcdef
+```
+
+Finally, start the server.
+
+```
+(venv)$ python helloworld.py
+```
+
+Visit <http://127.0.0.1:5000/> in your browser. Open it again in a second window. Smile! You've just
+set up a group chat.
+
+## Walkthrough
+
+This demo application uses the [Flask web microframework](http://flask.pocoo.org/). It is similar to
+many other popular web frameworks. We are only covering the very basics of the framework, but you can
+learn more by following the links above.
+
+### Main Application (helloworld.py)
+
+The first thing done in this file is to import the dependencies we will be using. In this case that
+is the Flask web framework, the os module, and most importantly the OpenTok SDK.
+
+```python
+from flask import Flask, render_template
+from opentok import OpenTok
+import os
+```
+
+Next this file performs some basic checks on the environment. If it cannot find the `API_KEY`and
+`API_SECRET` environment variables, there is no point in continuing.
+
+The object `app` is our application and its initialized by instantiating an object from Flask.
+Then we initialize an instance of OpenTok as `opentok`. If this file is run as the main file, 
+we should start running the app.
+
+```python
+app = Flask(__name__)
+opentok = OpenTok(api_key, api_secret)
+
+# ...
+
+if __name__ == "__main__":
+    app.run()
+```
+
+Now, lets discuss the Hello World application's functionality. We want to set up a group chat so
+that any client that visits a page will connect to the same OpenTok Session. Once they are connected
+they can Publish a Stream and Subscribe to all the other streams in that Session. So we just need
+one Session object, and it needs to be accessible every time a request is made. On the next line we
+simply call the `OpenTok` instance's `create_session` method to get a Session and store it in the
+`session` variable. Alternatively, `session_id`s are commonly stored in databses for applications
+that have many of them.
+
+```python
+session = opentok.create_session()
+```
+
+We only need one page, so we create one route handler for any HTTP GET requests to trigger.
+
+```python
+@app.route("/")
+def hello():
+  # ...
+```
+
+Now all we have to do is serve a page with the three values the client will need to connect to the
+session: `api_key`, `session_id`, and `token`. The `api_key` is available in the outer scope so we
+can just assign it. The `session_id` is available as the `session.session_id` attribute. The `token`
+is generated freshly on this request by calling the `generate_token` method of the `opentok`
+instance, and passing in the `session_id`. This is because a Token is a piece of information that
+carries a specific client's permissions in a certain Session. Ideally, as we've done here, you
+generate a unique token for each client that will connect.
+
+```python
+    key = api_key
+    session_id = session.session_id
+    token = opentok.generate_token(session_id)
+```
+
+Now all we have to do is serve a page with those three values. Lets call our `render_template`
+helper that will pick up a template called `index.html` from the `templates/` directory in our
+application and pass in the variables for it to include on the page.
+
+```python
+    return render_template('index.html', api_key=key, session_id=session_id, token=token)
+```
+
+### Main Template (templates/index.html)
+
+This file simply sets up the HTML page for the JavaScript application to run, imports the
+JavaScript library, and passes the values created by the server into the JavaScript application
+inside `public/js/helloworld.js`
+
+### JavaScript Applicaton (static/js/helloworld.js)
+
+The group chat is mostly implemented in this file. At a high level, we connect to the given
+Session, publish a stream from our webcam, and listen for new streams from other clients to
+subscribe to.
+
+For more details, read the comments in the file or go to the
+[JavaScript Client Library](http://tokbox.com/opentok/libraries/client/js/) for a full reference.

sample/Archiving/archiving.py

@@ -0,0 +1,73 @@
+from flask import Flask, render_template, request, redirect, url_for
+from opentok import OpenTok
+from email.utils import formatdate
+import os, time
+
+try:
+    api_key = os.environ['API_KEY']
+    api_secret = os.environ['API_SECRET']
+except Exception:
+    raise Exception('You must define API_KEY and API_SECRET environment variables')
+
+app = Flask(__name__)
+opentok = OpenTok(api_key, api_secret)
+session = opentok.create_session()
+
+@app.template_filter('datefmt')
+def datefmt(dt):
+    return formatdate(time.mktime(dt.timetuple()))
+
+@app.route("/")
+def index():
+    return render_template('index.html')
+
+@app.route("/host")
+def host():
+    key = api_key
+    session_id = session.session_id
+    token = opentok.generate_token(session_id)
+    return render_template('host.html', api_key=key, session_id=session_id, token=token)
+
+@app.route("/participant")
+def participant():
+    key = api_key
+    session_id = session.session_id
+    token = opentok.generate_token(session_id)
+    return render_template('participant.html', api_key=key, session_id=session_id, token=token)
+
+@app.route("/history")
+def history():
+    page = int(request.args.get('page', '1'))
+    offset = (page - 1) * 5
+    archives = opentok.get_archives(offset=offset, count=5)
+
+    show_previous = '/history?page=' + str(page-1) if page > 1 else None
+    show_next = '/history?page=' + str(page+1) if archives.count > (offset + 5) else None
+
+    return render_template('history.html', archives=archives, show_previous=show_previous,
+                            show_next=show_next)
+
+@app.route("/download/<archive_id>")
+def download(archive_id):
+    archive = opentok.get_archive(archive_id)
+    return redirect(archive.url)
+
+@app.route("/start")
+def start():
+    archive = opentok.start_archive(session.session_id, name="Python Archiving Sample App")
+    return archive.json()
+
+@app.route("/stop/<archive_id>")
+def stop(archive_id):
+    archive = opentok.stop_archive(archive_id)
+    return archive.json()
+
+@app.route("/delete/<archive_id>")
+def delete(archive_id):
+    opentok.delete_archive(archive_id)
+    return redirect(url_for('history'))
+
+
+if __name__ == "__main__":
+    app.debug = True
+    app.run()

sample/Archiving/requirements.txt

@@ -0,0 +1,2 @@
+Flask
+-e ./../..

sample/Archiving/static/css/sample.css

@@ -0,0 +1,22 @@
+/* Move down content because we have a fixed navbar that is 50px tall */
+body {
+  padding-top: 50px;
+  padding-bottom: 20px;
+  background-color: #F2F2F2;
+}
+
+/* Responsive: Portrait tablets and up */
+@media screen and (min-width: 768px) {
+  /* Remove padding from wrapping element since we kick in the grid classes here */
+  .body-content {
+    padding: 0;
+  }
+}
+
+#subscribers div {
+  float: left;
+}
+
+.bump-me {
+  padding-top: 40px;
+}

sample/Archiving/static/img/archiving-off.png

@@ -0,0 +1,37 @@
+var session = OT.initSession(sessionId),
+    publisher = OT.initPublisher("publisher"),
+    archiveID = null;
+
+session.connect(apiKey, token, function(err, info) {
+  if(err) {
+    alert(err.message || err);
+  }
+  session.publish(publisher);
+});
+
+session.on('streamCreated', function(event) {
+  session.subscribe(event.stream, "subscribers", { insertMode: "append" });
+});
+
+session.on('archiveStarted', function(event) {
+  archiveID = event.id;
+  console.log("ARCHIVE STARTED");
+  $(".start").hide();
+  $(".stop").show();
+});
+
+session.on('archiveStopped', function(event) {
+  archiveID = null;
+  console.log("ARCHIVE STOPPED");
+  $(".start").show();
+  $(".stop").hide();
+});
+
+$(document).ready(function() {
+  $(".start").click(function(event){
+    $.get("start");
+  }).show();
+  $(".stop").click(function(event){
+    $.get("stop/" + archiveID);
+  }).hide();
+});