Skip to content

Commit 2cc282f

Browse files
kyleconroykyleconroy
committed
Merge branch 'master' of github.com:twilio/twilio-python
2 parents 442d854 + 248f2c6 commit 2cc282f

16 files changed

Lines changed: 407 additions & 137 deletions

‎README.md‎

Lines changed: 57 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,93 @@
1-
A module for using the Twilio REST API and generating valid TwiML.
1+
A module for using the Twilio REST API and generating valid
2+
[TwiML](http://www.twilio.com/docs/api/twiml/ "TwiML -
3+
Twilio Markup Language"). [Click here to read the full
4+
documentation.](http://readthedocs.org/docs/twilio-python/en/latest/ "Twilio
5+
Python library documentation")
26

37
## Installation
48

5-
Install from PyPi using pip
9+
Install from PyPi using [pip](http://www.pip-installer.org/en/latest/), a
10+
package manager for Python.
611

7-
pip install twilio
12+
$ pip install twilio
13+
14+
Don't have pip installed? Try installing it, by running this from the command
15+
line:
16+
17+
$ curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python
18+
19+
Alternately, you can [download the source code
20+
(ZIP)](https://github.com/twilio/twilio-python/zipball/master "twilio-python
21+
source code") for `twilio-python`, and then run:
22+
23+
$ python setup.py install
24+
25+
You may need to run the above commands with `sudo`.
826

927
## Getting Started
1028

11-
Getting started with the Twilio API couldn't be easier. Create a `TwilioRestClient` and you're ready to go.
29+
Getting started with the Twilio API couldn't be easier. Create a
30+
`TwilioRestClient` and you're ready to go.
1231

1332
### API Credentials
1433

15-
To get started, the `TwilioRestClient` needs your Twilio credentials. You can either pass these directly to the constructor (see the code below) or via environment variables.
16-
17-
We suggest storing your credentials as environment variables. Why? You'll never have to worry about committing your credentials and accidentally posting them somewhere public.
34+
The `TwilioRestClient` needs your Twilio credentials. You can either pass these
35+
directly to the constructor (see the code below) or via environment variables.
1836

1937
```python
2038
from twilio.rest import TwilioRestClient
2139

22-
account = "AXXXXXXXXXXXXXXXXX"
40+
account = "ACXXXXXXXXXXXXXXXXX"
2341
token = "YYYYYYYYYYYYYYYYYY"
2442
client = TwilioRestClient(account, token)
2543
```
2644

27-
Alternatively, a `TwilioRestClient` constructor without these parameters will look for `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` inside the current environment.
45+
Alternately, a `TwilioRestClient` constructor without these parameters will
46+
look for `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` variables inside the
47+
current environment.
48+
49+
We suggest storing your credentials as environment variables. Why? You'll never
50+
have to worry about committing your credentials and accidentally posting them
51+
somewhere public.
52+
2853

2954
```python
3055
from twilio.rest import TwilioRestClient
3156
client = TwilioRestClient()
3257
```
3358

34-
### Making a Call
59+
### Make a Call
3560

3661
```python
3762
from twilio.rest import TwilioRestClient
3863

39-
account = "AXXXXXXXXXXXXXXXXX"
64+
account = "ACXXXXXXXXXXXXXXXXX"
4065
token = "YYYYYYYYYYYYYYYYYY"
4166
client = TwilioRestClient(account, token)
4267

43-
call = client.calls.create(to="9991231234", from_="9991231234", url="http://foo.com/call.xml")
68+
call = client.calls.create(to="9991231234",
69+
from_="9991231234",
70+
url="http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
4471
print call.sid
4572
```
4673

74+
### Send an SMS
75+
```python
76+
from twilio.rest import TwilioRestClient
77+
78+
account = "ACXXXXXXXXXXXXXXXXX"
79+
token = "YYYYYYYYYYYYYYYYYY"
80+
client = TwilioRestClient(account, token)
81+
82+
message = client.sms.messages.create(to="+12316851234", from_="+15555555555",
83+
body="Hello there!")
84+
```
4785

4886
### Handling a call using TwiML
4987

50-
To control phone calls, your application need to output TwiML. Use `twilio.twiml.Response` to easily create such responses.
88+
To control phone calls, your application needs to output
89+
[TwiML](http://www.twilio.com/docs/api/twiml/ "TwiML - Twilio Markup
90+
Language"). Use `twilio.twiml.Response` to easily create such responses.
5191

5292
```python
5393
from twilio import twiml
@@ -64,4 +104,7 @@ print str(r)
64104

65105
### Digging Deeper
66106

67-
The full power of the Twilio API is at your finger tips. The [full documentation](http://readthedocs.org/docs/twilio-python/en/latest/) explains all the awesome features available to use.
107+
The full power of the Twilio API is at your fingertips. The [full
108+
documentation](http://readthedocs.org/docs/twilio-python/en/latest/ "Twilio
109+
Python library documentation") explains all the awesome features available to
110+
use.

‎docs/getting-started.rst‎

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Quickstart
44

55
Getting started with the Twilio API couldn't be easier. Create a Twilio REST client to get started. For example, the following code makes a call using the Twilio REST API.
66

7-
Making a Call
7+
Make a Call
88
===============
99

1010
.. code-block:: python
@@ -16,36 +16,48 @@ Making a Call
1616
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
1717
1818
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
19-
call = client.calls.make(to="9991231234", from_="9991231234",
20-
url="http://foo.com/call.xml")
19+
call = client.calls.create(to="9991231234", from_="9991231234",
20+
url="http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
2121
print call.length
2222
print call.sid
2323
24+
Send an SMS
25+
================
26+
27+
.. code-block:: python
28+
29+
from twilio.rest import TwilioRestClient
30+
31+
account = "ACXXXXXXXXXXXXXXXXX"
32+
token = "YYYYYYYYYYYYYYYYYY"
33+
client = TwilioRestClient(account, token)
34+
35+
message = client.sms.messages.create(to="+12316851234", from_="+15555555555",
36+
body="Hello there!")
37+
2438
Generating TwiML
2539
=================
2640

27-
To control phone calls, your application need to output TwiML. Use :class:`twilio.twiml.Response` to easily create such responses.
41+
To control phone calls, your application needs to output `TwiML
42+
<http://www.twilio.com/docs/api/twiml/>`_. Use :class:`twilio.twiml.Response`
43+
to easily create such responses.
2844

2945
.. code-block:: python
3046
3147
from twilio import twiml
3248
3349
r = twiml.Response()
34-
r.play("monkey.mp3", loop=5)
50+
r.play("https://api.twilio.com/cowbell.mp3", loop=5)
3551
print str(r)
3652
3753
.. code-block:: xml
3854
3955
<?xml version="1.0" encoding="utf-8"?>
40-
<Response><Play loop="5">monkey.mp3</Play><Response>
56+
<Response><Play loop="5">https://api.twilio.com/cowbell.mp3</Play><Response>
4157
4258
Digging Deeper
4359
========================
4460

45-
The full power of the Twilio API is at your finger tips. The :ref:`user-guide` explains all the awesome features available to use.
46-
47-
48-
49-
50-
61+
The full power of the Twilio API is at your fingertips. The :ref:`user-guide`
62+
explains all the awesome features available to use.
5163

‎docs/index.rst‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,13 @@ Installation
1111

1212
.. code-block:: bash
1313
14-
pip install twilio
14+
$ pip install twilio
1515
16-
You can also download the source and install using :data:`setuptools`
16+
You can also `download the source <https://github.com/twilio/twilio-python/zipball/master>`_ and install by downloading :data:`setuptools`, navigating in the Terminal to the folder containing the **twilio-python** library, and then running:
1717

1818
.. code-block:: bash
1919
20-
python setup.py install
20+
$ python setup.py install
2121
2222
Getting Started
2323
================
@@ -74,12 +74,15 @@ Small functions useful for validating requests are coming from Twilio
7474
Upgrade Plan
7575
==================
7676

77-
`twilio-python` 3.0 introduced backwards-incompatible changes to the API. See the :doc:`/upgrade-guide` for step-by-step instructions for migrating to 3.0. In many cases, the same methods are still offered, just in different locations.
77+
`twilio-python` 3.0 introduced backwards-incompatible changes to the API. See
78+
the :doc:`/upgrade-guide` for step-by-step instructions for migrating to 3.0.
79+
In many cases, the same methods are still offered, just in different locations.
7880

7981
API Reference
8082
==================
8183

82-
A complete guide to all public APIs found in `twilio-python`. Auto-generated, so only use when you really need to dive deep into the library.
84+
A complete guide to all public APIs found in `twilio-python`. Auto-generated,
85+
so only use when you really need to dive deep into the library.
8386

8487
.. toctree::
8588
:maxdepth: 2
@@ -92,11 +95,11 @@ All development occurs over on `Github <https://github.com/twilio/twilio-python>
9295

9396
.. code-block:: bash
9497
95-
git clone git@github.com:twilio/twilio-python.git
98+
$ git clone git@github.com:twilio/twilio-python.git
9699
97100
98101
Report bugs using the Github `issue tracker <https://github.com/twilio/twilio-python/issues>`_.
99102

100-
If you’ve got questions that aren’t answered by this documentation, ask the `#twilio IRC channel <irc://irc.freenode.net/#twilio>`_
103+
If you have questions that aren't answered by this documentation, ask the `#twilio IRC channel <irc://irc.freenode.net/#twilio>`_
101104

102105
See the :doc:`/changelog` for version history.

‎docs/upgrade-guide.rst‎

Lines changed: 26 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Here is how you would place an outgoing call with the older version.
3131
d = {
3232
'From' : CALLER_ID,
3333
'To' : '415-555-1212',
34-
'Url' : 'http://demo.twilio.com/welcome',
34+
'Url' : 'http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient',
3535
}
3636
3737
print account.request('/%s/Accounts/%s/Calls' % \
@@ -53,7 +53,7 @@ The same code, updated to work with the new version (albeit using deprecated met
5353
d = {
5454
'From' : CALLER_ID,
5555
'To' : '415-555-1212',
56-
'Url' : 'http://demo.twilio.com/welcome',
56+
'Url' : 'http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient',
5757
}
5858
5959
print client.request('/%s/Accounts/%s/Calls' % \
@@ -70,15 +70,17 @@ A final version using the new interface.
7070
7171
client = TwilioRestClient(ACCOUNT_SID, ACCOUNT_TOKEN)
7272
call = client.calls.create(from_='NNNNNNNNNN', to='415-555-1212',
73-
url='http://demo.twilio.com/welcome')
73+
url='http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient')
7474
7575
print call
7676
7777
7878
Generating TwiML
7979
=================
8080

81-
:class:`Response` has moved into the :mod:`twiml` module. The `add*` methods have also been deprecated in favor of method names without the 'add' prefix (as shown below).
81+
:class:`Response` has moved into the :mod:`twiml` module. The `add*` methods
82+
have also been deprecated in favor of method names without the 'add' prefix (as
83+
shown below).
8284

8385
Here is how you would craft a response using the old library.
8486

@@ -90,7 +92,7 @@ Here is how you would craft a response using the old library.
9092
r.addSay("Hello World", voice=twilio.Say.MAN, language=twilio.Say.FRENCH,
9193
loop=10)
9294
r.addDial("4155551212", timeLimit=45)
93-
r.addPlay("http://www.mp3.com")
95+
r.addPlay("https://api.twilio.com/cowbell.mp3")
9496
print r
9597
9698
To use the new version, just change the import at the top.
@@ -103,10 +105,11 @@ To use the new version, just change the import at the top.
103105
r.addSay("Hello World", voice=twiml.Say.MAN, language=twiml.Say.FRENCH,
104106
loop=10)
105107
r.addDial("4155551212", timeLimit=45)
106-
r.addPlay("http://www.mp3.com")
108+
r.addPlay("https://api.twilio.com/cowbell.mp3")
107109
print str(r)
108110
109-
The add methods are deprecated and undocumented, so please change them to the new methods. For example, `r.addSay` would become `r.say`.
111+
The add methods are deprecated and undocumented, so please change them to the
112+
new methods. For example, `r.addSay` would become `r.say`.
110113

111114
.. code-block:: python
112115
@@ -117,15 +120,17 @@ The add methods are deprecated and undocumented, so please change them to the ne
117120
r.say("Hello World", voice=twiml.Say.MAN, language=twiml.Say.FRENCH,
118121
loop=10)
119122
r.dial("4155551212", timeLimit=45)
120-
r.play("http://www.mp3.com")
123+
r.play("https://api.twilio.com/cowbell.mp3")
121124
122125
print str(r)
123126
124127
125128
Checking Signatures
126129
=====================
127130

128-
The :class:`Utils` class has been renamed to :class:`TwilioValidation` in the :mod:`twilio.util` module and the :meth:`validateRequest` method has been renamed :meth:`validate`.
131+
The :class:`Utils` class has been renamed to :class:`TwilioValidation` in the
132+
:mod:`twilio.util` module and the :meth:`validateRequest` method has been
133+
renamed :meth:`validate`.
129134

130135
A sample using the old version of **twilio-python**.
131136

@@ -138,10 +143,14 @@ A sample using the old version of **twilio-python**.
138143
139144
utils = twilio.Utils(ACCOUNT_SID, ACCOUNT_TOKEN)
140145
146+
# the callback URL you provided to Twilio for the phone number/app
141147
url = "http://UUUUUUUUUUUUUUUUUU"
148+
149+
the POST variables attached to the request (e.g. "From", "To")
142150
post_vars = {}
143151
144-
signature = "SSSSSSSSSSSSSSSSSSSSSSSSSSSS"
152+
# X-Twilio-Signature header value
153+
signature = "HpS7PBa1Agvt4OtO+wZp75IuQa0=" # will look something like that
145154
146155
if utils.validateRequest(url, post_vars, signature):
147156
print "was confirmed to have come from Twilio."
@@ -158,12 +167,17 @@ The same sample, converted to use the new version.
158167
159168
utils = util.RequestValidator(ACCOUNT_TOKEN)
160169
161-
url = "http://UUUUUUUUUUUUUUUUUU"
170+
# the callback URL you provided to Twilio
171+
url = "http://www.example.com/my/callback/url.xml"
172+
173+
# the POST variables attached to the request (eg "From", "To")
162174
post_vars = {}
163175
164-
signature = "SSSSSSSSSSSSSSSSSSSSSSSSSSSS"
176+
# X-Twilio-Signature header value
177+
signature = "HpS7PBa1Agvt4OtO+wZp75IuQa0=" # will look something like that
165178
166179
if utils.validate(url, post_vars, signature):
167180
print "was confirmed to have come from Twilio."
168181
else:
169182
print "was NOT VALID. It might have been spoofed!"
183+

0 commit comments

Comments
 (0)