From abda96fe2c63e68b5073f8c307b129090f0e2044 Mon Sep 17 00:00:00 2001 From: Joe Gregorio Date: Fri, 11 Feb 2011 20:19:33 -0500 Subject: [PATCH] Added in more documentation, cleaned up use of postproc in HttpRequest and refreshed docs --- apiclient/discovery.py | 50 +++++++++++++++++++--- apiclient/http.py | 16 +++---- apiclient/model.py | 48 ++++++++++++++++++++- docs/apiclient.discovery.html | 42 ++++++++++++++---- docs/apiclient.ext.django_orm.html | 2 +- docs/apiclient.http.html | 12 +++--- docs/apiclient.model.html | 69 ++++++++++++++++++++++++++++-- 7 files changed, 203 insertions(+), 36 deletions(-) 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 @@ based APIs. __author__ = 'jcgregorio@google.com (Joe Gregorio)' +__all__ = [ + 'build', 'build_from_document' + ] import httplib2 import logging @@ -67,6 +70,28 @@ def build(serviceName, version, 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 @@ def build_from_document( 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 @@ def build_from_document( 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 @@ def createResource(http, baseUrl, model, requestBuilder, 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 @@ def createResource(http, baseUrl, model, requestBuilder, 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 @@ class HttpRequest(object): """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 @@ class RequestMockBuilder(object): """ 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 @@ import urllib 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 diff --git a/docs/apiclient.discovery.html b/docs/apiclient.discovery.html index eb11299..dd83c1b 100644 --- a/docs/apiclient.discovery.html +++ b/docs/apiclient.discovery.html @@ -35,8 +35,34 @@ based APIs.

Functions         -
build(serviceName, version, http=None, discoveryServiceUrl='https://www.googleapis.com/discovery/v0.2beta1/describe/{api}/{apiVersion}', developerKey=None, model=<apiclient.model.JsonModel object>, requestBuilder=<class 'apiclient.http.HttpRequest'>)
-
build_from_document(service, base, future=None, http=None, developerKey=None, model=<apiclient.model.JsonModel object>, requestBuilder=<class 'apiclient.http.HttpRequest'>)
Args:
+
build(serviceName, version, http=None, discoveryServiceUrl='https://www.googleapis.com/discovery/v0.2beta1/describe/{api}/{apiVersion}', developerKey=None, model=<apiclient.model.JsonModel object>, requestBuilder=<class 'apiclient.http.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.
+
build_from_document(service, base, future=None, http=None, developerKey=None, model=<apiclient.model.JsonModel object>, requestBuilder=<class 'apiclient.http.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
  future: string, discovery document with future capabilities
@@ -47,9 +73,11 @@ based APIs.

    from the API Console.
  model: Model class instance that serializes and
    de-serializes requests and responses.
-  requestBuilder: Takes an http request and packages it up to be executed.
-
createResource(http, baseUrl, model, requestBuilder, developerKey, resourceDesc, futureDesc)
-
key2param(key)
max-results -> max_results
+  requestBuilder: Takes an http request and packages it up to be executed.
+ 
+Returns:
+  A Resource object with methods for interacting with
+  the service.

@@ -57,9 +85,7 @@ based APIs.

Data -
       DISCOVERY_URI = 'https://www.googleapis.com/discovery/v0.2beta1/describe/{api}/{apiVersion}'
-URITEMPLATE = <_sre.SRE_Pattern object>
-VARNAME = <_sre.SRE_Pattern object>
+		__all__ = ['build', 'build_from_document']
__author__ = 'jcgregorio@google.com (Joe Gregorio)'

diff --git a/docs/apiclient.ext.django_orm.html b/docs/apiclient.ext.django_orm.html index 163f80e..73e8bea 100644 --- a/docs/apiclient.ext.django_orm.html +++ b/docs/apiclient.ext.django_orm.html @@ -8,7 +8,7 @@
 
 
apiclient.ext.django_orm		index
/usr/local/google/home/jcgregorio/projects/apiclient/apiclient/ext/django_orm.py
+>index
/home/jcgregorio/projects/apiary/apiclient/ext/django_orm.py

diff --git a/docs/apiclient.http.html b/docs/apiclient.http.html index 368a1dc..a378677 100644 --- a/docs/apiclient.http.html +++ b/docs/apiclient.http.html @@ -48,19 +48,17 @@ actuall HTTP request.

Encapsulates a single HTTP request.
 
  Methods defined here:
-
__init__(self, http, uri, method='GET', body=None, headers=None, postproc=None, methodId=None)
Constructor for an HttpRequest.
- 
-Only http and uri are required.
+
__init__(self, http, postproc, uri, method='GET', body=None, headers=None, methodId=None)
Constructor for an HttpRequest.
 
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.
execute(self, http=None)
Execute the request.
@@ -115,7 +113,7 @@ is taken from the rpcName in the discovery&nb For more details see the project wiki.
 
  Methods defined here:
-
__call__(self, http, uri, method='GET', body=None, headers=None, postproc=None, methodId=None)
Implements the callable interface that discovery.build() expects
+
__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
parameters and the expected response.
diff --git a/docs/apiclient.model.html b/docs/apiclient.model.html index acb9471..0df4c8f 100644 --- a/docs/apiclient.model.html +++ b/docs/apiclient.model.html @@ -9,7 +9,7 @@  
apiclient.model
index
/home/jcgregorio/projects/apiary/apiclient/model.py
-

Model objects for requests and responses
+

Model objects for requests and responses
 
Each API may support one or more serializations, such
as JSON, Atom, etc. The model classes are responsible
@@ -36,23 +36,34 @@ for converting between the wire format and th

__builtin__.object
+
Model +
+
JsonModel
+
+

+class JsonModel(Model) - -
 
-class JsonModel(__builtin__.object)
   Model class for JSON.
+		Model class for JSON.
 
Serializes and de-serializes between JSON and the Python
object representation of HTTP request and response bodies.
 
 Methods defined here:
+
Method resolution order:
+
JsonModel
+
Model
+
__builtin__.object
+
+
+Methods defined here:
request(self, headers, path_params, query_params, body_value)
Updates outgoing requests with JSON bodies.
 
Args:
@@ -81,6 +92,56 @@ Returns:
Raises:
  apiclient.errors.HttpError if a non 2xx response is received.
+
+Data descriptors inherited from Model:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class Model(__builtin__.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.
 
 Methods defined here:
+
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.
+ +
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.
+
Data descriptors defined here:
__dict__