From d9d00907069794d6149b0a00739b8a934c36c5bf Mon Sep 17 00:00:00 2001 From: Joe Gregorio Date: Fri, 13 Apr 2012 07:58:30 -0400 Subject: [PATCH] Updated docs --- apiclient/http.py | 4 - docs/apiclient.http.html | 457 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 450 insertions(+), 11 deletions(-) diff --git a/apiclient/http.py b/apiclient/http.py index 21455f9..86d6663 100644 --- a/apiclient/http.py +++ b/apiclient/http.py @@ -20,10 +20,6 @@ actuall HTTP request. """ __author__ = 'jcgregorio@google.com (Joe Gregorio)' -__all__ = [ - 'HttpRequest', 'RequestMockBuilder', 'HttpMock' - 'set_user_agent', 'tunnel_patch' - ] import StringIO import base64 diff --git a/docs/apiclient.http.html b/docs/apiclient.http.html index bfdde06..b4c2cc8 100644 --- a/docs/apiclient.http.html +++ b/docs/apiclient.http.html @@ -44,7 +44,19 @@ actuall HTTP request.

__builtin__.object
-
HttpRequest +
BatchHttpRequest +
HttpMock +
HttpMockSequence +
HttpRequest +
HttpRequestMock +
MediaUpload +
+
+
MediaFileUpload +
MediaInMemoryUpload +
+
+
MediaUploadProgress
RequestMockBuilder
@@ -53,6 +65,138 @@ actuall HTTP request.

+ + + + +
 
+class BatchHttpRequest(__builtin__.object)
   Batches multiple HttpRequest objects into a single HTTP request.
 
 Methods defined here:
+
__init__(self, callback=None, batch_uri=None)
Constructor for a BatchHttpRequest.
+ 
+Args:
+  callback: callable, A callback to be called for each response, of the
+    form callback(id, response). The first parameter is the request id, and
+    the second is the deserialized response object.
+  batch_uri: string, URI to send batch requests to.
+ +
add(self, request, callback=None, request_id=None)
Add a new request.
+ 
+Every callback added will be paired with a unique id, the request_id. That
+unique id will be passed back to the callback when the response comes back
+from the server. The default behavior is to have the library generate it's
+own unique id. If the caller passes in a request_id then they must ensure
+uniqueness for each request_id, and if they are not an exception is
+raised. Callers should either supply all request_ids or nevery supply a
+request id, to avoid such an error.
+ 
+Args:
+  request: HttpRequest, Request to add to the batch.
+  callback: callable, A callback to be called for this response, of the
+    form callback(id, response). The first parameter is the request id, and
+    the second is the deserialized response object.
+  request_id: string, A unique id for the request. The id will be passed to
+    the callback with the response.
+ 
+Returns:
+  None
+ 
+Raises:
+  BatchError if a resumable request is added to a batch.
+  KeyError is the request_id is not unique.
+ +
execute(self, http=None)
Execute all the requests as a single batched HTTP request.
+ 
+Args:
+  http: httplib2.Http, an http object to be used in place of the one the
+    HttpRequest request object was constructed with.  If one isn't supplied
+    then use a http object from the requests in this batch.
+ 
+Returns:
+  None
+ 
+Raises:
+  httplib2.Error if a transport error has occured.
+  apiclient.errors.BatchError if the response is the wrong format.
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class HttpMock(__builtin__.object)
   Mock of httplib2.Http
 
 Methods defined here:
+
__init__(self, filename, headers=None)
Args:
+  filename: string, absolute filename to read response from
+  headers: dict, header to return with response
+ +
request(self, uri, method='GET', body=None, headers=None, redirections=1, connection_type=None)
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class HttpMockSequence(__builtin__.object)
   Mock of httplib2.Http
+ 
+Mocks a sequence of calls to request returning different responses for each
+call. Create an instance initialized with the desired response headers
+and content and then use as if an httplib2.Http instance.
+ 
+  http = HttpMockSequence([
+    ({'status': '401'}, ''),
+    ({'status': '200'}, '{"access_token":"1/3w","expires_in":3600}'),
+    ({'status': '200'}, 'echo_request_headers'),
+    ])
+  resp, content = http.request("http://examples.com")
+ 
+There are special values you can pass in for content to trigger
+behavours that are helpful in testing.
+ 
+'echo_request_headers' means return the request headers in the response body
+'echo_request_headers_as_json' means return the request headers in
+   the response body
+'echo_request_body' means return the request body in the response body
+'echo_request_uri' means return the request uri in the response body
 
 Methods defined here:
+
__init__(self, iterable)
Args:
+  iterable: iterable, a sequence of pairs of (headers, body)
+ +
request(self, uri, method='GET', body=None, headers=None, redirections=1, connection_type=None)
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + @@ -71,7 +215,7 @@ Args:
  body: string, the request body of the HTTP request,
  headers: dict, the HTTP request headers
  methodId: string, a unique identifier for the API method being called.
-  resumable: MediaUpload, None if this is not a resumbale request. +  resumable: MediaUpload, None if this is not a resumbale request.
execute(self, http=None)
Execute the request.
 
@@ -90,11 +234,11 @@ Raises:
next_chunk(self, http=None)
Execute the next step of a resumable upload.
 
Can only be used if the method being executed supports media uploads and
-the MediaUpload object passed in was flagged as using resumable upload.
+the MediaUpload object passed in was flagged as using resumable upload.
 
Example:
 
-  media = MediaFileUpload('smiley.png', mimetype='image/png',
+  media = MediaFileUpload('smiley.png', mimetype='image/png',
                          chunksize=1000, resumable=True)
  request = service.objects().insert(
      bucket=buckets['items'][0]['id'],
@@ -118,6 +262,289 @@ Returns:
Static methods defined here:
from_json(s, http, postproc)
Returns an HttpRequest populated with info from a JSON object.
+
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+
 
class HttpRequest(__builtin__.object)
   

+ + + + + + + +
 
+class HttpRequestMock(__builtin__.object)
   Mock of HttpRequest.
+ 
+Do not construct directly, instead use RequestMockBuilder.
 
 Methods defined here:
+
__init__(self, resp, content, postproc)
Constructor for HttpRequestMock
+ 
+Args:
+  resp: httplib2.Response, the response to emulate coming from the request
+  content: string, the response body
+  postproc: callable, the post processing function usually supplied by
+            the model class. See model.JsonModel.response() as an example.
+ +
execute(self, http=None)
Execute the request.
+ 
+Same behavior as HttpRequest.execute(), but the response is
+mocked and not really from an HTTP request/response.
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class MediaFileUpload(MediaUpload)
   A MediaUpload for a file.
+ 
+Construct a MediaFileUpload and pass as the media_body parameter of the
+method. For example, if we had a service that allowed uploading images:
+ 
+ 
+  media = MediaFileUpload('smiley.png', mimetype='image/png', chunksize=1000,
+                  resumable=True)
+  service.objects().insert(
+      bucket=buckets['items'][0]['id'],
+      name='smiley.png',
+      media_body=media).execute()
 
 
Method resolution order:
+
MediaFileUpload
+
MediaUpload
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, filename, mimetype=None, chunksize=262144, resumable=False)
Constructor.
+ 
+Args:
+  filename: string, Name of the file.
+  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
+    used if resumable=True.
+  resumable: bool, True if this is a resumable upload. False means upload
+    in a single request.
+ +
chunksize(self)
+ +
getbytes(self, begin, length)
Get bytes from the media.
+ 
+Args:
+  begin: int, offset from beginning of file.
+  length: int, number of bytes to read, starting at begin.
+ 
+Returns:
+  A string of bytes read. May be shorted than length if EOF was reached
+  first.
+ +
mimetype(self)
+ +
resumable(self)
+ +
size(self)
+ +
to_json(self)
Creating a JSON representation of an instance of Credentials.
+ 
+Returns:
+   string, a JSON representation of this instance, suitable to pass to
+   from_json().
+ +
+Static methods defined here:
+
from_json(s)
+ +
+Class methods inherited from MediaUpload:
+
new_from_json(cls, s) from __builtin__.type
Utility class method to instantiate a MediaUpload subclass from a JSON
+representation produced by to_json().
+ 
+Args:
+  s: string, JSON from to_json().
+ 
+Returns:
+  An instance of the subclass of MediaUpload that was serialized with
+  to_json().
+ +
+Data descriptors inherited from MediaUpload:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class MediaInMemoryUpload(MediaUpload)
   MediaUpload for a chunk of bytes.
+ 
+Construct a MediaFileUpload and pass as the media_body parameter of the
+method. For example, if we had a service that allowed plain text:
 
 
Method resolution order:
+
MediaInMemoryUpload
+
MediaUpload
+
__builtin__.object
+
+
+Methods defined here:
+
__init__(self, body, mimetype='application/octet-stream', chunksize=262144, resumable=False)
Create a new MediaBytesUpload.
+ 
+Args:
+  body: string, Bytes of body content.
+  mimetype: string, Mime-type of the file or default of
+    'application/octet-stream'.
+  chunksize: int, File will be uploaded in chunks of this many bytes. Only
+    used if resumable=True.
+  resumable: bool, True if this is a resumable upload. False means upload
+    in a single request.
+ +
chunksize(self)
Chunk size for resumable uploads.
+ 
+Returns:
+  Chunk size in bytes.
+ +
getbytes(self, begin, length)
Get bytes from the media.
+ 
+Args:
+  begin: int, offset from beginning of file.
+  length: int, number of bytes to read, starting at begin.
+ 
+Returns:
+  A string of bytes read. May be shorter than length if EOF was reached
+  first.
+ +
mimetype(self)
Mime type of the body.
+ 
+Returns:
+  Mime type.
+ +
resumable(self)
Whether this upload is resumable.
+ 
+Returns:
+  True if resumable upload or False.
+ +
size(self)
Size of upload.
+ 
+Returns:
+  Size of the body.
+ +
to_json(self)
Create a JSON representation of a MediaInMemoryUpload.
+ 
+Returns:
+   string, a JSON representation of this instance, suitable to pass to
+   from_json().
+ +
+Static methods defined here:
+
from_json(s)
+ +
+Class methods inherited from MediaUpload:
+
new_from_json(cls, s) from __builtin__.type
Utility class method to instantiate a MediaUpload subclass from a JSON
+representation produced by to_json().
+ 
+Args:
+  s: string, JSON from to_json().
+ 
+Returns:
+  An instance of the subclass of MediaUpload that was serialized with
+  to_json().
+ +
+Data descriptors inherited from MediaUpload:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + +
 
+class MediaUpload(__builtin__.object)
   Describes a media object to upload.
+ 
+Base class that defines the interface of MediaUpload subclasses.
 
 Methods defined here:
+
chunksize(self)
+ +
getbytes(self, begin, end)
+ +
mimetype(self)
+ +
resumable(self)
+ +
size(self)
+ +
to_json(self)
Create a JSON representation of an instance of MediaUpload.
+ 
+Returns:
+   string, a JSON representation of this instance, suitable to pass to
+   from_json().
+ +
+Class methods defined here:
+
new_from_json(cls, s) from __builtin__.type
Utility class method to instantiate a MediaUpload subclass from a JSON
+representation produced by to_json().
+ 
+Args:
+  s: string, JSON from to_json().
+ 
+Returns:
+  An instance of the subclass of MediaUpload that was serialized with
+  to_json().
+ +
+Data descriptors defined here:
+
__dict__
+
dictionary for instance variables (if defined)
+
+
__weakref__
+
list of weak references to the object (if defined)
+
+

+ + + + + + + + - -
 
+class MediaUploadProgress(__builtin__.object)
   Status of a resumable upload.
 
 Methods defined here:
+
__init__(self, resumable_progress, total_size)
Constructor.
+ 
+Args:
+  resumable_progress: int, bytes sent so far.
+  total_size: int, total bytes in complete upload.
+ +
progress(self)
Percent of upload completed, as a float.
+
Data descriptors defined here:
__dict__
@@ -191,7 +618,24 @@ Data descriptors defined here:
Functions
       
tunnel_patch(http)
Tunnel PATCH requests over POST.
+
set_user_agent(http, user_agent)
Set the user-agent on every request.
+ 
+Args:
+   http - An instance of httplib2.Http
+       or something that acts like it.
+   user_agent: string, the value for the user-agent header.
+ 
+Returns:
+   A modified instance of http that was passed in.
+ 
+Example:
+ 
+  h = httplib2.Http()
+  h = set_user_agent(h, "my-app-name/6.0")
+ 
+Most of the time the user-agent will be set doing auth, this is for the rare
+cases where you are accessing an unauthenticated endpoint.
+
tunnel_patch(http)
Tunnel PATCH requests over POST.
Args:
   http - An instance of httplib2.Http
       or something that acts like it.
@@ -214,8 +658,7 @@ will result in a different signature.
Data
       __all__ = ['HttpRequest', 'RequestMockBuilder', 'HttpMockset_user_agent', 'tunnel_patch']
-__author__ = 'jcgregorio@google.com (Joe Gregorio)'

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