apiclient/discovery.py

# Copyright (C) 2010 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Client for discovery based APIs

A client library for Google's discovery
based APIs.
"""

__author__ = 'jcgregorio@google.com (Joe Gregorio)'


import httplib2
import logging
import re
import simplejson
import urlparse
import uritemplate


class HttpError(Exception):
  pass

DISCOVERY_URI = 'http://www.googleapis.com/discovery/0.1/describe\
{?api,apiVersion}'


def key2method(key):
  """
  max-results -> MaxResults
  """
  result = []
  key = list(key)
  newWord = True
  if not key[0].isalpha():
    result.append('X')
    newWord = False
  for c in key:
    if c.isalnum():
      if newWord:
        result.append(c.upper())
        newWord = False
      else:
        result.append(c.lower())
    else:
      newWord = True

  return ''.join(result)


def key2param(key):
  """
  max-results -> max_results
  """
  result = []
  key = list(key)
  if not key[0].isalpha():
    result.append('x')
  for c in key:
    if c.isalnum():
      result.append(c)
    else:
      result.append('_')

  return ''.join(result)


class JsonModel(object):

  def request(self, headers, path_params, query_params, body_value):
    query = self.build_query(query_params)
    headers['accept'] = 'application/json'
    if body_value is None:
      return (headers, path_params, query, None)
    else:
      model = {'data': body_value}
      headers['content-type'] = 'application/json'
      return (headers, path_params, query, simplejson.dumps(model))

  def build_query(self, params):
    query = '?alt=json&prettyprint=true'
    for key,value in params.iteritems():
      query += '&%s=%s' % (key, value)
    return query

  def response(self, resp, content):
    # Error handling is TBD, for example, do we retry
    # for some operation/error combinations?
    if resp.status < 300:
      return simplejson.loads(content)['data']
    else:
      logging.debug('Content from bad request was: %s' % content)
      if resp['content-type'] != 'application/json':
        raise HttpError('%d %s' % (resp.status, resp.reason))
      else:
        raise HttpError(simplejson.loads(content)['error'])


def build(service, version, http=httplib2.Http(),
    discoveryServiceUrl=DISCOVERY_URI, auth=None, model=JsonModel()):
  params = {
      'api': service,
      'apiVersion': version
      }

  requested_url = uritemplate.expand(discoveryServiceUrl, params)
  logging.info('URL being requested: %s' % requested_url)
  resp, content = http.request(requested_url)
  d = simplejson.loads(content)
  service = d['data'][service][version]
  base = service['baseUrl']
  resources = service['resources']

  class Service(object):
    """Top level interface for a service"""

    def __init__(self, http=http):
      self._http = http
      self._baseUrl = base
      self._model = model

  def createMethod(theclass, methodName, methodDesc):

    def method(self, **kwargs):
      return createResource(self._http, self._baseUrl, self._model,
          methodName, methodDesc)

    setattr(method, '__doc__', 'A description of how to use this function')
    setattr(theclass, methodName, method)

  for methodName, methodDesc in resources.iteritems():
    createMethod(Service, methodName, methodDesc)
  return Service()


def createResource(http, baseUrl, model, resourceName, resourceDesc):

  class Resource(object):
    """A class for interacting with a resource."""

    def __init__(self):
      self._http = http
      self._baseUrl = baseUrl
      self._model = model

  def createMethod(theclass, methodName, methodDesc):
    pathUrl = methodDesc['pathUrl']
    pathUrl = re.sub(r'\{', r'{+', pathUrl)
    httpMethod = methodDesc['httpMethod']

    argmap = {}
    if httpMethod in ['PUT', 'POST']:
      argmap['body'] = 'body'


    required_params = [] # Required parameters
    pattern_params = {}  # Parameters that must match a regex
    query_params = [] # Parameters that will be used in the query string
    path_params = {} # Parameters that will be used in the base URL
    for arg, desc in methodDesc['parameters'].iteritems():
      param = key2param(arg)
      argmap[param] = arg

      if desc.get('pattern', ''):
        pattern_params[param] = desc['pattern']
      if desc.get('required', False):
        required_params.append(param)
      if desc.get('parameterType') == 'query':
        query_params.append(param)
      if desc.get('parameterType') == 'path':
        path_params[param]=param

    def method(self, **kwargs):
      for name in kwargs.iterkeys():
        if name not in argmap:
          raise TypeError('Got an unexpected keyword argument "%s"' % name)

      for name in required_params:
        if name not in kwargs:
          raise TypeError('Missing required parameter "%s"' % name)

      for name, regex in pattern_params.iteritems():
        if name in kwargs:
          if re.match(regex, kwargs[name]) is None:
            raise TypeError('Parameter "%s" value "%s" does not match the pattern "%s"' % (name, kwargs[name], regex))

      actual_query_params = {}
      actual_path_params = {}
      for key, value in kwargs.iteritems():
        if key in query_params:
          actual_query_params[argmap[key]] = value
        if key in path_params:
          actual_path_params[argmap[key]] = value
      body_value = kwargs.get('body', None)

      headers = {}
      headers, params, query, body = self._model.request(headers, actual_path_params, actual_query_params, body_value)

      expanded_url = uritemplate.expand(pathUrl, params) 
      url = urlparse.urljoin(self._baseUrl, expanded_url + query)

      logging.info('URL being requested: %s' % url)
      resp, content = self._http.request(
          url, method=httpMethod, headers=headers, body=body)

      return self._model.response(resp, content)

    docs = ['A description of how to use this function\n\n']
    for arg in argmap.iterkeys():
      docs.append('%s - A parameter\n' % arg)

    setattr(method, '__doc__', ''.join(docs))
    setattr(theclass, methodName, method)

  for methodName, methodDesc in resourceDesc['methods'].iteritems():
    createMethod(Resource, methodName, methodDesc)

  return Resource()