Added in more documentation, cleaned up use of postproc in HttpRequest and refreshed docs
diff --git a/apiclient/discovery.py b/apiclient/discovery.py
index b557b8b..fa796ed 100644
--- a/apiclient/discovery.py
+++ b/apiclient/discovery.py
@@ -20,6 +20,9 @@
__author__ = 'jcgregorio@google.com (Joe Gregorio)'
+__all__ = [
+ 'build', 'build_from_document'
+ ]
import httplib2
import logging
@@ -67,6 +70,28 @@
developerKey=None,
model=JsonModel(),
requestBuilder=HttpRequest):
+ """Construct a Resource for interacting with an API.
+
+ Construct a Resource object for interacting with
+ an API. The serviceName and version are the
+ names from the Discovery service.
+
+ Args:
+ serviceName: string, name of the service
+ version: string, the version of the service
+ discoveryServiceUrl: string, a URI Template that points to
+ the location of the discovery service. It should have two
+ parameters {api} and {apiVersion} that when filled in
+ produce an absolute URI to the discovery document for
+ that service.
+ developerKey: string, key obtained from https://code.google.com/apis/console
+ model: apiclient.Model, converts to and from the wire format
+ requestBuilder: apiclient.http.HttpRequest, encapsulator for an HTTP request
+
+ Returns:
+ A Resource object with methods for interacting with
+ the service.
+ """
params = {
'api': serviceName,
'apiVersion': version
@@ -100,7 +125,12 @@
developerKey=None,
model=JsonModel(),
requestBuilder=HttpRequest):
- """
+ """Create a Resource for interacting with an API.
+
+ Same as `build()`, but constructs the Resource object
+ from a discovery document that is it given, as opposed to
+ retrieving one over HTTP.
+
Args:
service: string, discovery document
base: string, base URI for all HTTP requests, usually the discovery URI
@@ -113,6 +143,10 @@
model: Model class instance that serializes and
de-serializes requests and responses.
requestBuilder: Takes an http request and packages it up to be executed.
+
+ Returns:
+ A Resource object with methods for interacting with
+ the service.
"""
service = simplejson.loads(service)
@@ -229,10 +263,12 @@
url_result.path + expanded_url + query)
logging.info('URL being requested: %s' % url)
- return self._requestBuilder(self._http, url,
- method=httpMethod, body=body,
+ return self._requestBuilder(self._http,
+ self._model.response,
+ url,
+ method=httpMethod,
+ body=body,
headers=headers,
- postproc=self._model.response,
methodId=methodId)
docs = ['A description of how to use this function\n\n']
@@ -281,9 +317,11 @@
logging.info('URL being requested: %s' % url)
resp, content = self._http.request(url, method='GET', headers=headers)
- return self._requestBuilder(self._http, url, method='GET',
+ return self._requestBuilder(self._http,
+ self._model.response,
+ url,
+ method='GET',
headers=headers,
- postproc=self._model.response,
methodId=methodId)
setattr(theclass, methodName, method)
diff --git a/apiclient/http.py b/apiclient/http.py
index 31a8fe8..85ff93a 100644
--- a/apiclient/http.py
+++ b/apiclient/http.py
@@ -20,21 +20,19 @@
"""Encapsulates a single HTTP request.
"""
- def __init__(self, http, uri, method="GET", body=None, headers=None,
- postproc=None, methodId=None):
+ def __init__(self, http, postproc, uri, method="GET", body=None, headers=None,
+ methodId=None):
"""Constructor for an HttpRequest.
- Only http and uri are required.
-
Args:
http: httplib2.Http, the transport object to use to make a request
+ postproc: callable, called on the HTTP response and content to transform
+ it into a data object before returning, or raising an exception
+ on an error.
uri: string, the absolute URI to send the request to
method: string, the HTTP method to use
body: string, the request body of the HTTP request
headers: dict, the HTTP request headers
- postproc: callable, called on the HTTP response and content to transform
- it into a data object before returning, or raising an exception
- on an error.
methodId: string, a unique identifier for the API method being called.
"""
self.uri = uri
@@ -136,8 +134,8 @@
"""
self.responses = responses
- def __call__(self, http, uri, method="GET", body=None, headers=None,
- postproc=None, methodId=None):
+ def __call__(self, http, postproc, uri, method="GET", body=None,
+ headers=None, methodId=None):
"""Implements the callable interface that discovery.build() expects
of requestBuilder, which is to build an object compatible with
HttpRequest.execute(). See that method for the description of the
diff --git a/apiclient/model.py b/apiclient/model.py
index cd81c0b..1f2e1c1 100644
--- a/apiclient/model.py
+++ b/apiclient/model.py
@@ -18,8 +18,54 @@
from anyjson import simplejson
from errors import HttpError
+def _abstract():
+ raise NotImplementedError('You need to override this function')
-class JsonModel(object):
+
+class Model(object):
+ """Model base class.
+
+ All Model classes should implement this interface.
+ The Model serializes and de-serializes between a wire
+ format such as JSON and a Python object representation.
+ """
+
+ def request(self, headers, path_params, query_params, body_value):
+ """Updates outgoing requests with a deserialized body.
+
+ Args:
+ headers: dict, request headers
+ path_params: dict, parameters that appear in the request path
+ query_params: dict, parameters that appear in the query
+ body_value: object, the request body as a Python object, which must be
+ serializable.
+ Returns:
+ A tuple of (headers, path_params, query, body)
+
+ headers: dict, request headers
+ path_params: dict, parameters that appear in the request path
+ query: string, query part of the request URI
+ body: string, the body serialized in the desired wire format.
+ """
+ _abstract()
+
+ def response(self, resp, content):
+ """Convert the response wire format into a Python object.
+
+ Args:
+ resp: httplib2.Response, the HTTP response headers and status
+ content: string, the body of the HTTP response
+
+ Returns:
+ The body de-serialized as a Python object.
+
+ Raises:
+ apiclient.errors.HttpError if a non 2xx response is received.
+ """
+ _abstract()
+
+
+class JsonModel(Model):
"""Model class for JSON.
Serializes and de-serializes between JSON and the Python