documentation updates

Author: Lars Kellogg-Stedman

drive.py

@@ -44,22 +44,33 @@ def __init__(self,
         self.credentials = credentials
 
     def authenticate(self):
+        '''Establish Google credentials.  This will load stored credentials
+        and validate them, and it will call self.login() if stored
+        credentials are unavailable or fail to validate.'''
+
         self.load_credentials()
 
         if self.token is None:
             self.login()
         else:
             try:
+                # Always refresh the token.  This is a dirty hack to avoid
+                # doing anything more complicated.
                 self.refresh()
                 self.validate()
             except ValueError:
                 self.login()
 
+        # Add an Authorization header to all requests made through
+        # our requests.Session object.
         self.session.headers.update({
             'Authorization': 'Bearer %(access_token)s' % self.token
             })
 
     def refresh(self):
+        '''Use a refresh_token to refresh the access_token.  See
+        https://developers.google.com/drive/about-auth'''
+
         if not 'refresh_token' in self.token:
             raise ValueError('no refresh token')
 
@@ -76,6 +87,8 @@ def refresh(self):
         self.store_credentials()
 
     def login(self):
+        '''Perform OAuth authentication.'''
+
         params = {
             'client_id': self.client_id,
             'scope': ' '.join(OAUTH_SCOPES),
@@ -108,35 +121,48 @@ def login(self):
         self.store_credentials()
 
     def store_credentials(self):
+        '''Write credentials to file.'''
         with open(self.credentials, 'w') as fd:
             fd.write(yaml.safe_dump(self.token, encoding='utf-8',
                 default_flow_style=False))
 
     def load_credentials(self):
+        '''Read credentials from file.'''
         try:
             with open(self.credentials) as fd:
                 self.token = yaml.load(fd)
         except IOError:
             pass
 
     def validate(self):
+        '''Validate token.'''
+
         r = requests.get('%s?access_token=%s' % (
             VALIDATE_URI, self.token['access_token']
             ))
 
+        self._validate_response = r
+
         if not r:
             raise ValueError('failed to validate')
 
     def files(self):
+        '''Return an iterator over the files in Google Drive.'''
+
         r = self.session.get('%s/files' % DRIVE_URI).json
 
         for fspec in r['items']:
             yield fspec
 
     def get_file_metadata(self, fid):
+        '''Return the file metadata for a file identified by its ID.'''
+
         return self.session.get('%s/files/%s' % (DRIVE_URI, fid)).json
 
     def revisions(self, fid):
+        '''Return an iterator over the revisions of a file
+        identified by its ID.'''
+
         r = self.session.get('%s/files/%s/revisions' % (
             DRIVE_URI, fid)).json
 

gitdriver.py

@@ -16,6 +16,8 @@ def parse_args():
     p.add_argument('--html', '-H', action='store_const', const='text/html',
             dest='mime-type')
     p.add_argument('--mime-type', default='text/html')
+    p.add_argument('--raw', '-R', action='store_true',
+            help='Download original document if possible.')
     p.add_argument('docid')
 
     return p.parse_args()
@@ -29,19 +31,36 @@ def main():
             scopes=[DRIVE_RW_SCOPE],
             )
 
+    # Establish our credentials.
     gd.authenticate()
 
+    # Get information about the specified file.  This will throw
+    # an exception if the file does not exist.
     md = gd.get_file_metadata(opts.docid)
 
+    # Initialize the git repository.
     print 'Create repository "%(title)s"' % md
     subprocess.call(['git','init',md['title']])
     os.chdir(md['title'])
 
+    # Iterate over the revisions (from oldest to newest).
     for rev in gd.revisions(opts.docid):
         with open('content', 'w') as fd:
-            r = gd.session.get(rev['exportLinks'][opts.mime_type])
+            if 'exportLinks' in rev and not opts.raw:
+                # If the file provides an 'exportLinks' dictionary,
+                # download the requested MIME type.
+                r = gd.session.get(rev['exportLinks'][opts.mime_type])
+            elif 'downloadUrl' in rev:
+                # Otherwise, if there is a downloadUrl, use that.
+                r = gd.session.get(rev['downloadUrl'])
+            else:
+                raise KeyError('unable to download revision')
+
+            # Write file content into local file.
             for chunk in r.iter_content():
                 fd.write(chunk)
+
+        # Commit changes to repository.
         subprocess.call(['git', 'add', 'content'])
         subprocess.call(['git', 'commit', '-m',
             'revision from %s' % rev['modifiedDate']])