Clean up README and add lots of comments to moderator.py

README

@@ -29,24 +29,24 @@ You may need root privileges to do this.
 Running
 =======
 
-First run three-legged-dance.py to get OAuth
+Run buzz.py, which will use the apiclient
-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
 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

apiclient/discovery.py

@@ -48,7 +48,7 @@ DISCOVERY_URI = ('https://www.googleapis.com/discovery/v0.3/describe/'
 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):

apiclient/http.py

@@ -203,7 +203,8 @@ class HttpMockSequence(object):
   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 @@ def tunnel_patch(http):
       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,

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.client import OAuth2WebServerFlow
 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 @@ def main(argv):
           },
         "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)