OLD | NEW |
| (Empty) |
1 # Copyright 2014 Google Inc. All Rights Reserved. | |
2 # | |
3 # Licensed under the Apache License, Version 2.0 (the "License"); | |
4 # you may not use this file except in compliance with the License. | |
5 # You may obtain a copy of the License at | |
6 # | |
7 # http://www.apache.org/licenses/LICENSE-2.0 | |
8 # | |
9 # Unless required by applicable law or agreed to in writing, software | |
10 # distributed under the License is distributed on an "AS IS" BASIS, | |
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
12 # See the License for the specific language governing permissions and | |
13 # limitations under the License. | |
14 | |
15 """Client for discovery based APIs. | |
16 | |
17 A client library for Google's discovery based APIs. | |
18 """ | |
19 | |
20 __author__ = 'jcgregorio@google.com (Joe Gregorio)' | |
21 __all__ = [ | |
22 'build', | |
23 'build_from_document', | |
24 'fix_method_name', | |
25 'key2param', | |
26 ] | |
27 | |
28 | |
29 # Standard library imports | |
30 import StringIO | |
31 import copy | |
32 from email.generator import Generator | |
33 from email.mime.multipart import MIMEMultipart | |
34 from email.mime.nonmultipart import MIMENonMultipart | |
35 import json | |
36 import keyword | |
37 import logging | |
38 import mimetypes | |
39 import os | |
40 import re | |
41 import urllib | |
42 import urlparse | |
43 | |
44 try: | |
45 from urlparse import parse_qsl | |
46 except ImportError: | |
47 from cgi import parse_qsl | |
48 | |
49 # Third-party imports | |
50 from ... import httplib2 | |
51 import mimeparse | |
52 from ... import uritemplate | |
53 | |
54 # Local imports | |
55 from googleapiclient.errors import HttpError | |
56 from googleapiclient.errors import InvalidJsonError | |
57 from googleapiclient.errors import MediaUploadSizeError | |
58 from googleapiclient.errors import UnacceptableMimeTypeError | |
59 from googleapiclient.errors import UnknownApiNameOrVersion | |
60 from googleapiclient.errors import UnknownFileType | |
61 from googleapiclient.http import HttpRequest | |
62 from googleapiclient.http import MediaFileUpload | |
63 from googleapiclient.http import MediaUpload | |
64 from googleapiclient.model import JsonModel | |
65 from googleapiclient.model import MediaModel | |
66 from googleapiclient.model import RawModel | |
67 from googleapiclient.schema import Schemas | |
68 from oauth2client.client import GoogleCredentials | |
69 from oauth2client.util import _add_query_parameter | |
70 from oauth2client.util import positional | |
71 | |
72 | |
73 # The client library requires a version of httplib2 that supports RETRIES. | |
74 httplib2.RETRIES = 1 | |
75 | |
76 logger = logging.getLogger(__name__) | |
77 | |
78 URITEMPLATE = re.compile('{[^}]*}') | |
79 VARNAME = re.compile('[a-zA-Z0-9_-]+') | |
80 DISCOVERY_URI = ('https://www.googleapis.com/discovery/v1/apis/' | |
81 '{api}/{apiVersion}/rest') | |
82 DEFAULT_METHOD_DOC = 'A description of how to use this function' | |
83 HTTP_PAYLOAD_METHODS = frozenset(['PUT', 'POST', 'PATCH']) | |
84 _MEDIA_SIZE_BIT_SHIFTS = {'KB': 10, 'MB': 20, 'GB': 30, 'TB': 40} | |
85 BODY_PARAMETER_DEFAULT_VALUE = { | |
86 'description': 'The request body.', | |
87 'type': 'object', | |
88 'required': True, | |
89 } | |
90 MEDIA_BODY_PARAMETER_DEFAULT_VALUE = { | |
91 'description': ('The filename of the media request body, or an instance ' | |
92 'of a MediaUpload object.'), | |
93 'type': 'string', | |
94 'required': False, | |
95 } | |
96 | |
97 # Parameters accepted by the stack, but not visible via discovery. | |
98 # TODO(dhermes): Remove 'userip' in 'v2'. | |
99 STACK_QUERY_PARAMETERS = frozenset(['trace', 'pp', 'userip', 'strict']) | |
100 STACK_QUERY_PARAMETER_DEFAULT_VALUE = {'type': 'string', 'location': 'query'} | |
101 | |
102 # Library-specific reserved words beyond Python keywords. | |
103 RESERVED_WORDS = frozenset(['body']) | |
104 | |
105 | |
106 def fix_method_name(name): | |
107 """Fix method names to avoid reserved word conflicts. | |
108 | |
109 Args: | |
110 name: string, method name. | |
111 | |
112 Returns: | |
113 The name with a '_' prefixed if the name is a reserved word. | |
114 """ | |
115 if keyword.iskeyword(name) or name in RESERVED_WORDS: | |
116 return name + '_' | |
117 else: | |
118 return name | |
119 | |
120 | |
121 def key2param(key): | |
122 """Converts key names into parameter names. | |
123 | |
124 For example, converting "max-results" -> "max_results" | |
125 | |
126 Args: | |
127 key: string, the method key name. | |
128 | |
129 Returns: | |
130 A safe method name based on the key name. | |
131 """ | |
132 result = [] | |
133 key = list(key) | |
134 if not key[0].isalpha(): | |
135 result.append('x') | |
136 for c in key: | |
137 if c.isalnum(): | |
138 result.append(c) | |
139 else: | |
140 result.append('_') | |
141 | |
142 return ''.join(result) | |
143 | |
144 | |
145 @positional(2) | |
146 def build(serviceName, | |
147 version, | |
148 http=None, | |
149 discoveryServiceUrl=DISCOVERY_URI, | |
150 developerKey=None, | |
151 model=None, | |
152 requestBuilder=HttpRequest, | |
153 credentials=None): | |
154 """Construct a Resource for interacting with an API. | |
155 | |
156 Construct a Resource object for interacting with an API. The serviceName and | |
157 version are the names from the Discovery service. | |
158 | |
159 Args: | |
160 serviceName: string, name of the service. | |
161 version: string, the version of the service. | |
162 http: httplib2.Http, An instance of httplib2.Http or something that acts | |
163 like it that HTTP requests will be made through. | |
164 discoveryServiceUrl: string, a URI Template that points to the location of | |
165 the discovery service. It should have two parameters {api} and | |
166 {apiVersion} that when filled in produce an absolute URI to the discovery | |
167 document for that service. | |
168 developerKey: string, key obtained from | |
169 https://code.google.com/apis/console. | |
170 model: googleapiclient.Model, converts to and from the wire format. | |
171 requestBuilder: googleapiclient.http.HttpRequest, encapsulator for an HTTP | |
172 request. | |
173 credentials: oauth2client.Credentials, credentials to be used for | |
174 authentication. | |
175 | |
176 Returns: | |
177 A Resource object with methods for interacting with the service. | |
178 """ | |
179 params = { | |
180 'api': serviceName, | |
181 'apiVersion': version | |
182 } | |
183 | |
184 if http is None: | |
185 http = httplib2.Http() | |
186 | |
187 requested_url = uritemplate.expand(discoveryServiceUrl, params) | |
188 | |
189 # REMOTE_ADDR is defined by the CGI spec [RFC3875] as the environment | |
190 # variable that contains the network address of the client sending the | |
191 # request. If it exists then add that to the request for the discovery | |
192 # document to avoid exceeding the quota on discovery requests. | |
193 if 'REMOTE_ADDR' in os.environ: | |
194 requested_url = _add_query_parameter(requested_url, 'userIp', | |
195 os.environ['REMOTE_ADDR']) | |
196 logger.info('URL being requested: GET %s' % requested_url) | |
197 | |
198 resp, content = http.request(requested_url) | |
199 | |
200 if resp.status == 404: | |
201 raise UnknownApiNameOrVersion("name: %s version: %s" % (serviceName, | |
202 version)) | |
203 if resp.status >= 400: | |
204 raise HttpError(resp, content, uri=requested_url) | |
205 | |
206 try: | |
207 service = json.loads(content) | |
208 except ValueError, e: | |
209 logger.error('Failed to parse as JSON: ' + content) | |
210 raise InvalidJsonError() | |
211 | |
212 return build_from_document(content, base=discoveryServiceUrl, http=http, | |
213 developerKey=developerKey, model=model, requestBuilder=requestBuilder, | |
214 credentials=credentials) | |
215 | |
216 | |
217 @positional(1) | |
218 def build_from_document( | |
219 service, | |
220 base=None, | |
221 future=None, | |
222 http=None, | |
223 developerKey=None, | |
224 model=None, | |
225 requestBuilder=HttpRequest, | |
226 credentials=None): | |
227 """Create a Resource for interacting with an API. | |
228 | |
229 Same as `build()`, but constructs the Resource object from a discovery | |
230 document that is it given, as opposed to retrieving one over HTTP. | |
231 | |
232 Args: | |
233 service: string or object, the JSON discovery document describing the API. | |
234 The value passed in may either be the JSON string or the deserialized | |
235 JSON. | |
236 base: string, base URI for all HTTP requests, usually the discovery URI. | |
237 This parameter is no longer used as rootUrl and servicePath are included | |
238 within the discovery document. (deprecated) | |
239 future: string, discovery document with future capabilities (deprecated). | |
240 http: httplib2.Http, An instance of httplib2.Http or something that acts | |
241 like it that HTTP requests will be made through. | |
242 developerKey: string, Key for controlling API usage, generated | |
243 from the API Console. | |
244 model: Model class instance that serializes and de-serializes requests and | |
245 responses. | |
246 requestBuilder: Takes an http request and packages it up to be executed. | |
247 credentials: object, credentials to be used for authentication. | |
248 | |
249 Returns: | |
250 A Resource object with methods for interacting with the service. | |
251 """ | |
252 | |
253 # future is no longer used. | |
254 future = {} | |
255 | |
256 if isinstance(service, basestring): | |
257 service = json.loads(service) | |
258 base = urlparse.urljoin(service['rootUrl'], service['servicePath']) | |
259 schema = Schemas(service) | |
260 | |
261 if credentials: | |
262 # If credentials were passed in, we could have two cases: | |
263 # 1. the scopes were specified, in which case the given credentials | |
264 # are used for authorizing the http; | |
265 # 2. the scopes were not provided (meaning the Application Default | |
266 # Credentials are to be used). In this case, the Application Default | |
267 # Credentials are built and used instead of the original credentials. | |
268 # If there are no scopes found (meaning the given service requires no | |
269 # authentication), there is no authorization of the http. | |
270 if (isinstance(credentials, GoogleCredentials) and | |
271 credentials.create_scoped_required()): | |
272 scopes = service.get('auth', {}).get('oauth2', {}).get('scopes', {}) | |
273 if scopes: | |
274 credentials = credentials.create_scoped(scopes.keys()) | |
275 else: | |
276 # No need to authorize the http object | |
277 # if the service does not require authentication. | |
278 credentials = None | |
279 | |
280 if credentials: | |
281 http = credentials.authorize(http) | |
282 | |
283 if model is None: | |
284 features = service.get('features', []) | |
285 model = JsonModel('dataWrapper' in features) | |
286 return Resource(http=http, baseUrl=base, model=model, | |
287 developerKey=developerKey, requestBuilder=requestBuilder, | |
288 resourceDesc=service, rootDesc=service, schema=schema) | |
289 | |
290 | |
291 def _cast(value, schema_type): | |
292 """Convert value to a string based on JSON Schema type. | |
293 | |
294 See http://tools.ietf.org/html/draft-zyp-json-schema-03 for more details on | |
295 JSON Schema. | |
296 | |
297 Args: | |
298 value: any, the value to convert | |
299 schema_type: string, the type that value should be interpreted as | |
300 | |
301 Returns: | |
302 A string representation of 'value' based on the schema_type. | |
303 """ | |
304 if schema_type == 'string': | |
305 if type(value) == type('') or type(value) == type(u''): | |
306 return value | |
307 else: | |
308 return str(value) | |
309 elif schema_type == 'integer': | |
310 return str(int(value)) | |
311 elif schema_type == 'number': | |
312 return str(float(value)) | |
313 elif schema_type == 'boolean': | |
314 return str(bool(value)).lower() | |
315 else: | |
316 if type(value) == type('') or type(value) == type(u''): | |
317 return value | |
318 else: | |
319 return str(value) | |
320 | |
321 | |
322 def _media_size_to_long(maxSize): | |
323 """Convert a string media size, such as 10GB or 3TB into an integer. | |
324 | |
325 Args: | |
326 maxSize: string, size as a string, such as 2MB or 7GB. | |
327 | |
328 Returns: | |
329 The size as an integer value. | |
330 """ | |
331 if len(maxSize) < 2: | |
332 return 0L | |
333 units = maxSize[-2:].upper() | |
334 bit_shift = _MEDIA_SIZE_BIT_SHIFTS.get(units) | |
335 if bit_shift is not None: | |
336 return long(maxSize[:-2]) << bit_shift | |
337 else: | |
338 return long(maxSize) | |
339 | |
340 | |
341 def _media_path_url_from_info(root_desc, path_url): | |
342 """Creates an absolute media path URL. | |
343 | |
344 Constructed using the API root URI and service path from the discovery | |
345 document and the relative path for the API method. | |
346 | |
347 Args: | |
348 root_desc: Dictionary; the entire original deserialized discovery document. | |
349 path_url: String; the relative URL for the API method. Relative to the API | |
350 root, which is specified in the discovery document. | |
351 | |
352 Returns: | |
353 String; the absolute URI for media upload for the API method. | |
354 """ | |
355 return '%(root)supload/%(service_path)s%(path)s' % { | |
356 'root': root_desc['rootUrl'], | |
357 'service_path': root_desc['servicePath'], | |
358 'path': path_url, | |
359 } | |
360 | |
361 | |
362 def _fix_up_parameters(method_desc, root_desc, http_method): | |
363 """Updates parameters of an API method with values specific to this library. | |
364 | |
365 Specifically, adds whatever global parameters are specified by the API to the | |
366 parameters for the individual method. Also adds parameters which don't | |
367 appear in the discovery document, but are available to all discovery based | |
368 APIs (these are listed in STACK_QUERY_PARAMETERS). | |
369 | |
370 SIDE EFFECTS: This updates the parameters dictionary object in the method | |
371 description. | |
372 | |
373 Args: | |
374 method_desc: Dictionary with metadata describing an API method. Value comes | |
375 from the dictionary of methods stored in the 'methods' key in the | |
376 deserialized discovery document. | |
377 root_desc: Dictionary; the entire original deserialized discovery document. | |
378 http_method: String; the HTTP method used to call the API method described | |
379 in method_desc. | |
380 | |
381 Returns: | |
382 The updated Dictionary stored in the 'parameters' key of the method | |
383 description dictionary. | |
384 """ | |
385 parameters = method_desc.setdefault('parameters', {}) | |
386 | |
387 # Add in the parameters common to all methods. | |
388 for name, description in root_desc.get('parameters', {}).iteritems(): | |
389 parameters[name] = description | |
390 | |
391 # Add in undocumented query parameters. | |
392 for name in STACK_QUERY_PARAMETERS: | |
393 parameters[name] = STACK_QUERY_PARAMETER_DEFAULT_VALUE.copy() | |
394 | |
395 # Add 'body' (our own reserved word) to parameters if the method supports | |
396 # a request payload. | |
397 if http_method in HTTP_PAYLOAD_METHODS and 'request' in method_desc: | |
398 body = BODY_PARAMETER_DEFAULT_VALUE.copy() | |
399 body.update(method_desc['request']) | |
400 parameters['body'] = body | |
401 | |
402 return parameters | |
403 | |
404 | |
405 def _fix_up_media_upload(method_desc, root_desc, path_url, parameters): | |
406 """Updates parameters of API by adding 'media_body' if supported by method. | |
407 | |
408 SIDE EFFECTS: If the method supports media upload and has a required body, | |
409 sets body to be optional (required=False) instead. Also, if there is a | |
410 'mediaUpload' in the method description, adds 'media_upload' key to | |
411 parameters. | |
412 | |
413 Args: | |
414 method_desc: Dictionary with metadata describing an API method. Value comes | |
415 from the dictionary of methods stored in the 'methods' key in the | |
416 deserialized discovery document. | |
417 root_desc: Dictionary; the entire original deserialized discovery document. | |
418 path_url: String; the relative URL for the API method. Relative to the API | |
419 root, which is specified in the discovery document. | |
420 parameters: A dictionary describing method parameters for method described | |
421 in method_desc. | |
422 | |
423 Returns: | |
424 Triple (accept, max_size, media_path_url) where: | |
425 - accept is a list of strings representing what content types are | |
426 accepted for media upload. Defaults to empty list if not in the | |
427 discovery document. | |
428 - max_size is a long representing the max size in bytes allowed for a | |
429 media upload. Defaults to 0L if not in the discovery document. | |
430 - media_path_url is a String; the absolute URI for media upload for the | |
431 API method. Constructed using the API root URI and service path from | |
432 the discovery document and the relative path for the API method. If | |
433 media upload is not supported, this is None. | |
434 """ | |
435 media_upload = method_desc.get('mediaUpload', {}) | |
436 accept = media_upload.get('accept', []) | |
437 max_size = _media_size_to_long(media_upload.get('maxSize', '')) | |
438 media_path_url = None | |
439 | |
440 if media_upload: | |
441 media_path_url = _media_path_url_from_info(root_desc, path_url) | |
442 parameters['media_body'] = MEDIA_BODY_PARAMETER_DEFAULT_VALUE.copy() | |
443 if 'body' in parameters: | |
444 parameters['body']['required'] = False | |
445 | |
446 return accept, max_size, media_path_url | |
447 | |
448 | |
449 def _fix_up_method_description(method_desc, root_desc): | |
450 """Updates a method description in a discovery document. | |
451 | |
452 SIDE EFFECTS: Changes the parameters dictionary in the method description with | |
453 extra parameters which are used locally. | |
454 | |
455 Args: | |
456 method_desc: Dictionary with metadata describing an API method. Value comes | |
457 from the dictionary of methods stored in the 'methods' key in the | |
458 deserialized discovery document. | |
459 root_desc: Dictionary; the entire original deserialized discovery document. | |
460 | |
461 Returns: | |
462 Tuple (path_url, http_method, method_id, accept, max_size, media_path_url) | |
463 where: | |
464 - path_url is a String; the relative URL for the API method. Relative to | |
465 the API root, which is specified in the discovery document. | |
466 - http_method is a String; the HTTP method used to call the API method | |
467 described in the method description. | |
468 - method_id is a String; the name of the RPC method associated with the | |
469 API method, and is in the method description in the 'id' key. | |
470 - accept is a list of strings representing what content types are | |
471 accepted for media upload. Defaults to empty list if not in the | |
472 discovery document. | |
473 - max_size is a long representing the max size in bytes allowed for a | |
474 media upload. Defaults to 0L if not in the discovery document. | |
475 - media_path_url is a String; the absolute URI for media upload for the | |
476 API method. Constructed using the API root URI and service path from | |
477 the discovery document and the relative path for the API method. If | |
478 media upload is not supported, this is None. | |
479 """ | |
480 path_url = method_desc['path'] | |
481 http_method = method_desc['httpMethod'] | |
482 method_id = method_desc['id'] | |
483 | |
484 parameters = _fix_up_parameters(method_desc, root_desc, http_method) | |
485 # Order is important. `_fix_up_media_upload` needs `method_desc` to have a | |
486 # 'parameters' key and needs to know if there is a 'body' parameter because it | |
487 # also sets a 'media_body' parameter. | |
488 accept, max_size, media_path_url = _fix_up_media_upload( | |
489 method_desc, root_desc, path_url, parameters) | |
490 | |
491 return path_url, http_method, method_id, accept, max_size, media_path_url | |
492 | |
493 | |
494 # TODO(dhermes): Convert this class to ResourceMethod and make it callable | |
495 class ResourceMethodParameters(object): | |
496 """Represents the parameters associated with a method. | |
497 | |
498 Attributes: | |
499 argmap: Map from method parameter name (string) to query parameter name | |
500 (string). | |
501 required_params: List of required parameters (represented by parameter | |
502 name as string). | |
503 repeated_params: List of repeated parameters (represented by parameter | |
504 name as string). | |
505 pattern_params: Map from method parameter name (string) to regular | |
506 expression (as a string). If the pattern is set for a parameter, the | |
507 value for that parameter must match the regular expression. | |
508 query_params: List of parameters (represented by parameter name as string) | |
509 that will be used in the query string. | |
510 path_params: Set of parameters (represented by parameter name as string) | |
511 that will be used in the base URL path. | |
512 param_types: Map from method parameter name (string) to parameter type. Type | |
513 can be any valid JSON schema type; valid values are 'any', 'array', | |
514 'boolean', 'integer', 'number', 'object', or 'string'. Reference: | |
515 http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.1 | |
516 enum_params: Map from method parameter name (string) to list of strings, | |
517 where each list of strings is the list of acceptable enum values. | |
518 """ | |
519 | |
520 def __init__(self, method_desc): | |
521 """Constructor for ResourceMethodParameters. | |
522 | |
523 Sets default values and defers to set_parameters to populate. | |
524 | |
525 Args: | |
526 method_desc: Dictionary with metadata describing an API method. Value | |
527 comes from the dictionary of methods stored in the 'methods' key in | |
528 the deserialized discovery document. | |
529 """ | |
530 self.argmap = {} | |
531 self.required_params = [] | |
532 self.repeated_params = [] | |
533 self.pattern_params = {} | |
534 self.query_params = [] | |
535 # TODO(dhermes): Change path_params to a list if the extra URITEMPLATE | |
536 # parsing is gotten rid of. | |
537 self.path_params = set() | |
538 self.param_types = {} | |
539 self.enum_params = {} | |
540 | |
541 self.set_parameters(method_desc) | |
542 | |
543 def set_parameters(self, method_desc): | |
544 """Populates maps and lists based on method description. | |
545 | |
546 Iterates through each parameter for the method and parses the values from | |
547 the parameter dictionary. | |
548 | |
549 Args: | |
550 method_desc: Dictionary with metadata describing an API method. Value | |
551 comes from the dictionary of methods stored in the 'methods' key in | |
552 the deserialized discovery document. | |
553 """ | |
554 for arg, desc in method_desc.get('parameters', {}).iteritems(): | |
555 param = key2param(arg) | |
556 self.argmap[param] = arg | |
557 | |
558 if desc.get('pattern'): | |
559 self.pattern_params[param] = desc['pattern'] | |
560 if desc.get('enum'): | |
561 self.enum_params[param] = desc['enum'] | |
562 if desc.get('required'): | |
563 self.required_params.append(param) | |
564 if desc.get('repeated'): | |
565 self.repeated_params.append(param) | |
566 if desc.get('location') == 'query': | |
567 self.query_params.append(param) | |
568 if desc.get('location') == 'path': | |
569 self.path_params.add(param) | |
570 self.param_types[param] = desc.get('type', 'string') | |
571 | |
572 # TODO(dhermes): Determine if this is still necessary. Discovery based APIs | |
573 # should have all path parameters already marked with | |
574 # 'location: path'. | |
575 for match in URITEMPLATE.finditer(method_desc['path']): | |
576 for namematch in VARNAME.finditer(match.group(0)): | |
577 name = key2param(namematch.group(0)) | |
578 self.path_params.add(name) | |
579 if name in self.query_params: | |
580 self.query_params.remove(name) | |
581 | |
582 | |
583 def createMethod(methodName, methodDesc, rootDesc, schema): | |
584 """Creates a method for attaching to a Resource. | |
585 | |
586 Args: | |
587 methodName: string, name of the method to use. | |
588 methodDesc: object, fragment of deserialized discovery document that | |
589 describes the method. | |
590 rootDesc: object, the entire deserialized discovery document. | |
591 schema: object, mapping of schema names to schema descriptions. | |
592 """ | |
593 methodName = fix_method_name(methodName) | |
594 (pathUrl, httpMethod, methodId, accept, | |
595 maxSize, mediaPathUrl) = _fix_up_method_description(methodDesc, rootDesc) | |
596 | |
597 parameters = ResourceMethodParameters(methodDesc) | |
598 | |
599 def method(self, **kwargs): | |
600 # Don't bother with doc string, it will be over-written by createMethod. | |
601 | |
602 for name in kwargs.iterkeys(): | |
603 if name not in parameters.argmap: | |
604 raise TypeError('Got an unexpected keyword argument "%s"' % name) | |
605 | |
606 # Remove args that have a value of None. | |
607 keys = kwargs.keys() | |
608 for name in keys: | |
609 if kwargs[name] is None: | |
610 del kwargs[name] | |
611 | |
612 for name in parameters.required_params: | |
613 if name not in kwargs: | |
614 raise TypeError('Missing required parameter "%s"' % name) | |
615 | |
616 for name, regex in parameters.pattern_params.iteritems(): | |
617 if name in kwargs: | |
618 if isinstance(kwargs[name], basestring): | |
619 pvalues = [kwargs[name]] | |
620 else: | |
621 pvalues = kwargs[name] | |
622 for pvalue in pvalues: | |
623 if re.match(regex, pvalue) is None: | |
624 raise TypeError( | |
625 'Parameter "%s" value "%s" does not match the pattern "%s"' % | |
626 (name, pvalue, regex)) | |
627 | |
628 for name, enums in parameters.enum_params.iteritems(): | |
629 if name in kwargs: | |
630 # We need to handle the case of a repeated enum | |
631 # name differently, since we want to handle both | |
632 # arg='value' and arg=['value1', 'value2'] | |
633 if (name in parameters.repeated_params and | |
634 not isinstance(kwargs[name], basestring)): | |
635 values = kwargs[name] | |
636 else: | |
637 values = [kwargs[name]] | |
638 for value in values: | |
639 if value not in enums: | |
640 raise TypeError( | |
641 'Parameter "%s" value "%s" is not an allowed value in "%s"' % | |
642 (name, value, str(enums))) | |
643 | |
644 actual_query_params = {} | |
645 actual_path_params = {} | |
646 for key, value in kwargs.iteritems(): | |
647 to_type = parameters.param_types.get(key, 'string') | |
648 # For repeated parameters we cast each member of the list. | |
649 if key in parameters.repeated_params and type(value) == type([]): | |
650 cast_value = [_cast(x, to_type) for x in value] | |
651 else: | |
652 cast_value = _cast(value, to_type) | |
653 if key in parameters.query_params: | |
654 actual_query_params[parameters.argmap[key]] = cast_value | |
655 if key in parameters.path_params: | |
656 actual_path_params[parameters.argmap[key]] = cast_value | |
657 body_value = kwargs.get('body', None) | |
658 media_filename = kwargs.get('media_body', None) | |
659 | |
660 if self._developerKey: | |
661 actual_query_params['key'] = self._developerKey | |
662 | |
663 model = self._model | |
664 if methodName.endswith('_media'): | |
665 model = MediaModel() | |
666 elif 'response' not in methodDesc: | |
667 model = RawModel() | |
668 | |
669 headers = {} | |
670 headers, params, query, body = model.request(headers, | |
671 actual_path_params, actual_query_params, body_value) | |
672 | |
673 expanded_url = uritemplate.expand(pathUrl, params) | |
674 url = urlparse.urljoin(self._baseUrl, expanded_url + query) | |
675 | |
676 resumable = None | |
677 multipart_boundary = '' | |
678 | |
679 if media_filename: | |
680 # Ensure we end up with a valid MediaUpload object. | |
681 if isinstance(media_filename, basestring): | |
682 (media_mime_type, encoding) = mimetypes.guess_type(media_filename) | |
683 if media_mime_type is None: | |
684 raise UnknownFileType(media_filename) | |
685 if not mimeparse.best_match([media_mime_type], ','.join(accept)): | |
686 raise UnacceptableMimeTypeError(media_mime_type) | |
687 media_upload = MediaFileUpload(media_filename, | |
688 mimetype=media_mime_type) | |
689 elif isinstance(media_filename, MediaUpload): | |
690 media_upload = media_filename | |
691 else: | |
692 raise TypeError('media_filename must be str or MediaUpload.') | |
693 | |
694 # Check the maxSize | |
695 if maxSize > 0 and media_upload.size() > maxSize: | |
696 raise MediaUploadSizeError("Media larger than: %s" % maxSize) | |
697 | |
698 # Use the media path uri for media uploads | |
699 expanded_url = uritemplate.expand(mediaPathUrl, params) | |
700 url = urlparse.urljoin(self._baseUrl, expanded_url + query) | |
701 if media_upload.resumable(): | |
702 url = _add_query_parameter(url, 'uploadType', 'resumable') | |
703 | |
704 if media_upload.resumable(): | |
705 # This is all we need to do for resumable, if the body exists it gets | |
706 # sent in the first request, otherwise an empty body is sent. | |
707 resumable = media_upload | |
708 else: | |
709 # A non-resumable upload | |
710 if body is None: | |
711 # This is a simple media upload | |
712 headers['content-type'] = media_upload.mimetype() | |
713 body = media_upload.getbytes(0, media_upload.size()) | |
714 url = _add_query_parameter(url, 'uploadType', 'media') | |
715 else: | |
716 # This is a multipart/related upload. | |
717 msgRoot = MIMEMultipart('related') | |
718 # msgRoot should not write out it's own headers | |
719 setattr(msgRoot, '_write_headers', lambda self: None) | |
720 | |
721 # attach the body as one part | |
722 msg = MIMENonMultipart(*headers['content-type'].split('/')) | |
723 msg.set_payload(body) | |
724 msgRoot.attach(msg) | |
725 | |
726 # attach the media as the second part | |
727 msg = MIMENonMultipart(*media_upload.mimetype().split('/')) | |
728 msg['Content-Transfer-Encoding'] = 'binary' | |
729 | |
730 payload = media_upload.getbytes(0, media_upload.size()) | |
731 msg.set_payload(payload) | |
732 msgRoot.attach(msg) | |
733 # encode the body: note that we can't use `as_string`, because | |
734 # it plays games with `From ` lines. | |
735 fp = StringIO.StringIO() | |
736 g = Generator(fp, mangle_from_=False) | |
737 g.flatten(msgRoot, unixfrom=False) | |
738 body = fp.getvalue() | |
739 | |
740 multipart_boundary = msgRoot.get_boundary() | |
741 headers['content-type'] = ('multipart/related; ' | |
742 'boundary="%s"') % multipart_boundary | |
743 url = _add_query_parameter(url, 'uploadType', 'multipart') | |
744 | |
745 logger.info('URL being requested: %s %s' % (httpMethod,url)) | |
746 return self._requestBuilder(self._http, | |
747 model.response, | |
748 url, | |
749 method=httpMethod, | |
750 body=body, | |
751 headers=headers, | |
752 methodId=methodId, | |
753 resumable=resumable) | |
754 | |
755 docs = [methodDesc.get('description', DEFAULT_METHOD_DOC), '\n\n'] | |
756 if len(parameters.argmap) > 0: | |
757 docs.append('Args:\n') | |
758 | |
759 # Skip undocumented params and params common to all methods. | |
760 skip_parameters = rootDesc.get('parameters', {}).keys() | |
761 skip_parameters.extend(STACK_QUERY_PARAMETERS) | |
762 | |
763 all_args = parameters.argmap.keys() | |
764 args_ordered = [key2param(s) for s in methodDesc.get('parameterOrder', [])] | |
765 | |
766 # Move body to the front of the line. | |
767 if 'body' in all_args: | |
768 args_ordered.append('body') | |
769 | |
770 for name in all_args: | |
771 if name not in args_ordered: | |
772 args_ordered.append(name) | |
773 | |
774 for arg in args_ordered: | |
775 if arg in skip_parameters: | |
776 continue | |
777 | |
778 repeated = '' | |
779 if arg in parameters.repeated_params: | |
780 repeated = ' (repeated)' | |
781 required = '' | |
782 if arg in parameters.required_params: | |
783 required = ' (required)' | |
784 paramdesc = methodDesc['parameters'][parameters.argmap[arg]] | |
785 paramdoc = paramdesc.get('description', 'A parameter') | |
786 if '$ref' in paramdesc: | |
787 docs.append( | |
788 (' %s: object, %s%s%s\n The object takes the' | |
789 ' form of:\n\n%s\n\n') % (arg, paramdoc, required, repeated, | |
790 schema.prettyPrintByName(paramdesc['$ref']))) | |
791 else: | |
792 paramtype = paramdesc.get('type', 'string') | |
793 docs.append(' %s: %s, %s%s%s\n' % (arg, paramtype, paramdoc, required, | |
794 repeated)) | |
795 enum = paramdesc.get('enum', []) | |
796 enumDesc = paramdesc.get('enumDescriptions', []) | |
797 if enum and enumDesc: | |
798 docs.append(' Allowed values\n') | |
799 for (name, desc) in zip(enum, enumDesc): | |
800 docs.append(' %s - %s\n' % (name, desc)) | |
801 if 'response' in methodDesc: | |
802 if methodName.endswith('_media'): | |
803 docs.append('\nReturns:\n The media object as a string.\n\n ') | |
804 else: | |
805 docs.append('\nReturns:\n An object of the form:\n\n ') | |
806 docs.append(schema.prettyPrintSchema(methodDesc['response'])) | |
807 | |
808 setattr(method, '__doc__', ''.join(docs)) | |
809 return (methodName, method) | |
810 | |
811 | |
812 def createNextMethod(methodName): | |
813 """Creates any _next methods for attaching to a Resource. | |
814 | |
815 The _next methods allow for easy iteration through list() responses. | |
816 | |
817 Args: | |
818 methodName: string, name of the method to use. | |
819 """ | |
820 methodName = fix_method_name(methodName) | |
821 | |
822 def methodNext(self, previous_request, previous_response): | |
823 """Retrieves the next page of results. | |
824 | |
825 Args: | |
826 previous_request: The request for the previous page. (required) | |
827 previous_response: The response from the request for the previous page. (requi
red) | |
828 | |
829 Returns: | |
830 A request object that you can call 'execute()' on to request the next | |
831 page. Returns None if there are no more items in the collection. | |
832 """ | |
833 # Retrieve nextPageToken from previous_response | |
834 # Use as pageToken in previous_request to create new request. | |
835 | |
836 if 'nextPageToken' not in previous_response: | |
837 return None | |
838 | |
839 request = copy.copy(previous_request) | |
840 | |
841 pageToken = previous_response['nextPageToken'] | |
842 parsed = list(urlparse.urlparse(request.uri)) | |
843 q = parse_qsl(parsed[4]) | |
844 | |
845 # Find and remove old 'pageToken' value from URI | |
846 newq = [(key, value) for (key, value) in q if key != 'pageToken'] | |
847 newq.append(('pageToken', pageToken)) | |
848 parsed[4] = urllib.urlencode(newq) | |
849 uri = urlparse.urlunparse(parsed) | |
850 | |
851 request.uri = uri | |
852 | |
853 logger.info('URL being requested: %s %s' % (methodName,uri)) | |
854 | |
855 return request | |
856 | |
857 return (methodName, methodNext) | |
858 | |
859 | |
860 class Resource(object): | |
861 """A class for interacting with a resource.""" | |
862 | |
863 def __init__(self, http, baseUrl, model, requestBuilder, developerKey, | |
864 resourceDesc, rootDesc, schema): | |
865 """Build a Resource from the API description. | |
866 | |
867 Args: | |
868 http: httplib2.Http, Object to make http requests with. | |
869 baseUrl: string, base URL for the API. All requests are relative to this | |
870 URI. | |
871 model: googleapiclient.Model, converts to and from the wire format. | |
872 requestBuilder: class or callable that instantiates an | |
873 googleapiclient.HttpRequest object. | |
874 developerKey: string, key obtained from | |
875 https://code.google.com/apis/console | |
876 resourceDesc: object, section of deserialized discovery document that | |
877 describes a resource. Note that the top level discovery document | |
878 is considered a resource. | |
879 rootDesc: object, the entire deserialized discovery document. | |
880 schema: object, mapping of schema names to schema descriptions. | |
881 """ | |
882 self._dynamic_attrs = [] | |
883 | |
884 self._http = http | |
885 self._baseUrl = baseUrl | |
886 self._model = model | |
887 self._developerKey = developerKey | |
888 self._requestBuilder = requestBuilder | |
889 self._resourceDesc = resourceDesc | |
890 self._rootDesc = rootDesc | |
891 self._schema = schema | |
892 | |
893 self._set_service_methods() | |
894 | |
895 def _set_dynamic_attr(self, attr_name, value): | |
896 """Sets an instance attribute and tracks it in a list of dynamic attributes. | |
897 | |
898 Args: | |
899 attr_name: string; The name of the attribute to be set | |
900 value: The value being set on the object and tracked in the dynamic cache. | |
901 """ | |
902 self._dynamic_attrs.append(attr_name) | |
903 self.__dict__[attr_name] = value | |
904 | |
905 def __getstate__(self): | |
906 """Trim the state down to something that can be pickled. | |
907 | |
908 Uses the fact that the instance variable _dynamic_attrs holds attrs that | |
909 will be wiped and restored on pickle serialization. | |
910 """ | |
911 state_dict = copy.copy(self.__dict__) | |
912 for dynamic_attr in self._dynamic_attrs: | |
913 del state_dict[dynamic_attr] | |
914 del state_dict['_dynamic_attrs'] | |
915 return state_dict | |
916 | |
917 def __setstate__(self, state): | |
918 """Reconstitute the state of the object from being pickled. | |
919 | |
920 Uses the fact that the instance variable _dynamic_attrs holds attrs that | |
921 will be wiped and restored on pickle serialization. | |
922 """ | |
923 self.__dict__.update(state) | |
924 self._dynamic_attrs = [] | |
925 self._set_service_methods() | |
926 | |
927 def _set_service_methods(self): | |
928 self._add_basic_methods(self._resourceDesc, self._rootDesc, self._schema) | |
929 self._add_nested_resources(self._resourceDesc, self._rootDesc, self._schema) | |
930 self._add_next_methods(self._resourceDesc, self._schema) | |
931 | |
932 def _add_basic_methods(self, resourceDesc, rootDesc, schema): | |
933 # Add basic methods to Resource | |
934 if 'methods' in resourceDesc: | |
935 for methodName, methodDesc in resourceDesc['methods'].iteritems(): | |
936 fixedMethodName, method = createMethod( | |
937 methodName, methodDesc, rootDesc, schema) | |
938 self._set_dynamic_attr(fixedMethodName, | |
939 method.__get__(self, self.__class__)) | |
940 # Add in _media methods. The functionality of the attached method will | |
941 # change when it sees that the method name ends in _media. | |
942 if methodDesc.get('supportsMediaDownload', False): | |
943 fixedMethodName, method = createMethod( | |
944 methodName + '_media', methodDesc, rootDesc, schema) | |
945 self._set_dynamic_attr(fixedMethodName, | |
946 method.__get__(self, self.__class__)) | |
947 | |
948 def _add_nested_resources(self, resourceDesc, rootDesc, schema): | |
949 # Add in nested resources | |
950 if 'resources' in resourceDesc: | |
951 | |
952 def createResourceMethod(methodName, methodDesc): | |
953 """Create a method on the Resource to access a nested Resource. | |
954 | |
955 Args: | |
956 methodName: string, name of the method to use. | |
957 methodDesc: object, fragment of deserialized discovery document that | |
958 describes the method. | |
959 """ | |
960 methodName = fix_method_name(methodName) | |
961 | |
962 def methodResource(self): | |
963 return Resource(http=self._http, baseUrl=self._baseUrl, | |
964 model=self._model, developerKey=self._developerKey, | |
965 requestBuilder=self._requestBuilder, | |
966 resourceDesc=methodDesc, rootDesc=rootDesc, | |
967 schema=schema) | |
968 | |
969 setattr(methodResource, '__doc__', 'A collection resource.') | |
970 setattr(methodResource, '__is_resource__', True) | |
971 | |
972 return (methodName, methodResource) | |
973 | |
974 for methodName, methodDesc in resourceDesc['resources'].iteritems(): | |
975 fixedMethodName, method = createResourceMethod(methodName, methodDesc) | |
976 self._set_dynamic_attr(fixedMethodName, | |
977 method.__get__(self, self.__class__)) | |
978 | |
979 def _add_next_methods(self, resourceDesc, schema): | |
980 # Add _next() methods | |
981 # Look for response bodies in schema that contain nextPageToken, and methods | |
982 # that take a pageToken parameter. | |
983 if 'methods' in resourceDesc: | |
984 for methodName, methodDesc in resourceDesc['methods'].iteritems(): | |
985 if 'response' in methodDesc: | |
986 responseSchema = methodDesc['response'] | |
987 if '$ref' in responseSchema: | |
988 responseSchema = schema.get(responseSchema['$ref']) | |
989 hasNextPageToken = 'nextPageToken' in responseSchema.get('properties', | |
990 {}) | |
991 hasPageToken = 'pageToken' in methodDesc.get('parameters', {}) | |
992 if hasNextPageToken and hasPageToken: | |
993 fixedMethodName, method = createNextMethod(methodName + '_next') | |
994 self._set_dynamic_attr(fixedMethodName, | |
995 method.__get__(self, self.__class__)) | |
OLD | NEW |