Clean up README and add lots of comments to moderator.py
diff --git a/README b/README
index dd951a8..38f18b5 100644
--- a/README
+++ b/README
@@ -29,24 +29,24 @@
Running
=======
-First run three-legged-dance.py to get OAuth
-tokens for Buzz, which will be stored in
-buzz.dat in the working directory.
-
- $ python samples/buzz/three_legged_dance.py
-
-Then run buzz.py, which will use the apiclient
+Run buzz.py, which will use the apiclient
library to retrieve the title of the most
recent entry in Buzz and post a test message.
+The first time you run it you will be prompted
+to authorize the application to access your
+Buzz information.
$ python samples/buzz/buzz.py
After following the install directions (using setup.py or setpath.sh) you
-should be able to cd to samples/cmdline and run the code from there.
+should be able to cd to samples/buzz and run the code from there.
Third Party Libraries
-====================
+=====================
+
+These libraries should be installed when you install the client library, either
+automatically if you have setuptools installed, or manually if you do not:
http://code.google.com/p/httplib2
http://code.google.com/p/uri-templates
diff --git a/apiclient/discovery.py b/apiclient/discovery.py
index 2c89528..df01aa0 100644
--- a/apiclient/discovery.py
+++ b/apiclient/discovery.py
@@ -48,7 +48,7 @@
DEFAULT_METHOD_DOC = 'A description of how to use this function'
# Query parameters that work, but don't appear in discovery
-STACK_QUERY_PARAMETERS = ['trace', 'fields']
+STACK_QUERY_PARAMETERS = ['trace', 'fields', 'pp', 'prettyPrint', 'userIp', 'strict']
def key2param(key):
diff --git a/apiclient/http.py b/apiclient/http.py
index 206f3e6..138ce48 100644
--- a/apiclient/http.py
+++ b/apiclient/http.py
@@ -203,7 +203,8 @@
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_headers_as_json' means return the request headers in
+ the response body
'echo_request_body' means return the request body in the response body
"""
@@ -299,7 +300,8 @@
headers = {}
if method == 'PATCH':
if 'authorization' in headers and 'oauth_token' in headers['authorization']:
- logging.warning('OAuth 1.0 request made with Credentials applied after tunnel_patch.')
+ logging.warning(
+ 'OAuth 1.0 request made with Credentials applied after tunnel_patch.')
headers['x-http-method-override'] = "PATCH"
method = 'POST'
resp, content = request_orig(uri, method, body, headers,
diff --git a/samples/moderator/moderator.py b/samples/moderator/moderator.py
index c75c962..be62a1f 100644
--- a/samples/moderator/moderator.py
+++ b/samples/moderator/moderator.py
@@ -6,6 +6,18 @@
"""Simple command-line example for Moderator.
Command-line application that exercises the Google Moderator API.
+
+Usage:
+ $ python moderator.py
+
+You can also get help on all the command-line flags the program understands
+by running:
+
+ $ python moderator.py --help
+
+To get detailed log output run:
+
+ $ python moderator.py --logging_level=DEBUG
"""
__author__ = 'jcgregorio@google.com (Joe Gregorio)'
@@ -21,60 +33,79 @@
from oauth2client.tools import run
FLAGS = gflags.FLAGS
+
+# Set up a Flow object to be used if we need to authenticate. This
+# sample uses OAuth 2.0, and we set up the OAuth2WebServerFlow with
+# the information it needs to authenticate. Note that it is called
+# the Web Server Flow, but it can also handle the flow for native
+# applications <http://code.google.com/apis/accounts/docs/OAuth2.html#IA>
+# The client_id client_secret are copied from the Identity tab on
+# the Google APIs Console <http://code.google.com/apis/console>
FLOW = OAuth2WebServerFlow(
client_id='433807057907.apps.googleusercontent.com',
client_secret='jigtZpMApkRxncxikFpR+SFg',
scope='https://www.googleapis.com/auth/moderator',
user_agent='moderator-cmdline-sample/1.0')
+# The gflags module makes defining command-line options easy for
+# applications. Run this program with the '--help' argument to see
+# all the flags that it understands.
gflags.DEFINE_enum('logging_level', 'ERROR',
['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'],
'Set the level of logging detail.')
def main(argv):
+ # Let the gflags module process the command-line arguments
try:
argv = FLAGS(argv)
except gflags.FlagsError, e:
print '%s\\nUsage: %s ARGS\\n%s' % (e, argv[0], FLAGS)
sys.exit(1)
+ # Set the logging according to the command-line flag
logging.getLogger().setLevel(getattr(logging, FLAGS.logging_level))
+ # A Storage object is used to storage and retrieve Credentials.
+ # See <http://code.google.com/p/google-api-python-client/wiki/HowAuthenticationWorks>
storage = Storage('moderator.dat')
credentials = storage.get()
+ # If the Credentials don't exist or are invalid run through the
+ # native client flow. The Storage object will ensure that if successful
+ # the good Credentials will get written back to a file.
if credentials is None or credentials.invalid == True:
credentials = run(FLOW, storage)
+ # Create an httplib2.Http object to handle our HTTP requests and authorize it
+ # with our good Credentials.
http = httplib2.Http(cache=".cache")
http = credentials.authorize(http)
+ # Build a service object for interacting with the API.
service = build("moderator", "v1", http=http)
+ # Create a new Moderator series.
series_body = {
- "data": {
"description": "Share and rank tips for eating healthy and cheap!",
"name": "Eating Healthy & Cheap",
"videoSubmissionAllowed": False
}
- }
series = service.series().insert(body=series_body).execute()
print "Created a new series"
+ # Create a new Moderator topic in that series.
topic_body = {
- "data": {
"description": "Share your ideas on eating healthy!",
"name": "Ideas",
"presenter": "liz"
}
- }
topic = service.topics().insert(seriesId=series['id']['seriesId'],
body=topic_body).execute()
print "Created a new topic"
+ # Create a new Submission in that topic.
submission_body = {
- "data": {
"attachmentUrl": "http://www.youtube.com/watch?v=1a1wyc5Xxpg",
"attribution": {
"displayName": "Bashan",
@@ -82,16 +113,14 @@
},
"text": "Charlie Ayers @ Google"
}
- }
submission = service.submissions().insert(seriesId=topic['id']['seriesId'],
topicId=topic['id']['topicId'], body=submission_body).execute()
print "Inserted a new submisson on the topic"
+ # Vote on that newly added Submission.
vote_body = {
- "data": {
"vote": "PLUS"
}
- }
service.votes().insert(seriesId=topic['id']['seriesId'],
submissionId=submission['id']['submissionId'],
body=vote_body)