faset over fra Z3950 til google books

python/atom/auth.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python
+#
+#    Copyright (C) 2009 Google Inc.
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+
+# This module is used for version 2 of the Google Data APIs.
+
+
+__author__ = 'j.s@google.com (Jeff Scudder)'
+
+
+import base64
+
+
+class BasicAuth(object):
+  """Sets the Authorization header as defined in RFC1945"""
+
+  def __init__(self, user_id, password):
+    self.basic_cookie = base64.encodestring(
+        '%s:%s' % (user_id, password)).strip()
+
+  def modify_request(self, http_request):
+    http_request.headers['Authorization'] = 'Basic %s' % self.basic_cookie
+
+  ModifyRequest = modify_request
+
+
+class NoAuth(object):
+
+  def modify_request(self, http_request):
+    pass

python/atom/client.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python
+#
+# Copyright (C) 2009 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""AtomPubClient provides CRUD ops. in line with the Atom Publishing Protocol.
+
+"""
+
+__author__ = 'j.s@google.com (Jeff Scudder)'
+
+
+import atom.http_core
+
+
+class Error(Exception):
+  pass
+
+
+class MissingHost(Error):
+  pass
+
+
+class AtomPubClient(object):
+  host = None
+  auth_token = None
+  ssl = False # Whether to force all requests over https
+
+  def __init__(self, http_client=None, host=None,
+               auth_token=None, source=None, **kwargs):
+    """Creates a new AtomPubClient instance.
+
+    Args:
+      source: The name of your application.
+      http_client: An object capable of performing HTTP requests through a
+                   request method. This object is used to perform the request
+                   when the AtomPubClient's request method is called. Used to
+                   allow HTTP requests to be directed to a mock server, or use
+                   an alternate library instead of the default of httplib to
+                   make HTTP requests.
+      host: str The default host name to use if a host is not specified in the
+            requested URI.
+      auth_token: An object which sets the HTTP Authorization header when its
+                  modify_request method is called.
+    """
+    self.http_client = http_client or atom.http_core.ProxiedHttpClient()
+    if host is not None:
+      self.host = host
+    if auth_token is not None:
+      self.auth_token = auth_token
+    self.source = source
+
+  def request(self, method=None, uri=None, auth_token=None,
+              http_request=None, **kwargs):
+    """Performs an HTTP request to the server indicated.
+
+    Uses the http_client instance to make the request.
+
+    Args:
+      method: The HTTP method as a string, usually one of 'GET', 'POST',
+              'PUT', or 'DELETE'
+      uri: The URI desired as a string or atom.http_core.Uri.
+      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.
+    http_request = self.modify_request(http_request)
+    if isinstance(uri, (str, unicode)):
+      uri = atom.http_core.Uri.parse_uri(uri)
+    if uri is not None:
+      uri.modify_request(http_request)
+    if isinstance(method, (str, unicode)):
+      http_request.method = method
+    # Any unrecognized arguments are assumed to be capable of modifying the
+    # HTTP request.
+    for name, value in kwargs.iteritems():
+      if value is not None:
+        value.modify_request(http_request)
+    # Default to an http request if the protocol scheme is not set.
+    if http_request.uri.scheme is None:
+      http_request.uri.scheme = 'http'
+    # Override scheme. Force requests over https.
+    if self.ssl:
+      http_request.uri.scheme = 'https'
+    if http_request.uri.path is None:
+      http_request.uri.path = '/'
+    # Add the Authorization header at the very end. The Authorization header
+    # value may need to be calculated using information in the request.
+    if auth_token:
+      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.12' % self.source
+    else:
+      http_request.headers['User-Agent'] = 'gdata-py/2.0.12'
+
+    return http_request
+
+  ModifyRequest = modify_request

python/atom/core.py

@@ -0,0 +1,545 @@
+#!/usr/bin/env python
+#
+#    Copyright (C) 2008 Google Inc.
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+
+# This module is used for version 2 of the Google Data APIs.
+
+
+__author__ = 'j.s@google.com (Jeff Scudder)'
+
+
+import inspect
+try:
+  from xml.etree import cElementTree as ElementTree
+except ImportError:
+  try:
+    import cElementTree as ElementTree
+  except ImportError:
+    try:
+      from xml.etree import ElementTree
+    except ImportError:
+      from elementtree import ElementTree
+
+
+try:
+    from xml.dom.minidom import parseString as xmlString
+except ImportError:
+    xmlString = None
+
+STRING_ENCODING = 'utf-8'
+
+
+class XmlElement(object):
+  """Represents an element node in an XML document.
+
+  The text member is a UTF-8 encoded str or unicode.
+  """
+  _qname = None
+  _other_elements = None
+  _other_attributes = None
+  # The rule set contains mappings for XML qnames to child members and the
+  # appropriate member classes.
+  _rule_set = None
+  _members = None
+  text = None
+
+  def __init__(self, text=None, *args, **kwargs):
+    if ('_members' not in self.__class__.__dict__
+        or self.__class__._members is None):
+      self.__class__._members = tuple(self.__class__._list_xml_members())
+    for member_name, member_type in self.__class__._members:
+      if member_name in kwargs:
+        setattr(self, member_name, kwargs[member_name])
+      else:
+        if isinstance(member_type, list):
+          setattr(self, member_name, [])
+        else:
+          setattr(self, member_name, None)
+    self._other_elements = []
+    self._other_attributes = {}
+    if text is not None:
+      self.text = text
+
+  def _list_xml_members(cls):
+    """Generator listing all members which are XML elements or attributes.
+
+    The following members would be considered XML members:
+    foo = 'abc' - indicates an XML attribute with the qname abc
+    foo = SomeElement - indicates an XML child element
+    foo = [AnElement] - indicates a repeating XML child element, each instance
+        will be stored in a list in this member
+    foo = ('att1', '{http://example.com/namespace}att2') - indicates an XML
+        attribute which has different parsing rules in different versions of
+        the protocol. Version 1 of the XML parsing rules will look for an
+        attribute with the qname 'att1' but verion 2 of the parsing rules will
+        look for a namespaced attribute with the local name of 'att2' and an
+        XML namespace of 'http://example.com/namespace'.
+    """
+    members = []
+    for pair in inspect.getmembers(cls):
+      if not pair[0].startswith('_') and pair[0] != 'text':
+        member_type = pair[1]
+        if (isinstance(member_type, tuple) or isinstance(member_type, list)
+            or isinstance(member_type, (str, unicode))
+            or (inspect.isclass(member_type)
+                and issubclass(member_type, XmlElement))):
+          members.append(pair)
+    return members
+
+  _list_xml_members = classmethod(_list_xml_members)
+
+  def _get_rules(cls, version):
+    """Initializes the _rule_set for the class which is used when parsing XML.
+
+    This method is used internally for parsing and generating XML for an
+    XmlElement. It is not recommended that you call this method directly.
+
+    Returns:
+      A tuple containing the XML parsing rules for the appropriate version.
+
+      The tuple looks like:
+      (qname, {sub_element_qname: (member_name, member_class, repeating), ..},
+       {attribute_qname: member_name})
+
+      To give a couple of concrete example, the atom.data.Control _get_rules
+      with version of 2 will return:
+      ('{http://www.w3.org/2007/app}control',
+       {'{http://www.w3.org/2007/app}draft': ('draft',
+                                              <class 'atom.data.Draft'>,
+                                              False)},
+       {})
+      Calling _get_rules with version 1 on gdata.data.FeedLink will produce:
+      ('{http://schemas.google.com/g/2005}feedLink',
+       {'{http://www.w3.org/2005/Atom}feed': ('feed',
+                                              <class 'gdata.data.GDFeed'>,
+                                              False)},
+       {'href': 'href', 'readOnly': 'read_only', 'countHint': 'count_hint',
+        'rel': 'rel'})
+    """
+    # Initialize the _rule_set to make sure there is a slot available to store
+    # the parsing rules for this version of the XML schema.
+    # Look for rule set in the class __dict__ proxy so that only the
+    # _rule_set for this class will be found. By using the dict proxy
+    # we avoid finding rule_sets defined in superclasses.
+    # The four lines below provide support for any number of versions, but it
+    # runs a bit slower then hard coding slots for two versions, so I'm using
+    # the below two lines.
+    #if '_rule_set' not in cls.__dict__ or cls._rule_set is None:
+    #  cls._rule_set = []
+    #while len(cls.__dict__['_rule_set']) < version:
+    #  cls._rule_set.append(None)
+    # If there is no rule set cache in the class, provide slots for two XML
+    # versions. If and when there is a version 3, this list will need to be
+    # expanded.
+    if '_rule_set' not in cls.__dict__ or cls._rule_set is None:
+      cls._rule_set = [None, None]
+    # If a version higher than 2 is requested, fall back to version 2 because
+    # 2 is currently the highest supported version.
+    if version > 2:
+      return cls._get_rules(2)
+    # Check the dict proxy for the rule set to avoid finding any rule sets
+    # which belong to the superclass. We only want rule sets for this class.
+    if cls._rule_set[version-1] is None:
+      # The rule set for each version consists of the qname for this element
+      # ('{namespace}tag'), a dictionary (elements) for looking up the
+      # corresponding class member when given a child element's qname, and a
+      # dictionary (attributes) for looking up the corresponding class member
+      # when given an XML attribute's qname.
+      elements = {}
+      attributes = {}
+      if ('_members' not in cls.__dict__ or cls._members is None):
+        cls._members = tuple(cls._list_xml_members())
+      for member_name, target in cls._members:
+        if isinstance(target, list):
+          # This member points to a repeating element.
+          elements[_get_qname(target[0], version)] = (member_name, target[0],
+              True)
+        elif isinstance(target, tuple):
+          # This member points to a versioned XML attribute.
+          if version <= len(target):
+            attributes[target[version-1]] = member_name
+          else:
+            attributes[target[-1]] = member_name
+        elif isinstance(target, (str, unicode)):
+          # This member points to an XML attribute.
+          attributes[target] = member_name
+        elif issubclass(target, XmlElement):
+          # This member points to a single occurance element.
+          elements[_get_qname(target, version)] = (member_name, target, False)
+      version_rules = (_get_qname(cls, version), elements, attributes)
+      cls._rule_set[version-1] = version_rules
+      return version_rules
+    else:
+      return cls._rule_set[version-1]
+
+  _get_rules = classmethod(_get_rules)
+
+  def get_elements(self, tag=None, namespace=None, version=1):
+    """Find all sub elements which match the tag and namespace.
+
+    To find all elements in this object, call get_elements with the tag and
+    namespace both set to None (the default). This method searches through
+    the object's members and the elements stored in _other_elements which
+    did not match any of the XML parsing rules for this class.
+
+    Args:
+      tag: str
+      namespace: str
+      version: int Specifies the version of the XML rules to be used when
+               searching for matching elements.
+
+    Returns:
+      A list of the matching XmlElements.
+    """
+    matches = []
+    ignored1, elements, ignored2 = self.__class__._get_rules(version)
+    if elements:
+      for qname, element_def in elements.iteritems():
+        member = getattr(self, element_def[0])
+        if member:
+          if _qname_matches(tag, namespace, qname):
+            if element_def[2]:
+              # If this is a repeating element, copy all instances into the
+              # result list.
+              matches.extend(member)
+            else:
+              matches.append(member)
+    for element in self._other_elements:
+      if _qname_matches(tag, namespace, element._qname):
+        matches.append(element)
+    return matches
+
+  GetElements = get_elements
+  # FindExtensions and FindChildren are provided for backwards compatibility
+  # to the atom.AtomBase class.
+  # However, FindExtensions may return more results than the v1 atom.AtomBase
+  # method does, because get_elements searches both the expected children
+  # and the unexpected "other elements". The old AtomBase.FindExtensions
+  # method searched only "other elements" AKA extension_elements.
+  FindExtensions = get_elements
+  FindChildren = get_elements
+
+  def get_attributes(self, tag=None, namespace=None, version=1):
+    """Find all attributes which match the tag and namespace.
+
+    To find all attributes in this object, call get_attributes with the tag
+    and namespace both set to None (the default). This method searches
+    through the object's members and the attributes stored in
+    _other_attributes which did not fit any of the XML parsing rules for this
+    class.
+
+    Args:
+      tag: str
+      namespace: str
+      version: int Specifies the version of the XML rules to be used when
+               searching for matching attributes.
+
+    Returns:
+      A list of XmlAttribute objects for the matching attributes.
+    """
+    matches = []
+    ignored1, ignored2, attributes = self.__class__._get_rules(version)
+    if attributes:
+      for qname, attribute_def in attributes.iteritems():
+        if isinstance(attribute_def, (list, tuple)):
+          attribute_def = attribute_def[0]
+        member = getattr(self, attribute_def)
+        # TODO: ensure this hasn't broken existing behavior.
+        #member = getattr(self, attribute_def[0])
+        if member:
+          if _qname_matches(tag, namespace, qname):
+            matches.append(XmlAttribute(qname, member))
+    for qname, value in self._other_attributes.iteritems():
+      if _qname_matches(tag, namespace, qname):
+        matches.append(XmlAttribute(qname, value))
+    return matches
+
+  GetAttributes = get_attributes
+
+  def _harvest_tree(self, tree, version=1):
+    """Populates object members from the data in the tree Element."""
+    qname, elements, attributes = self.__class__._get_rules(version)
+    for element in tree:
+      if elements and element.tag in elements:
+        definition = elements[element.tag]
+        # If this is a repeating element, make sure the member is set to a
+        # list.
+        if definition[2]:
+          if getattr(self, definition[0]) is None:
+            setattr(self, definition[0], [])
+          getattr(self, definition[0]).append(_xml_element_from_tree(element,
+              definition[1], version))
+        else:
+          setattr(self, definition[0], _xml_element_from_tree(element,
+              definition[1], version))
+      else:
+        self._other_elements.append(_xml_element_from_tree(element, XmlElement,
+                                                           version))
+    for attrib, value in tree.attrib.iteritems():
+      if attributes and attrib in attributes:
+        setattr(self, attributes[attrib], value)
+      else:
+        self._other_attributes[attrib] = value
+    if tree.text:
+      self.text = tree.text
+
+  def _to_tree(self, version=1, encoding=None):
+    new_tree = ElementTree.Element(_get_qname(self, version))
+    self._attach_members(new_tree, version, encoding)
+    return new_tree
+
+  def _attach_members(self, tree, version=1, encoding=None):
+    """Convert members to XML elements/attributes and add them to the tree.
+
+    Args:
+      tree: An ElementTree.Element which will be modified. The members of
+            this object will be added as child elements or attributes
+            according to the rules described in _expected_elements and
+            _expected_attributes. The elements and attributes stored in
+            other_attributes and other_elements are also added a children
+            of this tree.
+      version: int Ingnored in this method but used by VersionedElement.
+      encoding: str (optional)
+    """
+    qname, elements, attributes = self.__class__._get_rules(version)
+    encoding = encoding or STRING_ENCODING
+    # Add the expected elements and attributes to the tree.
+    if elements:
+      for tag, element_def in elements.iteritems():
+        member = getattr(self, element_def[0])
+        # If this is a repeating element and there are members in the list.
+        if member and element_def[2]:
+          for instance in member:
+            instance._become_child(tree, version)
+        elif member:
+          member._become_child(tree, version)
+    if attributes:
+      for attribute_tag, member_name in attributes.iteritems():
+        value = getattr(self, member_name)
+        if value:
+          tree.attrib[attribute_tag] = value
+    # Add the unexpected (other) elements and attributes to the tree.
+    for element in self._other_elements:
+      element._become_child(tree, version)
+    for key, value in self._other_attributes.iteritems():
+      # I'm not sure if unicode can be used in the attribute name, so for now
+      # we assume the encoding is correct for the attribute name.
+      if not isinstance(value, unicode):
+        value = value.decode(encoding)
+      tree.attrib[key] = value
+    if self.text:
+      if isinstance(self.text, unicode):
+        tree.text = self.text
+      else:
+        tree.text = self.text.decode(encoding)
+
+  def to_string(self, version=1, encoding=None, pretty_print=None):
+    """Converts this object to XML."""
+
+    tree_string = ElementTree.tostring(self._to_tree(version, encoding))
+
+    if pretty_print and xmlString is not None:
+        return xmlString(tree_string).toprettyxml()
+ 
+    return tree_string
+ 
+  ToString = to_string
+
+  def __str__(self):
+    return self.to_string()
+
+  def _become_child(self, tree, version=1):
+    """Adds a child element to tree with the XML data in self."""
+    new_child = ElementTree.Element('')
+    tree.append(new_child)
+    new_child.tag = _get_qname(self, version)
+    self._attach_members(new_child, version)
+
+  def __get_extension_elements(self):
+    return self._other_elements
+
+  def __set_extension_elements(self, elements):
+    self._other_elements = elements
+
+  extension_elements = property(__get_extension_elements,
+      __set_extension_elements,
+      """Provides backwards compatibility for v1 atom.AtomBase classes.""")
+
+  def __get_extension_attributes(self):
+    return self._other_attributes
+
+  def __set_extension_attributes(self, attributes):
+    self._other_attributes = attributes
+
+  extension_attributes = property(__get_extension_attributes,
+      __set_extension_attributes,
+      """Provides backwards compatibility for v1 atom.AtomBase classes.""")
+
+  def _get_tag(self, version=1):
+    qname = _get_qname(self, version)
+    return qname[qname.find('}')+1:]
+
+  def _get_namespace(self, version=1):
+    qname = _get_qname(self, version)
+    if qname.startswith('{'):
+      return qname[1:qname.find('}')]
+    else:
+      return None
+
+  def _set_tag(self, tag):
+    if isinstance(self._qname, tuple):
+      self._qname = self._qname.copy()
+      if self._qname[0].startswith('{'):
+        self._qname[0] = '{%s}%s' % (self._get_namespace(1), tag)
+      else:
+        self._qname[0] = tag
+    else:
+      if self._qname.startswith('{'):
+        self._qname = '{%s}%s' % (self._get_namespace(), tag)
+      else:
+        self._qname = tag
+
+  def _set_namespace(self, namespace):
+    if isinstance(self._qname, tuple):
+      self._qname = self._qname.copy()
+      if namespace:
+         self._qname[0] = '{%s}%s' % (namespace, self._get_tag(1))
+      else:
+         self._qname[0] = self._get_tag(1)
+    else:
+      if namespace:
+         self._qname = '{%s}%s' % (namespace, self._get_tag(1))
+      else:
+         self._qname = self._get_tag(1)
+
+  tag = property(_get_tag, _set_tag,
+      """Provides backwards compatibility for v1 atom.AtomBase classes.""")
+
+  namespace = property(_get_namespace, _set_namespace,
+      """Provides backwards compatibility for v1 atom.AtomBase classes.""")
+
+  # Provided for backwards compatibility to atom.ExtensionElement
+  children = extension_elements
+  attributes = extension_attributes
+
+
+def _get_qname(element, version):
+  if isinstance(element._qname, tuple):
+    if version <= len(element._qname):
+      return element._qname[version-1]
+    else:
+      return element._qname[-1]
+  else:
+    return element._qname
+
+
+def _qname_matches(tag, namespace, qname):
+  """Logic determines if a QName matches the desired local tag and namespace.
+
+  This is used in XmlElement.get_elements and XmlElement.get_attributes to
+  find matches in the element's members (among all expected-and-unexpected
+  elements-and-attributes).
+
+  Args:
+    expected_tag: string
+    expected_namespace: string
+    qname: string in the form '{xml_namespace}localtag' or 'tag' if there is
+           no namespace.
+
+  Returns:
+    boolean True if the member's tag and namespace fit the expected tag and
+    namespace.
+  """
+  # If there is no expected namespace or tag, then everything will match.
+  if qname is None:
+    member_tag = None
+    member_namespace = None
+  else:
+    if qname.startswith('{'):
+      member_namespace = qname[1:qname.index('}')]
+      member_tag = qname[qname.index('}') + 1:]
+    else:
+      member_namespace = None
+      member_tag = qname
+  return ((tag is None and namespace is None)
+      # If there is a tag, but no namespace, see if the local tag matches.
+      or (namespace is None and member_tag == tag)
+      # There was no tag, but there was a namespace so see if the namespaces
+      # match.
+      or (tag is None and member_namespace == namespace)
+      # There was no tag, and the desired elements have no namespace, so check
+      # to see that the member's namespace is None.
+      or (tag is None and namespace == ''
+          and member_namespace is None)
+      # The tag and the namespace both match.
+      or (tag == member_tag
+          and namespace == member_namespace)
+      # The tag matches, and the expected namespace is the empty namespace,
+      # check to make sure the member's namespace is None.
+      or (tag == member_tag and namespace == ''
+          and member_namespace is None))
+
+
+def parse(xml_string, target_class=None, version=1, encoding=None):
+  """Parses the XML string according to the rules for the target_class.
+
+  Args:
+    xml_string: str or unicode
+    target_class: XmlElement or a subclass. If None is specified, the
+        XmlElement class is used.
+    version: int (optional) The version of the schema which should be used when
+        converting the XML into an object. The default is 1.
+    encoding: str (optional) The character encoding of the bytes in the
+        xml_string. Default is 'UTF-8'.
+  """
+  if target_class is None:
+    target_class = XmlElement
+  if isinstance(xml_string, unicode):
+    if encoding is None:
+      xml_string = xml_string.encode(STRING_ENCODING)
+    else:
+      xml_string = xml_string.encode(encoding)
+  tree = ElementTree.fromstring(xml_string)
+  return _xml_element_from_tree(tree, target_class, version)
+
+
+Parse = parse
+xml_element_from_string = parse
+XmlElementFromString = xml_element_from_string
+
+
+def _xml_element_from_tree(tree, target_class, version=1):
+  if target_class._qname is None:
+    instance = target_class()
+    instance._qname = tree.tag
+    instance._harvest_tree(tree, version)
+    return instance
+  # TODO handle the namespace-only case
+  # Namespace only will be used with Google Spreadsheets rows and
+  # Google Base item attributes.
+  elif tree.tag == _get_qname(target_class, version):
+    instance = target_class()
+    instance._harvest_tree(tree, version)
+    return instance
+  return None
+
+
+class XmlAttribute(object):
+
+  def __init__(self, qname, value):
+    self._qname = qname
+    self.value = value
+

python/atom/data.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env python
+#
+# Copyright (C) 2009 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# This module is used for version 2 of the Google Data APIs.
+
+
+__author__ = 'j.s@google.com (Jeff Scudder)'
+
+
+import atom.core
+
+
+XML_TEMPLATE = '{http://www.w3.org/XML/1998/namespace}%s'
+ATOM_TEMPLATE = '{http://www.w3.org/2005/Atom}%s'
+APP_TEMPLATE_V1 = '{http://purl.org/atom/app#}%s'
+APP_TEMPLATE_V2 = '{http://www.w3.org/2007/app}%s'
+
+
+class Name(atom.core.XmlElement):
+  """The atom:name element."""
+  _qname = ATOM_TEMPLATE % 'name'
+
+
+class Email(atom.core.XmlElement):
+  """The atom:email element."""
+  _qname = ATOM_TEMPLATE % 'email'
+
+
+class Uri(atom.core.XmlElement):
+  """The atom:uri element."""
+  _qname = ATOM_TEMPLATE % 'uri'
+
+
+class Person(atom.core.XmlElement):
+  """A foundation class which atom:author and atom:contributor extend.
+
+  A person contains information like name, email address, and web page URI for
+  an author or contributor to an Atom feed.
+  """
+  name = Name
+  email = Email
+  uri = Uri
+
+
+class Author(Person):
+  """The atom:author element.
+
+  An author is a required element in Feed unless each Entry contains an Author.
+  """
+  _qname = ATOM_TEMPLATE % 'author'
+
+
+class Contributor(Person):
+  """The atom:contributor element."""
+  _qname = ATOM_TEMPLATE % 'contributor'
+
+
+class Link(atom.core.XmlElement):
+  """The atom:link element."""
+  _qname = ATOM_TEMPLATE % 'link'
+  href = 'href'
+  rel = 'rel'
+  type = 'type'
+  hreflang = 'hreflang'
+  title = 'title'
+  length = 'length'
+
+
+class Generator(atom.core.XmlElement):
+  """The atom:generator element."""
+  _qname = ATOM_TEMPLATE % 'generator'
+  uri = 'uri'
+  version = 'version'
+
+
+class Text(atom.core.XmlElement):
+  """A foundation class from which atom:title, summary, etc. extend.
+
+  This class should never be instantiated.
+  """
+  type = 'type'
+
+
+class Title(Text):
+  """The atom:title element."""
+  _qname = ATOM_TEMPLATE % 'title'
+
+
+class Subtitle(Text):
+  """The atom:subtitle element."""
+  _qname = ATOM_TEMPLATE % 'subtitle'
+
+
+class Rights(Text):
+  """The atom:rights element."""
+  _qname = ATOM_TEMPLATE % 'rights'
+
+
+class Summary(Text):
+  """The atom:summary element."""
+  _qname = ATOM_TEMPLATE % 'summary'
+
+
+class Content(Text):
+  """The atom:content element."""
+  _qname = ATOM_TEMPLATE % 'content'
+  src = 'src'
+
+
+class Category(atom.core.XmlElement):
+  """The atom:category element."""
+  _qname = ATOM_TEMPLATE % 'category'
+  term = 'term'
+  scheme = 'scheme'
+  label = 'label'
+
+
+class Id(atom.core.XmlElement):
+  """The atom:id element."""
+  _qname = ATOM_TEMPLATE % 'id'
+
+
+class Icon(atom.core.XmlElement):
+  """The atom:icon element."""
+  _qname = ATOM_TEMPLATE % 'icon'
+
+
+class Logo(atom.core.XmlElement):
+  """The atom:logo element."""
+  _qname = ATOM_TEMPLATE % 'logo'
+
+
+class Draft(atom.core.XmlElement):
+  """The app:draft element which indicates if this entry should be public."""
+  _qname = (APP_TEMPLATE_V1 % 'draft', APP_TEMPLATE_V2 % 'draft')
+
+
+class Control(atom.core.XmlElement):
+  """The app:control element indicating restrictions on publication.
+
+  The APP control element may contain a draft element indicating whether or
+  not this entry should be publicly available.
+  """
+  _qname = (APP_TEMPLATE_V1 % 'control', APP_TEMPLATE_V2 % 'control')
+  draft = Draft
+
+
+class Date(atom.core.XmlElement):
+  """A parent class for atom:updated, published, etc."""
+
+
+class Updated(Date):
+  """The atom:updated element."""
+  _qname = ATOM_TEMPLATE % 'updated'
+
+
+class Published(Date):
+  """The atom:published element."""
+  _qname = ATOM_TEMPLATE % 'published'
+
+
+class LinkFinder(object):
+  """An "interface" providing methods to find link elements
+
+  Entry elements often contain multiple links which differ in the rel
+  attribute or content type. Often, developers are interested in a specific
+  type of link so this class provides methods to find specific classes of
+  links.
+
+  This class is used as a mixin in Atom entries and feeds.
+  """
+
+  def find_url(self, rel):
+    """Returns the URL in a link with the desired rel value."""
+    for link in self.link:
+      if link.rel == rel and link.href:
+        return link.href
+    return None
+
+  FindUrl = find_url
+
+  def get_link(self, rel):
+    """Returns a link object which has the desired rel value.
+
+    If you are interested in the URL instead of the link object,
+    consider using find_url instead.
+    """
+    for link in self.link:
+      if link.rel == rel and link.href:
+        return link
+    return None
+
+  GetLink = get_link
+
+  def find_self_link(self):
+    """Find the first link with rel set to 'self'
+
+    Returns:
+      A str containing the link's href or None if none of the links had rel
+      equal to 'self'
+    """
+    return self.find_url('self')
+
+  FindSelfLink = find_self_link
+
+  def get_self_link(self):
+    return self.get_link('self')
+
+  GetSelfLink = get_self_link
+
+  def find_edit_link(self):
+    return self.find_url('edit')
+
+  FindEditLink = find_edit_link
+
+  def get_edit_link(self):
+    return self.get_link('edit')
+
+  GetEditLink = get_edit_link
+
+  def find_edit_media_link(self):
+    link = self.find_url('edit-media')
+    # Search for media-edit as well since Picasa API used media-edit instead.
+    if link is None:
+      return self.find_url('media-edit')
+    return link
+
+  FindEditMediaLink = find_edit_media_link
+
+  def get_edit_media_link(self):
+    link = self.get_link('edit-media')
+    if link is None:
+      return self.get_link('media-edit')
+    return link
+
+  GetEditMediaLink = get_edit_media_link
+
+  def find_next_link(self):
+    return self.find_url('next')
+
+  FindNextLink = find_next_link
+
+  def get_next_link(self):
+    return self.get_link('next')
+
+  GetNextLink = get_next_link
+
+  def find_license_link(self):
+    return self.find_url('license')
+
+  FindLicenseLink = find_license_link
+
+  def get_license_link(self):
+    return self.get_link('license')
+
+  GetLicenseLink = get_license_link
+
+  def find_alternate_link(self):
+    return self.find_url('alternate')
+
+  FindAlternateLink = find_alternate_link
+
+  def get_alternate_link(self):
+    return self.get_link('alternate')
+
+  GetAlternateLink = get_alternate_link
+
+
+class FeedEntryParent(atom.core.XmlElement, LinkFinder):
+  """A super class for atom:feed and entry, contains shared attributes"""
+  author = [Author]
+  category = [Category]
+  contributor = [Contributor]
+  id = Id
+  link = [Link]
+  rights = Rights
+  title = Title
+  updated = Updated
+
+  def __init__(self, atom_id=None, text=None, *args, **kwargs):
+    if atom_id is not None:
+      self.id = atom_id
+    atom.core.XmlElement.__init__(self, text=text, *args, **kwargs)
+
+
+class Source(FeedEntryParent):
+  """The atom:source element."""
+  _qname = ATOM_TEMPLATE % 'source'
+  generator = Generator
+  icon = Icon
+  logo = Logo
+  subtitle = Subtitle
+
+
+class Entry(FeedEntryParent):
+  """The atom:entry element."""
+  _qname = ATOM_TEMPLATE % 'entry'
+  content = Content
+  published = Published
+  source = Source
+  summary = Summary
+  control = Control
+
+
+class Feed(Source):
+  """The atom:feed element which contains entries."""
+  _qname = ATOM_TEMPLATE % 'feed'
+  entry = [Entry]
+
+
+class ExtensionElement(atom.core.XmlElement):
+  """Provided for backwards compatibility to the v1 atom.ExtensionElement."""
+
+  def __init__(self, tag=None, namespace=None, attributes=None,
+      children=None, text=None, *args, **kwargs):
+    if namespace:
+      self._qname = '{%s}%s' % (namespace, tag)
+    else:
+      self._qname = tag
+    self.children = children or []
+    self.attributes = attributes or {}
+    self.text = text
+
+  _BecomeChildElement = atom.core.XmlElement._become_child
+
+

python/atom/http.py

@@ -0,0 +1,318 @@
+#!/usr/bin/python
+#
+# Copyright (C) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""HttpClients in this module use httplib to make HTTP requests.
+
+This module make HTTP requests based on httplib, but there are environments
+in which an httplib based approach will not work (if running in Google App
+Engine for example). In those cases, higher level classes (like AtomService
+and GDataService) can swap out the HttpClient to transparently use a 
+different mechanism for making HTTP requests.
+
+  HttpClient: Contains a request method which performs an HTTP call to the 
+      server.
+      
+  ProxiedHttpClient: Contains a request method which connects to a proxy using
+      settings stored in operating system environment variables then 
+      performs an HTTP call to the endpoint server.
+"""
+
+
+__author__ = 'api.jscudder (Jeff Scudder)'
+
+
+import types
+import os
+import httplib
+import atom.url
+import atom.http_interface
+import socket
+import base64
+import atom.http_core
+ssl_imported = False
+ssl = None
+try:
+  import ssl
+  ssl_imported = True
+except ImportError:
+  pass
+  
+
+
+class ProxyError(atom.http_interface.Error):
+  pass
+
+
+class TestConfigurationError(Exception):
+  pass
+
+
+DEFAULT_CONTENT_TYPE = 'application/atom+xml'
+
+
+class HttpClient(atom.http_interface.GenericHttpClient):
+  # Added to allow old v1 HttpClient objects to use the new 
+  # http_code.HttpClient. Used in unit tests to inject a mock client.
+  v2_http_client = None
+
+  def __init__(self, headers=None):
+    self.debug = False
+    self.headers = headers or {}
+
+  def request(self, operation, url, data=None, headers=None):
+    """Performs an HTTP call to the server, supports GET, POST, PUT, and 
+    DELETE.
+
+    Usage example, perform and HTTP GET on http://www.google.com/:
+      import atom.http
+      client = atom.http.HttpClient()
+      http_response = client.request('GET', 'http://www.google.com/')
+
+    Args:
+      operation: str The HTTP operation to be performed. This is usually one
+          of 'GET', 'POST', 'PUT', or 'DELETE'
+      data: filestream, list of parts, or other object which can be converted
+          to a string. Should be set to None when performing a GET or DELETE.
+          If data is a file-like object which can be read, this method will 
+          read a chunk of 100K bytes at a time and send them. 
+          If the data is a list of parts to be sent, each part will be 
+          evaluated and sent.
+      url: The full URL to which the request should be sent. Can be a string
+          or atom.url.Url.
+      headers: dict of strings. HTTP headers which should be sent
+          in the request. 
+    """
+    all_headers = self.headers.copy()
+    if headers:
+      all_headers.update(headers)
+
+    # If the list of headers does not include a Content-Length, attempt to
+    # calculate it based on the data object.
+    if data and 'Content-Length' not in all_headers:
+      if isinstance(data, types.StringTypes):
+        all_headers['Content-Length'] = str(len(data))
+      else:
+        raise atom.http_interface.ContentLengthRequired('Unable to calculate '
+            'the length of the data parameter. Specify a value for '
+            'Content-Length')
+
+    # Set the content type to the default value if none was set.
+    if 'Content-Type' not in all_headers:
+      all_headers['Content-Type'] = DEFAULT_CONTENT_TYPE
+
+    if self.v2_http_client is not None:
+      http_request = atom.http_core.HttpRequest(method=operation)
+      atom.http_core.Uri.parse_uri(str(url)).modify_request(http_request)
+      http_request.headers = all_headers
+      if data:
+        http_request._body_parts.append(data)
+      return self.v2_http_client.request(http_request=http_request)
+
+    if not isinstance(url, atom.url.Url):
+      if isinstance(url, types.StringTypes):
+        url = atom.url.parse_url(url)
+      else:
+        raise atom.http_interface.UnparsableUrlObject('Unable to parse url '
+            'parameter because it was not a string or atom.url.Url')
+    
+    connection = self._prepare_connection(url, all_headers)
+
+    if self.debug:
+      connection.debuglevel = 1
+
+    connection.putrequest(operation, self._get_access_url(url), 
+        skip_host=True)
+    if url.port is not None:
+      connection.putheader('Host', '%s:%s' % (url.host, url.port))
+    else:
+      connection.putheader('Host', url.host)
+
+    # Overcome a bug in Python 2.4 and 2.5
+    # httplib.HTTPConnection.putrequest adding
+    # HTTP request header 'Host: www.google.com:443' instead of
+    # 'Host: www.google.com', and thus resulting the error message
+    # 'Token invalid - AuthSub token has wrong scope' in the HTTP response.
+    if (url.protocol == 'https' and int(url.port or 443) == 443 and
+        hasattr(connection, '_buffer') and
+        isinstance(connection._buffer, list)):
+      header_line = 'Host: %s:443' % url.host
+      replacement_header_line = 'Host: %s' % url.host
+      try:
+        connection._buffer[connection._buffer.index(header_line)] = (
+            replacement_header_line)
+      except ValueError:  # header_line missing from connection._buffer
+        pass
+
+    # Send the HTTP headers.
+    for header_name in all_headers:
+      connection.putheader(header_name, all_headers[header_name])
+    connection.endheaders()
+
+    # If there is data, send it in the request.
+    if data:
+      if isinstance(data, list):
+        for data_part in data:
+          _send_data_part(data_part, connection)
+      else:
+        _send_data_part(data, connection)
+
+    # Return the HTTP Response from the server.
+    return connection.getresponse()
+    
+  def _prepare_connection(self, url, headers):
+    if not isinstance(url, atom.url.Url):
+      if isinstance(url, types.StringTypes):
+        url = atom.url.parse_url(url)
+      else:
+        raise atom.http_interface.UnparsableUrlObject('Unable to parse url '
+            'parameter because it was not a string or atom.url.Url')
+    if url.protocol == 'https':
+      if not url.port:
+        return httplib.HTTPSConnection(url.host)
+      return httplib.HTTPSConnection(url.host, int(url.port))
+    else:
+      if not url.port:
+        return httplib.HTTPConnection(url.host)
+      return httplib.HTTPConnection(url.host, int(url.port))
+
+  def _get_access_url(self, url):
+    return url.to_string()
+
+
+class ProxiedHttpClient(HttpClient):
+  """Performs an HTTP request through a proxy.
+  
+  The proxy settings are obtained from enviroment variables. The URL of the 
+  proxy server is assumed to be stored in the environment variables 
+  'https_proxy' and 'http_proxy' respectively. If the proxy server requires
+  a Basic Auth authorization header, the username and password are expected to 
+  be in the 'proxy-username' or 'proxy_username' variable and the 
+  'proxy-password' or 'proxy_password' variable.
+  
+  After connecting to the proxy server, the request is completed as in 
+  HttpClient.request.
+  """
+  def _prepare_connection(self, url, headers):
+    proxy_auth = _get_proxy_auth()
+    if url.protocol == 'https':
+      # destination is https
+      proxy = os.environ.get('https_proxy')
+      if proxy:
+        # Set any proxy auth headers 
+        if proxy_auth:
+          proxy_auth = 'Proxy-authorization: %s' % proxy_auth
+          
+        # Construct the proxy connect command.
+        port = url.port
+        if not port:
+          port = '443'
+        proxy_connect = 'CONNECT %s:%s HTTP/1.0\r\n' % (url.host, port)
+        
+        # Set the user agent to send to the proxy
+        if headers and 'User-Agent' in headers:
+          user_agent = 'User-Agent: %s\r\n' % (headers['User-Agent'])
+        else:
+          user_agent = ''
+        
+        proxy_pieces = '%s%s%s\r\n' % (proxy_connect, proxy_auth, user_agent)
+        
+        # Find the proxy host and port.
+        proxy_url = atom.url.parse_url(proxy)
+        if not proxy_url.port:
+          proxy_url.port = '80'
+        
+        # Connect to the proxy server, very simple recv and error checking
+        p_sock = socket.socket(socket.AF_INET,socket.SOCK_STREAM)
+        p_sock.connect((proxy_url.host, int(proxy_url.port)))
+        p_sock.sendall(proxy_pieces)
+        response = ''
+
+        # Wait for the full response.
+        while response.find("\r\n\r\n") == -1:
+          response += p_sock.recv(8192)
+       
+        p_status = response.split()[1]
+        if p_status != str(200):
+          raise ProxyError('Error status=%s' % str(p_status))
+
+        # Trivial setup for ssl socket.
+        sslobj = None
+        if ssl_imported:
+          sslobj = ssl.wrap_socket(p_sock, None, None)
+        else:
+          sock_ssl = socket.ssl(p_sock, None, None)
+          sslobj = httplib.FakeSocket(p_sock, sock_ssl)
+ 
+        # Initalize httplib and replace with the proxy socket.
+        connection = httplib.HTTPConnection(proxy_url.host)
+        connection.sock = sslobj
+        return connection
+      else:
+        # The request was HTTPS, but there was no https_proxy set.
+        return HttpClient._prepare_connection(self, url, headers)
+    else:
+      proxy = os.environ.get('http_proxy')
+      if proxy:
+        # Find the proxy host and port.
+        proxy_url = atom.url.parse_url(proxy)
+        if not proxy_url.port:
+          proxy_url.port = '80'
+        
+        if proxy_auth:
+          headers['Proxy-Authorization'] = proxy_auth.strip()
+
+        return httplib.HTTPConnection(proxy_url.host, int(proxy_url.port))
+      else:
+        # The request was HTTP, but there was no http_proxy set.
+        return HttpClient._prepare_connection(self, url, headers)
+
+  def _get_access_url(self, url):
+    return url.to_string()
+
+
+def _get_proxy_auth():
+  proxy_username = os.environ.get('proxy-username')
+  if not proxy_username:
+    proxy_username = os.environ.get('proxy_username')
+  proxy_password = os.environ.get('proxy-password')
+  if not proxy_password:
+    proxy_password = os.environ.get('proxy_password')
+  if proxy_username:
+    user_auth = base64.encodestring('%s:%s' % (proxy_username,
+                                               proxy_password))
+    return 'Basic %s\r\n' % (user_auth.strip())
+  else:
+    return ''
+
+
+def _send_data_part(data, connection):
+  if isinstance(data, types.StringTypes):
+    connection.send(data)
+    return
+  # Check to see if data is a file-like object that has a read method.
+  elif hasattr(data, 'read'):
+    # Read the file and send it a chunk at a time.
+    while 1:
+      binarydata = data.read(100000)
+      if binarydata == '': break
+      connection.send(binarydata)
+    return
+  else:
+    # The data object was not a file.
+    # Try to convert to a string and send the data.
+    connection.send(str(data))
+    return

python/atom/http_core.py

@@ -0,0 +1,597 @@
+#!/usr/bin/env python
+#
+#    Copyright (C) 2009 Google Inc.
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+
+# This module is used for version 2 of the Google Data APIs.
+# TODO: add proxy handling.
+
+
+__author__ = 'j.s@google.com (Jeff Scudder)'
+
+
+import os
+import StringIO
+import urlparse
+import urllib
+import httplib
+ssl = None
+try:
+  import ssl
+except ImportError:
+  pass
+
+
+
+class Error(Exception):
+  pass
+
+
+class UnknownSize(Error):
+  pass
+
+
+class ProxyError(Error):
+  pass
+
+
+MIME_BOUNDARY = 'END_OF_PART'
+
+
+def get_headers(http_response):
+  """Retrieves all HTTP headers from an HTTP response from the server.
+  
+  This method is provided for backwards compatibility for Python2.2 and 2.3.
+  The httplib.HTTPResponse object in 2.2 and 2.3 does not have a getheaders
+  method so this function will use getheaders if available, but if not it
+  will retrieve a few using getheader.
+  """
+  if hasattr(http_response, 'getheaders'):
+    return http_response.getheaders()
+  else:
+    headers = []
+    for header in (
+        'location', 'content-type', 'content-length', 'age', 'allow',
+        'cache-control', 'content-location', 'content-encoding', 'date',
+        'etag', 'expires', 'last-modified', 'pragma', 'server',
+        'set-cookie', 'transfer-encoding', 'vary', 'via', 'warning',
+        'www-authenticate', 'gdata-version'):
+      value = http_response.getheader(header, None)
+      if value is not None:
+        headers.append((header, value))
+    return headers
+
+
+class HttpRequest(object):
+  """Contains all of the parameters for an HTTP 1.1 request.
+
+  The HTTP headers are represented by a dictionary, and it is the
+  responsibility of the user to ensure that duplicate field names are combined
+  into one header value according to the rules in section 4.2 of RFC 2616.
+  """
+  method = None
+  uri = None
+
+  def __init__(self, uri=None, method=None, headers=None):
+    """Construct an HTTP request.
+
+    Args:
+      uri: The full path or partial path as a Uri object or a string.
+      method: The HTTP method for the request, examples include 'GET', 'POST',
+              etc.
+      headers: dict of strings The HTTP headers to include in the request.
+    """
+    self.headers = headers or {}
+    self._body_parts = []
+    if method is not None:
+      self.method = method
+    if isinstance(uri, (str, unicode)):
+      uri = Uri.parse_uri(uri)
+    self.uri = uri or Uri()
+
+
+  def add_body_part(self, data, mime_type, size=None):
+    """Adds data to the HTTP request body.
+
+    If more than one part is added, this is assumed to be a mime-multipart
+    request. This method is designed to create MIME 1.0 requests as specified
+    in RFC 1341.
+
+    Args:
+      data: str or a file-like object containing a part of the request body.
+      mime_type: str The MIME type describing the data
+      size: int Required if the data is a file like object. If the data is a
+            string, the size is calculated so this parameter is ignored.
+    """
+    if isinstance(data, str):
+      size = len(data)
+    if size is None:
+      # TODO: support chunked transfer if some of the body is of unknown size.
+      raise UnknownSize('Each part of the body must have a known size.')
+    if 'Content-Length' in self.headers:
+      content_length = int(self.headers['Content-Length'])
+    else:
+      content_length = 0
+    # If this is the first part added to the body, then this is not a multipart
+    # request.
+    if len(self._body_parts) == 0:
+      self.headers['Content-Type'] = mime_type
+      content_length = size
+      self._body_parts.append(data)
+    elif len(self._body_parts) == 1:
+      # This is the first member in a mime-multipart request, so change the
+      # _body_parts list to indicate a multipart payload.
+      self._body_parts.insert(0, 'Media multipart posting')
+      boundary_string = '\r\n--%s\r\n' % (MIME_BOUNDARY,)
+      content_length += len(boundary_string) + size
+      self._body_parts.insert(1, boundary_string)
+      content_length += len('Media multipart posting')
+      # Put the content type of the first part of the body into the multipart
+      # payload.
+      original_type_string = 'Content-Type: %s\r\n\r\n' % (
+          self.headers['Content-Type'],)
+      self._body_parts.insert(2, original_type_string)
+      content_length += len(original_type_string)
+      boundary_string = '\r\n--%s\r\n' % (MIME_BOUNDARY,)
+      self._body_parts.append(boundary_string)
+      content_length += len(boundary_string)
+      # Change the headers to indicate this is now a mime multipart request.
+      self.headers['Content-Type'] = 'multipart/related; boundary="%s"' % (
+          MIME_BOUNDARY,)
+      self.headers['MIME-version'] = '1.0'
+      # Include the mime type of this part.
+      type_string = 'Content-Type: %s\r\n\r\n' % (mime_type)
+      self._body_parts.append(type_string)
+      content_length += len(type_string)
+      self._body_parts.append(data)
+      ending_boundary_string = '\r\n--%s--' % (MIME_BOUNDARY,)
+      self._body_parts.append(ending_boundary_string)
+      content_length += len(ending_boundary_string)
+    else:
+      # This is a mime multipart request.
+      boundary_string = '\r\n--%s\r\n' % (MIME_BOUNDARY,)
+      self._body_parts.insert(-1, boundary_string)
+      content_length += len(boundary_string) + size
+      # Include the mime type of this part.
+      type_string = 'Content-Type: %s\r\n\r\n' % (mime_type)
+      self._body_parts.insert(-1, type_string)
+      content_length += len(type_string)
+      self._body_parts.insert(-1, data)
+    self.headers['Content-Length'] = str(content_length)
+  # I could add an "append_to_body_part" method as well.
+
+  AddBodyPart = add_body_part
+
+  def add_form_inputs(self, form_data,
+                      mime_type='application/x-www-form-urlencoded'):
+    """Form-encodes and adds data to the request body.
+
+    Args:
+      form_data: dict or sequnce or two member tuples which contains the
+                 form keys and values.
+      mime_type: str The MIME type of the form data being sent. Defaults
+                 to 'application/x-www-form-urlencoded'.
+    """
+    body = urllib.urlencode(form_data)
+    self.add_body_part(body, mime_type)
+
+  AddFormInputs = add_form_inputs
+
+  def _copy(self):
+    """Creates a deep copy of this request."""
+    copied_uri = Uri(self.uri.scheme, self.uri.host, self.uri.port,
+                     self.uri.path, self.uri.query.copy())
+    new_request = HttpRequest(uri=copied_uri, method=self.method,
+                              headers=self.headers.copy())
+    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:
+    if http_request.uri.port == 443:
+      http_request.uri.scheme = 'https'
+    else:
+      http_request.uri.scheme = 'http'
+
+
+class Uri(object):
+  """A URI as used in HTTP 1.1"""
+  scheme = None
+  host = None
+  port = None
+  path = None
+
+  def __init__(self, scheme=None, host=None, port=None, path=None, query=None):
+    """Constructor for a URI.
+
+    Args:
+      scheme: str This is usually 'http' or 'https'.
+      host: str The host name or IP address of the desired server.
+      post: int The server's port number.
+      path: str The path of the resource following the host. This begins with
+            a /, example: '/calendar/feeds/default/allcalendars/full'
+      query: dict of strings The URL query parameters. The keys and values are
+             both escaped so this dict should contain the unescaped values.
+             For example {'my key': 'val', 'second': '!!!'} will become
+             '?my+key=val&second=%21%21%21' which is appended to the path.
+    """
+    self.query = query or {}
+    if scheme is not None:
+      self.scheme = scheme
+    if host is not None:
+      self.host = host
+    if port is not None:
+      self.port = port
+    if path:
+      self.path = path
+
+  def _get_query_string(self):
+    param_pairs = []
+    for key, value in self.query.iteritems():
+      param_pairs.append('='.join((urllib.quote_plus(key),
+          urllib.quote_plus(str(value)))))
+    return '&'.join(param_pairs)
+
+  def _get_relative_path(self):
+    """Returns the path with the query parameters escaped and appended."""
+    param_string = self._get_query_string()
+    if self.path is None:
+      path = '/'
+    else:
+      path = self.path
+    if param_string:
+      return '?'.join([path, param_string])
+    else:
+      return path
+
+  def _to_string(self):
+    if self.scheme is None and self.port == 443:
+      scheme = 'https'
+    elif self.scheme is None:
+      scheme = 'http'
+    else:
+      scheme = self.scheme
+    if self.path is None:
+      path = '/'
+    else:
+      path = self.path
+    if self.port is None:
+      return '%s://%s%s' % (scheme, self.host, self._get_relative_path())
+    else:
+      return '%s://%s:%s%s' % (scheme, self.host, str(self.port),
+                               self._get_relative_path())
+
+  def __str__(self):
+    return self._to_string()
+
+  def modify_request(self, http_request=None):
+    """Sets HTTP request components based on the URI."""
+    if http_request is None:
+      http_request = HttpRequest()
+    if http_request.uri is None:
+      http_request.uri = Uri()
+    # Determine the correct scheme.
+    if self.scheme:
+      http_request.uri.scheme = self.scheme
+    if self.port:
+      http_request.uri.port = self.port
+    if self.host:
+      http_request.uri.host = self.host
+    # Set the relative uri path
+    if self.path:
+      http_request.uri.path = self.path
+    if self.query:
+      http_request.uri.query = self.query.copy()
+    return http_request
+
+  ModifyRequest = modify_request
+
+  def parse_uri(uri_string):
+    """Creates a Uri object which corresponds to the URI string.
+
+    This method can accept partial URIs, but it will leave missing
+    members of the Uri unset.
+    """
+    parts = urlparse.urlparse(uri_string)
+    uri = Uri()
+    if parts[0]:
+      uri.scheme = parts[0]
+    if parts[1]:
+      host_parts = parts[1].split(':')
+      if host_parts[0]:
+        uri.host = host_parts[0]
+      if len(host_parts) > 1:
+        uri.port = int(host_parts[1])
+    if parts[2]:
+      uri.path = parts[2]
+    if parts[4]:
+      param_pairs = parts[4].split('&')
+      for pair in param_pairs:
+        pair_parts = pair.split('=')
+        if len(pair_parts) > 1:
+          uri.query[urllib.unquote_plus(pair_parts[0])] = (
+              urllib.unquote_plus(pair_parts[1]))
+        elif len(pair_parts) == 1:
+          uri.query[urllib.unquote_plus(pair_parts[0])] = None
+    return uri
+
+  parse_uri = staticmethod(parse_uri)
+
+  ParseUri = parse_uri
+
+
+parse_uri = Uri.parse_uri
+
+
+ParseUri = Uri.parse_uri
+
+
+class HttpResponse(object):
+  status = None
+  reason = None
+  _body = None
+
+  def __init__(self, status=None, reason=None, headers=None, body=None):
+    self._headers = headers or {}
+    if status is not None:
+      self.status = status
+    if reason is not None:
+      self.reason = reason
+    if body is not None:
+      if hasattr(body, 'read'):
+        self._body = body
+      else:
+        self._body = StringIO.StringIO(body)
+
+  def getheader(self, name, default=None):
+    if name in self._headers:
+      return self._headers[name]
+    else:
+      return default
+
+  def getheaders(self):
+    return self._headers
+
+  def read(self, amt=None):
+    if self._body is None:
+      return None
+    if not amt:
+      return self._body.read()
+    else:
+      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 = get_headers(http_response)
+  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
+
+  def request(self, http_request):
+    return self._http_request(http_request.method, http_request.uri,
+                              http_request.headers, http_request._body_parts)
+
+  Request = request
+
+  def _get_connection(self, uri, headers=None):
+    """Opens a socket connection to the server to set up an HTTP request.
+
+    Args:
+      uri: The full URL for the request as a Uri object.
+      headers: A dict of string pairs containing the HTTP headers for the
+          request.
+    """
+    connection = None
+    if uri.scheme == 'https':
+      if not uri.port:
+        connection = httplib.HTTPSConnection(uri.host)
+      else:
+        connection = httplib.HTTPSConnection(uri.host, int(uri.port))
+    else:
+      if not uri.port:
+        connection = httplib.HTTPConnection(uri.host)
+      else:
+        connection = httplib.HTTPConnection(uri.host, int(uri.port))
+    return connection
+
+  def _http_request(self, method, uri, headers=None, body_parts=None):
+    """Makes an HTTP request using httplib.
+
+    Args:
+      method: str example: 'GET', 'POST', 'PUT', 'DELETE', etc.
+      uri: str or atom.http_core.Uri
+      headers: dict of strings mapping to strings which will be sent as HTTP
+               headers in the request.
+      body_parts: list of strings, objects with a read method, or objects
+                  which can be converted to strings using str. Each of these
+                  will be sent in order as the body of the HTTP request.
+    """
+    if isinstance(uri, (str, unicode)):
+      uri = Uri.parse_uri(uri)
+
+    connection = self._get_connection(uri, headers=headers)
+
+    if self.debug:
+      connection.debuglevel = 1
+
+    if connection.host != uri.host:
+      connection.putrequest(method, str(uri))
+    else:
+      connection.putrequest(method, uri._get_relative_path())
+
+    # Overcome a bug in Python 2.4 and 2.5
+    # httplib.HTTPConnection.putrequest adding
+    # HTTP request header 'Host: www.google.com:443' instead of
+    # 'Host: www.google.com', and thus resulting the error message
+    # 'Token invalid - AuthSub token has wrong scope' in the HTTP response.
+    if (uri.scheme == 'https' and int(uri.port or 443) == 443 and
+        hasattr(connection, '_buffer') and
+        isinstance(connection._buffer, list)):
+      header_line = 'Host: %s:443' % uri.host
+      replacement_header_line = 'Host: %s' % uri.host
+      try:
+        connection._buffer[connection._buffer.index(header_line)] = (
+            replacement_header_line)
+      except ValueError:  # header_line missing from connection._buffer
+        pass
+
+    # Send the HTTP headers.
+    for header_name, value in headers.iteritems():
+      connection.putheader(header_name, value)
+    connection.endheaders()
+
+    # If there is data, send it in the request.
+    if body_parts:
+      for part in body_parts:
+        _send_data_part(part, connection)
+
+    # Return the HTTP Response from the server.
+    return connection.getresponse()
+
+
+def _send_data_part(data, connection):
+  if isinstance(data, (str, unicode)):
+    # I might want to just allow str, not unicode.
+    connection.send(data)
+    return
+  # Check to see if data is a file-like object that has a read method.
+  elif hasattr(data, 'read'):
+    # Read the file and send it a chunk at a time.
+    while 1:
+      binarydata = data.read(100000)
+      if binarydata == '': break
+      connection.send(binarydata)
+    return
+  else:
+    # The data object was not a file.
+    # Try to convert to a string and send the data.
+    connection.send(str(data))
+    return
+
+
+class ProxiedHttpClient(HttpClient):
+
+  def _get_connection(self, uri, headers=None):
+    # Check to see if there are proxy settings required for this request.
+    proxy = None
+    if uri.scheme == 'https':
+      proxy = os.environ.get('https_proxy')
+    elif uri.scheme == 'http':
+      proxy = os.environ.get('http_proxy')
+    if not proxy:
+      return HttpClient._get_connection(self, uri, headers=headers)
+    # Now we have the URL of the appropriate proxy server.
+    # Get a username and password for the proxy if required.
+    proxy_auth = _get_proxy_auth()
+    if uri.scheme == 'https':
+      import socket
+      if proxy_auth:
+        proxy_auth = 'Proxy-authorization: %s' % proxy_auth
+      # Construct the proxy connect command.
+      port = uri.port
+      if not port:
+        port = 443
+      proxy_connect = 'CONNECT %s:%s HTTP/1.0\r\n' % (uri.host, port)
+      # Set the user agent to send to the proxy
+      user_agent = ''
+      if headers and 'User-Agent' in headers:
+        user_agent = 'User-Agent: %s\r\n' % (headers['User-Agent'])
+      proxy_pieces = '%s%s%s\r\n' % (proxy_connect, proxy_auth, user_agent)
+      # Find the proxy host and port.
+      proxy_uri = Uri.parse_uri(proxy)
+      if not proxy_uri.port:
+        proxy_uri.port = '80'
+      # Connect to the proxy server, very simple recv and error checking
+      p_sock = socket.socket(socket.AF_INET,socket.SOCK_STREAM)
+      p_sock.connect((proxy_uri.host, int(proxy_uri.port)))
+      p_sock.sendall(proxy_pieces)
+      response = ''
+      # Wait for the full response.
+      while response.find("\r\n\r\n") == -1:
+        response += p_sock.recv(8192)
+      p_status = response.split()[1]
+      if p_status != str(200):
+        raise ProxyError('Error status=%s' % str(p_status))
+      # Trivial setup for ssl socket.
+      sslobj = None
+      if ssl is not None:
+        sslobj = ssl.wrap_socket(p_sock, None, None)
+      else:
+        sock_ssl = socket.ssl(p_sock, None, Nonesock_)
+        sslobj = httplib.FakeSocket(p_sock, sock_ssl)
+      # Initalize httplib and replace with the proxy socket.
+      connection = httplib.HTTPConnection(proxy_uri.host)
+      connection.sock = sslobj
+      return connection
+    elif uri.scheme == 'http':
+      proxy_uri = Uri.parse_uri(proxy)
+      if not proxy_uri.port:
+        proxy_uri.port = '80'
+      if proxy_auth:
+        headers['Proxy-Authorization'] = proxy_auth.strip()
+      return httplib.HTTPConnection(proxy_uri.host, int(proxy_uri.port))
+    return None
+
+
+def _get_proxy_auth():
+  import base64
+  proxy_username = os.environ.get('proxy-username')
+  if not proxy_username:
+    proxy_username = os.environ.get('proxy_username')
+  proxy_password = os.environ.get('proxy-password')
+  if not proxy_password:
+    proxy_password = os.environ.get('proxy_password')
+  if proxy_username:
+    user_auth = base64.b64encode('%s:%s' % (proxy_username,
+                                            proxy_password))
+    return 'Basic %s\r\n' % (user_auth.strip())
+  else:
+    return ''

python/atom/http_interface.py

@@ -0,0 +1,156 @@
+#!/usr/bin/python
+#
+# Copyright (C) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""This module provides a common interface for all HTTP requests.
+
+  HttpResponse: Represents the server's response to an HTTP request. Provides
+      an interface identical to httplib.HTTPResponse which is the response
+      expected from higher level classes which use HttpClient.request.
+
+  GenericHttpClient: Provides an interface (superclass) for an object 
+      responsible for making HTTP requests. Subclasses of this object are
+      used in AtomService and GDataService to make requests to the server. By
+      changing the http_client member object, the AtomService is able to make
+      HTTP requests using different logic (for example, when running on 
+      Google App Engine, the http_client makes requests using the App Engine
+      urlfetch API). 
+"""
+
+
+__author__ = 'api.jscudder (Jeff Scudder)'
+
+
+import StringIO
+
+
+USER_AGENT = '%s GData-Python/2.0.12'
+
+
+class Error(Exception):
+  pass
+
+
+class UnparsableUrlObject(Error):
+  pass
+
+
+class ContentLengthRequired(Error):
+  pass
+  
+
+class HttpResponse(object):
+  def __init__(self, body=None, status=None, reason=None, headers=None):
+    """Constructor for an HttpResponse object. 
+
+    HttpResponse represents the server's response to an HTTP request from
+    the client. The HttpClient.request method returns a httplib.HTTPResponse
+    object and this HttpResponse class is designed to mirror the interface
+    exposed by httplib.HTTPResponse.
+
+    Args:
+      body: A file like object, with a read() method. The body could also
+          be a string, and the constructor will wrap it so that 
+          HttpResponse.read(self) will return the full string.
+      status: The HTTP status code as an int. Example: 200, 201, 404.
+      reason: The HTTP status message which follows the code. Example: 
+          OK, Created, Not Found
+      headers: A dictionary containing the HTTP headers in the server's 
+          response. A common header in the response is Content-Length.
+    """
+    if body:
+      if hasattr(body, 'read'):
+        self._body = body
+      else:
+        self._body = StringIO.StringIO(body)
+    else:
+      self._body = None
+    if status is not None:
+      self.status = int(status)
+    else:
+      self.status = None
+    self.reason = reason
+    self._headers = headers or {}
+
+  def getheader(self, name, default=None):
+    if name in self._headers:
+      return self._headers[name]
+    else:
+      return default
+    
+  def read(self, amt=None):
+    if not amt:
+      return self._body.read()
+    else:
+      return self._body.read(amt)
+
+
+class GenericHttpClient(object):
+  debug = False
+
+  def __init__(self, http_client, headers=None):
+    """
+    
+    Args:
+      http_client: An object which provides a request method to make an HTTP 
+          request. The request method in GenericHttpClient performs a 
+          call-through to the contained HTTP client object.
+      headers: A dictionary containing HTTP headers which should be included
+          in every HTTP request. Common persistent headers include 
+          'User-Agent'.
+    """
+    self.http_client = http_client
+    self.headers = headers or {}
+
+  def request(self, operation, url, data=None, headers=None):
+    all_headers = self.headers.copy()
+    if headers:
+      all_headers.update(headers)
+    return self.http_client.request(operation, url, data=data, 
+        headers=all_headers)
+
+  def get(self, url, headers=None):
+    return self.request('GET', url, headers=headers)
+
+  def post(self, url, data, headers=None):
+    return self.request('POST', url, data=data, headers=headers)
+
+  def put(self, url, data, headers=None):
+    return self.request('PUT', url, data=data, headers=headers)
+
+  def delete(self, url, headers=None):
+    return self.request('DELETE', url, headers=headers)
+
+
+class GenericToken(object):
+  """Represents an Authorization token to be added to HTTP requests.
+  
+  Some Authorization headers included calculated fields (digital
+  signatures for example) which are based on the parameters of the HTTP
+  request. Therefore the token is responsible for signing the request
+  and adding the Authorization header. 
+  """
+  def perform_request(self, http_client, operation, url, data=None, 
+                      headers=None):
+    """For the GenericToken, no Authorization token is set."""
+    return http_client.request(operation, url, data=data, headers=headers)
+
+  def valid_for_scope(self, url):
+    """Tells the caller if the token authorizes access to the desired URL.
+    
+    Since the generic token doesn't add an auth header, it is not valid for
+    any scope.
+    """
+    return False

python/atom/mock_http.py

@@ -0,0 +1,132 @@
+#!/usr/bin/python
+#
+# Copyright (C) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+__author__ = 'api.jscudder (Jeff Scudder)'
+
+
+import atom.http_interface
+import atom.url
+
+
+class Error(Exception):
+  pass
+
+
+class NoRecordingFound(Error):
+  pass
+
+
+class MockRequest(object):
+  """Holds parameters of an HTTP request for matching against future requests.
+  """
+  def __init__(self, operation, url, data=None, headers=None):
+    self.operation = operation
+    if isinstance(url, (str, unicode)):
+      url = atom.url.parse_url(url)
+    self.url = url
+    self.data = data
+    self.headers = headers
+
+
+class MockResponse(atom.http_interface.HttpResponse):
+  """Simulates an httplib.HTTPResponse object."""
+  def __init__(self, body=None, status=None, reason=None, headers=None):
+    if body and hasattr(body, 'read'):
+      self.body = body.read()
+    else:
+      self.body = body
+    if status is not None:
+      self.status = int(status)
+    else:
+      self.status = None
+    self.reason = reason
+    self._headers = headers or {}
+
+  def read(self):
+    return self.body
+
+
+class MockHttpClient(atom.http_interface.GenericHttpClient):
+  def __init__(self, headers=None, recordings=None, real_client=None):
+    """An HttpClient which responds to request with stored data.
+
+    The request-response pairs are stored as tuples in a member list named
+    recordings.
+
+    The MockHttpClient can be switched from replay mode to record mode by
+    setting the real_client member to an instance of an HttpClient which will
+    make real HTTP requests and store the server's response in list of 
+    recordings.
+    
+    Args:
+      headers: dict containing HTTP headers which should be included in all
+          HTTP requests.
+      recordings: The initial recordings to be used for responses. This list
+          contains tuples in the form: (MockRequest, MockResponse)
+      real_client: An HttpClient which will make a real HTTP request. The 
+          response will be converted into a MockResponse and stored in 
+          recordings.
+    """
+    self.recordings = recordings or []
+    self.real_client = real_client
+    self.headers = headers or {}
+
+  def add_response(self, response, operation, url, data=None, headers=None):
+    """Adds a request-response pair to the recordings list.
+    
+    After the recording is added, future matching requests will receive the
+    response.
+    
+    Args:
+      response: MockResponse
+      operation: str
+      url: str
+      data: str, Currently the data is ignored when looking for matching
+          requests.
+      headers: dict of strings: Currently the headers are ignored when
+          looking for matching requests.
+    """
+    request = MockRequest(operation, url, data=data, headers=headers)
+    self.recordings.append((request, response))
+
+  def request(self, operation, url, data=None, headers=None):
+    """Returns a matching MockResponse from the recordings.
+    
+    If the real_client is set, the request will be passed along and the 
+    server's response will be added to the recordings and also returned. 
+
+    If there is no match, a NoRecordingFound error will be raised.
+    """
+    if self.real_client is None:
+      if isinstance(url, (str, unicode)):
+        url = atom.url.parse_url(url)
+      for recording in self.recordings:
+        if recording[0].operation == operation and recording[0].url == url:
+          return recording[1]
+      raise NoRecordingFound('No recodings found for %s %s' % (
+          operation, url))
+    else:
+      # There is a real HTTP client, so make the request, and record the 
+      # response.
+      response = self.real_client.request(operation, url, data=data, 
+          headers=headers)
+      # TODO: copy the headers
+      stored_response = MockResponse(body=response, status=response.status,
+          reason=response.reason)
+      self.add_response(stored_response, operation, url, data=data, 
+          headers=headers)
+      return stored_response

python/atom/mock_http_core.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python
+#
+# Copyright (C) 2009 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# This module is used for version 2 of the Google Data APIs.
+
+
+__author__ = 'j.s@google.com (Jeff Scudder)'
+
+
+import StringIO
+import pickle
+import os.path
+import tempfile
+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.
+  # These are combined to form the file name
+  # /tmp/cache_prefix.cache_case_name.cache_test_name
+  cache_name_prefix = 'gdata_live_test'
+  cache_case_name = ''
+  cache_test_name = ''
+
+  def __init__(self, recordings=None, real_client=None):
+    self._recordings = recordings or []
+    if real_client is not None:
+      self.real_client = real_client
+
+  def add_response(self, http_request, status, reason, headers=None,
+      body=None):
+    response = MockHttpResponse(status, reason, headers, body)
+    # TODO Scrub the request and the response.
+    self._recordings.append((http_request._copy(), response))
+
+  AddResponse = add_response
+
+  def request(self, http_request):
+    """Provide a recorded response, or record a response for replay.
+
+    If the real_client is set, the request will be made using the
+    real_client, and the response from the server will be recorded.
+    If the real_client is None (the default), this method will examine
+    the recordings and find the first which matches.
+    """
+    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)
+      scrubbed_response = _scrub_response(response)
+      self.add_response(request, scrubbed_response.status,
+                        scrubbed_response.reason,
+                        dict(atom.http_core.get_headers(scrubbed_response)),
+                        scrubbed_response.read())
+      # Return the recording which we just added.
+      return self._recordings[-1][1]
+    raise NoRecordingFound('No recoding was found for request: %s %s' % (
+        request.method, str(request.uri)))
+
+  Request = request
+
+  def _save_recordings(self, filename):
+    recording_file = open(os.path.join(tempfile.gettempdir(), filename),
+                          'wb')
+    pickle.dump(self._recordings, recording_file)
+    recording_file.close()
+
+  def _load_recordings(self, filename):
+    recording_file = open(os.path.join(tempfile.gettempdir(), filename),
+                          'rb')
+    self._recordings = pickle.load(recording_file)
+    recording_file.close()
+
+  def _delete_recordings(self, filename):
+    full_path = os.path.join(tempfile.gettempdir(), filename)
+    if os.path.exists(full_path):
+      os.remove(full_path)
+
+  def _load_or_use_client(self, filename, http_client):
+    if os.path.exists(os.path.join(tempfile.gettempdir(), filename)):
+      self._load_recordings(filename)
+    else:
+      self.real_client = http_client
+
+  def use_cached_session(self, name=None, real_http_client=None):
+    """Attempts to load recordings from a previous live request.
+
+    If a temp file with the recordings exists, then it is used to fulfill
+    requests. If the file does not exist, then a real client is used to
+    actually make the desired HTTP requests. Requests and responses are
+    recorded and will be written to the desired temprary cache file when
+    close_session is called.
+
+    Args:
+      name: str (optional) The file name of session file to be used. The file
+            is loaded from the temporary directory of this machine. If no name
+            is passed in, a default name will be constructed using the
+            cache_name_prefix, cache_case_name, and cache_test_name of this
+            object.
+      real_http_client: atom.http_core.HttpClient the real client to be used
+                        if the cached recordings are not found. If the default
+                        value is used, this will be an
+                        atom.http_core.HttpClient.
+    """
+    if real_http_client is None:
+      real_http_client = atom.http_core.HttpClient()
+    if name is None:
+      self._recordings_cache_name = self.get_cache_file_name()
+    else:
+      self._recordings_cache_name = name
+    self._load_or_use_client(self._recordings_cache_name, real_http_client)
+
+  def close_session(self):
+    """Saves recordings in the temporary file named in use_cached_session."""
+    if self.real_client is not None:
+      self._save_recordings(self._recordings_cache_name)
+
+  def delete_session(self, name=None):
+    """Removes recordings from a previous live request."""
+    if name is None:
+      self._delete_recordings(self._recordings_cache_name)
+    else:
+      self._delete_recordings(name)
+
+  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
+     to cause the stored response to be returned."""
+  # Check to see if the host names match.
+  if (http_request.uri.host is not None
+      and http_request.uri.host != stored_request.uri.host):
+    return False
+  # Check the request path in the URL (/feeds/private/full/x)
+  elif http_request.uri.path != stored_request.uri.path:
+    return False
+  # Check the method used in the request (GET, POST, etc.)
+  elif http_request.method != stored_request.method:
+    return False
+  # If there is a gsession ID in either request, make sure that it is matched
+  # exactly.
+  elif ('gsessionid' in http_request.uri.query
+        or 'gsessionid' in stored_request.uri.query):
+    if 'gsessionid' not in stored_request.uri.query:
+      return False
+    elif 'gsessionid' not in http_request.uri.query:
+      return False
+    elif (http_request.uri.query['gsessionid']
+          != stored_request.uri.query['gsessionid']):
+      return False
+  # Ignores differences in the query params (?start-index=5&max-results=20),
+  # the body of the request, the port number, HTTP headers, just to name a
+  # few.
+  return True
+
+
+def _scrub_request(http_request):
+  """ Removes email address and password from a client login request.
+
+  Since the mock server saves the request and response in plantext, sensitive
+  information like the password should be removed before saving the
+  recordings. At the moment only requests sent to a ClientLogin url are
+  scrubbed.
+  """
+  if (http_request and http_request.uri and http_request.uri.path and
+      http_request.uri.path.endswith('ClientLogin')):
+    # Remove the email and password from a ClientLogin request.
+    http_request._body_parts = []
+    http_request.add_form_inputs(
+        {'form_data': 'client login request has been scrubbed'})
+  else:
+    # We can remove the body of the post from the recorded request, since
+    # the request body is not used when finding a matching recording.
+    http_request._body_parts = []
+  return http_request
+
+
+def _scrub_response(http_response):
+  return http_response
+
+
+class EchoHttpClient(object):
+  """Sends the request data back in the response.
+
+  Used to check the formatting of the request as it was sent. Always responds
+  with a 200 OK, and some information from the HTTP request is returned in
+  special Echo-X headers in the response. The following headers are added
+  in the response:
+  'Echo-Host': The host name and port number to which the HTTP connection is
+               made. If no port was passed in, the header will contain
+               host:None.
+  'Echo-Uri': The path portion of the URL being requested. /example?x=1&y=2
+  'Echo-Scheme': The beginning of the URL, usually 'http' or 'https'
+  'Echo-Method': The HTTP method being used, 'GET', 'POST', 'PUT', etc.
+  """
+
+  def request(self, http_request):
+    return self._http_request(http_request.uri, http_request.method,
+                              http_request.headers, http_request._body_parts)
+
+  def _http_request(self, uri, method, headers=None, body_parts=None):
+    body = StringIO.StringIO()
+    response = atom.http_core.HttpResponse(status=200, reason='OK', body=body)
+    if headers is None:
+      response._headers = {}
+    else:
+      # Copy headers from the request to the response but convert values to
+      # strings. Server response headers always come in as strings, so an int
+      # should be converted to a corresponding string when echoing.
+      for header, value in headers.iteritems():
+        response._headers[header] = str(value)
+    response._headers['Echo-Host'] = '%s:%s' % (uri.host, str(uri.port))
+    response._headers['Echo-Uri'] = uri._get_relative_path()
+    response._headers['Echo-Scheme'] = uri.scheme
+    response._headers['Echo-Method'] = method
+    for part in body_parts:
+      if isinstance(part, str):
+        body.write(part)
+      elif hasattr(part, 'read'):
+        body.write(part.read())
+    body.seek(0)
+    return response
+
+
+class SettableHttpClient(object):
+  """An HTTP Client which responds with the data given in set_response."""
+
+  def __init__(self, status, reason, body, headers):
+    """Configures the response for the server.
+
+    See set_response for details on the arguments to the constructor.
+    """
+    self.set_response(status, reason, body, headers)
+    self.last_request = None
+
+  def set_response(self, status, reason, body, headers):
+    """Determines the response which will be sent for each request.
+
+    Args:
+      status: An int for the HTTP status code, example: 200, 404, etc.
+      reason: String for the HTTP reason, example: OK, NOT FOUND, etc.
+      body: The body of the HTTP response as a string or a file-like
+            object (something with a read method).
+      headers: dict of strings containing the HTTP headers in the response.
+    """
+    self.response = atom.http_core.HttpResponse(status=status, reason=reason,
+        body=body)
+    self.response._headers = headers.copy()
+
+  def request(self, http_request):
+    self.last_request = http_request
+    return self.response
+
+
+class MockHttpResponse(atom.http_core.HttpResponse):
+
+  def __init__(self, status=None, reason=None, headers=None, body=None):
+    self._headers = headers or {}
+    if status is not None:
+      self.status = status
+    if reason is not None:
+      self.reason = reason
+    if body is not None:
+      # Instead of using a file-like object for the body, store as a string
+      # so that reads can be repeated.
+      if hasattr(body, 'read'):
+        self._body = body.read()
+      else:
+        self._body = body
+
+  def read(self):
+    return self._body

python/atom/mock_service.py

@@ -0,0 +1,243 @@
+#!/usr/bin/python
+#
+# Copyright (C) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""MockService provides CRUD ops. for mocking calls to AtomPub services.
+
+  MockService: Exposes the publicly used methods of AtomService to provide
+      a mock interface which can be used in unit tests.
+"""
+
+import atom.service
+import pickle
+
+
+__author__ = 'api.jscudder (Jeffrey Scudder)'
+
+
+# Recordings contains pairings of HTTP MockRequest objects with MockHttpResponse objects.
+recordings = []
+# If set, the mock service HttpRequest are actually made through this object.
+real_request_handler = None
+
+def ConcealValueWithSha(source):
+  import sha
+  return sha.new(source[:-5]).hexdigest()
+
+def DumpRecordings(conceal_func=ConcealValueWithSha):
+  if conceal_func:
+    for recording_pair in recordings:
+      recording_pair[0].ConcealSecrets(conceal_func)
+  return pickle.dumps(recordings)
+
+def LoadRecordings(recordings_file_or_string):
+  if isinstance(recordings_file_or_string, str):
+    atom.mock_service.recordings =  pickle.loads(recordings_file_or_string)
+  elif hasattr(recordings_file_or_string, 'read'):
+    atom.mock_service.recordings = pickle.loads(
+      recordings_file_or_string.read())
+
+def HttpRequest(service, operation, data, uri, extra_headers=None,
+    url_params=None, escape_params=True, content_type='application/atom+xml'):
+  """Simulates an HTTP call to the server, makes an actual HTTP request if 
+  real_request_handler is set.
+
+  This function operates in two different modes depending on if 
+  real_request_handler is set or not. If real_request_handler is not set,
+  HttpRequest will look in this module's recordings list to find a response
+  which matches the parameters in the function call. If real_request_handler
+  is set, this function will call real_request_handler.HttpRequest, add the
+  response to the recordings list, and respond with the actual response.
+
+  Args:
+    service: atom.AtomService object which contains some of the parameters
+        needed to make the request. The following members are used to
+        construct the HTTP call: server (str), additional_headers (dict),
+        port (int), and ssl (bool).
+    operation: str The HTTP operation to be performed. This is usually one of
+        'GET', 'POST', 'PUT', or 'DELETE'
+    data: ElementTree, filestream, list of parts, or other object which can be
+        converted to a string.
+        Should be set to None when performing a GET or PUT.
+        If data is a file-like object which can be read, this method will read
+        a chunk of 100K bytes at a time and send them.
+        If the data is a list of parts to be sent, each part will be evaluated
+        and sent.
+    uri: The beginning of the URL to which the request should be sent.
+        Examples: '/', '/base/feeds/snippets',
+        '/m8/feeds/contacts/default/base'
+    extra_headers: dict of strings. HTTP headers which should be sent
+        in the request. These headers are in addition to those stored in
+        service.additional_headers.
+    url_params: dict of strings. Key value pairs to be added to the URL as
+        URL parameters. For example {'foo':'bar', 'test':'param'} will
+        become ?foo=bar&test=param.
+    escape_params: bool default True. If true, the keys and values in
+        url_params will be URL escaped when the form is constructed
+        (Special characters converted to %XX form.)
+    content_type: str The MIME type for the data being sent. Defaults to
+        'application/atom+xml', this is only used if data is set.
+  """
+  full_uri = atom.service.BuildUri(uri, url_params, escape_params)
+  (server, port, ssl, uri) = atom.service.ProcessUrl(service, uri)
+  current_request = MockRequest(operation, full_uri, host=server, ssl=ssl, 
+      data=data, extra_headers=extra_headers, url_params=url_params, 
+      escape_params=escape_params, content_type=content_type)
+  # If the request handler is set, we should actually make the request using 
+  # the request handler and record the response to replay later.
+  if real_request_handler:
+    response = real_request_handler.HttpRequest(service, operation, data, uri,
+        extra_headers=extra_headers, url_params=url_params, 
+        escape_params=escape_params, content_type=content_type)
+    # TODO: need to copy the HTTP headers from the real response into the
+    # recorded_response.
+    recorded_response = MockHttpResponse(body=response.read(), 
+        status=response.status, reason=response.reason)
+    # Insert a tuple which maps the request to the response object returned
+    # when making an HTTP call using the real_request_handler.
+    recordings.append((current_request, recorded_response))
+    return recorded_response
+  else:
+    # Look through available recordings to see if one matches the current 
+    # request.
+    for request_response_pair in recordings:
+      if request_response_pair[0].IsMatch(current_request):
+        return request_response_pair[1]
+  return None
+
+
+class MockRequest(object):
+  """Represents a request made to an AtomPub server.
+  
+  These objects are used to determine if a client request matches a recorded
+  HTTP request to determine what the mock server's response will be. 
+  """
+
+  def __init__(self, operation, uri, host=None, ssl=False, port=None, 
+      data=None, extra_headers=None, url_params=None, escape_params=True,
+      content_type='application/atom+xml'):
+    """Constructor for a MockRequest
+    
+    Args:
+      operation: str One of 'GET', 'POST', 'PUT', or 'DELETE' this is the
+          HTTP operation requested on the resource.
+      uri: str The URL describing the resource to be modified or feed to be
+          retrieved. This should include the protocol (http/https) and the host
+          (aka domain). For example, these are some valud full_uris:
+          'http://example.com', 'https://www.google.com/accounts/ClientLogin'
+      host: str (optional) The server name which will be placed at the 
+          beginning of the URL if the uri parameter does not begin with 'http'.
+          Examples include 'example.com', 'www.google.com', 'www.blogger.com'.
+      ssl: boolean (optional) If true, the request URL will begin with https 
+          instead of http.
+      data: ElementTree, filestream, list of parts, or other object which can be
+          converted to a string. (optional)
+          Should be set to None when performing a GET or PUT.
+          If data is a file-like object which can be read, the constructor 
+          will read the entire file into memory. If the data is a list of 
+          parts to be sent, each part will be evaluated and stored.
+      extra_headers: dict (optional) HTTP headers included in the request.
+      url_params: dict (optional) Key value pairs which should be added to 
+          the URL as URL parameters in the request. For example uri='/', 
+          url_parameters={'foo':'1','bar':'2'} could become '/?foo=1&bar=2'.
+      escape_params: boolean (optional) Perform URL escaping on the keys and 
+          values specified in url_params. Defaults to True.
+      content_type: str (optional) Provides the MIME type of the data being 
+          sent.
+    """
+    self.operation = operation
+    self.uri = _ConstructFullUrlBase(uri, host=host, ssl=ssl)
+    self.data = data
+    self.extra_headers = extra_headers
+    self.url_params = url_params or {}
+    self.escape_params = escape_params
+    self.content_type = content_type
+
+  def ConcealSecrets(self, conceal_func):
+    """Conceal secret data in this request."""
+    if self.extra_headers.has_key('Authorization'):
+      self.extra_headers['Authorization'] = conceal_func(
+        self.extra_headers['Authorization'])
+
+  def IsMatch(self, other_request):
+    """Check to see if the other_request is equivalent to this request.
+    
+    Used to determine if a recording matches an incoming request so that a
+    recorded response should be sent to the client.
+
+    The matching is not exact, only the operation and URL are examined 
+    currently.
+
+    Args:
+      other_request: MockRequest The request which we want to check this
+          (self) MockRequest against to see if they are equivalent.
+    """
+    # More accurate matching logic will likely be required.
+    return (self.operation == other_request.operation and self.uri == 
+        other_request.uri)
+
+
+def _ConstructFullUrlBase(uri, host=None, ssl=False):
+  """Puts URL components into the form http(s)://full.host.strinf/uri/path
+  
+  Used to construct a roughly canonical URL so that URLs which begin with 
+  'http://example.com/' can be compared to a uri of '/' when the host is 
+  set to 'example.com'
+
+  If the uri contains 'http://host' already, the host and ssl parameters
+  are ignored.
+
+  Args:
+    uri: str The path component of the URL, examples include '/'
+    host: str (optional) The host name which should prepend the URL. Example:
+        'example.com'
+    ssl: boolean (optional) If true, the returned URL will begin with https
+        instead of http.
+
+  Returns:
+    String which has the form http(s)://example.com/uri/string/contents
+  """
+  if uri.startswith('http'):
+    return uri
+  if ssl:
+    return 'https://%s%s' % (host, uri)
+  else:
+    return 'http://%s%s' % (host, uri)
+
+
+class MockHttpResponse(object):
+  """Returned from MockService crud methods as the server's response."""
+
+  def __init__(self, body=None, status=None, reason=None, headers=None):
+    """Construct a mock HTTPResponse and set members.
+
+    Args:
+      body: str (optional) The HTTP body of the server's response. 
+      status: int (optional) 
+      reason: str (optional)
+      headers: dict (optional)
+    """
+    self.body = body
+    self.status = status
+    self.reason = reason
+    self.headers = headers or {}
+
+  def read(self):
+    return self.body
+
+  def getheader(self, header_name):
+    return self.headers[header_name]
+

python/atom/service.py

@@ -0,0 +1,740 @@
+#!/usr/bin/python
+#
+# Copyright (C) 2006, 2007, 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""AtomService provides CRUD ops. in line with the Atom Publishing Protocol.
+
+  AtomService: Encapsulates the ability to perform insert, update and delete
+               operations with the Atom Publishing Protocol on which GData is
+               based. An instance can perform query, insertion, deletion, and
+               update.
+
+  HttpRequest: Function that performs a GET, POST, PUT, or DELETE HTTP request
+       to the specified end point. An AtomService object or a subclass can be
+       used to specify information about the request.
+"""
+
+__author__ = 'api.jscudder (Jeff Scudder)'
+
+
+import atom.http_interface
+import atom.url
+import atom.http
+import atom.token_store
+
+import os
+import httplib
+import urllib
+import re
+import base64
+import socket
+import warnings
+try:
+  from xml.etree import cElementTree as ElementTree
+except ImportError:
+  try:
+    import cElementTree as ElementTree
+  except ImportError:
+    try:
+      from xml.etree import ElementTree
+    except ImportError:
+      from elementtree import ElementTree
+import atom
+
+
+class AtomService(object):
+  """Performs Atom Publishing Protocol CRUD operations.
+  
+  The AtomService contains methods to perform HTTP CRUD operations. 
+  """
+
+  # Default values for members
+  port = 80
+  ssl = False 
+  # Set the current_token to force the AtomService to use this token
+  # instead of searching for an appropriate token in the token_store.
+  current_token = None
+  auto_store_tokens = True
+  auto_set_current_token = True
+
+  def _get_override_token(self):
+    return self.current_token
+
+  def _set_override_token(self, token):
+    self.current_token = token
+
+  override_token = property(_get_override_token, _set_override_token)
+
+  #@atom.v1_deprecated('Please use atom.client.AtomPubClient instead.')
+  def __init__(self, server=None, additional_headers=None, 
+      application_name='', http_client=None, token_store=None):
+    """Creates a new AtomService client.
+    
+    Args:
+      server: string (optional) The start of a URL for the server
+              to which all operations should be directed. Example: 
+              'www.google.com'
+      additional_headers: dict (optional) Any additional HTTP headers which
+                          should be included with CRUD operations.
+      http_client: An object responsible for making HTTP requests using a
+                   request method. If none is provided, a new instance of
+                   atom.http.ProxiedHttpClient will be used.
+      token_store: Keeps a collection of authorization tokens which can be
+                   applied to requests for a specific URLs. Critical methods are
+                   find_token based on a URL (atom.url.Url or a string), add_token,
+                   and remove_token.
+    """
+    self.http_client = http_client or atom.http.ProxiedHttpClient()
+    self.token_store = token_store or atom.token_store.TokenStore()
+    self.server = server
+    self.additional_headers = additional_headers or {}
+    self.additional_headers['User-Agent'] = atom.http_interface.USER_AGENT % (
+        application_name,)
+    # If debug is True, the HTTPConnection will display debug information
+    self._set_debug(False)
+
+  __init__ = atom.v1_deprecated(
+      'Please use atom.client.AtomPubClient instead.')(
+          __init__)
+
+  def _get_debug(self):
+    return self.http_client.debug
+
+  def _set_debug(self, value):
+    self.http_client.debug = value
+
+  debug = property(_get_debug, _set_debug, 
+      doc='If True, HTTP debug information is printed.')
+
+  def use_basic_auth(self, username, password, scopes=None):
+    if username is not None and password is not None:
+      if scopes is None:
+        scopes = [atom.token_store.SCOPE_ALL]
+      base_64_string = base64.encodestring('%s:%s' % (username, password))
+      token = BasicAuthToken('Basic %s' % base_64_string.strip(), 
+          scopes=[atom.token_store.SCOPE_ALL])
+      if self.auto_set_current_token:
+        self.current_token = token
+      if self.auto_store_tokens:
+        return self.token_store.add_token(token)
+      return True
+    return False
+
+  def UseBasicAuth(self, username, password, for_proxy=False):
+    """Sets an Authenticaiton: Basic HTTP header containing plaintext.
+
+    Deprecated, use use_basic_auth instead.
+    
+    The username and password are base64 encoded and added to an HTTP header
+    which will be included in each request. Note that your username and 
+    password are sent in plaintext.
+
+    Args:
+      username: str
+      password: str
+    """
+    self.use_basic_auth(username, password)
+
+  #@atom.v1_deprecated('Please use atom.client.AtomPubClient for requests.')
+  def request(self, operation, url, data=None, headers=None, 
+      url_params=None):
+    if isinstance(url, (str, unicode)):
+      if url.startswith('http:') and self.ssl:
+        # Force all requests to be https if self.ssl is True.
+        url = atom.url.parse_url('https:' + url[5:])
+      elif not url.startswith('http') and self.ssl: 
+        url = atom.url.parse_url('https://%s%s' % (self.server, url))
+      elif not url.startswith('http'):
+        url = atom.url.parse_url('http://%s%s' % (self.server, url))
+      else:
+        url = atom.url.parse_url(url)
+
+    if url_params:
+      for name, value in url_params.iteritems():
+        url.params[name] = value
+
+    all_headers = self.additional_headers.copy()
+    if headers:
+      all_headers.update(headers)
+
+    # If the list of headers does not include a Content-Length, attempt to
+    # calculate it based on the data object.
+    if data and 'Content-Length' not in all_headers:
+      content_length = CalculateDataLength(data)
+      if content_length:
+        all_headers['Content-Length'] = str(content_length)
+
+    # Find an Authorization token for this URL if one is available.
+    if self.override_token:
+      auth_token = self.override_token
+    else:
+      auth_token = self.token_store.find_token(url)
+    return auth_token.perform_request(self.http_client, operation, url, 
+        data=data, headers=all_headers)
+
+  request = atom.v1_deprecated(
+      'Please use atom.client.AtomPubClient for requests.')(
+          request)
+
+  # CRUD operations
+  def Get(self, uri, extra_headers=None, url_params=None, escape_params=True):
+    """Query the APP server with the given URI
+
+    The uri is the portion of the URI after the server value 
+    (server example: 'www.google.com').
+
+    Example use:
+    To perform a query against Google Base, set the server to 
+    'base.google.com' and set the uri to '/base/feeds/...', where ... is 
+    your query. For example, to find snippets for all digital cameras uri 
+    should be set to: '/base/feeds/snippets?bq=digital+camera'
+
+    Args:
+      uri: string The query in the form of a URI. Example:
+           '/base/feeds/snippets?bq=digital+camera'.
+      extra_headers: dicty (optional) Extra HTTP headers to be included
+                     in the GET request. These headers are in addition to 
+                     those stored in the client's additional_headers property.
+                     The client automatically sets the Content-Type and 
+                     Authorization headers.
+      url_params: dict (optional) Additional URL parameters to be included
+                  in the query. These are translated into query arguments
+                  in the form '&dict_key=value&...'.
+                  Example: {'max-results': '250'} becomes &max-results=250
+      escape_params: boolean (optional) If false, the calling code has already
+                     ensured that the query will form a valid URL (all
+                     reserved characters have been escaped). If true, this
+                     method will escape the query and any URL parameters
+                     provided.
+
+    Returns:
+      httplib.HTTPResponse The server's response to the GET request.
+    """
+    return self.request('GET', uri, data=None, headers=extra_headers, 
+                        url_params=url_params)
+
+  def Post(self, data, uri, extra_headers=None, url_params=None, 
+           escape_params=True, content_type='application/atom+xml'):
+    """Insert data into an APP server at the given URI.
+
+    Args:
+      data: string, ElementTree._Element, or something with a __str__ method 
+            The XML to be sent to the uri. 
+      uri: string The location (feed) to which the data should be inserted. 
+           Example: '/base/feeds/items'. 
+      extra_headers: dict (optional) HTTP headers which are to be included. 
+                     The client automatically sets the Content-Type,
+                     Authorization, and Content-Length headers.
+      url_params: dict (optional) Additional URL parameters to be included
+                  in the URI. These are translated into query arguments
+                  in the form '&dict_key=value&...'.
+                  Example: {'max-results': '250'} becomes &max-results=250
+      escape_params: boolean (optional) If false, the calling code has already
+                     ensured that the query will form a valid URL (all
+                     reserved characters have been escaped). If true, this
+                     method will escape the query and any URL parameters
+                     provided.
+
+    Returns:
+      httplib.HTTPResponse Server's response to the POST request.
+    """
+    if extra_headers is None:
+      extra_headers = {}
+    if content_type:
+      extra_headers['Content-Type'] = content_type
+    return self.request('POST', uri, data=data, headers=extra_headers, 
+                        url_params=url_params)
+
+  def Put(self, data, uri, extra_headers=None, url_params=None, 
+           escape_params=True, content_type='application/atom+xml'):
+    """Updates an entry at the given URI.
+     
+    Args:
+      data: string, ElementTree._Element, or xml_wrapper.ElementWrapper The 
+            XML containing the updated data.
+      uri: string A URI indicating entry to which the update will be applied.
+           Example: '/base/feeds/items/ITEM-ID'
+      extra_headers: dict (optional) HTTP headers which are to be included.
+                     The client automatically sets the Content-Type,
+                     Authorization, and Content-Length headers.
+      url_params: dict (optional) Additional URL parameters to be included
+                  in the URI. These are translated into query arguments
+                  in the form '&dict_key=value&...'.
+                  Example: {'max-results': '250'} becomes &max-results=250
+      escape_params: boolean (optional) If false, the calling code has already
+                     ensured that the query will form a valid URL (all
+                     reserved characters have been escaped). If true, this
+                     method will escape the query and any URL parameters
+                     provided.
+  
+    Returns:
+      httplib.HTTPResponse Server's response to the PUT request.
+    """
+    if extra_headers is None:
+      extra_headers = {}
+    if content_type:
+      extra_headers['Content-Type'] = content_type
+    return self.request('PUT', uri, data=data, headers=extra_headers, 
+                        url_params=url_params)
+
+  def Delete(self, uri, extra_headers=None, url_params=None, 
+             escape_params=True):
+    """Deletes the entry at the given URI.
+
+    Args:
+      uri: string The URI of the entry to be deleted. Example: 
+           '/base/feeds/items/ITEM-ID'
+      extra_headers: dict (optional) HTTP headers which are to be included.
+                     The client automatically sets the Content-Type and
+                     Authorization headers.
+      url_params: dict (optional) Additional URL parameters to be included
+                  in the URI. These are translated into query arguments
+                  in the form '&dict_key=value&...'.
+                  Example: {'max-results': '250'} becomes &max-results=250
+      escape_params: boolean (optional) If false, the calling code has already
+                     ensured that the query will form a valid URL (all
+                     reserved characters have been escaped). If true, this
+                     method will escape the query and any URL parameters
+                     provided.
+
+    Returns:
+      httplib.HTTPResponse Server's response to the DELETE request.
+    """
+    return self.request('DELETE', uri, data=None, headers=extra_headers, 
+                        url_params=url_params)
+
+
+class BasicAuthToken(atom.http_interface.GenericToken):
+  def __init__(self, auth_header, scopes=None):
+    """Creates a token used to add Basic Auth headers to HTTP requests.
+
+    Args:
+      auth_header: str The value for the Authorization header.
+      scopes: list of str or atom.url.Url specifying the beginnings of URLs
+          for which this token can be used. For example, if scopes contains
+          'http://example.com/foo', then this token can be used for a request to
+          'http://example.com/foo/bar' but it cannot be used for a request to
+          'http://example.com/baz'
+    """
+    self.auth_header = auth_header
+    self.scopes = scopes or []
+
+  def perform_request(self, http_client, operation, url, data=None,
+                      headers=None):
+    """Sets the Authorization header to the basic auth string."""
+    if headers is None:
+      headers = {'Authorization':self.auth_header}
+    else:
+      headers['Authorization'] = self.auth_header
+    return http_client.request(operation, url, data=data, headers=headers)
+
+  def __str__(self):
+    return self.auth_header
+
+  def valid_for_scope(self, url):
+    """Tells the caller if the token authorizes access to the desired URL.
+    """
+    if isinstance(url, (str, unicode)):
+      url = atom.url.parse_url(url)
+    for scope in self.scopes:
+      if scope == atom.token_store.SCOPE_ALL:
+        return True
+      if isinstance(scope, (str, unicode)):
+        scope = atom.url.parse_url(scope)
+      if scope == url:
+        return True
+      # Check the host and the path, but ignore the port and protocol.
+      elif scope.host == url.host and not scope.path:
+        return True
+      elif scope.host == url.host and scope.path and not url.path:
+        continue
+      elif scope.host == url.host and url.path.startswith(scope.path):
+        return True
+    return False
+
+
+def PrepareConnection(service, full_uri):
+  """Opens a connection to the server based on the full URI.
+
+  This method is deprecated, instead use atom.http.HttpClient.request.
+
+  Examines the target URI and the proxy settings, which are set as
+  environment variables, to open a connection with the server. This
+  connection is used to make an HTTP request.
+
+  Args:
+    service: atom.AtomService or a subclass. It must have a server string which
+      represents the server host to which the request should be made. It may also
+      have a dictionary of additional_headers to send in the HTTP request.
+    full_uri: str Which is the target relative (lacks protocol and host) or
+    absolute URL to be opened. Example:
+    'https://www.google.com/accounts/ClientLogin' or
+    'base/feeds/snippets' where the server is set to www.google.com.
+
+  Returns:
+    A tuple containing the httplib.HTTPConnection and the full_uri for the
+    request.
+  """
+  deprecation('calling deprecated function PrepareConnection')
+  (server, port, ssl, partial_uri) = ProcessUrl(service, full_uri)
+  if ssl:
+    # destination is https
+    proxy = os.environ.get('https_proxy')
+    if proxy:
+      (p_server, p_port, p_ssl, p_uri) = ProcessUrl(service, proxy, True)
+      proxy_username = os.environ.get('proxy-username')
+      if not proxy_username:
+        proxy_username = os.environ.get('proxy_username')
+      proxy_password = os.environ.get('proxy-password')
+      if not proxy_password:
+        proxy_password = os.environ.get('proxy_password')
+      if proxy_username:
+        user_auth = base64.encodestring('%s:%s' % (proxy_username,
+                                                   proxy_password))
+        proxy_authorization = ('Proxy-authorization: Basic %s\r\n' % (
+            user_auth.strip()))
+      else:
+        proxy_authorization = ''
+      proxy_connect = 'CONNECT %s:%s HTTP/1.0\r\n' % (server, port)
+      user_agent = 'User-Agent: %s\r\n' % (
+          service.additional_headers['User-Agent'])
+      proxy_pieces = (proxy_connect + proxy_authorization + user_agent
+                       + '\r\n')
+
+      #now connect, very simple recv and error checking
+      p_sock = socket.socket(socket.AF_INET,socket.SOCK_STREAM)
+      p_sock.connect((p_server,p_port))
+      p_sock.sendall(proxy_pieces)
+      response = ''
+
+      # Wait for the full response.
+      while response.find("\r\n\r\n") == -1:
+        response += p_sock.recv(8192)
+       
+      p_status=response.split()[1]
+      if p_status!=str(200):
+        raise 'Error status=',str(p_status)
+
+      # Trivial setup for ssl socket.
+      ssl = socket.ssl(p_sock, None, None)
+      fake_sock = httplib.FakeSocket(p_sock, ssl)
+
+      # Initalize httplib and replace with the proxy socket.
+      connection = httplib.HTTPConnection(server)
+      connection.sock=fake_sock
+      full_uri = partial_uri
+
+    else:
+      connection = httplib.HTTPSConnection(server, port)
+      full_uri = partial_uri
+
+  else:
+    # destination is http
+    proxy = os.environ.get('http_proxy')
+    if proxy:
+      (p_server, p_port, p_ssl, p_uri) = ProcessUrl(service.server, proxy, True)
+      proxy_username = os.environ.get('proxy-username')
+      if not proxy_username:
+        proxy_username = os.environ.get('proxy_username')
+      proxy_password = os.environ.get('proxy-password')
+      if not proxy_password:
+        proxy_password = os.environ.get('proxy_password')
+      if proxy_username:
+        UseBasicAuth(service, proxy_username, proxy_password, True)
+      connection = httplib.HTTPConnection(p_server, p_port)
+      if not full_uri.startswith("http://"):
+        if full_uri.startswith("/"):
+          full_uri = "http://%s%s" % (service.server, full_uri)
+        else:
+          full_uri = "http://%s/%s" % (service.server, full_uri)
+    else:
+      connection = httplib.HTTPConnection(server, port)
+      full_uri = partial_uri
+
+  return (connection, full_uri)
+
+
+def UseBasicAuth(service, username, password, for_proxy=False):
+  """Sets an Authenticaiton: Basic HTTP header containing plaintext.
+
+  Deprecated, use AtomService.use_basic_auth insread.
+  
+  The username and password are base64 encoded and added to an HTTP header
+  which will be included in each request. Note that your username and 
+  password are sent in plaintext. The auth header is added to the 
+  additional_headers dictionary in the service object.
+
+  Args:
+    service: atom.AtomService or a subclass which has an 
+        additional_headers dict as a member.
+    username: str
+    password: str
+  """
+  deprecation('calling deprecated function UseBasicAuth')
+  base_64_string = base64.encodestring('%s:%s' % (username, password))
+  base_64_string = base_64_string.strip()
+  if for_proxy:
+    header_name = 'Proxy-Authorization'
+  else:
+    header_name = 'Authorization'
+  service.additional_headers[header_name] = 'Basic %s' % (base_64_string,)
+
+
+def ProcessUrl(service, url, for_proxy=False):
+  """Processes a passed URL.  If the URL does not begin with https?, then
+  the default value for server is used
+
+  This method is deprecated, use atom.url.parse_url instead.
+  """
+  if not isinstance(url, atom.url.Url):
+    url = atom.url.parse_url(url)
+
+  server = url.host
+  ssl = False
+  port = 80
+
+  if not server:
+    if hasattr(service, 'server'):
+      server = service.server
+    else:
+      server = service
+    if not url.protocol and hasattr(service, 'ssl'):
+      ssl = service.ssl
+    if hasattr(service, 'port'):
+      port = service.port
+  else:
+    if url.protocol == 'https':
+      ssl = True
+    elif url.protocol == 'http':
+      ssl = False
+    if url.port:
+      port = int(url.port)
+    elif port == 80 and ssl:
+      port = 443
+
+  return (server, port, ssl, url.get_request_uri())
+
+def DictionaryToParamList(url_parameters, escape_params=True):
+  """Convert a dictionary of URL arguments into a URL parameter string.
+
+  This function is deprcated, use atom.url.Url instead.
+
+  Args:
+    url_parameters: The dictionaty of key-value pairs which will be converted
+                    into URL parameters. For example,
+                    {'dry-run': 'true', 'foo': 'bar'}
+                    will become ['dry-run=true', 'foo=bar'].
+
+  Returns:
+    A list which contains a string for each key-value pair. The strings are
+    ready to be incorporated into a URL by using '&'.join([] + parameter_list)
+  """
+  # Choose which function to use when modifying the query and parameters.
+  # Use quote_plus when escape_params is true.
+  transform_op = [str, urllib.quote_plus][bool(escape_params)]
+  # Create a list of tuples containing the escaped version of the
+  # parameter-value pairs.
+  parameter_tuples = [(transform_op(param), transform_op(value))
+                     for param, value in (url_parameters or {}).items()]
+  # Turn parameter-value tuples into a list of strings in the form
+  # 'PARAMETER=VALUE'.
+  return ['='.join(x) for x in parameter_tuples]
+
+
+def BuildUri(uri, url_params=None, escape_params=True):
+  """Converts a uri string and a collection of parameters into a URI.
+
+  This function is deprcated, use atom.url.Url instead.
+
+  Args:
+    uri: string
+    url_params: dict (optional)
+    escape_params: boolean (optional)
+    uri: string The start of the desired URI. This string can alrady contain
+         URL parameters. Examples: '/base/feeds/snippets', 
+         '/base/feeds/snippets?bq=digital+camera'
+    url_parameters: dict (optional) Additional URL parameters to be included
+                    in the query. These are translated into query arguments
+                    in the form '&dict_key=value&...'.
+                    Example: {'max-results': '250'} becomes &max-results=250
+    escape_params: boolean (optional) If false, the calling code has already
+                   ensured that the query will form a valid URL (all
+                   reserved characters have been escaped). If true, this
+                   method will escape the query and any URL parameters
+                   provided.
+
+  Returns:
+    string The URI consisting of the escaped URL parameters appended to the
+    initial uri string.
+  """
+  # Prepare URL parameters for inclusion into the GET request.
+  parameter_list = DictionaryToParamList(url_params, escape_params)
+
+  # Append the URL parameters to the URL.
+  if parameter_list:
+    if uri.find('?') != -1:
+      # If there are already URL parameters in the uri string, add the
+      # parameters after a new & character.
+      full_uri = '&'.join([uri] + parameter_list)
+    else:
+      # The uri string did not have any URL parameters (no ? character)
+      # so put a ? between the uri and URL parameters.
+      full_uri = '%s%s' % (uri, '?%s' % ('&'.join([] + parameter_list)))  
+  else:
+    full_uri = uri
+        
+  return full_uri
+
+  
+def HttpRequest(service, operation, data, uri, extra_headers=None, 
+    url_params=None, escape_params=True, content_type='application/atom+xml'):
+  """Performs an HTTP call to the server, supports GET, POST, PUT, and DELETE.
+  
+  This method is deprecated, use atom.http.HttpClient.request instead.
+
+  Usage example, perform and HTTP GET on http://www.google.com/:
+    import atom.service
+    client = atom.service.AtomService()
+    http_response = client.Get('http://www.google.com/')
+  or you could set the client.server to 'www.google.com' and use the 
+  following:
+    client.server = 'www.google.com'
+    http_response = client.Get('/')
+
+  Args:
+    service: atom.AtomService object which contains some of the parameters 
+        needed to make the request. The following members are used to 
+        construct the HTTP call: server (str), additional_headers (dict), 
+        port (int), and ssl (bool).
+    operation: str The HTTP operation to be performed. This is usually one of
+        'GET', 'POST', 'PUT', or 'DELETE'
+    data: ElementTree, filestream, list of parts, or other object which can be 
+        converted to a string. 
+        Should be set to None when performing a GET or PUT.
+        If data is a file-like object which can be read, this method will read
+        a chunk of 100K bytes at a time and send them. 
+        If the data is a list of parts to be sent, each part will be evaluated
+        and sent.
+    uri: The beginning of the URL to which the request should be sent. 
+        Examples: '/', '/base/feeds/snippets', 
+        '/m8/feeds/contacts/default/base'
+    extra_headers: dict of strings. HTTP headers which should be sent
+        in the request. These headers are in addition to those stored in 
+        service.additional_headers.
+    url_params: dict of strings. Key value pairs to be added to the URL as
+        URL parameters. For example {'foo':'bar', 'test':'param'} will 
+        become ?foo=bar&test=param.
+    escape_params: bool default True. If true, the keys and values in 
+        url_params will be URL escaped when the form is constructed 
+        (Special characters converted to %XX form.)
+    content_type: str The MIME type for the data being sent. Defaults to
+        'application/atom+xml', this is only used if data is set.
+  """
+  deprecation('call to deprecated function HttpRequest')
+  full_uri = BuildUri(uri, url_params, escape_params)
+  (connection, full_uri) = PrepareConnection(service, full_uri)
+
+  if extra_headers is None:
+    extra_headers = {}
+
+  # Turn on debug mode if the debug member is set.
+  if service.debug:
+    connection.debuglevel = 1
+
+  connection.putrequest(operation, full_uri)
+
+  # If the list of headers does not include a Content-Length, attempt to 
+  # calculate it based on the data object.
+  if (data and not service.additional_headers.has_key('Content-Length') and 
+      not extra_headers.has_key('Content-Length')):
+    content_length = CalculateDataLength(data)
+    if content_length:
+      extra_headers['Content-Length'] = str(content_length)
+
+  if content_type:
+    extra_headers['Content-Type'] = content_type 
+
+  # Send the HTTP headers.
+  if isinstance(service.additional_headers, dict):
+    for header in service.additional_headers:
+      connection.putheader(header, service.additional_headers[header])
+  if isinstance(extra_headers, dict):
+    for header in extra_headers:
+      connection.putheader(header, extra_headers[header])
+  connection.endheaders()
+
+  # If there is data, send it in the request.
+  if data:
+    if isinstance(data, list):
+      for data_part in data:
+        __SendDataPart(data_part, connection)
+    else:
+      __SendDataPart(data, connection)
+
+  # Return the HTTP Response from the server.
+  return connection.getresponse()
+  
+
+def __SendDataPart(data, connection):
+  """This method is deprecated, use atom.http._send_data_part"""
+  deprecated('call to deprecated function __SendDataPart')
+  if isinstance(data, str):
+    #TODO add handling for unicode.
+    connection.send(data)
+    return
+  elif ElementTree.iselement(data):
+    connection.send(ElementTree.tostring(data))
+    return
+  # Check to see if data is a file-like object that has a read method.
+  elif hasattr(data, 'read'):
+    # Read the file and send it a chunk at a time.
+    while 1:
+      binarydata = data.read(100000)
+      if binarydata == '': break
+      connection.send(binarydata)
+    return
+  else:
+    # The data object was not a file.
+    # Try to convert to a string and send the data.
+    connection.send(str(data))
+    return
+
+
+def CalculateDataLength(data):
+  """Attempts to determine the length of the data to send. 
+  
+  This method will respond with a length only if the data is a string or
+  and ElementTree element.
+
+  Args:
+    data: object If this is not a string or ElementTree element this funtion
+        will return None.
+  """
+  if isinstance(data, str):
+    return len(data)
+  elif isinstance(data, list):
+    return None
+  elif ElementTree.iselement(data):
+    return len(ElementTree.tostring(data))
+  elif hasattr(data, 'read'):
+    # If this is a file-like object, don't try to guess the length.
+    return None
+  else:
+    return len(str(data))
+    
+
+def deprecation(message):
+  warnings.warn(message, DeprecationWarning, stacklevel=2)

python/atom/token_store.py

@@ -0,0 +1,117 @@
+#!/usr/bin/python
+#
+# Copyright (C) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""This module provides a TokenStore class which is designed to manage
+auth tokens required for different services.
+
+Each token is valid for a set of scopes which is the start of a URL. An HTTP
+client will use a token store to find a valid Authorization header to send
+in requests to the specified URL. If the HTTP client determines that a token
+has expired or been revoked, it can remove the token from the store so that
+it will not be used in future requests.
+"""
+
+
+__author__ = 'api.jscudder (Jeff Scudder)'
+
+
+import atom.http_interface
+import atom.url
+
+
+SCOPE_ALL = 'http'
+
+
+class TokenStore(object):
+  """Manages Authorization tokens which will be sent in HTTP headers."""
+  def __init__(self, scoped_tokens=None):
+    self._tokens = scoped_tokens or {}
+
+  def add_token(self, token):
+    """Adds a new token to the store (replaces tokens with the same scope).
+
+    Args:
+      token: A subclass of http_interface.GenericToken. The token object is 
+          responsible for adding the Authorization header to the HTTP request.
+          The scopes defined in the token are used to determine if the token
+          is valid for a requested scope when find_token is called.
+
+    Returns:
+      True if the token was added, False if the token was not added becase
+      no scopes were provided.
+    """
+    if not hasattr(token, 'scopes') or not token.scopes:
+      return False
+
+    for scope in token.scopes:
+      self._tokens[str(scope)] = token
+    return True  
+
+  def find_token(self, url):
+    """Selects an Authorization header token which can be used for the URL.
+
+    Args:
+      url: str or atom.url.Url or a list containing the same.
+          The URL which is going to be requested. All
+          tokens are examined to see if any scopes begin match the beginning
+          of the URL. The first match found is returned.
+
+    Returns:
+      The token object which should execute the HTTP request. If there was
+      no token for the url (the url did not begin with any of the token
+      scopes available), then the atom.http_interface.GenericToken will be 
+      returned because the GenericToken calls through to the http client
+      without adding an Authorization header.
+    """
+    if url is None:
+      return None
+    if isinstance(url, (str, unicode)):
+      url = atom.url.parse_url(url)
+    if url in self._tokens:
+      token = self._tokens[url]
+      if token.valid_for_scope(url):
+        return token
+      else:
+        del self._tokens[url]
+    for scope, token in self._tokens.iteritems():
+      if token.valid_for_scope(url):
+        return token
+    return atom.http_interface.GenericToken()
+
+  def remove_token(self, token):
+    """Removes the token from the token_store.
+
+    This method is used when a token is determined to be invalid. If the
+    token was found by find_token, but resulted in a 401 or 403 error stating
+    that the token was invlid, then the token should be removed to prevent
+    future use.
+
+    Returns:
+      True if a token was found and then removed from the token
+      store. False if the token was not in the TokenStore.
+    """
+    token_found = False
+    scopes_to_delete = []
+    for scope, stored_token in self._tokens.iteritems():
+      if stored_token == token:
+        scopes_to_delete.append(scope)
+        token_found = True
+    for scope in scopes_to_delete:
+      del self._tokens[scope]
+    return token_found
+
+  def remove_all_tokens(self):
+    self._tokens = {} 

python/atom/url.py

@@ -0,0 +1,139 @@
+#!/usr/bin/python
+#
+# Copyright (C) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+__author__ = 'api.jscudder (Jeff Scudder)'
+
+
+import urlparse
+import urllib
+
+
+DEFAULT_PROTOCOL = 'http'
+DEFAULT_PORT = 80
+
+
+def parse_url(url_string):
+  """Creates a Url object which corresponds to the URL string.
+  
+  This method can accept partial URLs, but it will leave missing
+  members of the Url unset.
+  """
+  parts = urlparse.urlparse(url_string)
+  url = Url()
+  if parts[0]:
+    url.protocol = parts[0]
+  if parts[1]:
+    host_parts = parts[1].split(':')
+    if host_parts[0]:
+      url.host = host_parts[0]
+    if len(host_parts) > 1:
+      url.port = host_parts[1]
+  if parts[2]:
+    url.path = parts[2]
+  if parts[4]:
+    param_pairs = parts[4].split('&')
+    for pair in param_pairs:
+      pair_parts = pair.split('=')
+      if len(pair_parts) > 1:
+        url.params[urllib.unquote_plus(pair_parts[0])] = (
+            urllib.unquote_plus(pair_parts[1]))
+      elif len(pair_parts) == 1:
+        url.params[urllib.unquote_plus(pair_parts[0])] = None
+  return url
+   
+class Url(object):
+  """Represents a URL and implements comparison logic.
+  
+  URL strings which are not identical can still be equivalent, so this object
+  provides a better interface for comparing and manipulating URLs than 
+  strings. URL parameters are represented as a dictionary of strings, and
+  defaults are used for the protocol (http) and port (80) if not provided.
+  """
+  def __init__(self, protocol=None, host=None, port=None, path=None, 
+               params=None):
+    self.protocol = protocol
+    self.host = host
+    self.port = port
+    self.path = path
+    self.params = params or {}
+
+  def to_string(self):
+    url_parts = ['', '', '', '', '', '']
+    if self.protocol:
+      url_parts[0] = self.protocol
+    if self.host:
+      if self.port:
+        url_parts[1] = ':'.join((self.host, str(self.port)))
+      else:
+        url_parts[1] = self.host
+    if self.path:
+      url_parts[2] = self.path
+    if self.params:
+      url_parts[4] = self.get_param_string()
+    return urlparse.urlunparse(url_parts)
+
+  def get_param_string(self):
+    param_pairs = []
+    for key, value in self.params.iteritems():
+      param_pairs.append('='.join((urllib.quote_plus(key), 
+          urllib.quote_plus(str(value)))))
+    return '&'.join(param_pairs)
+
+  def get_request_uri(self):
+    """Returns the path with the parameters escaped and appended."""
+    param_string = self.get_param_string()
+    if param_string:
+      return '?'.join([self.path, param_string])
+    else:
+      return self.path
+
+  def __cmp__(self, other):
+    if not isinstance(other, Url):
+      return cmp(self.to_string(), str(other))
+    difference = 0
+    # Compare the protocol
+    if self.protocol and other.protocol:
+      difference = cmp(self.protocol, other.protocol)
+    elif self.protocol and not other.protocol:
+      difference = cmp(self.protocol, DEFAULT_PROTOCOL)
+    elif not self.protocol and other.protocol:
+      difference = cmp(DEFAULT_PROTOCOL, other.protocol)
+    if difference != 0:
+      return difference
+    # Compare the host
+    difference = cmp(self.host, other.host)
+    if difference != 0:
+      return difference
+    # Compare the port
+    if self.port and other.port:
+      difference = cmp(self.port, other.port)
+    elif self.port and not other.port:
+      difference = cmp(self.port, DEFAULT_PORT)
+    elif not self.port and other.port:
+      difference = cmp(DEFAULT_PORT, other.port)
+    if difference != 0:
+      return difference
+    # Compare the path
+    difference = cmp(self.path, other.path)
+    if difference != 0:
+      return difference
+    # Compare the parameters
+    return cmp(self.params, other.params)
+
+  def __str__(self):
+    return self.to_string()
+