Updated generated docs
diff --git a/docs/oauth2client.appengine.html b/docs/oauth2client.appengine.html
index 1607892..2265100 100644
--- a/docs/oauth2client.appengine.html
+++ b/docs/oauth2client.appengine.html
@@ -8,7 +8,7 @@
<td valign=bottom> <br>
<font color="#ffffff" face="helvetica, arial"> <br><big><big><strong><a href="oauth2client.html"><font color="#ffffff">oauth2client</font></a>.appengine</strong></big></big></font></td
><td align=right valign=bottom
-><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:/usr/local/google/home/jcgregorio/projects/apiclient/oauth2client/appengine.py">/usr/local/google/home/jcgregorio/projects/apiclient/oauth2client/appengine.py</a></font></td></tr></table>
+><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:/usr/local/google/home/jcgregorio/projects/apiclient-release/oauth2client/appengine.py">/usr/local/google/home/jcgregorio/projects/apiclient-release/oauth2client/appengine.py</a></font></td></tr></table>
<p><tt>Utilities for Google App Engine<br>
<br>
Utilities for making it easier to use OAuth 2.0 on Google App Engine.</tt></p>
@@ -21,14 +21,16 @@
<tr><td bgcolor="#aa55cc"><tt> </tt></td><td> </td>
<td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="google.appengine.api.app_identity.app_identity.html">google.appengine.api.app_identity.app_identity</a><br>
<a href="base64.html">base64</a><br>
-<a href="google.appengine.ext.db.html">google.appengine.ext.db</a><br>
-</td><td width="25%" valign=top><a href="httplib2.html">httplib2</a><br>
-<a href="google.appengine.api.memcache.html">google.appengine.api.memcache</a><br>
+<a href="oauth2client.clientsecrets.html">oauth2client.clientsecrets</a><br>
+</td><td width="25%" valign=top><a href="google.appengine.ext.db.html">google.appengine.ext.db</a><br>
+<a href="httplib2.html">httplib2</a><br>
+<a href="logging.html">logging</a><br>
+</td><td width="25%" valign=top><a href="google.appengine.api.memcache.html">google.appengine.api.memcache</a><br>
<a href="pickle.html">pickle</a><br>
-</td><td width="25%" valign=top><a href="simplejson.html">simplejson</a><br>
-<a href="time.html">time</a><br>
+<a href="simplejson.html">simplejson</a><br>
+</td><td width="25%" valign=top><a href="time.html">time</a><br>
<a href="google.appengine.api.users.html">google.appengine.api.users</a><br>
-</td><td width="25%" valign=top><a href="google.appengine.ext.webapp.html">google.appengine.ext.webapp</a><br>
+<a href="google.appengine.ext.webapp.html">google.appengine.ext.webapp</a><br>
</td></tr></table></td></tr></table><p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#ee77aa">
@@ -41,6 +43,17 @@
</font></dt><dd>
<dl>
<dt><font face="helvetica, arial"><a href="oauth2client.appengine.html#OAuth2Decorator">OAuth2Decorator</a>
+</font></dt><dd>
+<dl>
+<dt><font face="helvetica, arial"><a href="oauth2client.appengine.html#OAuth2DecoratorFromClientSecrets">OAuth2DecoratorFromClientSecrets</a>
+</font></dt></dl>
+</dd>
+</dl>
+</dd>
+<dt><font face="helvetica, arial"><a href="exceptions.html#Exception">exceptions.Exception</a>(<a href="exceptions.html#BaseException">exceptions.BaseException</a>)
+</font></dt><dd>
+<dl>
+<dt><font face="helvetica, arial"><a href="oauth2client.appengine.html#InvalidClientSecretsError">InvalidClientSecretsError</a>
</font></dt></dl>
</dd>
<dt><font face="helvetica, arial"><a href="google.appengine.ext.db.html#Model">google.appengine.ext.db.Model</a>(<a href="__builtin__.html#object">__builtin__.object</a>)
@@ -95,9 +108,7 @@
<br>
This credential does not require a flow to instantiate because it represents<br>
a two legged flow, and therefore has all of the required information to<br>
-generate and refresh its own access tokens.<br>
- <br>
-AssertionFlowCredentials objects may be safely pickled and unpickled.<br> </tt></td></tr>
+generate and refresh its own access tokens.<br> </tt></td></tr>
<tr><td> </td>
<td width="100%"><dl><dt>Method resolution order:</dt>
<dd><a href="oauth2client.appengine.html#AppAssertionCredentials">AppAssertionCredentials</a></dd>
@@ -525,8 +536,6 @@
</dl>
<hr>
Methods defined here:<br>
-<dl><dt><a name="CredentialsProperty-empty"><strong>empty</strong></a>(self, value)</dt></dl>
-
<dl><dt><a name="CredentialsProperty-get_value_for_datastore"><strong>get_value_for_datastore</strong></a>(self, model_instance)</dt><dd><tt># For writing to datastore.</tt></dd></dl>
<dl><dt><a name="CredentialsProperty-make_value_from_datastore"><strong>make_value_from_datastore</strong></a>(self, value)</dt><dd><tt># For reading from datastore.</tt></dd></dl>
@@ -585,6 +594,19 @@
Returns:<br>
Default value as provided by <a href="#CredentialsProperty-__init__">__init__</a>(default).</tt></dd></dl>
+<dl><dt><a name="CredentialsProperty-empty"><strong>empty</strong></a>(self, value)</dt><dd><tt>Determine if value is empty in the context of this property.<br>
+ <br>
+For most kinds, this is equivalent to "not value", but for kinds like<br>
+bool, the test is more subtle, so subclasses can override this method<br>
+if necessary.<br>
+ <br>
+Args:<br>
+ value: Value to validate against this <a href="google.appengine.ext.db.html#Property">Property</a>.<br>
+ <br>
+Returns:<br>
+ True if this value is considered empty in the context of this <a href="google.appengine.ext.db.html#Property">Property</a><br>
+ type, otherwise False.</tt></dd></dl>
+
<hr>
Data descriptors inherited from <a href="google.appengine.ext.db.html#Property">google.appengine.ext.db.Property</a>:<br>
<dl><dt><strong>__dict__</strong></dt>
@@ -686,6 +708,66 @@
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#ffc8d8">
<td colspan=3 valign=bottom> <br>
+<font color="#000000" face="helvetica, arial"><a name="InvalidClientSecretsError">class <strong>InvalidClientSecretsError</strong></a>(<a href="exceptions.html#Exception">exceptions.Exception</a>)</font></td></tr>
+
+<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
+<td colspan=2><tt>The client_secrets.json file is malformed or missing required fields.<br> </tt></td></tr>
+<tr><td> </td>
+<td width="100%"><dl><dt>Method resolution order:</dt>
+<dd><a href="oauth2client.appengine.html#InvalidClientSecretsError">InvalidClientSecretsError</a></dd>
+<dd><a href="exceptions.html#Exception">exceptions.Exception</a></dd>
+<dd><a href="exceptions.html#BaseException">exceptions.BaseException</a></dd>
+<dd><a href="__builtin__.html#object">__builtin__.object</a></dd>
+</dl>
+<hr>
+Data descriptors defined here:<br>
+<dl><dt><strong>__weakref__</strong></dt>
+<dd><tt>list of weak references to the object (if defined)</tt></dd>
+</dl>
+<hr>
+Methods inherited from <a href="exceptions.html#Exception">exceptions.Exception</a>:<br>
+<dl><dt><a name="InvalidClientSecretsError-__init__"><strong>__init__</strong></a>(...)</dt><dd><tt>x.<a href="#InvalidClientSecretsError-__init__">__init__</a>(...) initializes x; see x.__class__.__doc__ for signature</tt></dd></dl>
+
+<hr>
+Data and other attributes inherited from <a href="exceptions.html#Exception">exceptions.Exception</a>:<br>
+<dl><dt><strong>__new__</strong> = <built-in method __new__ of type object><dd><tt>T.<a href="#InvalidClientSecretsError-__new__">__new__</a>(S, ...) -> a new <a href="__builtin__.html#object">object</a> with type S, a subtype of T</tt></dl>
+
+<hr>
+Methods inherited from <a href="exceptions.html#BaseException">exceptions.BaseException</a>:<br>
+<dl><dt><a name="InvalidClientSecretsError-__delattr__"><strong>__delattr__</strong></a>(...)</dt><dd><tt>x.<a href="#InvalidClientSecretsError-__delattr__">__delattr__</a>('name') <==> del x.name</tt></dd></dl>
+
+<dl><dt><a name="InvalidClientSecretsError-__getattribute__"><strong>__getattribute__</strong></a>(...)</dt><dd><tt>x.<a href="#InvalidClientSecretsError-__getattribute__">__getattribute__</a>('name') <==> x.name</tt></dd></dl>
+
+<dl><dt><a name="InvalidClientSecretsError-__getitem__"><strong>__getitem__</strong></a>(...)</dt><dd><tt>x.<a href="#InvalidClientSecretsError-__getitem__">__getitem__</a>(y) <==> x[y]</tt></dd></dl>
+
+<dl><dt><a name="InvalidClientSecretsError-__getslice__"><strong>__getslice__</strong></a>(...)</dt><dd><tt>x.<a href="#InvalidClientSecretsError-__getslice__">__getslice__</a>(i, j) <==> x[i:j]<br>
+ <br>
+Use of negative indices is not supported.</tt></dd></dl>
+
+<dl><dt><a name="InvalidClientSecretsError-__reduce__"><strong>__reduce__</strong></a>(...)</dt></dl>
+
+<dl><dt><a name="InvalidClientSecretsError-__repr__"><strong>__repr__</strong></a>(...)</dt><dd><tt>x.<a href="#InvalidClientSecretsError-__repr__">__repr__</a>() <==> repr(x)</tt></dd></dl>
+
+<dl><dt><a name="InvalidClientSecretsError-__setattr__"><strong>__setattr__</strong></a>(...)</dt><dd><tt>x.<a href="#InvalidClientSecretsError-__setattr__">__setattr__</a>('name', value) <==> x.name = value</tt></dd></dl>
+
+<dl><dt><a name="InvalidClientSecretsError-__setstate__"><strong>__setstate__</strong></a>(...)</dt></dl>
+
+<dl><dt><a name="InvalidClientSecretsError-__str__"><strong>__str__</strong></a>(...)</dt><dd><tt>x.<a href="#InvalidClientSecretsError-__str__">__str__</a>() <==> str(x)</tt></dd></dl>
+
+<dl><dt><a name="InvalidClientSecretsError-__unicode__"><strong>__unicode__</strong></a>(...)</dt></dl>
+
+<hr>
+Data descriptors inherited from <a href="exceptions.html#BaseException">exceptions.BaseException</a>:<br>
+<dl><dt><strong>__dict__</strong></dt>
+</dl>
+<dl><dt><strong>args</strong></dt>
+</dl>
+<dl><dt><strong>message</strong></dt>
+</dl>
+</td></tr></table> <p>
+<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
+<tr bgcolor="#ffc8d8">
+<td colspan=3 valign=bottom> <br>
<font color="#000000" face="helvetica, arial"><a name="OAuth2Decorator">class <strong>OAuth2Decorator</strong></a>(<a href="__builtin__.html#object">__builtin__.object</a>)</font></td></tr>
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
@@ -699,7 +781,7 @@
decorator = <a href="#OAuth2Decorator">OAuth2Decorator</a>(<br>
client_id='837...ent.com',<br>
client_secret='Qh...wwI',<br>
- scope='https://www.googleapis.com/auth/buzz')<br>
+ scope='https://www.googleapis.com/auth/plus')<br>
<br>
<br>
class MainHandler(webapp.<a href="google.appengine.ext.webapp.html#RequestHandler">RequestHandler</a>):<br>
@@ -711,16 +793,20 @@
# in API calls<br> </tt></td></tr>
<tr><td> </td>
<td width="100%">Methods defined here:<br>
-<dl><dt><a name="OAuth2Decorator-__init__"><strong>__init__</strong></a>(self, client_id, client_secret, scope, auth_uri<font color="#909090">='https://accounts.google.com/o/oauth2/auth'</font>, token_uri<font color="#909090">='https://accounts.google.com/o/oauth2/token'</font>)</dt><dd><tt>Constructor for <a href="#OAuth2Decorator">OAuth2Decorator</a><br>
+<dl><dt><a name="OAuth2Decorator-__init__"><strong>__init__</strong></a>(self, client_id, client_secret, scope, auth_uri<font color="#909090">='https://accounts.google.com/o/oauth2/auth'</font>, token_uri<font color="#909090">='https://accounts.google.com/o/oauth2/token'</font>, message<font color="#909090">=None</font>)</dt><dd><tt>Constructor for <a href="#OAuth2Decorator">OAuth2Decorator</a><br>
<br>
Args:<br>
client_id: string, client identifier.<br>
client_secret: string client secret.<br>
- scope: string, scope of the credentials being requested.<br>
+ scope: string or list of strings, scope(s) of the credentials being<br>
+ requested.<br>
auth_uri: string, URI for authorization endpoint. For convenience<br>
defaults to Google's endpoints but any OAuth 2.0 provider can be used.<br>
token_uri: string, URI for token endpoint. For convenience<br>
- defaults to Google's endpoints but any OAuth 2.0 provider can be used.</tt></dd></dl>
+ defaults to Google's endpoints but any OAuth 2.0 provider can be used.<br>
+ message: Message to display if there are problems with the OAuth 2.0<br>
+ configuration. The message may contain HTML and will be presented on the<br>
+ web interface for any method that uses the decorator.</tt></dd></dl>
<dl><dt><a name="OAuth2Decorator-authorize_url"><strong>authorize_url</strong></a>(self)</dt><dd><tt>Returns the URL to start the OAuth dance.<br>
<br>
@@ -771,6 +857,97 @@
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#ffc8d8">
<td colspan=3 valign=bottom> <br>
+<font color="#000000" face="helvetica, arial"><a name="OAuth2DecoratorFromClientSecrets">class <strong>OAuth2DecoratorFromClientSecrets</strong></a>(<a href="oauth2client.appengine.html#OAuth2Decorator">OAuth2Decorator</a>)</font></td></tr>
+
+<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
+<td colspan=2><tt>An <a href="#OAuth2Decorator">OAuth2Decorator</a> that builds from a clientsecrets file.<br>
+ <br>
+Uses a clientsecrets file as the source for all the information when<br>
+constructing an <a href="#OAuth2Decorator">OAuth2Decorator</a>.<br>
+ <br>
+Example:<br>
+ <br>
+ decorator = <a href="#OAuth2DecoratorFromClientSecrets">OAuth2DecoratorFromClientSecrets</a>(<br>
+ os.path.join(os.path.dirname(__file__), 'client_secrets.json')<br>
+ scope='https://www.googleapis.com/auth/plus')<br>
+ <br>
+ <br>
+ class MainHandler(webapp.<a href="google.appengine.ext.webapp.html#RequestHandler">RequestHandler</a>):<br>
+ <br>
+ @decorator.oauth_required<br>
+ def get(self):<br>
+ http = decorator.<a href="#OAuth2DecoratorFromClientSecrets-http">http</a>()<br>
+ # http is authorized with the user's Credentials and can be used<br>
+ # in API calls<br> </tt></td></tr>
+<tr><td> </td>
+<td width="100%"><dl><dt>Method resolution order:</dt>
+<dd><a href="oauth2client.appengine.html#OAuth2DecoratorFromClientSecrets">OAuth2DecoratorFromClientSecrets</a></dd>
+<dd><a href="oauth2client.appengine.html#OAuth2Decorator">OAuth2Decorator</a></dd>
+<dd><a href="__builtin__.html#object">__builtin__.object</a></dd>
+</dl>
+<hr>
+Methods defined here:<br>
+<dl><dt><a name="OAuth2DecoratorFromClientSecrets-__init__"><strong>__init__</strong></a>(self, filename, scope, message<font color="#909090">=None</font>)</dt><dd><tt>Constructor<br>
+ <br>
+Args:<br>
+ filename: string, File name of client secrets.<br>
+ scope: string, Space separated list of scopes.<br>
+ message: string, A friendly string to display to the user if the<br>
+ clientsecrets file is missing or invalid. The message may contain HTML and<br>
+ will be presented on the web interface for any method that uses the<br>
+ decorator.</tt></dd></dl>
+
+<hr>
+Methods inherited from <a href="oauth2client.appengine.html#OAuth2Decorator">OAuth2Decorator</a>:<br>
+<dl><dt><a name="OAuth2DecoratorFromClientSecrets-authorize_url"><strong>authorize_url</strong></a>(self)</dt><dd><tt>Returns the URL to start the OAuth dance.<br>
+ <br>
+Must only be called from with a webapp.<a href="google.appengine.ext.webapp.html#RequestHandler">RequestHandler</a> subclassed method<br>
+that had been decorated with either @oauth_required or @oauth_aware.</tt></dd></dl>
+
+<dl><dt><a name="OAuth2DecoratorFromClientSecrets-has_credentials"><strong>has_credentials</strong></a>(self)</dt><dd><tt>True if for the logged in user there are valid access Credentials.<br>
+ <br>
+Must only be called from with a webapp.<a href="google.appengine.ext.webapp.html#RequestHandler">RequestHandler</a> subclassed method<br>
+that had been decorated with either @oauth_required or @oauth_aware.</tt></dd></dl>
+
+<dl><dt><a name="OAuth2DecoratorFromClientSecrets-http"><strong>http</strong></a>(self)</dt><dd><tt>Returns an authorized http instance.<br>
+ <br>
+Must only be called from within an @oauth_required decorated method, or<br>
+from within an @oauth_aware decorated method where <a href="#OAuth2DecoratorFromClientSecrets-has_credentials">has_credentials</a>()<br>
+returns True.</tt></dd></dl>
+
+<dl><dt><a name="OAuth2DecoratorFromClientSecrets-oauth_aware"><strong>oauth_aware</strong></a>(self, method)</dt><dd><tt>Decorator that sets up for OAuth 2.0 dance, but doesn't do it.<br>
+ <br>
+Does all the setup for the OAuth dance, but doesn't initiate it.<br>
+This decorator is useful if you want to create a page that knows<br>
+whether or not the user has granted access to this application.<br>
+From within a method decorated with @oauth_aware the <a href="#OAuth2DecoratorFromClientSecrets-has_credentials">has_credentials</a>()<br>
+and <a href="#OAuth2DecoratorFromClientSecrets-authorize_url">authorize_url</a>() methods can be called.<br>
+ <br>
+Args:<br>
+ method: callable, to be decorated method of a webapp.<a href="google.appengine.ext.webapp.html#RequestHandler">RequestHandler</a><br>
+ instance.</tt></dd></dl>
+
+<dl><dt><a name="OAuth2DecoratorFromClientSecrets-oauth_required"><strong>oauth_required</strong></a>(self, method)</dt><dd><tt>Decorator that starts the OAuth 2.0 dance.<br>
+ <br>
+Starts the OAuth dance for the logged in user if they haven't already<br>
+granted access for this application.<br>
+ <br>
+Args:<br>
+ method: callable, to be decorated method of a webapp.<a href="google.appengine.ext.webapp.html#RequestHandler">RequestHandler</a><br>
+ instance.</tt></dd></dl>
+
+<hr>
+Data descriptors inherited from <a href="oauth2client.appengine.html#OAuth2Decorator">OAuth2Decorator</a>:<br>
+<dl><dt><strong>__dict__</strong></dt>
+<dd><tt>dictionary for instance variables (if defined)</tt></dd>
+</dl>
+<dl><dt><strong>__weakref__</strong></dt>
+<dd><tt>list of weak references to the object (if defined)</tt></dd>
+</dl>
+</td></tr></table> <p>
+<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
+<tr bgcolor="#ffc8d8">
+<td colspan=3 valign=bottom> <br>
<font color="#000000" face="helvetica, arial"><a name="OAuth2Handler">class <strong>OAuth2Handler</strong></a>(<a href="google.appengine.ext.webapp.html#RequestHandler">google.appengine.ext.webapp.RequestHandler</a>)</font></td></tr>
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
@@ -917,12 +1094,12 @@
property_name: string, name of the property that is a <a href="#CredentialsProperty">CredentialsProperty</a><br>
cache: memcache, a write-through cache to put in front of the datastore</tt></dd></dl>
-<dl><dt><a name="StorageByKeyName-get"><strong>get</strong></a>(self)</dt><dd><tt>Retrieve Credential from datastore.<br>
+<dl><dt><a name="StorageByKeyName-locked_get"><strong>locked_get</strong></a>(self)</dt><dd><tt>Retrieve Credential from datastore.<br>
<br>
Returns:<br>
oauth2client.Credentials</tt></dd></dl>
-<dl><dt><a name="StorageByKeyName-put"><strong>put</strong></a>(self, credentials)</dt><dd><tt>Write a Credentials to the datastore.<br>
+<dl><dt><a name="StorageByKeyName-locked_put"><strong>locked_put</strong></a>(self, credentials)</dt><dd><tt>Write a Credentials to the datastore.<br>
<br>
Args:<br>
credentials: Credentials, the credentials to store.</tt></dd></dl>
@@ -933,14 +1110,14 @@
<br>
This lock is not reentrant.</tt></dd></dl>
-<dl><dt><a name="StorageByKeyName-locked_get"><strong>locked_get</strong></a>(self)</dt><dd><tt>Retrieve credential.<br>
+<dl><dt><a name="StorageByKeyName-get"><strong>get</strong></a>(self)</dt><dd><tt>Retrieve credential.<br>
<br>
-The <a href="oauth2client.client.html#Storage">Storage</a> lock must be held when this is called.<br>
+The <a href="oauth2client.client.html#Storage">Storage</a> lock must *not* be held when this is called.<br>
<br>
Returns:<br>
oauth2client.client.Credentials</tt></dd></dl>
-<dl><dt><a name="StorageByKeyName-locked_put"><strong>locked_put</strong></a>(self, credentials)</dt><dd><tt>Write a credential.<br>
+<dl><dt><a name="StorageByKeyName-put"><strong>put</strong></a>(self, credentials)</dt><dd><tt>Write a credential.<br>
<br>
The <a href="oauth2client.client.html#Storage">Storage</a> lock must be held when this is called.<br>
<br>
@@ -968,6 +1145,17 @@
<tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td>
<td width="100%"><dl><dt><a name="-main"><strong>main</strong></a>()</dt></dl>
+ <dl><dt><a name="-oauth2decorator_from_clientsecrets"><strong>oauth2decorator_from_clientsecrets</strong></a>(filename, scope, message<font color="#909090">=None</font>)</dt><dd><tt>Creates an <a href="#OAuth2Decorator">OAuth2Decorator</a> populated from a clientsecrets file.<br>
+ <br>
+Args:<br>
+ filename: string, File name of client secrets.<br>
+ scope: string, Space separated list of scopes.<br>
+ message: string, A friendly string to display to the user if the<br>
+ clientsecrets file is missing or invalid. The message may contain HTML and<br>
+ will be presented on the web interface for any method that uses the<br>
+ decorator.<br>
+ <br>
+Returns: An <a href="#OAuth2Decorator">OAuth2Decorator</a></tt></dd></dl>
</td></tr></table><p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#55aa55">