You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+98-46
Original file line number
Diff line number
Diff line change
@@ -15,68 +15,101 @@ The Python library documentation can be found [here][libdocs].
15
15
16
16
`twilio-python` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.
17
17
18
-
### Migrating from 5.x
19
-
20
-
Please consult the [official migration guide](https://www.twilio.com/docs/libraries/python/migration-guide) for information on upgrading your application using twilio-python 5.x to 6.x
21
-
22
18
### Supported Python Versions
23
19
24
20
This library supports the following Python implementations:
25
21
26
-
* Python 3.7
27
-
* Python 3.8
28
-
* Python 3.9
29
-
* Python 3.10
30
-
* Python 3.11
22
+
- Python 3.7
23
+
- Python 3.8
24
+
- Python 3.9
25
+
- Python 3.10
26
+
- Python 3.11
31
27
32
28
## Installation
33
29
34
30
Install from PyPi using [pip](https://pip.pypa.io/en/latest/), a
35
31
package manager for Python.
36
32
37
-
pip install twilio
33
+
```shell
34
+
pip3 install twilio
35
+
```
38
36
39
37
If pip install fails on Windows, check the path length of the directory. If it is greater 260 characters then enable [Long Paths](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation) or choose other shorter location.
40
38
41
39
Don't have pip installed? Try installing it, by running this from the command
> If the command line gives you an error message that says Permission Denied, try running the above commands with `sudo` (e.g., `sudo pip3 install twilio`).
51
56
52
-
You may need to run the above commands with `sudo`.
57
+
### Test your installation
53
58
54
-
## Getting Started
59
+
Try sending yourself an SMS message. Save the following code sample to your computer with a text editor. Be sure to update the `account_sid`, `auth_token`, and `from_` phone number with values from your [Twilio account](https://console.twilio.com). The `to` phone number will be your own mobile phone.
55
60
56
-
Getting started with the Twilio API couldn't be easier. Create a
57
-
`Client` and you're ready to go.
61
+
```python
62
+
from twilio.rest import Client
63
+
64
+
# Your Account SID and Auth Token from console.twilio.com
65
+
account_sid ="ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
66
+
auth_token ="your_auth_token"
67
+
68
+
client = Client(account_sid, auth_token)
69
+
70
+
message = client.messages.create(
71
+
to="+15558675309",
72
+
from_="+15017250604",
73
+
body="Hello from Python!")
74
+
75
+
print(message.sid)
76
+
```
77
+
78
+
Save the file as `send_sms.py`. In the terminal, `cd` to the directory containing the file you just saved then run:
79
+
80
+
```shell
81
+
python3 send_sms.py
82
+
```
83
+
84
+
After a brief delay, you will receive the text message on your phone.
85
+
86
+
> **Warning**
87
+
> It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.
88
+
89
+
## Use the helper library
58
90
59
91
### API Credentials
60
92
61
-
The `Twilio` client needs your Twilio credentials. You can either pass these
62
-
directly to the constructor (see the code below) or via environment variables.
93
+
The `Twilio` client needs your Twilio credentials. You can either pass these directly to the constructor (see the code below) or via environment variables.
63
94
64
95
Authenticating with Account SID and Auth Token:
96
+
65
97
```python
66
98
from twilio.rest import Client
67
99
68
-
account_sid ="ACXXXXXXXXXXXXXXXXX"
69
-
auth_token ="YYYYYYYYYYYYYYYYYY"
100
+
account_sid ="ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
101
+
auth_token ="your_auth_token"
70
102
client = Client(account_sid, auth_token)
71
103
```
72
104
73
105
Authenticating with API Key and API Secret:
106
+
74
107
```python
75
108
from twilio.rest import Client
76
109
77
110
api_key ="XXXXXXXXXXXXXXXXX"
78
111
api_secret ="YYYYYYYYYYYYYYYYYY"
79
-
account_sid ="ACXXXXXXXXXXXXXXXXX"
112
+
account_sid ="ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
80
113
client = Client(api_key, api_secret, account_sid)
81
114
```
82
115
@@ -88,7 +121,6 @@ We suggest storing your credentials as environment variables. Why? You'll never
88
121
have to worry about committing your credentials and accidentally posting them
89
122
somewhere public.
90
123
91
-
92
124
```python
93
125
from twilio.rest import Client
94
126
client = Client()
@@ -103,7 +135,8 @@ from twilio.rest import Client
103
135
104
136
client = Client(region='au1', edge='sydney')
105
137
```
106
-
A `Client` constructor without these parameters will also look for `TWILIO_REGION` and `TWILIO_EDGE` variables inside the current environment.
138
+
139
+
A `Client` constructor without these parameters will also look for `TWILIO_REGION` and `TWILIO_EDGE` variables inside the current environment.
107
140
108
141
Alternatively, you may specify the edge and/or region after constructing the Twilio client:
109
142
@@ -122,27 +155,46 @@ This will result in the `hostname` transforming from `api.twilio.com` to `api.sy
The library automatically handles paging for you. Collections, such as `calls` and `messages`, have `list` and `stream` methods that page under the hood. With both `list` and `stream`, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`page_size`). The library will then handle the task for you.
184
+
185
+
`list` eagerly fetches all records and returns them as a list, whereas `stream` returns an iterator and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the `page` method.
186
+
187
+
#### Use the `list` method
188
+
189
+
```python
190
+
from twilio.rest import Client
191
+
192
+
account_sid ="ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
193
+
auth_token ="your_auth_token"
194
+
client = Client(account_sid, auth_token)
195
+
196
+
for sms in client.messages.list():
197
+
print(sms.to)
146
198
```
147
199
148
200
### Asynchronous API Requests
@@ -154,10 +206,10 @@ from twilio.http.async_http_client import AsyncTwilioHttpClient
@@ -172,7 +224,7 @@ Log the API request and response data to the console:
172
224
```python
173
225
import logging
174
226
175
-
client = Client(username, password)
227
+
client = Client(account_sid, auth_token)
176
228
logging.basicConfig()
177
229
client.http_client.logger.setLevel(logging.INFO)
178
230
```
@@ -182,20 +234,22 @@ Log the API request and response data to a file:
182
234
```python
183
235
import logging
184
236
185
-
client = Client(username, password)
237
+
client = Client(account_sid, auth_token)
186
238
logging.basicConfig(filename='./log.txt')
187
239
client.http_client.logger.setLevel(logging.INFO)
188
240
```
189
241
190
242
### Handling Exceptions
191
243
244
+
Version 8.x of `twilio-python` exports an exception class to help you handle exceptions that are specific to Twilio methods. To use it, import `TwilioRestException` and catch exceptions as follows:
245
+
192
246
```python
193
247
from twilio.rest import Client
194
248
from twilio.base.exceptions import TwilioRestException
@@ -204,8 +258,6 @@ except TwilioRestException as e:
204
258
print(e)
205
259
```
206
260
207
-
For more descriptive exception types, please see the [Twilio documentation](https://www.twilio.com/docs/libraries/python/usage-guide#exceptions).
208
-
209
261
### Generating TwiML
210
262
211
263
To control phone calls, your application needs to output [TwiML][twiml].
@@ -225,9 +277,9 @@ print(str(r))
225
277
<Response><Say>Welcome to twilio!</Say></Response>
226
278
```
227
279
228
-
### Using a Custom HTTP Client
280
+
### Other advanced examples
229
281
230
-
To use a custom HTTP client with this helper library, please see the [Twilio documentation](https://www.twilio.com/docs/libraries/python/custom-http-clients-python).
282
+
-[Learn how to create your own custom HTTP client](./advanced-examples/custom-http-client.md)
0 commit comments