OLD | NEW |
| (Empty) |
1 #!/usr/bin/python2.4 | |
2 # | |
3 # Copyright 2014 Google Inc. All Rights Reserved. | |
4 # | |
5 # Licensed under the Apache License, Version 2.0 (the "License"); | |
6 # you may not use this file except in compliance with the License. | |
7 # You may obtain a copy of the License at | |
8 # | |
9 # http://www.apache.org/licenses/LICENSE-2.0 | |
10 # | |
11 # Unless required by applicable law or agreed to in writing, software | |
12 # distributed under the License is distributed on an "AS IS" BASIS, | |
13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
14 # See the License for the specific language governing permissions and | |
15 # limitations under the License. | |
16 | |
17 """Model objects for requests and responses. | |
18 | |
19 Each API may support one or more serializations, such | |
20 as JSON, Atom, etc. The model classes are responsible | |
21 for converting between the wire format and the Python | |
22 object representation. | |
23 """ | |
24 | |
25 __author__ = 'jcgregorio@google.com (Joe Gregorio)' | |
26 | |
27 import json | |
28 import logging | |
29 import urllib | |
30 | |
31 from googleapiclient import __version__ | |
32 from errors import HttpError | |
33 | |
34 | |
35 dump_request_response = False | |
36 | |
37 | |
38 def _abstract(): | |
39 raise NotImplementedError('You need to override this function') | |
40 | |
41 | |
42 class Model(object): | |
43 """Model base class. | |
44 | |
45 All Model classes should implement this interface. | |
46 The Model serializes and de-serializes between a wire | |
47 format such as JSON and a Python object representation. | |
48 """ | |
49 | |
50 def request(self, headers, path_params, query_params, body_value): | |
51 """Updates outgoing requests with a serialized body. | |
52 | |
53 Args: | |
54 headers: dict, request headers | |
55 path_params: dict, parameters that appear in the request path | |
56 query_params: dict, parameters that appear in the query | |
57 body_value: object, the request body as a Python object, which must be | |
58 serializable. | |
59 Returns: | |
60 A tuple of (headers, path_params, query, body) | |
61 | |
62 headers: dict, request headers | |
63 path_params: dict, parameters that appear in the request path | |
64 query: string, query part of the request URI | |
65 body: string, the body serialized in the desired wire format. | |
66 """ | |
67 _abstract() | |
68 | |
69 def response(self, resp, content): | |
70 """Convert the response wire format into a Python object. | |
71 | |
72 Args: | |
73 resp: httplib2.Response, the HTTP response headers and status | |
74 content: string, the body of the HTTP response | |
75 | |
76 Returns: | |
77 The body de-serialized as a Python object. | |
78 | |
79 Raises: | |
80 googleapiclient.errors.HttpError if a non 2xx response is received. | |
81 """ | |
82 _abstract() | |
83 | |
84 | |
85 class BaseModel(Model): | |
86 """Base model class. | |
87 | |
88 Subclasses should provide implementations for the "serialize" and | |
89 "deserialize" methods, as well as values for the following class attributes. | |
90 | |
91 Attributes: | |
92 accept: The value to use for the HTTP Accept header. | |
93 content_type: The value to use for the HTTP Content-type header. | |
94 no_content_response: The value to return when deserializing a 204 "No | |
95 Content" response. | |
96 alt_param: The value to supply as the "alt" query parameter for requests. | |
97 """ | |
98 | |
99 accept = None | |
100 content_type = None | |
101 no_content_response = None | |
102 alt_param = None | |
103 | |
104 def _log_request(self, headers, path_params, query, body): | |
105 """Logs debugging information about the request if requested.""" | |
106 if dump_request_response: | |
107 logging.info('--request-start--') | |
108 logging.info('-headers-start-') | |
109 for h, v in headers.iteritems(): | |
110 logging.info('%s: %s', h, v) | |
111 logging.info('-headers-end-') | |
112 logging.info('-path-parameters-start-') | |
113 for h, v in path_params.iteritems(): | |
114 logging.info('%s: %s', h, v) | |
115 logging.info('-path-parameters-end-') | |
116 logging.info('body: %s', body) | |
117 logging.info('query: %s', query) | |
118 logging.info('--request-end--') | |
119 | |
120 def request(self, headers, path_params, query_params, body_value): | |
121 """Updates outgoing requests with a serialized body. | |
122 | |
123 Args: | |
124 headers: dict, request headers | |
125 path_params: dict, parameters that appear in the request path | |
126 query_params: dict, parameters that appear in the query | |
127 body_value: object, the request body as a Python object, which must be | |
128 serializable by json. | |
129 Returns: | |
130 A tuple of (headers, path_params, query, body) | |
131 | |
132 headers: dict, request headers | |
133 path_params: dict, parameters that appear in the request path | |
134 query: string, query part of the request URI | |
135 body: string, the body serialized as JSON | |
136 """ | |
137 query = self._build_query(query_params) | |
138 headers['accept'] = self.accept | |
139 headers['accept-encoding'] = 'gzip, deflate' | |
140 if 'user-agent' in headers: | |
141 headers['user-agent'] += ' ' | |
142 else: | |
143 headers['user-agent'] = '' | |
144 headers['user-agent'] += 'google-api-python-client/%s (gzip)' % __version__ | |
145 | |
146 if body_value is not None: | |
147 headers['content-type'] = self.content_type | |
148 body_value = self.serialize(body_value) | |
149 self._log_request(headers, path_params, query, body_value) | |
150 return (headers, path_params, query, body_value) | |
151 | |
152 def _build_query(self, params): | |
153 """Builds a query string. | |
154 | |
155 Args: | |
156 params: dict, the query parameters | |
157 | |
158 Returns: | |
159 The query parameters properly encoded into an HTTP URI query string. | |
160 """ | |
161 if self.alt_param is not None: | |
162 params.update({'alt': self.alt_param}) | |
163 astuples = [] | |
164 for key, value in params.iteritems(): | |
165 if type(value) == type([]): | |
166 for x in value: | |
167 x = x.encode('utf-8') | |
168 astuples.append((key, x)) | |
169 else: | |
170 if getattr(value, 'encode', False) and callable(value.encode): | |
171 value = value.encode('utf-8') | |
172 astuples.append((key, value)) | |
173 return '?' + urllib.urlencode(astuples) | |
174 | |
175 def _log_response(self, resp, content): | |
176 """Logs debugging information about the response if requested.""" | |
177 if dump_request_response: | |
178 logging.info('--response-start--') | |
179 for h, v in resp.iteritems(): | |
180 logging.info('%s: %s', h, v) | |
181 if content: | |
182 logging.info(content) | |
183 logging.info('--response-end--') | |
184 | |
185 def response(self, resp, content): | |
186 """Convert the response wire format into a Python object. | |
187 | |
188 Args: | |
189 resp: httplib2.Response, the HTTP response headers and status | |
190 content: string, the body of the HTTP response | |
191 | |
192 Returns: | |
193 The body de-serialized as a Python object. | |
194 | |
195 Raises: | |
196 googleapiclient.errors.HttpError if a non 2xx response is received. | |
197 """ | |
198 self._log_response(resp, content) | |
199 # Error handling is TBD, for example, do we retry | |
200 # for some operation/error combinations? | |
201 if resp.status < 300: | |
202 if resp.status == 204: | |
203 # A 204: No Content response should be treated differently | |
204 # to all the other success states | |
205 return self.no_content_response | |
206 return self.deserialize(content) | |
207 else: | |
208 logging.debug('Content from bad request was: %s' % content) | |
209 raise HttpError(resp, content) | |
210 | |
211 def serialize(self, body_value): | |
212 """Perform the actual Python object serialization. | |
213 | |
214 Args: | |
215 body_value: object, the request body as a Python object. | |
216 | |
217 Returns: | |
218 string, the body in serialized form. | |
219 """ | |
220 _abstract() | |
221 | |
222 def deserialize(self, content): | |
223 """Perform the actual deserialization from response string to Python | |
224 object. | |
225 | |
226 Args: | |
227 content: string, the body of the HTTP response | |
228 | |
229 Returns: | |
230 The body de-serialized as a Python object. | |
231 """ | |
232 _abstract() | |
233 | |
234 | |
235 class JsonModel(BaseModel): | |
236 """Model class for JSON. | |
237 | |
238 Serializes and de-serializes between JSON and the Python | |
239 object representation of HTTP request and response bodies. | |
240 """ | |
241 accept = 'application/json' | |
242 content_type = 'application/json' | |
243 alt_param = 'json' | |
244 | |
245 def __init__(self, data_wrapper=False): | |
246 """Construct a JsonModel. | |
247 | |
248 Args: | |
249 data_wrapper: boolean, wrap requests and responses in a data wrapper | |
250 """ | |
251 self._data_wrapper = data_wrapper | |
252 | |
253 def serialize(self, body_value): | |
254 if (isinstance(body_value, dict) and 'data' not in body_value and | |
255 self._data_wrapper): | |
256 body_value = {'data': body_value} | |
257 return json.dumps(body_value) | |
258 | |
259 def deserialize(self, content): | |
260 content = content.decode('utf-8') | |
261 body = json.loads(content) | |
262 if self._data_wrapper and isinstance(body, dict) and 'data' in body: | |
263 body = body['data'] | |
264 return body | |
265 | |
266 @property | |
267 def no_content_response(self): | |
268 return {} | |
269 | |
270 | |
271 class RawModel(JsonModel): | |
272 """Model class for requests that don't return JSON. | |
273 | |
274 Serializes and de-serializes between JSON and the Python | |
275 object representation of HTTP request, and returns the raw bytes | |
276 of the response body. | |
277 """ | |
278 accept = '*/*' | |
279 content_type = 'application/json' | |
280 alt_param = None | |
281 | |
282 def deserialize(self, content): | |
283 return content | |
284 | |
285 @property | |
286 def no_content_response(self): | |
287 return '' | |
288 | |
289 | |
290 class MediaModel(JsonModel): | |
291 """Model class for requests that return Media. | |
292 | |
293 Serializes and de-serializes between JSON and the Python | |
294 object representation of HTTP request, and returns the raw bytes | |
295 of the response body. | |
296 """ | |
297 accept = '*/*' | |
298 content_type = 'application/json' | |
299 alt_param = 'media' | |
300 | |
301 def deserialize(self, content): | |
302 return content | |
303 | |
304 @property | |
305 def no_content_response(self): | |
306 return '' | |
307 | |
308 | |
309 class ProtocolBufferModel(BaseModel): | |
310 """Model class for protocol buffers. | |
311 | |
312 Serializes and de-serializes the binary protocol buffer sent in the HTTP | |
313 request and response bodies. | |
314 """ | |
315 accept = 'application/x-protobuf' | |
316 content_type = 'application/x-protobuf' | |
317 alt_param = 'proto' | |
318 | |
319 def __init__(self, protocol_buffer): | |
320 """Constructs a ProtocolBufferModel. | |
321 | |
322 The serialzed protocol buffer returned in an HTTP response will be | |
323 de-serialized using the given protocol buffer class. | |
324 | |
325 Args: | |
326 protocol_buffer: The protocol buffer class used to de-serialize a | |
327 response from the API. | |
328 """ | |
329 self._protocol_buffer = protocol_buffer | |
330 | |
331 def serialize(self, body_value): | |
332 return body_value.SerializeToString() | |
333 | |
334 def deserialize(self, content): | |
335 return self._protocol_buffer.FromString(content) | |
336 | |
337 @property | |
338 def no_content_response(self): | |
339 return self._protocol_buffer() | |
340 | |
341 | |
342 def makepatch(original, modified): | |
343 """Create a patch object. | |
344 | |
345 Some methods support PATCH, an efficient way to send updates to a resource. | |
346 This method allows the easy construction of patch bodies by looking at the | |
347 differences between a resource before and after it was modified. | |
348 | |
349 Args: | |
350 original: object, the original deserialized resource | |
351 modified: object, the modified deserialized resource | |
352 Returns: | |
353 An object that contains only the changes from original to modified, in a | |
354 form suitable to pass to a PATCH method. | |
355 | |
356 Example usage: | |
357 item = service.activities().get(postid=postid, userid=userid).execute() | |
358 original = copy.deepcopy(item) | |
359 item['object']['content'] = 'This is updated.' | |
360 service.activities.patch(postid=postid, userid=userid, | |
361 body=makepatch(original, item)).execute() | |
362 """ | |
363 patch = {} | |
364 for key, original_value in original.iteritems(): | |
365 modified_value = modified.get(key, None) | |
366 if modified_value is None: | |
367 # Use None to signal that the element is deleted | |
368 patch[key] = None | |
369 elif original_value != modified_value: | |
370 if type(original_value) == type({}): | |
371 # Recursively descend objects | |
372 patch[key] = makepatch(original_value, modified_value) | |
373 else: | |
374 # In the case of simple types or arrays we just replace | |
375 patch[key] = modified_value | |
376 else: | |
377 # Don't add anything to patch if there's no change | |
378 pass | |
379 for key in modified: | |
380 if key not in original: | |
381 patch[key] = modified[key] | |
382 | |
383 return patch | |
OLD | NEW |