8000 Merge pull request #314 from twilio/docs-and-style · jstacoder/twilio-python@b69555b · GitHub
[go: up one dir, main page]
Skip to content

Commit b69555b

Browse files
jingmingjingming
authored
Merge pull request twilio#314 from twilio/docs-and-style
Docs and style
2 parents ca97ade + eaa8cbf commit b69555b

File tree

10 files changed

+138
-29
lines changed

10 files changed

+138
-29
lines changed

‎twilio/compat.py

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,3 @@
1515
except ImportError:
1616
# python 3
1717
izip = zip
18-

‎twilio/domain.py

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
class Domain(object):
2+
"""
3+
This represents at Twilio API subdomain.
4+
5+
Like, `api.twilio.com` or `lookups.twilio.com'.
6+
"""
27
def __init__(self, twilio):
38
"""
49
:param Twilio twilio:
@@ -8,10 +13,27 @@ def __init__(self, twilio):
813
self.base_url = None
914

1015
def absolute_url(self, uri):
16+
"""
17+
Converts a relative `uri` to an absolute url.
18+
:param string uri: The relative uri to make absolute.
19+
:return: An absolute url (based off this domain)
20+
"""
1121
return '{}/{}'.format(self.base_url.strip('/'), uri.strip('/'))
1222

1323
def request(self, method, uri, params=None, data=None, headers=None,
1424
auth=None, timeout=None, allow_redirects=False):
25+
"""
26+
Makes an HTTP request to this domain.
27+
:param string method: The HTTP method.
28+
:param string uri: The HTTP uri.
29+
:param dict params: Query parameters.
30+
:param object data: The request body.
31+
:param dict headers: The HTTP headers.
32+
:param tuple auth: Basic auth tuple of (username, password)
33+
:param int timeout: The request timeout.
34+
:param bool allow_redirects: True if the client should follow HTTP
35+
redirects.
36+
"""
1537
url = self.absolute_url(uri)
1638
return self.twilio.request(
1739
method,

‎twilio/http/__init__.py

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,12 @@ def get_cert_file():
2020

2121

2222
class HttpClient(object):
23-
def request(self,
24-
method,
25-
url,
26-
params=None,
27-
data=None,
28-
headers=None,
29-
auth=None,
30-
timeout=None,
31-
allow_redirects=False):
23+
"""
24+
An abstract class representing an HTTP client.
25+
"""
26+
def request(self, method, url, params=None, data=None, headers=None, auth=None,
27+
timeout=None, allow_redirects=False):
28+
"""
29+
Make an HTTP request.
30+
"""
3231
raise TwilioException('HttpClient is an abstract class')

‎twilio/http/debug.py

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,19 @@
33

44

55
class DebugClient(HttpClient):
6+
"""
7+
A `DebugClient` can be used to print out requests before sending them out.
8+
"""
69
def __init__(self, client):
710
super(DebugClient, self).__init__()
811
self._client = client
912

10-
def request(self,
11-
method,
12-
url,
13-
params=None,
14-
data=None,
15-
headers=None,
16-
auth=None,
13+
def request(self, method, url, params=None, data=None, headers=None, auth=None,
1714
timeout=None,
1815
allow_redirects=False):
16+
"""
17+
Make an HTTP request.
18+
"""
1919
req = Request(method=method, url=url, auth=auth, params=params, data=data, headers=headers)
2020
print(req)
2121
return self._client.request(

‎twilio/http/http_client.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55

66

77
class TwilioHttpClient(HttpClient):
8-
"""General purpose HTTP Client for interacting with the Twilio API"""
8+
"""
9+
General purpose HTTP Client for interacting with the Twilio API
10+
"""
911
def request(self, method, url, params=None, data=None, headers=None, auth=None, timeout=None,
1012
allow_redirects=False):
1113
"""

‎twilio/http/request.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33

44
class Request(object):
5+
"""
6+
An HTTP request.
7+
"""
58
ANY = '*'
69

710
def __init__(self,
@@ -71,4 +74,3 @@ def __str__(self):
7174

7275
def __repr__(self):
7376
return str(self)
74-

‎twilio/page.py

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,12 @@
33

44

55
class Page(object):
6+
"""
7+
Represents a page of records in a collection.
8+
9+
A `Page` lets you iterate over its records and fetch the next and previous
10+
pages in the collection.
11+
"""
612
META_KEYS = {
713
'end',
814
'first_page_uri',
@@ -26,22 +32,40 @@ def __init__(self, version, response):
2632
self._records = iter(self.load_page(payload))
2733

2834
def __iter__(self):
35+
"""
36+
A `Page` is a valid iterator.
37+
"""
2938
return self
3039

3140
def __next__(self):
3241
return self.next()
3342

3443
def next(self):
44+
"""
45+
Returns the next record in the `Page`.
46+
"""
3547
return self.get_instance(next(self._records))
3648

3749
@classmethod
3850
def process_response(self, response):
51+
"""
52+
Load a JSON response.
53+
54+
:param Response response: The HTTP response.
55+
:return dict: The JSON-loaded content.
56+
"""
3957
if response.status_code != 200:
4058
raise TwilioException('Unable to fetch page', response)
4159

4260
return json.loads(response.content)
4361

4462
def load_page(self, payload):
63+
"""
64+
Parses the collection of records out of a list payload.
65+
66+
:param dict payload: The JSON-loaded content.
67+
:return list: The list of records.
68+
"""
4569
if 'meta' in payload and 'key' in payload['meta']:
4670
return payload[payload['meta']['key']]
4771
else:
@@ -54,6 +78,9 @@ def load_page(self, payload):
5478

5579
@property
5680
def previous_page_url(self):
81+
"""
82+
:return str: Returns a link to the previous_page_url or None if doesn't exist.
83+
"""
5784
if 'meta' in self._payload and 'previous_page_url' in self._payload['meta']:
5885
return self._payload['meta']['previous_page_url']
5986
elif 'previous_page_uri' in self._payload and self._payload['previous_page_uri']:
@@ -63,6 +90,9 @@ def previous_page_url(self):
6390

6491
@property
6592
def next_page_url(self):
93+
"""
94+
:return str: Returns a link to the next_page_url or None if doesn't exist.
95+
"""
6696
if 'meta' in self._payload and 'next_page_url' in self._payload['meta']:
6797
return self._payload['meta']['next_page_url']
6898
elif 'next_page_uri' in self._payload and self._payload['next_page_uri']:
@@ -71,9 +101,17 @@ def next_page_url(self):
71101
return None
72102

73103
def get_instance(self, payload):
104+
"""
105+
:param dict payload: A JSON-loaded representation of an instance record.
106+
:return: A rich, resource-dependent object.
107+
"""
74108
raise TwilioException('Page.get_instance() must be implemented in the derived class')
75109

76110
def next_page(self):
111+
"""
112+
Return the `Page` after this one.
113+
:return Page: The next page.
114+
"""
77115
if not self.next_page_url:
78116
return None
79117

@@ -82,6 +120,10 @@ def next_page(self):
82120
return cls(self._version, response, self._solution)
83121

84122
def previous_page(self):
123+
"""
124+
Return the `Page` before this one.
125+
:return Page: The previous page.
126+
"""
85127
if not self.previous_page_url:
86128
return None
87129

@@ -91,4 +133,3 @@ def previous_page(self):
91133

92134
def __repr__(self):
93135
return '<Page>'
94-

‎twilio/security.py

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -61,10 +61,3 @@ def validate(self, uri, params, signature):
6161
:returns: True if the request passes validation, False if not
6262
"""
6363
return compare(self.compute_signature(uri, params), signature)
64-
65-
66-
67-
68-
69-
70-

‎twilio/values.py

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,10 @@
33

44

55
def of(d):
6-
return {k: v for k, v in iteritems(d) if v != unset}
6+
"""
7+
Remove unset values from a dict.
78
9+
:param dict d: A dict to strip.
10+
:return dict: A dict with unset values removed.
11+
"""
12+
return {k: v for k, v in iteritems(d) if v != unset}

‎twilio/version.py

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66

77

88
class Version(object):
9+
"""
10+
Represents an API version.
11+
"""
912
MAX_PAGE_SIZE = 1000
1013

1114
def __init__(self, domain):
@@ -17,13 +20,22 @@ def __init__(self, domain):
1720
self.version = None
1821

1922
def absolute_url(self, uri):
23+
"""
24+
Turns a relative uri into an absolute url.
25+
"""
2026
return self.domain.absolute_url(self.relative_uri(uri))
2127

2228
def relative_uri(self, uri):
29+
"""
30+
Turns a relative uri into a versioned relative uri.
31+
"""
2332
return '{}/{}'.format(self.version.strip('/'), uri.strip('/'))
2433

2534
def request(self, method, uri, params=None, data=None, headers=None,
2635
auth=None, timeout=None, allow_redirects=False):
36+
"""
37+
Make an HTTP request.
38+
"""
2739
url = self.relative_uri(uri)
2840
return self.domain.request(
2941
method,
@@ -38,6 +50,9 @@ def request(self, method, uri, params=None, data=None, headers=None,
3850

3951
@classmethod
4052
def exception(cls, method, uri, response, message):
53+
"""
54+
Wraps an exceptional response in a `TwilioRestException`.
55+
"""
4156
# noinspection PyBroadException
4257
try:
4358
error_payload = json.loads(response.content)
@@ -50,6 +65,9 @@ def exception(cls, method, uri, response, message):
5065

5166
def fetch(self, method, uri, params=None, data=None, headers=None, auth=None, timeout=None,
5267
allow_redirects=False):
68+
"""
69+
Fetch a resource instance.
70+
"""
5371
response = self.request(
5472
method,
5573
uri,
@@ -68,6 +86,9 @@ def fetch(self, method, uri, params=None, data=None, headers=None, auth=None, ti
6886

6987
def update(self, method, uri, params=None, data=None, headers=None, auth=None, timeout=None,
7088
allow_redirects=False):
89+
"""
90+
Update a resource instance.
91+
"""
7192
response = self.request(
7293
method,
7394
uri,
@@ -86,6 +107,9 @@ def update(self, method, uri, params=None, data=None, headers=None, auth=None, t
86107

87108
def delete(self, method, uri, params=None, data=None, headers=None, auth=None, timeout=None,
88109
allow_redirects=False):
110+
"""
111+
Delete a resource.
112+
"""
89113
response = self.request(
90114
method,
91115
uri,
@@ -103,12 +127,21 @@ def delete(self, method, uri, params=None, data=None, headers=None, auth=None, t
103127
return response.status_code == 204
104128

105129
def read_limits(self, limit=None, page_size=None):
130+
"""
131+
Takes a limit on the max number of records to read and a max page_size
132+
and calculates the max number of pages to read.
133+
134+
:param int limit: Max number of records to read.
135+
:param int page_size: Max page size.
136+
:return dict: A dictionary of paging limits.
137+
"""
106138
page_limit = values.unset
107139

108140
if limit is not None:
109141

110142
if page_size is None:
111-
# If there is no user-specified page_size, pick the most network efficient size
143+
# If there is no user-specified page_size, pick the most
144+
# network efficient size
112145
page_size = min(limit, self.MAX_PAGE_SIZE)
113146

114147
page_limit = int(ceil(limit / float(page_size)))
@@ -121,6 +154,9 @@ def read_limits(self, limit=None, page_size=None):
121154

122155
def page(self, method, uri, params=None, data=None, headers=None, auth=None, timeout=None,
123156
allow_redirects=False):
157+
"""
158+
Makes an HTTP request.
159+
"""
124160
return self.request(
125161
method,
126162
uri,
@@ -133,6 +169,13 @@ def page(self, method, uri, params=None, data=None, headers=None, auth=None, tim
133169
)
134170

135171
def stream(self, page, limit=None, page_limit=None):
172+
"""
173+
Generates records one a time from a page, stopping at prescribed limits.
174+
175+
:param Page page: The page to stream.
176+
:param int limit: The max number of records to read.
177+
:param int page_imit: The max number of pages to read.
178+
"""
136179
current_record = 1
137180
current_page = 1
138181

@@ -151,6 +194,9 @@ def stream(self, page, limit=None, page_limit=None):
151194

152195
def create(self, method, uri, params=None, data=None, headers=None, auth=None, timeout=None,
153196
allow_redirects=False):
197+
"""
198+
Create a resource instance.
199+
"""
154200
response = self.request(
155201
method,
156202
uri,

0 commit comments

Comments
 (0)
0