Skip to content

Commit 0d7eb75

Browse files
aoberoiaoberoi
committed
rewrite README to follow outline, fixes #19 
1 parent efb1ec5 commit 0d7eb75

File tree

1 file changed

+124
-42
lines changed

1 file changed

+124
-42
lines changed

‎README.rst

Lines changed: 124 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ Pip (recommended):
1818
Pip helps manage dependencies for Python projects using the PyPI index. Find more info here:
1919
http://www.pip-installer.org/en/latest/
2020

21-
Add the opentok package as a dependency in your project. The most common way is to add it to your
22-
requirements.txt file::
21+
Add the ``opentok`` package as a dependency in your project. The most common way is to add it to your
22+
``requirements.txt`` file::
2323

2424
opentok>=2.2
2525

@@ -34,62 +34,144 @@ Download the latest package zip from the `Releases page
3434
<https://github.com/opentok/Opentok-Python-SDK/releases>`_
3535

3636

37-
## Requirements
37+
Usage
38+
-----
3839

39-
The OpenTok Python SDK requires Python 2.2 or greater.
40+
Initializing
41+
~~~~~~~~~~~~
4042

41-
You need an OpenTok API key and API secret, which you can obtain at <https://dashboard.tokbox.com>.
43+
Import the package at the top of any file where you will use it. At the very least you will need the
44+
``OpenTok`` class. Then initialize an OpenTok instance with your own API Key and API Secret.::
4245

43-
# OpenTokSDK
46+
from opentok import OpenTok
4447

45-
In order to use any of the functions of the SDK, you must first create an `OpenTokSDK` object with your developer credentials.
46-
The `OpenTokSDK` constructor takes two parameters:
48+
opentok = OpenTok(api_key, api_secret)
4749

48-
* api_key (string) - Your OpenTok [API key](https://dashboard.tokbox.com)
49-
* api_secret (string) - Your OpenTok [API secret](https://dashboard.tokbox.com)
50+
Creating Sessions
51+
~~~~~~~~~~~~~~~~~
5052

51-
```python
52-
import OpenTokSDK
53+
The create an OpenTok Session, use the ``opentok.create_session()`` method. There are two optional
54+
keyword parameters for this method: ``location`` which can be set to a string containing an IP
55+
address, and ``p2p`` which is a boolean. This method returns a ``Session`` object. Its
56+
``session_id`` attribute is useful when saving to a persistent store (e.g. database).::
5357

54-
# Creating an OpenTok Object
55-
API_KEY = '' # Replace with your API key.
56-
API_SECRET = '' # Replace with your API secret.
57-
OTSDK = OpenTokSDK.OpenTokSDK(API_KEY,API_SECRET)
58-
```
58+
# Just a plain Session
59+
session = opentok.create_session()
60+
# A p2p Session
61+
session = opentok.create_session(p2p=True)
62+
# A Session with a location hint
63+
session = opentok.create_session(location=u'12.34.56.78')
5964

65+
# Store this session ID in the database
66+
session_id = session.session_id
6067

61-
## Creating Sessions
68+
Generating Tokens
69+
~~~~~~~~~~~~~~~~~
6270

63-
Use the `createSession()` method of the OpenTokSDK object to create a session and a session ID:
71+
Once a Session is created, you can start generating Tokens for clients to use when connecting to it.
72+
You can generate a token either by calling the ``opentok.generate_token(session_id)`` method or by
73+
calling the ``session.generate_token()`` method on a ``Session`` instance after creating it. There
74+
is a set of optional keyword parameters: ``role``, ``expire_time``, and ``data``.::
6475

65-
```python
66-
# creating an OpenTok server-enabled session:
67-
session_id = OTSDK.create_session().session_id
76+
# Generate a Token from just a session_id (fetched from a database)
77+
token = opentok.generate_token(session_id)
78+
# Generate a Token by calling the method on the Session (returned from create_session)
79+
token = session.generate_token()
6880

69-
# Creating a peer-to-peer session
70-
session_properties = {OpenTokSDK.SessionProperties.p2p_preference: "enabled"}
71-
session_id = OTSDK.create_session(properties=session_properties).session_id
72-
```
81+
from opentok import Roles
82+
# Set some options in a token
83+
token = session.generate_token(role=Roles.moderator,
84+
expire_time=int(time.time()) + 10,
85+
data=u'name=Johnny')
7386

74-
## Generating Tokens
75-
With the generated sessionId, you generate tokens for each user.
87+
Working with Archives
88+
~~~~~~~~~~~~~~~~~~~~~
7689

77-
```python
78-
# Generate a publisher token that will expire in 24 hours:
79-
token = OTSDK.generate_token(session_id)
90+
You can start the recording of an OpenTok Session using the ``opentok.start_archive(session_id)``
91+
method. This method takes an optional keyword argument ``name`` to assign a name to the archive.
92+
This method will return an ``Archive`` instance. Note that you can only start an Archive on
93+
a Session that has clients connection.::
8094

81-
# Generate a subscriber token that has connection data
82-
role = OpenTokSDK.RoleConstants.SUBSCRIBER
83-
connect_data = "username=Bob,level=4"
84-
token = OTSDK.generate_token(session_id, role, None, connect_data)
85-
```
95+
archive = opentok.start_archive(session_id, name=u'Important Presentation')
8696

87-
Possible Errors:
88-
* "Null or empty session ID are not valid"
89-
* "An invalid session ID was passed"
97+
# Store this archive_id in the database
98+
archive_id = archive.id
9099

91-
# More information
100+
You can stop the recording of a started Archive using the ``opentok.stop_archive(archive_id)``
101+
method. You can also do this using the ``archive.stop()`` method of an ``Archive`` instance.::
92102

93-
See the [reference documentation](docs/reference.md).
103+
# Stop an Archive from an archive_id (fetched from database)
104+
opentok.stop_archive(archive_id)
105+
# Stop an Archive from an instance (returned from opentok.start_archive)
106+
archive.stop()
94107

95-
For more information on OpenTok, go to <http://www.tokbox.com/>.
108+
To get an ``Archive`` instance (and all the information about it) from an archive ID, use the
109+
``opentok.get_archive(archive_id)`` method.::
110+
111+
archive = opentok.get_archive(archive_id)
112+
113+
To delete an Archive, you can call the ``opentok.delete_archive(archive_id)`` method or the
114+
``archive.delete()`` method of an ``Archive`` instance.::
115+
116+
# Delete an Archive from an archive ID (fetched from database)
117+
opentok.delete_archive(archive_id)
118+
# Delete an Archive from an Archive instance (returned from opentok.start_archive or
119+
opentok.get_archive)
120+
archive.delete()
121+
122+
You can also get a list of all the Archives you've created (up to 1000) with your API Key. This is
123+
done using the ``opentok.list_archives()`` method. There are two optional keyword parameters:
124+
``count`` and ``offset``; they can help you paginate through the results. This method returns an
125+
instance of the ``ArchiveList`` class.::
126+
127+
archive_list = opentok.list_archive()
128+
129+
# Get a specific Archive from the list
130+
archive = archive_list.items[i]
131+
132+
# Iterate over items
133+
for archive in iter(archive_list):
134+
pass
135+
136+
# Get the total number of Archives for this API Key
137+
total = archive_list.total
138+
139+
Documentation
140+
-------------
141+
142+
**TODO:** Reference documentation is available at http://opentok.github.io/opentok-python-sdk/
143+
144+
Requirements
145+
------------
146+
147+
You need an OpenTok API key and API secret, which you can obtain at https://dashboard.tokbox.com/
148+
149+
The OpenTok Python SDK requires Python 2.6, 2.7, 3.2, 3.3, or 3.4
150+
151+
Release Notes
152+
-------------
153+
154+
See the `Releases <https://github.com/opentok/Opentok-Python-SDK/releases>`_ page for details about
155+
each release.
156+
157+
Important changes in v2.0
158+
~~~~~~~~~~~~~~~~~~~~~~~~~
159+
160+
This version of the SDK includes support for working with OpenTok 2.0 archives. (This API does not
161+
work with OpenTok 1.0 archives.)
162+
163+
Development and Contributing
164+
----------------------------
165+
166+
Interested in contributing? We <3 pull requests! File a new
167+
`Issue <https://github.com/opentok/opentok-python-sdk/issues>`_ or take a look at the existing ones.
168+
If you are going to send us a pull request, please try to run the test suite first and also include
169+
tests for your changes.
170+
171+
Support
172+
-------
173+
174+
See http://tokbox.com/opentok/support/ for all our support options.
175+
176+
Find a bug? File it on the `Issues <https://github.com/opentok/opentok-python-sdk/issues>`_ page.
177+
Hint: test cases are really helpful!

0 commit comments

Comments
 (0)