Improving debuggability of mock http core by adding dump request/response and detecting if the most recent response came from cache or the live server.

j.s@google.com · j.s@google.com · commit 541a5f0d00a4 · 2009-12-17T19:24:53.000Z
diff --git a/src/atom/client.py b/src/atom/client.py
@@ -25,6 +25,14 @@
 import atom.http_core
 
 
+class Error(Exception):
+  pass
+
+
+class MissingHost(Error):
+  pass
+
+
 class AtomPubClient(object):
   host = None
   auth_token = None
@@ -67,6 +75,10 @@ def request(self, method=None, uri=None, auth_token=None,
       http_request:
       auth_token: An authorization token object whose modify_request method
                   sets the HTTP Authorization header.
+
+    Returns:
+      The results of calling self.http_client.request. With the default
+      http_client, this is an HTTP response object.
     """
     # Modify the request based on the AtomPubClient settings and parameters
     # passed in to the request.
@@ -96,48 +108,75 @@ def request(self, method=None, uri=None, auth_token=None,
       auth_token.modify_request(http_request)
     elif self.auth_token:
       self.auth_token.modify_request(http_request)
+    # Check to make sure there is a host in the http_request.
+    if http_request.uri.host is None:
+      raise MissingHost('No host provided in request %s %s' % (
+          http_request.method, str(http_request.uri)))
     # Perform the fully specified request using the http_client instance.
     # Sends the request to the server and returns the server's response.
     return self.http_client.request(http_request)
 
   Request = request
 
   def get(self, uri=None, auth_token=None, http_request=None, **kwargs):
+    """Performs a request using the GET method, returns an HTTP response."""
     return self.request(method='GET', uri=uri, auth_token=auth_token,
                         http_request=http_request, **kwargs)
 
   Get = get
 
   def post(self, uri=None, data=None, auth_token=None, http_request=None,
            **kwargs):
+    """Sends data using the POST method, returns an HTTP response."""
     return self.request(method='POST', uri=uri, auth_token=auth_token,
                         http_request=http_request, data=data, **kwargs)
 
   Post = post
 
   def put(self, uri=None, data=None, auth_token=None, http_request=None,
           **kwargs):
+    """Sends data using the PUT method, returns an HTTP response."""
     return self.request(method='PUT', uri=uri, auth_token=auth_token,
                         http_request=http_request, data=data, **kwargs)
 
   Put = put
 
   def delete(self, uri=None, auth_token=None, http_request=None, **kwargs):
+    """Performs a request using the DELETE method, returns an HTTP response."""
     return self.request(method='DELETE', uri=uri, auth_token=auth_token,
                         http_request=http_request, **kwargs)
 
   Delete = delete
 
   def modify_request(self, http_request):
+    """Changes the HTTP request before sending it to the server.
+    
+    Sets the User-Agent HTTP header and fills in the HTTP host portion
+    of the URL if one was not included in the request (for this it uses
+    the self.host member if one is set). This method is called in
+    self.request.
+
+    Args:
+      http_request: An atom.http_core.HttpRequest() (optional) If one is
+                    not provided, a new HttpRequest is instantiated.
+
+    Returns:
+      An atom.http_core.HttpRequest() with the User-Agent header set and
+      if this client has a value in its host member, the host in the request
+      URL is set.
+    """
     if http_request is None:
       http_request = atom.http_core.HttpRequest()
+
     if self.host is not None and http_request.uri.host is None:
       http_request.uri.host = self.host
+
     # Set the user agent header for logging purposes.
     if self.source:
-      http_request.headers['User-Agent'] = '%s gdata-py/2.0.5' % self.source
+      http_request.headers['User-Agent'] = '%s gdata-py/2.0.6' % self.source
     else:
-      http_request.headers['User-Agent'] = 'gdata-py/2.0.5'
+      http_request.headers['User-Agent'] = 'gdata-py/2.0.6'
+
     return http_request
 
   ModifyRequest = modify_request
diff --git a/src/atom/http_core.py b/src/atom/http_core.py
@@ -174,6 +174,26 @@ def _copy(self):
     new_request._body_parts = self._body_parts[:]
     return new_request
 
+  def _dump(self):
+    """Converts to a printable string for debugging purposes.
+    
+    In order to preserve the request, it does not read from file-like objects
+    in the body.
+    """
+    output =  'HTTP Request\n  method: %s\n  url: %s\n  headers:\n' % (
+        self.method, str(self.uri))
+    for header, value in self.headers.iteritems():
+      output += '    %s: %s\n' % (header, value)
+    output += '  body sections:\n'
+    i = 0
+    for part in self._body_parts:
+      if isinstance(part, (str, unicode)):
+        output += '    %s: %s\n' % (i, part)
+      else:
+        output += '    %s: <file like object>\n' % i
+      i += 1
+    return output
+
 
 def _apply_defaults(http_request):
   if http_request.uri.scheme is None:
@@ -350,6 +370,23 @@ def read(self, amt=None):
       return self._body.read(amt)
 
 
+def _dump_response(http_response):
+  """Converts to a string for printing debug messages.
+  
+  Does not read the body since that may consume the content.
+  """
+  output = 'HttpResponse\n  status: %s\n  reason: %s\n  headers:' % (
+      http_response.status, http_response.reason)
+  headers = http_response.getheaders()
+  if isinstance(headers, dict):
+    for header, value in headers.iteritems():
+      output += '    %s: %s\n' % (header, value)
+  else:
+    for pair in headers:
+      output += '    %s: %s\n' % (pair[0], pair[1])
+  return output
+
+
 class HttpClient(object):
   """Performs HTTP requests using httplib."""
   debug = None
@@ -395,6 +432,7 @@ def _http_request(self, method, uri, headers=None, body_parts=None):
     """
     if isinstance(uri, (str, unicode)):
       uri = Uri.parse_uri(uri)
+
     connection = self._get_connection(uri, headers=headers)
 
     if self.debug:
diff --git a/src/atom/mock_http_core.py b/src/atom/mock_http_core.py
@@ -28,9 +28,18 @@
 import atom.http_core
 
 
+class Error(Exception):
+  pass
+
+
+class NoRecordingFound(Error):
+  pass
+
+
 class MockHttpClient(object):
   debug = None
   real_client = None
+  last_request_was_live = False
 
   # The following members are used to construct the session cache temp file
   # name.
@@ -64,20 +73,25 @@ def request(self, http_request):
     request = http_request._copy()
     _scrub_request(request)
     if self.real_client is None:
+      self.last_request_was_live = False
       for recording in self._recordings:
         if _match_request(recording[0], request):
           return recording[1]
     else:
       # Pass along the debug settings to the real client.
       self.real_client.debug = self.debug
       # Make an actual request since we can use the real HTTP client.
+      self.last_request_was_live = True
       response = self.real_client.request(http_request)
-      _scrub_response(response)
-      self.add_response(request, response.status, response.reason,
-          dict(response.getheaders()), response.read())
+      scrubbed_response = _scrub_response(response)
+      self.add_response(request, scrubbed_response.status,
+                        scrubbed_response.reason,
+                        dict(scrubbed_response.getheaders()),
+                        scrubbed_response.read())
       # Return the recording which we just added.
       return self._recordings[-1][1]
-    return None
+    raise NoRecordingFound('No recoding was found for request: %s %s' % (
+        request.method, str(request.uri)))
 
   Request = request
 
@@ -148,6 +162,18 @@ def get_cache_file_name(self):
     return '%s.%s.%s' % (self.cache_name_prefix, self.cache_case_name,
                          self.cache_test_name)
 
+  def _dump(self):
+    """Provides debug information in a string."""
+    output = 'MockHttpClient\n  real_client: %s\n  cache file name: %s\n' % (
+        self.real_client, self.get_cache_file_name())
+    output += '  recordings:\n'
+    i = 0
+    for recording in self._recordings:
+      output += '    recording %i is for: %s %s\n' % (
+          i, recording[0].method, str(recording[0].uri))
+      i += 1
+    return output
+
 
 def _match_request(http_request, stored_request):
   """Determines whether a request is similar enough to a stored request
diff --git a/src/gdata/docs/client.py b/src/gdata/docs/client.py
@@ -365,6 +365,7 @@ def upload(self, media, title, folder_or_uri=None, content_type=None,
     Returns:
       A gdata.docs.data.DocsEntry containing information about uploaded doc.
     """
+    uri = None
     if folder_or_uri is not None:
       if isinstance(folder_or_uri, gdata.docs.data.DocsEntry):
         # Verify that we're uploading the resource into to a folder.
diff --git a/src/gdata/gauth.py b/src/gdata/gauth.py
@@ -209,7 +209,8 @@ def generate_auth_sub_url(next, scopes, secure=False, session=True,
     next: atom.http_core.Uri or string The URL user will be sent to after
           authorizing this web application to access their data.
     scopes: list containint strings or atom.http_core.Uri objects. The URLs
-            of the services to be accessed.
+            of the services to be accessed. Could also be a single string
+            or single atom.http_core.Uri for requesting just one scope.
     secure: boolean (optional) Determines whether or not the issued token
             is a secure token.
     session: boolean (optional) Determines whether or not the issued token
@@ -234,6 +235,10 @@ def generate_auth_sub_url(next, scopes, secure=False, session=True,
   """
   if isinstance(next, (str, unicode)):
     next = atom.http_core.Uri.parse_uri(next)
+  # If the user passed in a string instead of a list for scopes, convert to
+  # a single item tuple.
+  if isinstance(scopes, (str, unicode, atom.http_core.Uri)):
+    scopes = (scopes,)
   scopes_string = ' '.join([str(scope) for scope in scopes])
   next.query[scopes_param_prefix] = scopes_string
 
@@ -1075,6 +1080,25 @@ def load_tokens(blob):
 
 
 def ae_save(token, token_key):
+  """Stores an auth token in the App Engine datastore.
+  
+  This is a convenience method for using the library with App Engine.
+  Recommended usage is to associate the auth token with the current_user.
+  If a user is signed in to the app using the App Engine users API, you
+  can use
+  gdata.gauth.ae_save(some_token, users.get_current_user().user_id())
+  If you are not using the Users API you are free to choose whatever
+  string you would like for a token_string.
+
+  Args:
+    token: an auth token object. Must be one of ClientLoginToken,
+           AuthSubToken, SecureAuthSubToken, OAuthRsaToken, or OAuthHmacToken
+           (see token_to_blob).
+    token_key: str A unique identified to be used when you want to retrieve
+               the token. If the user is signed in to App Engine using the
+               users API, I recommend using the user ID for the token_key:
+               users.get_current_user().user_id()
+  """
   import gdata.alt.app_engine
   key_name = ''.join(('gd_auth_token', token_key))
   return gdata.alt.app_engine.set_token(key_name, token_to_blob(token))
@@ -1084,6 +1108,19 @@ def ae_save(token, token_key):
 
 
 def ae_load(token_key):
+  """Retrieves a token object from the App Engine datastore.
+  
+  This is a convenience method for using the library with App Engine.
+  See also ae_save.
+
+  Args:
+    token_key: str The unique key associated with the desired token when it
+               was saved using ae_save.
+
+  Returns:
+    A token object if there was a token associated with the token_key or None
+    if the key could not be found.
+  """
   import gdata.alt.app_engine
   key_name = ''.join(('gd_auth_token', token_key))
   token_string = gdata.alt.app_engine.get_token(key_name)
@@ -1097,6 +1134,7 @@ def ae_load(token_key):
 
 
 def ae_delete(token_key):
+  """Removes the token object from the App Engine datastore."""
   import gdata.alt.app_engine
   key_name = ''.join(('gd_auth_token', token_key))
   gdata.alt.app_engine.delete_token(key_name)
