Package googleapiclient :: Module discovery
[hide private]
[frames] | no frames]

Source Code for Module googleapiclient.discovery

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