diff --git a/docs/apiclient.http.html b/docs/apiclient.http.html index 69a1cad..0aff590 100644 --- a/docs/apiclient.http.html +++ b/docs/apiclient.http.html @@ -508,7 +508,6 @@ Data descriptors inherited from MediaU Note that the Python file object is compatible with io.Base and can be used
with this class also.
 
- 
  fh = io.BytesIO('...Some data to upload...')
  media = MediaIoBaseUpload(fh, mimetype='image/png',
    chunksize=1024*1024, resumable=True)
@@ -527,7 +526,8 @@ Methods defined here:
__init__(self, fh, mimetype, chunksize=524288, resumable=False)
Constructor.
 
Args:
-  fh: io.Base or file object, The source of the bytes to upload.
+  fh: io.Base or file object, The source of the bytes to upload. MUST be
+    opened in blocking mode, do not use streams opened in non-blocking mode.
  mimetype: string, Mime-type of the file. If None then a mime-type will be
    guessed from the file extension.
  chunksize: int, File will be uploaded in chunks of this many bytes. Only
diff --git a/docs/build.sh b/docs/build.sh index 502d8f0..6f9cddc 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -28,4 +28,4 @@ export PYTHONPATH=`pwd`/..:$GOOGLE_APPENGINE find ../apiclient/ -name "*.py" | sed "s/\/__init__.py//" | sed "s/\.py//" | sed "s/^\.\.\///" | sed "s#/#.#g" | xargs python `which pydoc` -w find ../oauth2client/ -name "*.py" | sed "s/\/__init__.py//" | sed "s/\.py//" | sed "s/^\.\.\///" | sed "s#/#.#g" | xargs python `which pydoc` -w find ../uritemplate/ -name "*.py" | sed "s/\/__init__.py//" | sed "s/\.py//" | sed "s/^\.\.\///" | sed "s#/#.#g" | xargs python `which pydoc` -w -epydoc --output epy --graph all --docformat plaintext apiclient oauth2client +epydoc --output epy --graph classtree --docformat plaintext apiclient oauth2client diff --git a/docs/epy/apiclient-module.html b/docs/epy/apiclient-module.html index 9116cb7..315e135 100644 --- a/docs/epy/apiclient-module.html +++ b/docs/epy/apiclient-module.html @@ -134,7 +134,7 @@
- Generated by Epydoc 3.0.1 on Thu Jun 14 08:01:54 2012 + Generated by Epydoc 3.0.1 on Fri Jun 15 09:51:49 2012
- Generated by Epydoc 3.0.1 on Thu Jun 14 08:01:59 2012 + Generated by Epydoc 3.0.1 on Fri Jun 15 09:51:51 2012
- Generated by Epydoc 3.0.1 on Thu Jun 14 08:01:54 2012 + Generated by Epydoc 3.0.1 on Fri Jun 15 09:51:49 2012 267 if type(value) == type('') or type(value) == type(u''): 268 return value 269 else: -270 return str(value) -271 elif schema_type == 'integer': -272 return str(int(value)) -273 elif schema_type == 'number': -274 return str(float(value)) -275 elif schema_type == 'boolean': -276 return str(bool(value)).lower() -277 else: -278 if type(value) == type('') or type(value) == type(u''): -279 return value -280 else: -281 return str(value) -282 -283 -284 MULTIPLIERS = { -285 "KB": 2 ** 10, -286 "MB": 2 ** 20, -287 "GB": 2 ** 30, -288 "TB": 2 ** 40, -289 } -290 -291 -
292 -def _media_size_to_long(maxSize): -
293 """Convert a string media size, such as 10GB or 3TB into an integer. -294 -295 Args: -296 maxSize: string, size as a string, such as 2MB or 7GB. -297 -298 Returns: -299 The size as an integer value. -300 """ -301 if len(maxSize) < 2: -302 return 0 -303 units = maxSize[-2:].upper() -304 multiplier = MULTIPLIERS.270 if value is None: +271 raise ValueError('String parameters can not be None.') +272 return str(value) +273 elif schema_type == 'integer': +274 return str(int(value)) +275 elif schema_type == 'number': +276 return str(float(value)) +277 elif schema_type == 'boolean': +278 return str(bool(value)).lower() +279 else: +280 if type(value) == type('') or type(value) == type(u''): +281 return value +282 else: +283 return str(value) +
284 +285 +286 MULTIPLIERS = { +287 "KB": 2 ** 10, +288 "MB": 2 ** 20, +289 "GB": 2 ** 30, +290 "TB": 2 ** 40, +291 } +292 +293 +
294 -def _media_size_to_long(maxSize): +
295 """Convert a string media size, such as 10GB or 3TB into an integer. +296 +297 Args: +298 maxSize: string, size as a string, such as 2MB or 7GB. +299 +300 Returns: +301 The size as an integer value. +302 """ +303 if len(maxSize) < 2: +304 return 0 +305 units = maxSize[-2:].upper() +306 multiplier = MULTIPLIERS.get(units, 0) -305 if multiplier: -306 return int(maxSize[:-2]) * multiplier -307 else: -308 return int(maxSize) -
309 -310 -
311 -def createResource(http, baseUrl, model, requestBuilder, -312 developerKey, resourceDesc, rootDesc, schema): -
313 """Build a Resource from the API description. -314 -315 Args: -316 http: httplib2.Http, Object to make http requests with. -317 baseUrl: string, base URL for the API. All requests are relative to this -318 URI. -319 model: apiclient.Model, converts to and from the wire format. -320 requestBuilder: class or callable that instantiates an -321 apiclient.HttpRequest object. -322 developerKey: string, key obtained from -323 https://code.google.com/apis/console -324 resourceDesc: object, section of deserialized discovery document that -325 describes a resource. Note that the top level discovery document -326 is considered a resource. -327 rootDesc: object, the entire deserialized discovery document. -328 schema: object, mapping of schema names to schema descriptions. -329 -330 Returns: -331 An instance of Resource with all the methods attached for interacting with -332 that resource. -333 """ -334 -335 class Resource(object): -336 """A class for interacting with a resource.""" -337 -338 def __init__(self): -339 self._http = 307 if multiplier: +308 return int(maxSize[:-2]) * multiplier +309 else: +310 return int(maxSize) +
311 +312 +
313 -def createResource(http, baseUrl, model, requestBuilder, +314 developerKey, resourceDesc, rootDesc, schema): +
315 """Build a Resource from the API description. +316 +317 Args: +318 http: httplib2.Http, Object to make http requests with. +319 baseUrl: string, base URL for the API. All requests are relative to this +320 URI. +321 model: apiclient.Model, converts to and from the wire format. +322 requestBuilder: class or callable that instantiates an +323 apiclient.HttpRequest object. +324 developerKey: string, key obtained from +325 https://code.google.com/apis/console +326 resourceDesc: object, section of deserialized discovery document that +327 describes a resource. Note that the top level discovery document +328 is considered a resource. +329 rootDesc: object, the entire deserialized discovery document. +330 schema: object, mapping of schema names to schema descriptions. +331 +332 Returns: +333 An instance of Resource with all the methods attached for interacting with +334 that resource. +335 """ +336 +337 class Resource(object): +338 """A class for interacting with a resource.""" +339 +340 def __init__(self): +341 self._http = http -340 self._baseUrl = baseUrl -341 self._model = model -342 self._developerKey = developerKey -343 self._requestBuilder = requestBuilder -
344 -345 def createMethod(theclass, methodName, methodDesc, rootDesc): -346 """Creates a method for attaching to a Resource. -347 -348 Args: -349 theclass: type, the class to attach methods to. -350 methodName: string, name of the method to use. -351 methodDesc: object, fragment of deserialized discovery document that -352 describes the method. -353 rootDesc: object, the entire deserialized discovery document. -354 """ -355 methodName = fix_method_name(methodName) -356 pathUrl = methodDesc['path'] -357 httpMethod = methodDesc['httpMethod'] -358 methodId = methodDesc['id'] -359 -360 mediaPathUrl = None -361 342 self._baseUrl = baseUrl +343 self._model = model +344 self._developerKey = developerKey +345 self._requestBuilder = requestBuilder +346 +347 def createMethod(theclass, methodName, methodDesc, rootDesc): +348 """Creates a method for attaching to a Resource. +349 +350 Args: +351 theclass: type, the class to attach methods to. +352 methodName: string, name of the method to use. +353 methodDesc: object, fragment of deserialized discovery document that +354 describes the method. +355 rootDesc: object, the entire deserialized discovery document. +356 """ +357 methodName = fix_method_name(methodName) +358 pathUrl = methodDesc['path'] +359 httpMethod = methodDesc['httpMethod'] +360 methodId = methodDesc['id'] +361 +362 mediaPathUrl = None +363 accept = [] -362 maxSize = 0 -363 if 'mediaUpload' in methodDesc: -364 mediaUpload = methodDesc['mediaUpload'] -365 # TODO(jcgregorio) Use URLs from discovery once it is updated. -366 parsed = list(urlparse.urlparse(baseUrl)) -367 basePath = parsed[2] -368 mediaPathUrl = '/upload' + basePath + pathUrl -369 364 maxSize = 0 +365 if 'mediaUpload' in methodDesc: +366 mediaUpload = methodDesc['mediaUpload'] +367 # TODO(jcgregorio) Use URLs from discovery once it is updated. +368 parsed = list(urlparse.urlparse(baseUrl)) +369 basePath = parsed[2] +370 mediaPathUrl = '/upload' + basePath + pathUrl +371 accept = mediaUpload['accept'] -370 maxSize = _media_size_to_long(mediaUpload.372 maxSize = _media_size_to_long(mediaUpload.get('maxSize', '')) -371 -372 if 'parameters' not in methodDesc: -373 methodDesc['parameters'] = {} -374 -375 # Add in the parameters common to all methods. -376 for name, desc in rootDesc.373 +374 if 'parameters' not in methodDesc: +375 methodDesc['parameters'] = {} +376 +377 # Add in the parameters common to all methods. +378 for name, desc in rootDesc.get('parameters', {}).iteritems(): -377 methodDesc['parameters'][name] = desc -378 -379 # Add in undocumented query parameters. -380 for name in STACK_QUERY_PARAMETERS: -381 methodDesc['parameters'][name] = { -382 'type': 'string', -383 'location': 'query' -384 } -385 -386 if httpMethod in ['PUT', 'POST', 'PATCH'] and 'request' in methodDesc: -387 methodDesc['parameters']['body'] = { -388 'description': 'The request body.', -389 'type': 'object', -390 'required': True, -391 } -392 if 'request' in methodDesc: -393 methodDesc['parameters']['body'].update(methodDesc['request']) -394 else: -395 methodDesc['parameters']['body']['type'] = 'object' -396 if 'mediaUpload' in methodDesc: -397 methodDesc['parameters']['media_body'] = { -398 'description': 'The filename of the media request body.', -399 'type': 'string', -400 'required': False, -401 } -402 if 'body' in methodDesc['parameters']: -403 methodDesc['parameters']['body']['required'] = False -404 -405 argmap = {} # Map from method parameter name to query parameter name -406 required_params = [] # Required parameters -407 repeated_params = [] # Repeated parameters -408 pattern_params = {} # Parameters that must match a regex -409 query_params = [] # Parameters that will be used in the query string -410 path_params = {} # Parameters that will be used in the base URL -411 param_type = {} # The type of the parameter -412 enum_params = {} # Allowable enumeration values for each parameter -413 -414 -415 if 'parameters' in methodDesc: -416 for arg, desc in methodDesc['parameters'].iteritems(): -417 param = key2param(arg) -418 argmap[param] = arg -419 -420 if desc.379 methodDesc['parameters'][name] = desc +380 +381 # Add in undocumented query parameters. +382 for name in STACK_QUERY_PARAMETERS: +383 methodDesc['parameters'][name] = { +384 'type': 'string', +385 'location': 'query' +386 } +387 +388 if httpMethod in ['PUT', 'POST', 'PATCH'] and 'request' in methodDesc: +389 methodDesc['parameters']['body'] = { +390 'description': 'The request body.', +391 'type': 'object', +392 'required': True, +393 } +394 if 'request' in methodDesc: +395 methodDesc['parameters']['body'].update(methodDesc['request']) +396 else: +397 methodDesc['parameters']['body']['type'] = 'object' +398 if 'mediaUpload' in methodDesc: +399 methodDesc['parameters']['media_body'] = { +400 'description': 'The filename of the media request body.', +401 'type': 'string', +402 'required': False, +403 } +404 if 'body' in methodDesc['parameters']: +405 methodDesc['parameters']['body']['required'] = False +406 +407 argmap = {} # Map from method parameter name to query parameter name +408 required_params = [] # Required parameters +409 repeated_params = [] # Repeated parameters +410 pattern_params = {} # Parameters that must match a regex +411 query_params = [] # Parameters that will be used in the query string +412 path_params = {} # Parameters that will be used in the base URL +413 param_type = {} # The type of the parameter +414 enum_params = {} # Allowable enumeration values for each parameter +415 +416 +417 if 'parameters' in methodDesc: +418 for arg, desc in methodDesc['parameters'].iteritems(): +419 param = key2param(arg) +420 argmap[param] = arg +421 +422 if desc.get('pattern', ''): -421 pattern_params[param] = desc['pattern'] -422 if desc.423 pattern_params[param] = desc['pattern'] +424 if desc.get('enum', ''): -423 enum_params[param] = desc['enum'] -424 if desc.425 enum_params[param] = desc['enum'] +426 if desc.get('required', False): -425 required_params.append(param) -426 if desc.427 required_params.append(param) +428 if desc.get('repeated', False): -427 repeated_params.append(param) -428 if desc.429 repeated_params.append(param) +430 if desc.get('location') == 'query': -429 query_params.append(param) -430 if desc.431 query_params.append(param) +432 if desc.get('location') == 'path': -431 path_params[param] = param -432 param_type[param] = desc.433 path_params[param] = param +434 param_type[param] = desc.get('type', 'string') -433 -434 for match in URITEMPLATE.finditer(pathUrl): -435 for namematch in VARNAME.finditer(match.group(0)): -436 name = key2param(namematch.group(0)) -437 path_params[name] = name -438 if name in query_params: -439 query_params.remove(name) -440 -441 def method(self, **kwargs): -442 # Don't bother with doc string, it will be over-written by createMethod. -443 for name in kwargs.iterkeys(): -444 if name not in argmap: -445 raise TypeError('Got an unexpected keyword argument "%s"' % name) -446 -447 for name in required_params: -448 if name not in kwargs: -449 raise TypeError('Missing required parameter "%s"' % name) -450 -451 for name, regex in pattern_params.iteritems(): -452 if name in kwargs: -453 if isinstance(kwargs[name], basestring): -454 pvalues = [kwargs[name]] -455 else: -456 pvalues = kwargs[name] -457 for pvalue in pvalues: -458 if re.match(regex, pvalue) is None: -459 raise TypeError( -460 'Parameter "%s" value "%s" does not match the pattern "%s"' % -461 (name, pvalue, regex)) -462 -463 for name, enums in enum_params.iteritems(): -464 if name in kwargs: -465 # We need to handle the case of a repeated enum -466 # name differently, since we want to handle both -467 # arg='value' and arg=['value1', 'value2'] -468 if (name in repeated_params and -469 not isinstance(kwargs[name], basestring)): -470 values = kwargs[name] -471 else: -472 values = [kwargs[name]] -473 for value in values: -474 if value not in enums: -475 raise TypeError( -476 'Parameter "%s" value "%s" is not an allowed value in "%s"' % -477 (name, value, str(enums))) -478 -479 actual_query_params = {} -480 actual_path_params = {} -481 for key, value in kwargs.iteritems(): -482 to_type = param_type.435 +436 for match in URITEMPLATE.finditer(pathUrl): +437 for namematch in VARNAME.finditer(match.group(0)): +438 name = key2param(namematch.group(0)) +439 path_params[name] = name +440 if name in query_params: +441 query_params.remove(name) +442 +443 def method(self, **kwargs): +444 # Don't bother with doc string, it will be over-written by createMethod. +445 for name in kwargs.iterkeys(): +446 if name not in argmap: +447 raise TypeError('Got an unexpected keyword argument "%s"' % name) +448 +449 for name in required_params: +450 if name not in kwargs: +451 raise TypeError('Missing required parameter "%s"' % name) +452 +453 for name, regex in pattern_params.iteritems(): +454 if name in kwargs: +455 if isinstance(kwargs[name], basestring): +456 pvalues = [kwargs[name]] +457 else: +458 pvalues = kwargs[name] +459 for pvalue in pvalues: +460 if re.match(regex, pvalue) is None: +461 raise TypeError( +462 'Parameter "%s" value "%s" does not match the pattern "%s"' % +463 (name, pvalue, regex)) +464 +465 for name, enums in enum_params.iteritems(): +466 if name in kwargs: +467 # We need to handle the case of a repeated enum +468 # name differently, since we want to handle both +469 # arg='value' and arg=['value1', 'value2'] +470 if (name in repeated_params and +471 not isinstance(kwargs[name], basestring)): +472 values = kwargs[name] +473 else: +474 values = [kwargs[name]] +475 for value in values: +476 if value not in enums: +477 raise TypeError( +478 'Parameter "%s" value "%s" is not an allowed value in "%s"' % +479 (name, value, str(enums))) +480 +481 actual_query_params = {} +482 actual_path_params = {} +483 for key, value in kwargs.iteritems(): +484 to_type = param_type.get(key, 'string') -483 # For repeated parameters we cast each member of the list. -484 if key in repeated_params and type(value) == type([]): -485 cast_value = [_cast(x, to_type) for x in value] -486 else: -487 cast_value = _cast(value, to_type) -488 if key in query_params: -489 actual_query_params[argmap[key]] = cast_value -490 if key in path_params: -491 actual_path_params[argmap[key]] = cast_value -492 body_value = kwargs.485 # For repeated parameters we cast each member of the list. +486 if key in repeated_params and type(value) == type([]): +487 cast_value = [_cast(x, to_type) for x in value] +488 else: +489 cast_value = _cast(value, to_type) +490 if key in query_params: +491 actual_query_params[argmap[key]] = cast_value +492 if key in path_params: +493 actual_path_params[argmap[key]] = cast_value +494 body_value = kwargs.get('body', None) -493 media_filename = kwargs.495 media_filename = kwargs.get('media_body', None) -494 -495 if self._developerKey: -496 actual_query_params['key'] = self._developerKey -497 -498 model = self._model -499 # If there is no schema for the response then presume a binary blob. -500 if 'response' not in methodDesc: -501 model = RawModel() -502 -503 headers = {} -504 headers, params, query, body = model.496 +497 if self._developerKey: +498 actual_query_params['key'] = self._developerKey +499 +500 model = self._model +501 # If there is no schema for the response then presume a binary blob. +502 if 'response' not in methodDesc: +503 model = RawModel() +504 +505 headers = {} +506 headers, params, query, body = model.request(headers, -505 actual_path_params, actual_query_params, body_value) -506 -507 expanded_url = uritemplate.expand(pathUrl, params) -508 url = urlparse.urljoin(self._baseUrl, expanded_url + query) -509 -510 507 actual_path_params, actual_query_params, body_value) +508 +509 expanded_url = uritemplate.expand(pathUrl, params) +510 url = urlparse.urljoin(self._baseUrl, expanded_url + query) +511 +512 resumable = None -511 multipart_boundary = '' -512 -513 if media_filename: -514 # Ensure we end up with a valid MediaUpload object. -515 if isinstance(media_filename, basestring): -516 (media_mime_type, encoding) = mimetypes.guess_type(media_filename) -517 if media_mime_type is None: -518 raise UnknownFileType(media_filename) -519 if not mimeparse.best_match([media_mime_type], ','.join(513 multipart_boundary = '' +514 +515 if media_filename: +516 # Ensure we end up with a valid MediaUpload object. +517 if isinstance(media_filename, basestring): +518 (media_mime_type, encoding) = mimetypes.guess_type(media_filename) +519 if media_mime_type is None: +520 raise UnknownFileType(media_filename) +521 if not mimeparse.best_match([media_mime_type], ','.join(accept)): -520 raise UnacceptableMimeTypeError(media_mime_type) -521 media_upload = MediaFileUpload(media_filename, media_mime_type) -522 elif isinstance(media_filename, MediaUpload): -523 media_upload = media_filename -524 else: -525 raise TypeError('media_filename must be str or MediaUpload.') -526 -527 # Check the maxSize -528 if maxSize > 0 and media_upload.522 raise UnacceptableMimeTypeError(media_mime_type) +523 media_upload = MediaFileUpload(media_filename, media_mime_type) +524 elif isinstance(media_filename, MediaUpload): +525 media_upload = media_filename +526 else: +527 raise TypeError('media_filename must be str or MediaUpload.') +528 +529 # Check the maxSize +530 if maxSize > 0 and media_upload.size() > maxSize: -529 raise MediaUploadSizeError("Media larger than: %s" % maxSize) -530 -531 # Use the media path uri for media uploads -532 expanded_url = uritemplate.expand(mediaPathUrl, params) -533 url = urlparse.urljoin(self._baseUrl, expanded_url + query) -534 if media_upload.531 raise MediaUploadSizeError("Media larger than: %s" % maxSize) +532 +533 # Use the media path uri for media uploads +534 expanded_url = uritemplate.expand(mediaPathUrl, params) +535 url = urlparse.urljoin(self._baseUrl, expanded_url + query) +536 if media_upload.resumable(): -535 url = _add_query_parameter(url, 'uploadType', 'resumable') -536 -537 if media_upload.537 url = _add_query_parameter(url, 'uploadType', 'resumable') +538 +539 if media_upload.resumable(): -538 # This is all we need to do for resumable, if the body exists it gets -539 # sent in the first request, otherwise an empty body is sent. -540 540 # This is all we need to do for resumable, if the body exists it gets +541 # sent in the first request, otherwise an empty body is sent. +542 resumable = media_upload -541 else: -542 # A non-resumable upload -543 if body is None: -544 # This is a simple media upload -545 headers['content-type'] = media_upload.543 else: +544 # A non-resumable upload +545 if body is None: +546 # This is a simple media upload +547 headers['content-type'] = media_upload.mimetype() -546 body = media_upload.548 body = media_upload.getbytes(0, media_upload.size()) -547 url = _add_query_parameter(url, 'uploadType', 'media') -548 else: -549 # This is a multipart/related upload. -550 msgRoot = MIMEMultipart('related') -551 # msgRoot should not write out it's own headers -552 setattr(msgRoot, '_write_headers', lambda self: None) -553 -554 # attach the body as one part -555 msg = MIMENonMultipart(*headers['content-type'].split('/')) -556 msg.set_payload(body) -557 msgRoot.attach(msg) -558 -559 # attach the media as the second part -560 msg = MIMENonMultipart(*media_upload.549 url = _add_query_parameter(url, 'uploadType', 'media') +550 else: +551 # This is a multipart/related upload. +552 msgRoot = MIMEMultipart('related') +553 # msgRoot should not write out it's own headers +554 setattr(msgRoot, '_write_headers', lambda self: None) +555 +556 # attach the body as one part +557 msg = MIMENonMultipart(*headers['content-type'].split('/')) +558 msg.set_payload(body) +559 msgRoot.attach(msg) +560 +561 # attach the media as the second part +562 msg = MIMENonMultipart(*media_upload.mimetype().split('/')) -561 msg['Content-Transfer-Encoding'] = 'binary' -562 -563 payload = media_upload.563 msg['Content-Transfer-Encoding'] = 'binary' +564 +565 payload = media_upload.getbytes(0, media_upload.size()) -564 msg.set_payload(payload) -565 msgRoot.attach(msg) -566 body = msgRoot.as_string() -567 -568 multipart_boundary = msgRoot.get_boundary() -569 headers['content-type'] = ('multipart/related; ' -570 'boundary="%s"') % multipart_boundary -571 url = _add_query_parameter(url, 'uploadType', 'multipart') -572 -573 566 msg.set_payload(payload) +567 msgRoot.attach(msg) +568 body = msgRoot.as_string() +569 +570 multipart_boundary = msgRoot.get_boundary() +571 headers['content-type'] = ('multipart/related; ' +572 'boundary="%s"') % multipart_boundary +573 url = _add_query_parameter(url, 'uploadType', 'multipart') +574 +575 logger.info('URL being requested: %s' % url) -574 return self._requestBuilder(self._http, -575 model.576 return self._requestBuilder(self._http, +577 model.response, -576 url, -577 method=httpMethod, -578 body=body, -579 headers=headers, -580 methodId=methodId, -581 578 url, +579 method=httpMethod, +580 body=body, +581 headers=headers, +582 methodId=methodId, +583 resumable=resumable) -582 -583 docs = [methodDesc.584 +585 docs = [methodDesc.get('description', DEFAULT_METHOD_DOC), '\n\n'] -584 if len(argmap) > 0: -585 docs.append('Args:\n') -586 -587 # Skip undocumented params and params common to all methods. -588 skip_parameters = rootDesc.586 if len(argmap) > 0: +587 docs.append('Args:\n') +588 +589 # Skip undocumented params and params common to all methods. +590 skip_parameters = rootDesc.get('parameters', {}).keys() -589 skip_parameters.append(STACK_QUERY_PARAMETERS) -590 -591 for arg in argmap.iterkeys(): -592 if arg in skip_parameters: -593 continue -594 -595 repeated = '' -596 if arg in repeated_params: -597 repeated = ' (repeated)' -598 required = '' -599 if arg in required_params: -600 required = ' (required)' -601 paramdesc = methodDesc['parameters'][argmap[arg]] -602 paramdoc = paramdesc.591 skip_parameters.append(STACK_QUERY_PARAMETERS) +592 +593 for arg in argmap.iterkeys(): +594 if arg in skip_parameters: +595 continue +596 +597 repeated = '' +598 if arg in repeated_params: +599 repeated = ' (repeated)' +600 required = '' +601 if arg in required_params: +602 required = ' (required)' +603 paramdesc = methodDesc['parameters'][argmap[arg]] +604 paramdoc = paramdesc.get('description', 'A parameter') -603 if '$ref' in paramdesc: -604 docs.append( -605 (' %s: object, %s%s%s\n The object takes the' -606 ' form of:\n\n%s\n\n') % (arg, paramdoc, required, repeated, -607 schema.prettyPrintByName(paramdesc['$ref']))) -608 else: -609 paramtype = paramdesc.605 if '$ref' in paramdesc: +606 docs.append( +607 (' %s: object, %s%s%s\n The object takes the' +608 ' form of:\n\n%s\n\n') % (arg, paramdoc, required, repeated, +609 schema.prettyPrintByName(paramdesc['$ref']))) +610 else: +611 paramtype = paramdesc.get('type', 'string') -610 docs.append(' %s: %s, %s%s%s\n' % (arg, paramtype, paramdoc, required, -611 repeated)) -612 enum = paramdesc.612 docs.append(' %s: %s, %s%s%s\n' % (arg, paramtype, paramdoc, required, +613 repeated)) +614 enum = paramdesc.get('enum', []) -613 enumDesc = paramdesc.615 enumDesc = paramdesc.get('enumDescriptions', []) -614 if enum and enumDesc: -615 docs.append(' Allowed values\n') -616 for (name, desc) in zip(enum, enumDesc): -617 docs.append(' %s - %s\n' % (name, desc)) -618 if 'response' in methodDesc: -619 docs.append('\nReturns:\n An object of the form\n\n ') -620 docs.append(schema.prettyPrintSchema(methodDesc['response'])) -621 -622 setattr(method, '__doc__', ''.join(docs)) -623 setattr(theclass, methodName, method) -624 -625 def createNextMethod(theclass, methodName, methodDesc, rootDesc): -626 """Creates any _next methods for attaching to a Resource. -627 -628 The _next methods allow for easy iteration through list() responses. +616 if enum and enumDesc: +617 docs.append(' Allowed values\n') +618 for (name, desc) in zip(enum, enumDesc): +619 docs.append(' %s - %s\n' % (name, desc)) +620 if 'response' in methodDesc: +621 docs.append('\nReturns:\n An object of the form\n\n ') +622 docs.append(schema.prettyPrintSchema(methodDesc['response'])) +623 +624 setattr(method, '__doc__', ''.join(docs)) +625 setattr(theclass, methodName, method) +626 +627 def createNextMethod(theclass, methodName, methodDesc, rootDesc): +628 """Creates any _next methods for attaching to a Resource. 629 -630 Args: -631 theclass: type, the class to attach methods to. -632 methodName: string, name of the method to use. -633 methodDesc: object, fragment of deserialized discovery document that -634 describes the method. -635 rootDesc: object, the entire deserialized discovery document. -636 """ -637 methodName = fix_method_name(methodName) -638 methodId = methodDesc['id'] + '.next' -639 -640 def methodNext(self, previous_request, previous_response): -641 """Retrieves the next page of results. -642 -643 Args: -644 previous_request: The request for the previous page. -645 previous_response: The response from the request for the previous page. -646 -647 Returns: -648 A request object that you can call 'execute()' on to request the next -649 page. Returns None if there are no more items in the collection. -650 """ -651 # Retrieve nextPageToken from previous_response -652 # Use as pageToken in previous_request to create new request. -653 -654 if 'nextPageToken' not in previous_response: -655 return None -656 -657 630 The _next methods allow for easy iteration through list() responses. +631 +632 Args: +633 theclass: type, the class to attach methods to. +634 methodName: string, name of the method to use. +635 methodDesc: object, fragment of deserialized discovery document that +636 describes the method. +637 rootDesc: object, the entire deserialized discovery document. +638 """ +639 methodName = fix_method_name(methodName) +640 methodId = methodDesc['id'] + '.next' +641 +642 def methodNext(self, previous_request, previous_response): +643 """Retrieves the next page of results. +644 +645 Args: +646 previous_request: The request for the previous page. +647 previous_response: The response from the request for the previous page. +648 +649 Returns: +650 A request object that you can call 'execute()' on to request the next +651 page. Returns None if there are no more items in the collection. +652 """ +653 # Retrieve nextPageToken from previous_response +654 # Use as pageToken in previous_request to create new request. +655 +656 if 'nextPageToken' not in previous_response: +657 return None +658 +659 request = copy.copy(previous_request) -658 -659 pageToken = previous_response['nextPageToken'] -660 parsed = list(urlparse.urlparse(660 +661 pageToken = previous_response['nextPageToken'] +662 parsed = list(urlparse.urlparse(request.uri)) -661 q = parse_qsl(parsed[4]) -662 -663 # Find and remove old 'pageToken' value from URI -664 newq = [(key, value) for (key, value) in q if key != 'pageToken'] -665 newq.append(('pageToken', pageToken)) -666 parsed[4] = urllib.urlencode(newq) -667 uri = urlparse.urlunparse(parsed) -668 -669 663 q = parse_qsl(parsed[4]) +664 +665 # Find and remove old 'pageToken' value from URI +666 newq = [(key, value) for (key, value) in q if key != 'pageToken'] +667 newq.append(('pageToken', pageToken)) +668 parsed[4] = urllib.urlencode(newq) +669 uri = urlparse.urlunparse(parsed) +670 +671 request.uri = uri -670 -671 672 +673 logger.info('URL being requested: %s' % uri) -672 -673 return 674 +675 return request -674 -675 setattr(theclass, methodName, methodNext) 676 -677 # Add basic methods to Resource -678 if 'methods' in resourceDesc: -679 for methodName, methodDesc in resourceDesc['methods'].iteritems(): -680 createMethod(Resource, methodName, methodDesc, rootDesc) -681 -682 # Add in nested resources -683 if 'resources' in resourceDesc: -684 -685 def createResourceMethod(theclass, methodName, methodDesc, rootDesc): -686 """Create a method on the Resource to access a nested Resource. -687 -688 Args: -689 theclass: type, the class to attach methods to. -690 methodName: string, name of the method to use. -691 methodDesc: object, fragment of deserialized discovery document that -692 describes the method. -693 rootDesc: object, the entire deserialized discovery document. -694 """ -695 methodName = fix_method_name(methodName) -696 -697 def methodResource(self): -698 return createResource(self._http, self._baseUrl, self._model, -699 self._requestBuilder, self._developerKey, -700 methodDesc, rootDesc, schema) -701 -702 setattr(methodResource, '__doc__', 'A collection resource.') -703 setattr(methodResource, '__is_resource__', True) -704 setattr(theclass, methodName, methodResource) -705 -706 for methodName, methodDesc in resourceDesc['resources'].iteritems(): -707 createResourceMethod(Resource, methodName, methodDesc, rootDesc) -708 -709 # Add _next() methods -710 # Look for response bodies in schema that contain nextPageToken, and methods -711 # that take a pageToken parameter. -712 if 'methods' in resourceDesc: -713 for methodName, methodDesc in resourceDesc['methods'].iteritems(): -714 if 'response' in methodDesc: -715 responseSchema = methodDesc['response'] -716 if '$ref' in responseSchema: -717 responseSchema = schema.677 setattr(theclass, methodName, methodNext) +678 +679 # Add basic methods to Resource +680 if 'methods' in resourceDesc: +681 for methodName, methodDesc in resourceDesc['methods'].iteritems(): +682 createMethod(Resource, methodName, methodDesc, rootDesc) +683 +684 # Add in nested resources +685 if 'resources' in resourceDesc: +686 +687 def createResourceMethod(theclass, methodName, methodDesc, rootDesc): +688 """Create a method on the Resource to access a nested Resource. +689 +690 Args: +691 theclass: type, the class to attach methods to. +692 methodName: string, name of the method to use. +693 methodDesc: object, fragment of deserialized discovery document that +694 describes the method. +695 rootDesc: object, the entire deserialized discovery document. +696 """ +697 methodName = fix_method_name(methodName) +698 +699 def methodResource(self): +700 return createResource(self._http, self._baseUrl, self._model, +701 self._requestBuilder, self._developerKey, +702 methodDesc, rootDesc, schema) +703 +704 setattr(methodResource, '__doc__', 'A collection resource.') +705 setattr(methodResource, '__is_resource__', True) +706 setattr(theclass, methodName, methodResource) +707 +708 for methodName, methodDesc in resourceDesc['resources'].iteritems(): +709 createResourceMethod(Resource, methodName, methodDesc, rootDesc) +710 +711 # Add _next() methods +712 # Look for response bodies in schema that contain nextPageToken, and methods +713 # that take a pageToken parameter. +714 if 'methods' in resourceDesc: +715 for methodName, methodDesc in resourceDesc['methods'].iteritems(): +716 if 'response' in methodDesc: +717 responseSchema = methodDesc['response'] +718 if '$ref' in responseSchema: +719 responseSchema = schema.get(responseSchema['$ref']) -718 hasNextPageToken = 'nextPageToken' in responseSchema.720 hasNextPageToken = 'nextPageToken' in responseSchema.get('properties', -719 {}) -720 hasPageToken = 'pageToken' in methodDesc.721 {}) +722 hasPageToken = 'pageToken' in methodDesc.get('parameters', {}) -721 if hasNextPageToken and hasPageToken: -722 createNextMethod(Resource, methodName + '_next', -723 resourceDesc['methods'][methodName], -724 methodName) -725 -726 return Resource() -727