8000 numerous clarification changes to our documentation. · michaelhelmick/twilio-python@b2629da · GitHub
[go: up one dir, main page]

Skip to content 8000

Commit b2629da

Browse files
author
Kevin Burke
committed
numerous clarification changes to our documentation.
these come from user testing results, which indicated the following: - beginning python developers had no idea how to install pip - the environment method of storing credentials is confusing - other python developers don't know how to run python setup.py install.
1 parent 86729ec commit b2629da

14 files changed

+318
-99
lines changed

README.md

Lines changed: 49 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,34 @@
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 TwiML. [Check out
2+
the full documentation](http://readthedocs.org/docs/twilio-python/en/latest/
3+
"Twilio Python library documentation")
24

35
## Installation
46

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

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

923
## Getting Started
1024

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

1328
### API Credentials
1429

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.
30+
The `TwilioRestClient` needs your Twilio credentials. You can either pass these
31+
directly to the constructor (see the code below) or via environment variables.
1832

1933
```python
2034
from twilio.rest import TwilioRestClient
@@ -24,14 +38,21 @@ token = "YYYYYYYYYYYYYYYYYY"
2438
client = TwilioRestClient(account, token)
2539
```
2640

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

2950
```python
3051
from twilio.rest import TwilioRestClient
3152
client = TwilioRestClient()
3253
```
3354

34-
### Making a Call
55+
### Make a Call
3556

3657
```python
3758
from twilio.rest import TwilioRestClient
@@ -40,14 +61,27 @@ account = "AXXXXXXXXXXXXXXXXX"
4061
token = "YYYYYYYYYYYYYYYYYY"
4162
client = TwilioRestClient(account, token)
4263

43-
call = client.calls.create(to="9991231234", from_="9991231234", url="http://foo.com/call.xml")
64+
call = client.calls.create(to="9991231234",
65+
from_="9991231234",
66+
url="http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
4467
print call.sid
4568
```
4669

70+
### Send an SMS
71+
from twilio.rest import TwilioRestClient
72+
73+
account = "AXXXXXXXXXXXXXXXXX"
74+
token = "YYYYYYYYYYYYYYYYYY"
75+
client = TwilioRestClient(account, token)
76+
77+
message = client.sms.messages.create(to="+12316851234", from_="+15555555555",
78+
body="Hello there!")
4779

4880
### Handling a call using TwiML
4981

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

5286
```python
5387
from twilio import twiml
@@ -64,4 +98,7 @@ print str(r)
6498

6599
### Digging Deeper
66100

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.
101+
The full power of the Twilio API is at your fingertips. The [full
102+
documentation](http://readthedocs.org/docs/twilio-python/en/latest/ "Twilio
103+
Python library documentation") explains
104+
all the awesome features available to use.

docs/getting-started.rst

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@ Making a Call
2424
Generating TwiML
2525
=================
2626

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

2931
.. code-block:: python
3032
@@ -42,10 +44,6 @@ To control phone calls, your application needs to output TwiML. Use :class:`twil
4244
Digging Deeper
4345
========================
4446

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-
47+
The full power of the Twilio API is at your fingertips. The :ref:`user-guide`
48+
explains all the awesome features available to use.
5149

docs/index.rst

Lines changed: 9 additions & 6 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
1616
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 arent 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/usage/accounts.rst

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,12 @@ Use the :meth:`Account.update` to modify one of your accounts. Right now the onl
1818
1919
from twilio.rest import TwilioRestClient
2020
21-
conn = TwilioRestClient()
22-
account = conn.accounts.get()
21+
# To find these visit https://www.twilio.com/user/account
22+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
23+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
24+
25+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
26+
account = client.accounts.get()
2327
account.update(name="My Awesome Account")
2428
2529
Creating Subaccounts
@@ -31,8 +35,12 @@ Subaccounts are easy to make.
3135
3236
from twilio.rest import TwilioRestClient
3337
34-
conn = TwilioRestClient()
35-
subaccount = conn.accounts.create(name="My Awesome SubAccount")
38+
# To find these visit https://www.twilio.com/user/account
39+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
40+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
41+
42+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
43+
subaccount = client.accounts.create(name="My Awesome SubAccount")
3644
3745
Managing Subaccounts
3846
-------------------------
@@ -43,10 +51,14 @@ Say you have a subaccount for Client X with an account sid `AC123`
4351
4452
from twilio.rest import TwilioRestClient
4553
46-
conn = TwilioRestClient()
54+
# To find these visit https://www.twilio.com/user/account
55+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
56+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
57+
58+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
4759
4860
# Client X's subaccount
49-
subaccount = conn.accounts.get('AC123')
61+
subaccount = client.accounts.get('AC123')
5062
5163
Client X hasn't paid you recently, so let's suspend their account.
5264

@@ -63,13 +75,9 @@ If it was just a misunderstanding, reenable their account.
6375
Otherwise, close their account permanently.
6476

6577
.. warning::
66-
This action can't be undone. Be careful
78+
This action can't be undone.
6779

6880
.. code-block:: python
6981
7082
subaccount.close()
7183
72-
73-
74-
75-

docs/usage/applications.rst

Lines changed: 31 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,12 @@ The following code will print out the :attr:`friendly_name` for each :class:`App
1717
1818
from twilio.rest import TwilioRestClient
1919
20-
conn = TwilioRestClient()
21-
for app in conn.applications.list():
20+
# To find these visit https://www.twilio.com/user/account
21+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
22+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
23+
24+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
25+
for app in client.applications.list():
2226
print app.friendly_name
2327
2428
@@ -31,8 +35,12 @@ You can filter applications by FriendlyName
3135
3236
from twilio.rest import TwilioRestClient
3337
34-
conn = TwilioRestClient()
35-
for app in conn.applications.list(friendly_name="FOO"):
38+
# To find these visit https://www.twilio.com/user/account
39+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
40+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
41+
42+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
43+
for app in client.applications.list(friendly_name="FOO"):
3644
print app.sid
3745
3846
Creating an Application
@@ -44,8 +52,12 @@ When creating an application, no fields are required. We create an application w
4452
4553
from twilio.rest import TwilioRestClient
4654
47-
conn = TwilioRestClient()
48-
application = conn.applications.create(friendly_name="My New App")
55+
# To find these visit https://www.twilio.com/user/account
56+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
57+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
58+
59+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
60+
application = client.applications.create(friendly_name="My New App")
4961
5062
5163
Updating an Application
@@ -55,9 +67,13 @@ Updating an Application
5567
5668
from twilio.rest import TwilioRestClient
5769
58-
conn = TwilioRestClient()
59-
url = "http://www.example.com/twiml.xml"
60-
application = conn.applications.update(app_sid, voice_url=url)
70+
# To find these visit https://www.twilio.com/user/account
71+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
72+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
73+
74+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
75+
url = "http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient"
76+
application = client.applications.update(app_sid, voice_url=url)
6177
6278
6379
Deleting an Application
@@ -67,5 +83,9 @@ Deleting an Application
6783
6884
from twilio.rest import TwilioRestClient
6985
70-
conn = TwilioRestClient()
71-
conn.applications.delete(app_sid)
86+
# To find these visit https://www.twilio.com/user/account
87+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
88+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
89+
90+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
91+
client.applications.delete(app_sid)

docs/usage/basics.rst

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,10 @@ To access Twilio REST resources, you'll first need to instantiate a :class:`Twil
99
Authentication
1010
--------------------------
1111

12-
The :class:`TwilioRestClient` needs your Twilio credentials. While these can be passed in directly to the constructor, 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.
12+
The :class:`TwilioRestClient` needs your Twilio credentials. While these can be
13+
passed in directly to the constructor, we suggest storing your credentials as
14+
environment variables. Why? You'll never have to worry about committing your
15+
credentials and accidentally posting them somewhere public.
1316

1417
The :class:`TwilioRestClient` looks for :const:`TWILIO_ACCOUNT_SID` and :const:`TWILIO_AUTH_TOKEN` inside the current environment.
1518

@@ -21,7 +24,8 @@ With those two values set, create a new :class:`TwilioClient`.
2124
2225
conn = TwilioRestClient()
2326
24-
If you'd rather not use environment variables, pass your account credentials directly to the the constructor.
27+
If you'd rather not use environment variables, pass your account credentials
28+
directly to the the constructor.
2529

2630
.. code-block:: python
2731
@@ -41,7 +45,11 @@ The :class:`TwilioRestClient` gives you access to various list resources. :meth:
4145
4246
from twilio.rest import TwilioRestClient
4347
44-
client = TwilioRestClient()
48+
# To find these visit https://www.twilio.com/user/account
49+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
50+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
51+
52+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
4553
resources = client.phone_calls.list()
4654
4755
:meth:`resource.ListResource.list` accepts paging arguments. The following will return page 3 with page size of 25.
@@ -50,7 +58,11 @@ The :class:`TwilioRestClient` gives you access to various list resources. :meth:
5058
5159
from twilio.rest import TwilioRestClient
5260
53-
client = TwilioRestClient()
61+
# To find these visit https://www.twilio.com/user/account
62+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
63+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
64+
65+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
5466
resources = client.phone_calls.list(page=3, page_size=25)
5567
5668
@@ -65,7 +77,11 @@ Sometimes you'd like to retrieve all records from a list resource. Instead of ma
6577
6678
from twilio.rest import TwilioRestClient
6779
68-
client = TwilioRestClient()
80+
# To find these visit https://www.twilio.com/user/account
81+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
82+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
83+
84+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
6985
for number in client.phone_numbers.iter():
7086
print number.friendly_name
7187
@@ -79,7 +95,11 @@ To get an individual instance resource, use :class:`resources.ListResource.get`.
7995
8096
from twilio.rest import TwilioRestClient
8197
82-
client = TwilioRestClient()
98+
# To find these visit https://www.twilio.com/user/account
99+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
100+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
101+
102+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
83103
84104
call = client.calls.get("CA123")
85105
print call.sid

0 commit comments

Comments
 (0)
0