10000 Document `version.py` · raghav7997/twilio-python@65e3def · GitHub
[go: up one dir, main page]
Skip to content

Commit 65e3def

Browse files
author
Doug Black
committed
Document version.py 
1 parent 43161b8 commit 65e3def

File tree

1 file changed

+47
-1
lines changed

1 file changed

+47
-1
lines changed

‎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