Merge lp:~gtg-user/gtg/identica-backend into lp:~gtg/gtg/old-trunk

[Luca Invernizzi]

identi.ca backend, which follows the lines of the twitter backend, but does not authenticate through oauth (and uses a different library).

Note: i've added a branch with all my merge requests merged. https://code.edge.launchpad.net/~gtg-user/gtg/all_the_backends_merge_requests/

[lp:~gtg-user/gtg/identica-backend]

876. By Luca Invernizzi on 2010-08-24

removed print statements

877. By Luca Invernizzi on 2010-08-25

merge w/ trunk

=== added file 'GTG/backends/backend_identica.py'
--- GTG/backends/backend_identica.py	1970-01-01 00:00:00 +0000
+++ GTG/backends/backend_identica.py	2010-08-25 16:29:48 +0000
@@ -0,0 +1,280 @@
+# -*- coding: utf-8 -*-
+# -----------------------------------------------------------------------------
+# Getting Things Gnome! - a personal organizer for the GNOME desktop
+# Copyright (c) 2008-2009 - Lionel Dricot & Bertrand Rousseau
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public License along with
+# this program.  If not, see <http://www.gnu.org/licenses/>.
+# -----------------------------------------------------------------------------
+
+'''
+Identi.ca backend: imports direct messages, replies and/or the user timeline.
+'''
+
+import os
+import re
+import sys
+import uuid
+import urllib2
+
+from GTG                                import _
+from GTG.backends.genericbackend        import GenericBackend
+from GTG.core                           import CoreConfig
+from GTG.backends.backendsignals        import BackendSignals
+from GTG.backends.periodicimportbackend import PeriodicImportBackend
+from GTG.backends.syncengine            import SyncEngine
+from GTG.tools.logger                   import Log
+
+#The Ubuntu version of python twitter is not updated: 
+# it does not have identi.ca support. Meanwhile, we ship the right version
+# with our code.
+import GTG.backends.twitter as twitter
+
+
+
+class Backend(PeriodicImportBackend):
+    '''
+    Identi.ca backend: imports direct messages, replies and/or the user
+    timeline.
+    '''
+
+
+    _general_description = { \
+        GenericBackend.BACKEND_NAME: "backend_identica", \
+        GenericBackend.BACKEND_HUMAN_NAME: _("Identi.ca"), \
+        GenericBackend.BACKEND_AUTHORS:    ["Luca Invernizzi"], \
+        GenericBackend.BACKEND_TYPE:       GenericBackend.TYPE_IMPORT, \
+        GenericBackend.BACKEND_DESCRIPTION: \
+            _("Imports your identi.ca  messages into your GTG " + \
+              "tasks. You can choose to either import all your " + \
+              "messages or just those with a set of hash tags. \n" + \
+              "The message will be interpreted following this" + \
+              " format: \n" + \
+              "<b>my task title, task description #tag @anothertag</b>\n" + \
+              " Tags can be  anywhere in the message"),\
+        }
+
+    base_url = "http://identi.ca/api/"
+
+    _static_parameters = { \
+        "username": { \
+            GenericBackend.PARAM_TYPE: GenericBackend.TYPE_STRING, \
+            GenericBackend.PARAM_DEFAULT_VALUE: "", },
+        "password": { \
+            GenericBackend.PARAM_TYPE: GenericBackend.TYPE_PASSWORD, \
+            GenericBackend.PARAM_DEFAULT_VALUE: "", },
+        "period": { \
+            GenericBackend.PARAM_TYPE: GenericBackend.TYPE_INT, \
+            GenericBackend.PARAM_DEFAULT_VALUE: 2, },
+        "import-tags": { \
+            GenericBackend.PARAM_TYPE: GenericBackend.TYPE_LIST_OF_STRINGS, \
+            GenericBackend.PARAM_DEFAULT_VALUE: ["#todo"], },
+        "import-from-replies": { \
+            GenericBackend.PARAM_TYPE: GenericBackend.TYPE_BOOL, \
+            GenericBackend.PARAM_DEFAULT_VALUE: False, },
+        "import-from-my-tweets": { \
+            GenericBackend.PARAM_TYPE: GenericBackend.TYPE_BOOL, \
+            GenericBackend.PARAM_DEFAULT_VALUE: False, },
+        "import-from-direct-messages": { \
+            GenericBackend.PARAM_TYPE: GenericBackend.TYPE_BOOL, \
+            GenericBackend.PARAM_DEFAULT_VALUE: True, },
+        }
+
+    def __init__(self, parameters):
+        '''
+        See GenericBackend for an explanation of this function.
+        Re-loads the saved state of the synchronization
+        '''
+        super(Backend, self).__init__(parameters)
+        #loading the list of already imported tasks
+        self.data_path = os.path.join('backends/identica/', "tasks_dict-%s" %\
+                                     self.get_id())
+        self.sync_engine = self._load_pickled_file(self.data_path, \
+                                                        SyncEngine())
+        
+    def save_state(self):
+        '''
+        See GenericBackend for an explanation of this function.
+        Saves the state of the synchronization.
+        '''
+        self._store_pickled_file(self.data_path, self.sync_engine)
+
+    def do_periodic_import(self):
+        '''
+        See GenericBackend for an explanation of this function.
+        '''
+        #we need to authenticate only to see the direct messages or the replies
+        # (why the replies? Don't know. But python-twitter requires that)
+        # (invernizzi)
+        with self.controlled_execution(self._parameters['username'],\
+                                       self._parameters['password'], \
+                                       self.base_url, \
+                                       self) as api:
+            #select what to import
+            tweets_to_import = []
+            if self._parameters["import-from-direct-messages"]:
+                tweets_to_import += api.GetDirectMessages()
+            if self._parameters["import-from-my-tweets"]:
+                tweets_to_import += \
+                        api.GetUserTimeline(self._parameters["username"])
+            if self._parameters["import-from-replies"]:
+                tweets_to_import += \
+                    api.GetReplies(self._parameters["username"])
+            #do the import
+            for tweet in tweets_to_import:
+                self._process_tweet(tweet)
+
+    def _process_tweet(self, tweet):
+        '''
+        Given a tweet, checks if a task representing it must be
+        created in GTG and, if so, it creates it.
+
+        @param tweet: a tweet.
+        '''
+        self.cancellation_point()
+        tweet_id = str(tweet.GetId())
+        is_syncable = self._is_tweet_syncable(tweet)
+        #the "lambda" is because we don't consider tweets deletion (to be
+        # faster)
+        action, tid = self.sync_engine.analyze_remote_id(\
+                                        tweet_id, \
+                                        self.datastore.has_task, \
+                                        lambda tweet_id: True, \
+                                        is_syncable)
+        Log.debug("processing tweet (%s, %s)" % (action, is_syncable))
+        
+        self.cancellation_point()
+        if action == None or action == SyncEngine.UPDATE:
+            return
+
+        elif action == SyncEngine.ADD:
+            tid = str(uuid.uuid4())
+            task = self.datastore.task_factory(tid)
+            self._populate_task(task, tweet)
+            #we care only to add tweets and if the list of tags which must be
+            #imported changes (lost-syncability can happen). Thus, we don't
+            # care about SyncMeme(s)
+            self.sync_engine.record_relationship(local_id = tid,\
+                                     remote_id = tweet_id, \
+                                     meme = None)
+            self.datastore.push_task(task)
+
+        elif action == SyncEngine.LOST_SYNCABILITY:
+            self.sync_engine.break_relationship(remote_id = tweet_id)
+            self.datastore.request_task_deletion(tid)
+
+        self.save_state()
+
+    def _populate_task(self, task, message):
+        '''
+        Given a twitter message and a GTG task, fills the task with the content
+        of the message
+        '''
+        try:
+            #this works only for some messages
+            task.add_tag("@" + message.GetSenderScreenName())
+        except:
+            pass
+        text = message.GetText()    
+        
+        #convert #hastags to @tags
+        matches = re.finditer("(?<![^|\s])(#\w+)", text)
+        for g in matches:
+            text = text[:g.start()] + '@' + text[g.start() + 1:]
+        #add tags objects (it's not enough to have @tag in the text to add a
+        # tag
+        for tag in self._extract_tags_from_text(text):
+            task.add_tag(tag)
+
+        split_text = text.split(",", 1)
+        task.set_title(split_text[0])
+        if len(split_text) > 1:
+            task.set_text(split_text[1])
+
+        task.add_remote_id(self.get_id(), str(message.GetId()))
+
+    def _is_tweet_syncable(self, tweet):
+        '''
+        Returns True if the given tweet matches the user-specified tags to be
+        synced
+
+        @param tweet: a tweet
+        '''
+        if CoreConfig.ALLTASKS_TAG in self._parameters["import-tags"]:
+            return True
+        else:
+            tags = set(Backend._extract_tags_from_text(tweet.GetText()))
+            return tags.intersection(set(self._parameters["import-tags"])) \
+                    != set()
+
+    @staticmethod
+    def _extract_tags_from_text(text):
+        '''
+        Given a string, returns a list of @tags and #hashtags
+        '''
+        return list(re.findall(r'(?:^|[\s])((?:#|@)\w+)', text))
+
+###############################################################################
+### AUTHENTICATION ############################################################
+###############################################################################
+
+    class controlled_execution(object):
+        '''
+        This class performs the login to identica and execute the appropriate
+        response if something goes wrong during authentication or at network
+        level
+        '''
+
+        def __init__(self, username, password, base_url, backend):
+            '''
+            Sets the login parameters
+            '''
+            self.username = username
+            self.password = password
+            self.backend = backend
+            self.base_url = base_url
+
+        def __enter__(self):
+            '''
+            Logins to identica and returns the Api object
+            '''
+            return twitter.Api(self.username, self.password, \
+                            base_url = self.base_url)
+
+        def __exit__(self, type, value, traceback):
+            '''
+            Analyzes the eventual exception risen during the connection to
+            identica
+            '''
+            if isinstance(value, urllib2.HTTPError):
+                if value.getcode() == 401:
+                    self.signal_authentication_wrong()
+                if value.getcode() in [502, 404]:
+                    self.signal_network_down()
+            elif isinstance(value, twitter.TwitterError):
+                self.signal_authentication_wrong()
+            elif isinstance(value, urllib2.URLError):
+                self.signal_network_down()
+            else:
+                return False
+            return True
+
+        def signal_authentication_wrong(self):
+            self.backend.quit(disable = True)
+            BackendSignals().backend_failed(self.backend.get_id(), \
+                            BackendSignals.ERRNO_AUTHENTICATION)
+
+        def signal_network_down(self):
+            BackendSignals().backend_failed(self.backend.get_id(), \
+                            BackendSignals.ERRNO_NETWORK)
+

=== added file 'GTG/backends/twitter.py'
--- GTG/backends/twitter.py	1970-01-01 00:00:00 +0000
+++ GTG/backends/twitter.py	2010-08-25 16:29:48 +0000
@@ -0,0 +1,2547 @@
+#!/usr/bin/python2.4
+#
+# Copyright 2007 Google Inc. All Rights Reserved.
+#
+# 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.
+
+'''A library that provides a python interface to the Twitter API'''
+
+__author__ = '[e-mail]'
+__version__ = '0.7-devel'
+
+
+import base64
+import calendar
+import httplib
+import os
+import rfc822
+import simplejson
+import sys
+import tempfile
+import textwrap
+import time
+import urllib
+import urllib2
+import urlparse
+import gzip
+import StringIO
+
+try:
+  from hashlib import md5
+except ImportError:
+  from md5 import md5
+
+
+CHARACTER_LIMIT = 140
+
+# A singleton representing a lazily instantiated FileCache.
+DEFAULT_CACHE = object()
+
+
+class TwitterError(Exception):
+  '''Base class for Twitter errors'''
+  
+  @property
+  def message(self):
+    '''Returns the first argument used to construct this error.'''
+    return self.args[0]
+
+
+class Status(object):
+  '''A class representing the Status structure used by the twitter API.
+
+  The Status structure exposes the following properties:
+
+    status.created_at
+    status.created_at_in_seconds # read only
+    status.favorited
+    status.in_reply_to_screen_name
+    status.in_reply_to_user_id
+    status.in_reply_to_status_id
+    status.truncated
+    status.source
+    status.id
+    status.text
+    status.location
+    status.relative_created_at # read only
+    status.user
+  '''
+  def __init__(self,
+               created_at=None,
+               favorited=None,
+               id=None,
+               text=None,
+               location=None,
+               user=None,
+               in_reply_to_screen_name=None,
+               in_reply_to_user_id=None,
+               in_reply_to_status_id=None,
+               truncated=None,
+               source=None,
+               now=None):
+    '''An object to hold a Twitter status message.
+
+    This class is normally instantiated by the twitter.Api class and
+    returned in a sequence.
+
+    Note: Dates are posted in the form "Sat Jan 27 04:17:38 +0000 2007"
+
+    Args:
+      created_at: The time this status message was posted
+      favorited: Whether this is a favorite of the authenticated user
+      id: The unique id of this status message
+      text: The text of this status message
+      location: the geolocation string associated with this message
+      relative_created_at:
+        A human readable string representing the posting time
+      user:
+        A twitter.User instance representing the person posting the message
+      now:
+        The current time, if the client choses to set it.  Defaults to the
+        wall clock time.
+    '''
+    self.created_at = created_at
+    self.favorited = favorited
+    self.id = id
+    self.text = text
+    self.location = location
+    self.user = user
+    self.now = now
+    self.in_reply_to_screen_name = in_reply_to_screen_name
+    self.in_reply_to_user_id = in_reply_to_user_id
+    self.in_reply_to_status_id = in_reply_to_status_id
+    self.truncated = truncated
+    self.source = source
+
+  def GetCreatedAt(self):
+    '''Get the time this status message was posted.
+
+    Returns:
+      The time this status message was posted
+    '''
+    return self._created_at
+
+  def SetCreatedAt(self, created_at):
+    '''Set the time this status message was posted.
+
+    Args:
+      created_at: The time this status message was created
+    '''
+    self._created_at = created_at
+
+  created_at = property(GetCreatedAt, SetCreatedAt,
+                        doc='The time this status message was posted.')
+
+  def GetCreatedAtInSeconds(self):
+    '''Get the time this status message was posted, in seconds since the epoch.
+
+    Returns:
+      The time this status message was posted, in seconds since the epoch.
+    '''
+    return calendar.timegm(rfc822.parsedate(self.created_at))
+
+  created_at_in_seconds = property(GetCreatedAtInSeconds,
+                                   doc="The time this status message was "
+                                       "posted, in seconds since the epoch")
+
+  def GetFavorited(self):
+    '''Get the favorited setting of this status message.
+
+    Returns:
+      True if this status message is favorited; False otherwise
+    '''
+    return self._favorited
+
+  def SetFavorited(self, favorited):
+    '''Set the favorited state of this status message.
+
+    Args:
+      favorited: boolean True/False favorited state of this status message
+    '''
+    self._favorited = favorited
+
+  favorited = property(GetFavorited, SetFavorited,
+                       doc='The favorited state of this status message.')
+
+  def GetId(self):
+    '''Get the unique id of this status message.
+
+    Returns:
+      The unique id of this status message
+    '''
+    return self._id
+
+  def SetId(self, id):
+    '''Set the unique id of this status message.
+
+    Args:
+      id: The unique id of this status message
+    '''
+    self._id = id
+
+  id = property(GetId, SetId,
+                doc='The unique id of this status message.')
+
+  def GetInReplyToScreenName(self):
+    return self._in_reply_to_screen_name
+
+  def SetInReplyToScreenName(self, in_reply_to_screen_name):
+    self._in_reply_to_screen_name = in_reply_to_screen_name
+
+  in_reply_to_screen_name = property(GetInReplyToScreenName, SetInReplyToScreenName,
+                doc='')
+
+  def GetInReplyToUserId(self):
+    return self._in_reply_to_user_id
+
+  def SetInReplyToUserId(self, in_reply_to_user_id):
+    self._in_reply_to_user_id = in_reply_to_user_id
+
+  in_reply_to_user_id = property(GetInReplyToUserId, SetInReplyToUserId,
+                doc='')
+
+  def GetInReplyToStatusId(self):
+    return self._in_reply_to_status_id
+
+  def SetInReplyToStatusId(self, in_reply_to_status_id):
+    self._in_reply_to_status_id = in_reply_to_status_id
+
+  in_reply_to_status_id = property(GetInReplyToStatusId, SetInReplyToStatusId,
+                doc='')
+
+  def GetTruncated(self):
+    return self._truncated
+
+  def SetTruncated(self, truncated):
+    self._truncated = truncated
+
+  truncated = property(GetTruncated, SetTruncated,
+                doc='')
+
+  def GetSource(self):
+    return self._source
+
+  def SetSource(self, source):
+    self._source = source
+
+  source = property(GetSource, SetSource,
+                doc='')
+
+  def GetText(self):
+    '''Get the text of this status message.
+
+    Returns:
+      The text of this status message.
+    '''
+    return self._text
+
+  def SetText(self, text):
+    '''Set the text of this status message.
+
+    Args:
+      text: The text of this status message
+    '''
+    self._text = text
+
+  text = property(GetText, SetText,
+                  doc='The text of this status message')
+
+  def GetLocation(self):
+    '''Get the geolocation associated with this status message
+
+    Returns:
+      The geolocation string of this status message.
+    '''
+    return self._location
+
+  def SetLocation(self, location):
+    '''Set the geolocation associated with this status message
+
+    Args:
+      location: The geolocation string of this status message
+    '''
+    self._location = location
+
+  location = property(GetLocation, SetLocation,
+                      doc='The geolocation string of this status message')
+
+  def GetRelativeCreatedAt(self):
+    '''Get a human redable string representing the posting time
+
+    Returns:
+      A human readable string representing the posting time
+    '''
+    fudge = 1.25
+    delta  = long(self.now) - long(self.created_at_in_seconds)
+
+    if delta < (1 * fudge):
+      return 'about a second ago'
+    elif delta < (60 * (1/fudge)):
+      return 'about %d seconds ago' % (delta)
+    elif delta < (60 * fudge):
+      return 'about a minute ago'
+    elif delta < (60 * 60 * (1/fudge)):
+      return 'about %d minutes ago' % (delta / 60)
+    elif delta < (60 * 60 * fudge) or delta / (60 * 60) == 1:
+      return 'about an hour ago'
+    elif delta < (60 * 60 * 24 * (1/fudge)):
+      return 'about %d hours ago' % (delta / (60 * 60))
+    elif delta < (60 * 60 * 24 * fudge) or delta / (60 * 60 * 24) == 1:
+      return 'about a day ago'
+    else:
+      return 'about %d days ago' % (delta / (60 * 60 * 24))
+
+  relative_created_at = property(GetRelativeCreatedAt,
+                                 doc='Get a human readable string representing'
+                                     'the posting time')
+
+  def GetUser(self):
+    '''Get a twitter.User reprenting the entity posting this status message.
+
+    Returns:
+      A twitter.User reprenting the entity posting this status message
+    '''
+    return self._user
+
+  def SetUser(self, user):
+    '''Set a twitter.User reprenting the entity posting this status message.
+
+    Args:
+      user: A twitter.User reprenting the entity posting this status message
+    '''
+    self._user = user
+
+  user = property(GetUser, SetUser,
+                  doc='A twitter.User reprenting the entity posting this '
+                      'status message')
+
+  def GetNow(self):
+    '''Get the wallclock time for this status message.
+
+    Used to calculate relative_created_at.  Defaults to the time
+    the object was instantiated.
+
+    Returns:
+      Whatever the status instance believes the current time to be,
+      in seconds since the epoch.
+    '''
+    if self._now is None:
+      self._now = time.time()
+    return self._now
+
+  def SetNow(self, now):
+    '''Set the wallclock time for this status message.
+
+    Used to calculate relative_created_at.  Defaults to the time
+    the object was instantiated.
+
+    Args:
+      now: The wallclock time for this instance.
+    '''
+    self._now = now
+
+  now = property(GetNow, SetNow,
+                 doc='The wallclock time for this status instance.')
+
+
+  def __ne__(self, other):
+    return not self.__eq__(other)
+
+  def __eq__(self, other):
+    try:
+      return other and \
+             self.created_at == other.created_at and \
+             self.id == other.id and \
+             self.text == other.text and \
+             self.location == other.location and \
+             self.user == other.user and \
+             self.in_reply_to_screen_name == other.in_reply_to_screen_name and \
+             self.in_reply_to_user_id == other.in_reply_to_user_id and \
+             self.in_reply_to_status_id == other.in_reply_to_status_id and \
+             self.truncated == other.truncated and \
+             self.favorited == other.favorited and \
+             self.source == other.source
+    except AttributeError:
+      return False
+
+  def __str__(self):
+    '''A string representation of this twitter.Status instance.
+
+    The return value is the same as the JSON string representation.
+
+    Returns:
+      A string representation of this twitter.Status instance.
+    '''
+    return self.AsJsonString()
+
+  def AsJsonString(self):
+    '''A JSON string representation of this twitter.Status instance.
+
+    Returns:
+      A JSON string representation of this twitter.Status instance
+   '''
+    return simplejson.dumps(self.AsDict(), sort_keys=True)
+
+  def AsDict(self):
+    '''A dict representation of this twitter.Status instance.
+
+    The return value uses the same key names as the JSON representation.
+
+    Return:
+      A dict representing this twitter.Status instance
+    '''
+    data = {}
+    if self.created_at:
+      data['created_at'] = self.created_at
+    if self.favorited:
+      data['favorited'] = self.favorited
+    if self.id:
+      data['id'] = self.id
+    if self.text:
+      data['text'] = self.text
+    if self.location:
+      data['location'] = self.location  
+    if self.user:
+      data['user'] = self.user.AsDict()
+    if self.in_reply_to_screen_name:
+      data['in_reply_to_screen_name'] = self.in_reply_to_screen_name
+    if self.in_reply_to_user_id:
+      data['in_reply_to_user_id'] = self.in_reply_to_user_id
+    if self.in_reply_to_status_id:
+      data['in_reply_to_status_id'] = self.in_reply_to_status_id
+    if self.truncated is not None:
+      data['truncated'] = self.truncated
+    if self.favorited is not None:
+      data['favorited'] = self.favorited
+    if self.source:
+      data['source'] = self.source
+    return data
+
+  @staticmethod
+  def NewFromJsonDict(data):
+    '''Create a new instance based on a JSON dict.
+
+    Args:
+      data: A JSON dict, as converted from the JSON in the twitter API
+    Returns:
+      A twitter.Status instance
+    '''
+    if 'user' in data:
+      user = User.NewFromJsonDict(data['user'])
+    else:
+      user = None
+    return Status(created_at=data.get('created_at', None),
+                  favorited=data.get('favorited', None),
+                  id=data.get('id', None),
+                  text=data.get('text', None),
+                  location=data.get('location', None),
+                  in_reply_to_screen_name=data.get('in_reply_to_screen_name', None),
+                  in_reply_to_user_id=data.get('in_reply_to_user_id', None),
+                  in_reply_to_status_id=data.get('in_reply_to_status_id', None),
+                  truncated=data.get('truncated', None),
+                  source=data.get('source', None),
+                  user=user)
+
+
+class User(object):
+  '''A class representing the User structure used by the twitter API.
+
+  The User structure exposes the following properties:
+
+    user.id
+    user.name
+    user.screen_name
+    user.location
+    user.description
+    user.profile_image_url
+    user.profile_background_tile
+    user.profile_background_image_url
+    user.profile_sidebar_fill_color
+    user.profile_background_color
+    user.profile_link_color
+    user.profile_text_color
+    user.protected
+    user.utc_offset
+    user.time_zone
+    user.url
+    user.status
+    user.statuses_count
+    user.followers_count
+    user.friends_count
+    user.favourites_count
+  '''
+  def __init__(self,
+               id=None,
+               name=None,
+               screen_name=None,
+               location=None,
+               description=None,
+               profile_image_url=None,
+               profile_background_tile=None,
+               profile_background_image_url=None,
+               profile_sidebar_fill_color=None,
+               profile_background_color=None,
+               profile_link_color=None,
+               profile_text_color=None,
+               protected=None,
+               utc_offset=None,
+               time_zone=None,
+               followers_count=None,
+               friends_count=None,
+               statuses_count=None,
+               favourites_count=None,
+               url=None,
+               status=None):
+    self.id = id
+    self.name = name
+    self.screen_name = screen_name
+    self.location = location
+    self.description = description
+    self.profile_image_url = profile_image_url
+    self.profile_background_tile = profile_background_tile
+    self.profile_background_image_url = profile_background_image_url
+    self.profile_sidebar_fill_color = profile_sidebar_fill_color
+    self.profile_background_color = profile_background_color
+    self.profile_link_color = profile_link_color
+    self.profile_text_color = profile_text_color
+    self.protected = protected
+    self.utc_offset = utc_offset
+    self.time_zone = time_zone
+    self.followers_count = followers_count
+    self.friends_count = friends_count
+    self.statuses_count = statuses_count
+    self.favourites_count = favourites_count
+    self.url = url
+    self.status = status
+
+
+  def GetId(self):
+    '''Get the unique id of this user.
+
+    Returns:
+      The unique id of this user
+    '''
+    return self._id
+
+  def SetId(self, id):
+    '''Set the unique id of this user.
+
+    Args:
+      id: The unique id of this user.
+    '''
+    self._id = id
+
+  id = property(GetId, SetId,
+                doc='The unique id of this user.')
+
+  def GetName(self):
+    '''Get the real name of this user.
+
+    Returns:
+      The real name of this user
+    '''
+    return self._name
+
+  def SetName(self, name):
+    '''Set the real name of this user.
+
+    Args:
+      name: The real name of this user
+    '''
+    self._name = name
+
+  name = property(GetName, SetName,
+                  doc='The real name of this user.')
+
+  def GetScreenName(self):
+    '''Get the short username of this user.
+
+    Returns:
+      The short username of this user
+    '''
+    return self._screen_name
+
+  def SetScreenName(self, screen_name):
+    '''Set the short username of this user.
+
+    Args:
+      screen_name: the short username of this user
+    '''
+    self._screen_name = screen_name
+
+  screen_name = property(GetScreenName, SetScreenName,
+                         doc='The short username of this user.')
+
+  def GetLocation(self):
+    '''Get the geographic location of this user.
+
+    Returns:
+      The geographic location of this user
+    '''
+    return self._location
+
+  def SetLocation(self, location):
+    '''Set the geographic location of this user.
+
+    Args:
+      location: The geographic location of this user
+    '''
+    self._location = location
+
+  location = property(GetLocation, SetLocation,
+                      doc='The geographic location of this user.')
+
+  def GetDescription(self):
+    '''Get the short text description of this user.
+
+    Returns:
+      The short text description of this user
+    '''
+    return self._description
+
+  def SetDescription(self, description):
+    '''Set the short text description of this user.
+
+    Args:
+      description: The short text description of this user
+    '''
+    self._description = description
+
+  description = property(GetDescription, SetDescription,
+                         doc='The short text description of this user.')
+
+  def GetUrl(self):
+    '''Get the homepage url of this user.
+
+    Returns:
+      The homepage url of this user
+    '''
+    return self._url
+
+  def SetUrl(self, url):
+    '''Set the homepage url of this user.
+
+    Args:
+      url: The homepage url of this user
+    '''
+    self._url = url
+
+  url = property(GetUrl, SetUrl,
+                 doc='The homepage url of this user.')
+
+  def GetProfileImageUrl(self):
+    '''Get the url of the thumbnail of this user.
+
+    Returns:
+      The url of the thumbnail of this user
+    '''
+    return self._profile_image_url
+
+  def SetProfileImageUrl(self, profile_image_url):
+    '''Set the url of the thumbnail of this user.
+
+    Args:
+      profile_image_url: The url of the thumbnail of this user
+    '''
+    self._profile_image_url = profile_image_url
+
+  profile_image_url= property(GetProfileImageUrl, SetProfileImageUrl,
+                              doc='The url of the thumbnail of this user.')
+
+  def GetProfileBackgroundTile(self):
+    '''Boolean for whether to tile the profile background image.
+
+    Returns:
+      True if the background is to be tiled, False if not, None if unset.
+    '''
+    return self._profile_background_tile
+
+  def SetProfileBackgroundTile(self, profile_background_tile):
+    '''Set the boolean flag for whether to tile the profile background image.
+
+    Args:
+      profile_background_tile: Boolean flag for whether to tile or not.
+    '''
+    self._profile_background_tile = profile_background_tile
+
+  profile_background_tile = property(GetProfileBackgroundTile, SetProfileBackgroundTile,
+                                     doc='Boolean for whether to tile the background image.')
+
+  def GetProfileBackgroundImageUrl(self):
+    return self._profile_background_image_url
+
+  def SetProfileBackgroundImageUrl(self, profile_background_image_url):
+    self._profile_background_image_url = profile_background_image_url
+
+  profile_background_image_url = property(GetProfileBackgroundImageUrl, SetProfileBackgroundImageUrl,
+                                          doc='The url of the profile background of this user.')
+
+  def GetProfileSidebarFillColor(self):
+    return self._profile_sidebar_fill_color
+
+  def SetProfileSidebarFillColor(self, profile_sidebar_fill_color):
+    self._profile_sidebar_fill_color = profile_sidebar_fill_color
+
+  profile_sidebar_fill_color = property(GetProfileSidebarFillColor, SetProfileSidebarFillColor)
+
+  def GetProfileBackgroundColor(self):
+    return self._profile_background_color
+
+  def SetProfileBackgroundColor(self, profile_background_color):
+    self._profile_background_color = profile_background_color
+
+  profile_background_color = property(GetProfileBackgroundColor, SetProfileBackgroundColor)
+
+  def GetProfileLinkColor(self):
+    return self._profile_link_color
+
+  def SetProfileLinkColor(self, profile_link_color):
+    self._profile_link_color = profile_link_color
+
+  profile_link_color = property(GetProfileLinkColor, SetProfileLinkColor)
+
+  def GetProfileTextColor(self):
+    return self._profile_text_color
+
+  def SetProfileTextColor(self, profile_text_color):
+    self._profile_text_color = profile_text_color
+
+  profile_text_color = property(GetProfileTextColor, SetProfileTextColor)
+
+  def GetProtected(self):
+    return self._protected
+
+  def SetProtected(self, protected):
+    self._protected = protected
+
+  protected = property(GetProtected, SetProtected)
+
+  def GetUtcOffset(self):
+    return self._utc_offset
+
+  def SetUtcOffset(self, utc_offset):
+    self._utc_offset = utc_offset
+
+  utc_offset = property(GetUtcOffset, SetUtcOffset)
+
+  def GetTimeZone(self):
+    '''Returns the current time zone string for the user.
+
+    Returns:
+      The descriptive time zone string for the user.
+    '''
+    return self._time_zone
+
+  def SetTimeZone(self, time_zone):
+    '''Sets the user's time zone string.
+
+    Args:
+      time_zone: The descriptive time zone to assign for the user.
+    '''
+    self._time_zone = time_zone
+
+  time_zone = property(GetTimeZone, SetTimeZone)
+
+  def GetStatus(self):
+    '''Get the latest twitter.Status of this user.
+
+    Returns:
+      The latest twitter.Status of this user
+    '''
+    return self._status
+
+  def SetStatus(self, status):
+    '''Set the latest twitter.Status of this user.
+
+    Args:
+      status: The latest twitter.Status of this user
+    '''
+    self._status = status
+
+  status = property(GetStatus, SetStatus,
+                  doc='The latest twitter.Status of this user.')
+
+  def GetFriendsCount(self):
+    '''Get the friend count for this user.
+    
+    Returns:
+      The number of users this user has befriended.
+    '''
+    return self._friends_count
+
+  def SetFriendsCount(self, count):
+    '''Set the friend count for this user.
+
+    Args:
+      count: The number of users this user has befriended.
+    '''
+    self._friends_count = count
+
+  friends_count = property(GetFriendsCount, SetFriendsCount,
+                  doc='The number of friends for this user.')
+
+  def GetFollowersCount(self):
+    '''Get the follower count for this user.
+    
+    Returns:
+      The number of users following this user.
+    '''
+    return self._followers_count
+
+  def SetFollowersCount(self, count):
+    '''Set the follower count for this user.
+
+    Args:
+      count: The number of users following this user.
+    '''
+    self._followers_count = count
+
+  followers_count = property(GetFollowersCount, SetFollowersCount,
+                  doc='The number of users following this user.')
+
+  def GetStatusesCount(self):
+    '''Get the number of status updates for this user.
+    
+    Returns:
+      The number of status updates for this user.
+    '''
+    return self._statuses_count
+
+  def SetStatusesCount(self, count):
+    '''Set the status update count for this user.
+
+    Args:
+      count: The number of updates for this user.
+    '''
+    self._statuses_count = count
+
+  statuses_count = property(GetStatusesCount, SetStatusesCount,
+                  doc='The number of updates for this user.')
+
+  def GetFavouritesCount(self):
+    '''Get the number of favourites for this user.
+    
+    Returns:
+      The number of favourites for this user.
+    '''
+    return self._favourites_count
+
+  def SetFavouritesCount(self, count):
+    '''Set the favourite count for this user.
+
+    Args:
+      count: The number of favourites for this user.
+    '''
+    self._favourites_count = count
+
+  favourites_count = property(GetFavouritesCount, SetFavouritesCount,
+                  doc='The number of favourites for this user.')
+
+  def __ne__(self, other):
+    return not self.__eq__(other)
+
+  def __eq__(self, other):
+    try:
+      return other and \
+             self.id == other.id and \
+             self.name == other.name and \
+             self.screen_name == other.screen_name and \
+             self.location == other.location and \
+             self.description == other.description and \
+             self.profile_image_url == other.profile_image_url and \
+             self.profile_background_tile == other.profile_background_tile and \
+             self.profile_background_image_url == other.profile_background_image_url and \
+             self.profile_sidebar_fill_color == other.profile_sidebar_fill_color and \
+             self.profile_background_color == other.profile_background_color and \
+             self.profile_link_color == other.profile_link_color and \
+             self.profile_text_color == other.profile_text_color and \
+             self.protected == other.protected and \
+             self.utc_offset == other.utc_offset and \
+             self.time_zone == other.time_zone and \
+             self.url == other.url and \
+             self.statuses_count == other.statuses_count and \
+             self.followers_count == other.followers_count and \
+             self.favourites_count == other.favourites_count and \
+             self.friends_count == other.friends_count and \
+             self.status == other.status
+    except AttributeError:
+      return False
+
+  def __str__(self):
+    '''A string representation of this twitter.User instance.
+
+    The return value is the same as the JSON string representation.
+
+    Returns:
+      A string representation of this twitter.User instance.
+    '''
+    return self.AsJsonString()
+
+  def AsJsonString(self):
+    '''A JSON string representation of this twitter.User instance.
+
+    Returns:
+      A JSON string representation of this twitter.User instance
+   '''
+    return simplejson.dumps(self.AsDict(), sort_keys=True)
+
+  def AsDict(self):
+    '''A dict representation of this twitter.User instance.
+
+    The return value uses the same key names as the JSON representation.
+
+    Return:
+      A dict representing this twitter.User instance
+    '''
+    data = {}
+    if self.id:
+      data['id'] = self.id
+    if self.name:
+      data['name'] = self.name
+    if self.screen_name:
+      data['screen_name'] = self.screen_name
+    if self.location:
+      data['location'] = self.location
+    if self.description:
+      data['description'] = self.description
+    if self.profile_image_url:
+      data['profile_image_url'] = self.profile_image_url
+    if self.profile_background_tile is not None:
+      data['profile_background_tile'] = self.profile_background_tile
+    if self.profile_background_image_url:
+      data['profile_sidebar_fill_color'] = self.profile_background_image_url
+    if self.profile_background_color:
+      data['profile_background_color'] = self.profile_background_color
+    if self.profile_link_color:
+      data['profile_link_color'] = self.profile_link_color
+    if self.profile_text_color:
+      data['profile_text_color'] = self.profile_text_color
+    if self.protected is not None:
+      data['protected'] = self.protected
+    if self.utc_offset:
+      data['utc_offset'] = self.utc_offset
+    if self.time_zone:
+      data['time_zone'] = self.time_zone
+    if self.url:
+      data['url'] = self.url
+    if self.status:
+      data['status'] = self.status.AsDict()
+    if self.friends_count:
+      data['friends_count'] = self.friends_count
+    if self.followers_count:
+      data['followers_count'] = self.followers_count
+    if self.statuses_count:
+      data['statuses_count'] = self.statuses_count
+    if self.favourites_count:
+      data['favourites_count'] = self.favourites_count
+    return data
+
+  @staticmethod
+  def NewFromJsonDict(data):
+    '''Create a new instance based on a JSON dict.
+
+    Args:
+      data: A JSON dict, as converted from the JSON in the twitter API
+    Returns:
+      A twitter.User instance
+    '''
+    if 'status' in data:
+      status = Status.NewFromJsonDict(data['status'])
+    else:
+      status = None
+    return User(id=data.get('id', None),
+                name=data.get('name', None),
+                screen_name=data.get('screen_name', None),
+                location=data.get('location', None),
+                description=data.get('description', None),
+                statuses_count=data.get('statuses_count', None),
+                followers_count=data.get('followers_count', None),
+                favourites_count=data.get('favourites_count', None),
+                friends_count=data.get('friends_count', None),
+                profile_image_url=data.get('profile_image_url', None),
+                profile_background_tile = data.get('profile_background_tile', None),
+                profile_background_image_url = data.get('profile_background_image_url', None),
+                profile_sidebar_fill_color = data.get('profile_sidebar_fill_color', None),
+                profile_background_color = data.get('profile_background_color', None),
+                profile_link_color = data.get('profile_link_color', None),
+                profile_text_color = data.get('profile_text_color', None),
+                protected = data.get('protected', None),
+                utc_offset = data.get('utc_offset', None),
+                time_zone = data.get('time_zone', None),
+                url=data.get('url', None),
+                status=status)
+
+class DirectMessage(object):
+  '''A class representing the DirectMessage structure used by the twitter API.
+
+  The DirectMessage structure exposes the following properties:
+
+    direct_message.id
+    direct_message.created_at
+    direct_message.created_at_in_seconds # read only
+    direct_message.sender_id
+    direct_message.sender_screen_name
+    direct_message.recipient_id
+    direct_message.recipient_screen_name
+    direct_message.text
+  '''
+
+  def __init__(self,
+               id=None,
+               created_at=None,
+               sender_id=None,
+               sender_screen_name=None,
+               recipient_id=None,
+               recipient_screen_name=None,
+               text=None):
+    '''An object to hold a Twitter direct message.
+
+    This class is normally instantiated by the twitter.Api class and
+    returned in a sequence.
+
+    Note: Dates are posted in the form "Sat Jan 27 04:17:38 +0000 2007"
+
+    Args:
+      id: The unique id of this direct message
+      created_at: The time this direct message was posted
+      sender_id: The id of the twitter user that sent this message
+      sender_screen_name: The name of the twitter user that sent this message
+      recipient_id: The id of the twitter that received this message
+      recipient_screen_name: The name of the twitter that received this message
+      text: The text of this direct message
+    '''
+    self.id = id
+    self.created_at = created_at
+    self.sender_id = sender_id
+    self.sender_screen_name = sender_screen_name
+    self.recipient_id = recipient_id
+    self.recipient_screen_name = recipient_screen_name
+    self.text = text
+
+  def GetId(self):
+    '''Get the unique id of this direct message.
+
+    Returns:
+      The unique id of this direct message
+    '''
+    return self._id
+
+  def SetId(self, id):
+    '''Set the unique id of this direct message.
+
+    Args:
+      id: The unique id of this direct message
+    '''
+    self._id = id
+
+  id = property(GetId, SetId,
+                doc='The unique id of this direct message.')
+
+  def GetCreatedAt(self):
+    '''Get the time this direct message was posted.
+
+    Returns:
+      The time this direct message was posted
+    '''
+    return self._created_at
+
+  def SetCreatedAt(self, created_at):
+    '''Set the time this direct message was posted.
+
+    Args:
+      created_at: The time this direct message was created
+    '''
+    self._created_at = created_at
+
+  created_at = property(GetCreatedAt, SetCreatedAt,
+                        doc='The time this direct message was posted.')
+
+  def GetCreatedAtInSeconds(self):
+    '''Get the time this direct message was posted, in seconds since the epoch.
+
+    Returns:
+      The time this direct message was posted, in seconds since the epoch.
+    '''
+    return calendar.timegm(rfc822.parsedate(self.created_at))
+
+  created_at_in_seconds = property(GetCreatedAtInSeconds,
+                                   doc="The time this direct message was "
+                                       "posted, in seconds since the epoch")
+
+  def GetSenderId(self):
+    '''Get the unique sender id of this direct message.
+
+    Returns:
+      The unique sender id of this direct message
+    '''
+    return self._sender_id
+
+  def SetSenderId(self, sender_id):
+    '''Set the unique sender id of this direct message.
+
+    Args:
+      sender id: The unique sender id of this direct message
+    '''
+    self._sender_id = sender_id
+
+  sender_id = property(GetSenderId, SetSenderId,
+                doc='The unique sender id of this direct message.')
+
+  def GetSenderScreenName(self):
+    '''Get the unique sender screen name of this direct message.
+
+    Returns:
+      The unique sender screen name of this direct message
+    '''
+    return self._sender_screen_name
+
+  def SetSenderScreenName(self, sender_screen_name):
+    '''Set the unique sender screen name of this direct message.
+
+    Args:
+      sender_screen_name: The unique sender screen name of this direct message
+    '''
+    self._sender_screen_name = sender_screen_name
+
+  sender_screen_name = property(GetSenderScreenName, SetSenderScreenName,
+                doc='The unique sender screen name of this direct message.')
+
+  def GetRecipientId(self):
+    '''Get the unique recipient id of this direct message.
+
+    Returns:
+      The unique recipient id of this direct message
+    '''
+    return self._recipient_id
+
+  def SetRecipientId(self, recipient_id):
+    '''Set the unique recipient id of this direct message.
+
+    Args:
+      recipient id: The unique recipient id of this direct message
+    '''
+    self._recipient_id = recipient_id
+
+  recipient_id = property(GetRecipientId, SetRecipientId,
+                doc='The unique recipient id of this direct message.')
+
+  def GetRecipientScreenName(self):
+    '''Get the unique recipient screen name of this direct message.
+
+    Returns:
+      The unique recipient screen name of this direct message
+    '''
+    return self._recipient_screen_name
+
+  def SetRecipientScreenName(self, recipient_screen_name):
+    '''Set the unique recipient screen name of this direct message.
+
+    Args:
+      recipient_screen_name: The unique recipient screen name of this direct message
+    '''
+    self._recipient_screen_name = recipient_screen_name
+
+  recipient_screen_name = property(GetRecipientScreenName, SetRecipientScreenName,
+                doc='The unique recipient screen name of this direct message.')
+
+  def GetText(self):
+    '''Get the text of this direct message.
+
+    Returns:
+      The text of this direct message.
+    '''
+    return self._text
+
+  def SetText(self, text):
+    '''Set the text of this direct message.
+
+    Args:
+      text: The text of this direct message
+    '''
+    self._text = text
+
+  text = property(GetText, SetText,
+                  doc='The text of this direct message')
+
+  def __ne__(self, other):
+    return not self.__eq__(other)
+
+  def __eq__(self, other):
+    try:
+      return other and \
+          self.id == other.id and \
+          self.created_at == other.created_at and \
+          self.sender_id == other.sender_id and \
+          self.sender_screen_name == other.sender_screen_name and \
+          self.recipient_id == other.recipient_id and \
+          self.recipient_screen_name == other.recipient_screen_name and \
+          self.text == other.text
+    except AttributeError:
+      return False
+
+  def __str__(self):
+    '''A string representation of this twitter.DirectMessage instance.
+
+    The return value is the same as the JSON string representation.
+
+    Returns:
+      A string representation of this twitter.DirectMessage instance.
+    '''
+    return self.AsJsonString()
+
+  def AsJsonString(self):
+    '''A JSON string representation of this twitter.DirectMessage instance.
+
+    Returns:
+      A JSON string representation of this twitter.DirectMessage instance
+   '''
+    return simplejson.dumps(self.AsDict(), sort_keys=True)
+
+  def AsDict(self):
+    '''A dict representation of this twitter.DirectMessage instance.
+
+    The return value uses the same key names as the JSON representation.
+
+    Return:
+      A dict representing this twitter.DirectMessage instance
+    '''
+    data = {}
+    if self.id:
+      data['id'] = self.id
+    if self.created_at:
+      data['created_at'] = self.created_at
+    if self.sender_id:
+      data['sender_id'] = self.sender_id
+    if self.sender_screen_name:
+      data['sender_screen_name'] = self.sender_screen_name
+    if self.recipient_id:
+      data['recipient_id'] = self.recipient_id
+    if self.recipient_screen_name:
+      data['recipient_screen_name'] = self.recipient_screen_name
+    if self.text:
+      data['text'] = self.text
+    return data
+
+  @staticmethod
+  def NewFromJsonDict(data):
+    '''Create a new instance based on a JSON dict.
+
+    Args:
+      data: A JSON dict, as converted from the JSON in the twitter API
+    Returns:
+      A twitter.DirectMessage instance
+    '''
+    return DirectMessage(created_at=data.get('created_at', None),
+                         recipient_id=data.get('recipient_id', None),
+                         sender_id=data.get('sender_id', None),
+                         text=data.get('text', None),
+                         sender_screen_name=data.get('sender_screen_name', None),
+                         id=data.get('id', None),
+                         recipient_screen_name=data.get('recipient_screen_name', None))
+
+class Api(object):
+  '''A python interface into the Twitter API
+
+  By default, the Api caches results for 1 minute.
+
+  Example usage:
+
+    To create an instance of the twitter.Api class, with no authentication:
+
+      >>> import twitter
+      >>> api = twitter.Api()
+
+    To fetch the most recently posted public twitter status messages:
+
+      >>> statuses = api.GetPublicTimeline()
+      >>> print [s.user.name for s in statuses]
+      [u'DeWitt', u'Kesuke Miyagi', u'ev', u'Buzz Andersen', u'Biz Stone'] #...
+
+    To fetch a single user's public status messages, where "user" is either
+    a Twitter "short name" or their user id.
+
+      >>> statuses = api.GetUserTimeline(user)
+      >>> print [s.text for s in statuses]
+
+    To use authentication, instantiate the twitter.Api class with a
+    username and password:
+
+      >>> api = twitter.Api(username='twitter user', password='twitter pass')
+
+    To fetch your friends (after being authenticated):
+
+      >>> users = api.GetFriends()
+      >>> print [u.name for u in users]
+
+    To post a twitter status message (after being authenticated):
+
+      >>> status = api.PostUpdate('I love python-twitter!')
+      >>> print status.text
+      I love python-twitter!
+
+    There are many other methods, including:
+
+      >>> api.PostUpdates(status)
+      >>> api.PostDirectMessage(user, text)
+      >>> api.GetUser(user)
+      >>> api.GetReplies()
+      >>> api.GetUserTimeline(user)
+      >>> api.GetStatus(id)
+      >>> api.DestroyStatus(id)
+      >>> api.GetFriendsTimeline(user)
+      >>> api.GetFriends(user)
+      >>> api.GetFollowers()
+      >>> api.GetFeatured()
+      >>> api.GetDirectMessages()
+      >>> api.PostDirectMessage(user, text)
+      >>> api.DestroyDirectMessage(id)
+      >>> api.DestroyFriendship(user)
+      >>> api.CreateFriendship(user)
+      >>> api.GetUserByEmail(email)
+      >>> api.VerifyCredentials()
+  '''
+
+  DEFAULT_CACHE_TIMEOUT = 60 # cache for 1 minute
+
+  _API_REALM = 'Twitter API'
+
+  def __init__(self,
+               username=None,
+               password=None,
+               input_encoding=None,
+               request_headers=None,
+               cache=DEFAULT_CACHE,
+               shortner=None,
+               base_url=None,
+               use_gzip_compression=False):
+    '''Instantiate a new twitter.Api object.
+
+    Args:
+      username:
+        The username of the twitter account.  [optional]
+      password:
+        The password for the twitter account. [optional]
+      input_encoding:
+        The encoding used to encode input strings. [optional]
+      request_header:
+        A dictionary of additional HTTP request headers. [optional]
+      cache:
+        The cache instance to use. Defaults to DEFAULT_CACHE.
+        Use None to disable caching. [optional]
+      shortner:
+        The shortner instance to use.  Defaults to None.
+        See shorten_url.py for an example shortner. [optional]
+      base_url:
+        The base URL to use to contact the Twitter API.
+        Defaults to https://twitter.com. [optional]
+      use_gzip_compression:
+        Set to True to tell enable gzip compression for any call
+        made to Twitter.  Defaults to False. [optional]
+    '''
+    self.SetCache(cache)
+    self._urllib = urllib2
+    self._cache_timeout = Api.DEFAULT_CACHE_TIMEOUT
+    self._InitializeRequestHeaders(request_headers)
+    self._InitializeUserAgent()
+    self._InitializeDefaultParameters()
+    self._input_encoding = input_encoding
+    self._use_gzip = use_gzip_compression
+    self.SetCredentials(username, password)
+    if base_url is None:
+      self.base_url = 'https://twitter.com'
+    else:
+      self.base_url = base_url
+
+  def GetPublicTimeline(self,
+                        since_id=None):
+    '''Fetch the sequnce of public twitter.Status message for all users.
+
+    Args:
+      since_id:
+        Returns only public statuses with an ID greater than
+        (that is, more recent than) the specified ID. [optional]
+
+    Returns:
+      An sequence of twitter.Status instances, one for each message
+    '''
+    parameters = {}
+
+    if since_id:
+      parameters['since_id'] = since_id
+
+    url  = '%s/statuses/public_timeline.json' % self.base_url
+    json = self._FetchUrl(url,  parameters=parameters)
+    data = simplejson.loads(json)
+
+    self._CheckForTwitterError(data)
+
+    return [Status.NewFromJsonDict(x) for x in data]
+
+  def FilterPublicTimeline(self,
+                           term,
+                           since_id=None):
+    '''Filter the public twitter timeline by a given search term on
+    the local machine.
+
+    Args:
+      term:
+        term to search by.
+      since_id:
+        Returns only public statuses with an ID greater than
+        (that is, more recent than) the specified ID. [optional]
+
+    Returns:
+      A sequence of twitter.Status instances, one for each message
+      containing the term
+    '''
+    statuses = self.GetPublicTimeline(since_id)
+    results  = []
+
+    for s in statuses:
+      if s.text.lower().find(term.lower()) != -1:
+        results.append(s)
+
+    return results
+
+  def GetSearch(self,
+                term,
+                geocode=None,
+                since_id=None,
+                per_page=15,
+                page=1,
+                lang="en",
+                show_user="true",
+                query_users=False):
+    '''Return twitter search results for a given term.
+
+    Args:
+      term:
+        term to search by.
+      since_id:
+        Returns only public statuses with an ID greater than
+        (that is, more recent than) the specified ID. [optional]
+      geocode:
+        geolocation information in the form (latitude, longitude, radius)
+        [optional]
+      per_page:
+        number of results to return.  Default is 15 [optional]
+      page:
+        which page of search results to return
+      lang:
+        language for results.  Default is English [optional]
+      show_user:
+        prefixes screen name in status
+      query_users:
+        If set to False, then all users only have screen_name and
+        profile_image_url available.
+        If set to True, all information of users are available,
+        but it uses lots of request quota, one per status.
+    Returns:
+      A sequence of twitter.Status instances, one for each message containing
+      the term
+    '''
+    # Build request parameters
+    parameters = {}
+
+    if since_id:
+      parameters['since_id'] = since_id
+
+    if not term:
+      return []
+
+    parameters['q'] = urllib.quote_plus(term)
+    parameters['show_user'] = show_user
+    parameters['lang'] = lang
+    parameters['rpp'] = per_page
+    parameters['page'] = page
+
+    if geocode is not None:
+      parameters['geocode'] = ','.join(map(str, geocode))
+
+    # Make and send requests
+    url  = 'http://search.twitter.com/search.json'
+    json = self._FetchUrl(url, parameters=parameters)
+    data = simplejson.loads(json)
+
+    self._CheckForTwitterError(data)
+
+    results = []
+
+    for x in data['results']:
+      temp = Status.NewFromJsonDict(x)
+
+      if query_users:
+        # Build user object with new request
+        temp.user = self.GetUser(urllib.quote(x['from_user']))
+      else:
+        temp.user = User(screen_name=x['from_user'], profile_image_url=x['profile_image_url'])
+
+      results.append(temp)
+
+    # Return built list of statuses
+    return results # [Status.NewFromJsonDict(x) for x in data['results']]
+
+  def GetFriendsTimeline(self,
+                         user=None,
+                         count=None,
+                         since=None,
+                         since_id=None):
+    '''Fetch the sequence of twitter.Status messages for a user's friends
+
+    The twitter.Api instance must be authenticated if the user is private.
+
+    Args:
+      user:
+        Specifies the ID or screen name of the user for whom to return
+        the friends_timeline.  If unspecified, the username and password
+        must be set in the twitter.Api instance.  [Optional]
+      count: 
+        Specifies the number of statuses to retrieve. May not be
+        greater than 200. [Optional]
+      since:
+        Narrows the returned results to just those statuses created
+        after the specified HTTP-formatted date. [Optional]
+      since_id:
+        Returns only public statuses with an ID greater than (that is,
+        more recent than) the specified ID. [Optional]
+
+    Returns:
+      A sequence of twitter.Status instances, one for each message
+    '''
+    if not user and not self._username:
+      raise TwitterError("User must be specified if API is not authenticated.")
+    if user:
+      url = '%s/statuses/friends_timeline/%s.json' % (self.base_url, user)
+    else:
+      url = '%s/statuses/friends_timeline.json' % self.base_url
+    parameters = {}
+    if count is not None:
+      try:
+        if int(count) > 200:
+          raise TwitterError("'count' may not be greater than 200")
+      except ValueError:
+        raise TwitterError("'count' must be an integer")
+      parameters['count'] = count
+    if since:
+      parameters['since'] = since
+    if since_id:
+      parameters['since_id'] = since_id
+    json = self._FetchUrl(url, parameters=parameters)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return [Status.NewFromJsonDict(x) for x in data]
+
+  def GetUserTimeline(self,
+                      id=None,
+                      user_id=None,
+                      screen_name=None,
+                      since_id=None,
+                      max_id=None,
+                      count=None,
+                      page=None):
+    '''Fetch the sequence of public Status messages for a single user.
+
+    The twitter.Api instance must be authenticated if the user is private.
+
+    Args:
+      id:
+        Specifies the ID or screen name of the user for whom to return
+        the user_timeline. [optional]
+      user_id:
+        Specfies the ID of the user for whom to return the
+        user_timeline. Helpful for disambiguating when a valid user ID
+        is also a valid screen name. [optional]
+      screen_name:
+        Specfies the screen name of the user for whom to return the
+        user_timeline. Helpful for disambiguating when a valid screen
+        name is also a user ID. [optional]
+      since_id:
+        Returns only public statuses with an ID greater than (that is,
+        more recent than) the specified ID. [optional]
+      max_id:
+        Returns only statuses with an ID less than (that is, older
+        than) or equal to the specified ID. [optional]
+      count:
+        Specifies the number of statuses to retrieve. May not be
+        greater than 200.  [optional]
+      page:
+         Specifies the page of results to retrieve. Note: there are
+         pagination limits. [optional]
+
+    Returns:
+      A sequence of Status instances, one for each message up to count
+    '''
+    parameters = {}
+
+    if id:
+      url = '%s/statuses/user_timeline/%s.json' % (self.base_url, id)
+    elif user_id:
+      url = '%s/statuses/user_timeline.json?user_id=%d' % (self.base_url, user_id)
+    elif screen_name:
+      url = ('%s/statuses/user_timeline.json?screen_name=%s' % (self.base_url,
+             screen_name))
+    elif not self._username:
+      raise TwitterError("User must be specified if API is not authenticated.")
+    else:
+      url = '%s/statuses/user_timeline.json' % self.base_url
+
+    if since_id:
+      try:
+        parameters['since_id'] = long(since_id)
+      except:
+        raise TwitterError("since_id must be an integer")
+
+    if max_id:
+      try:
+        parameters['max_id'] = long(max_id)
+      except:
+        raise TwitterError("max_id must be an integer")
+
+    if count:
+      try:
+        parameters['count'] = int(count)
+      except:
+        raise TwitterError("count must be an integer")
+
+    if page:
+      try:
+        parameters['page'] = int(page)
+      except:
+        raise TwitterError("page must be an integer")
+
+    json = self._FetchUrl(url, parameters=parameters)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return [Status.NewFromJsonDict(x) for x in data]
+
+  def GetStatus(self, id):
+    '''Returns a single status message.
+
+    The twitter.Api instance must be authenticated if the status message is private.
+
+    Args:
+      id: The numerical ID of the status you're trying to retrieve.
+
+    Returns:
+      A twitter.Status instance representing that status message
+    '''
+    try:
+      if id:
+        long(id)
+    except:
+      raise TwitterError("id must be an long integer")
+    url = '%s/statuses/show/%s.json' % (self.base_url, id)
+    json = self._FetchUrl(url)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return Status.NewFromJsonDict(data)
+
+  def DestroyStatus(self, id):
+    '''Destroys the status specified by the required ID parameter.
+
+    The twitter.Api instance must be authenticated and thee
+    authenticating user must be the author of the specified status.
+
+    Args:
+      id: The numerical ID of the status you're trying to destroy.
+
+    Returns:
+      A twitter.Status instance representing the destroyed status message
+    '''
+    try:
+      if id:
+        long(id)
+    except:
+      raise TwitterError("id must be an integer")
+    url = '%s/statuses/destroy/%s.json' % (self.base_url, id)
+    json = self._FetchUrl(url, post_data={})
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return Status.NewFromJsonDict(data)
+
+  def PostUpdate(self, status, in_reply_to_status_id=None):
+    '''Post a twitter status message from the authenticated user.
+
+    The twitter.Api instance must be authenticated.
+
+    Args:
+      status:
+        The message text to be posted.  Must be less than or equal to
+        140 characters.
+      in_reply_to_status_id:
+        The ID of an existing status that the status to be posted is
+        in reply to.  This implicitly sets the in_reply_to_user_id
+        attribute of the resulting status to the user ID of the
+        message being replied to.  Invalid/missing status IDs will be
+        ignored. [Optional]
+    Returns:
+      A twitter.Status instance representing the message posted.
+    '''
+    if not self._username:
+      raise TwitterError("The twitter.Api instance must be authenticated.")
+
+    url = '%s/statuses/update.json' % self.base_url
+
+    if len(status) > CHARACTER_LIMIT:
+      raise TwitterError("Text must be less than or equal to %d characters. "
+                         "Consider using PostUpdates." % CHARACTER_LIMIT)
+
+    data = {'status': status}
+    if in_reply_to_status_id:
+      data['in_reply_to_status_id'] = in_reply_to_status_id
+    json = self._FetchUrl(url, post_data=data)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return Status.NewFromJsonDict(data)
+
+  def PostUpdates(self, status, continuation=None, **kwargs):
+    '''Post one or more twitter status messages from the authenticated user.
+
+    Unlike api.PostUpdate, this method will post multiple status updates
+    if the message is longer than 140 characters.
+
+    The twitter.Api instance must be authenticated.
+
+    Args:
+      status:
+        The message text to be posted.  May be longer than 140 characters.
+      continuation:
+        The character string, if any, to be appended to all but the
+        last message.  Note that Twitter strips trailing '...' strings
+        from messages.  Consider using the unicode \u2026 character
+        (horizontal ellipsis) instead. [Defaults to None]
+      **kwargs:
+        See api.PostUpdate for a list of accepted parameters.
+    Returns:
+      A of list twitter.Status instance representing the messages posted.
+    '''
+    results = list()
+    if continuation is None:
+      continuation = ''
+    line_length = CHARACTER_LIMIT - len(continuation)
+    lines = textwrap.wrap(status, line_length)
+    for line in lines[0:-1]:
+      results.append(self.PostUpdate(line + continuation, **kwargs))
+    results.append(self.PostUpdate(lines[-1], **kwargs))
+    return results
+
+  def GetReplies(self, since=None, since_id=None, page=None): 
+    '''Get a sequence of status messages representing the 20 most recent
+    replies (status updates prefixed with @username) to the authenticating
+    user.
+
+    Args:
+      page: 
+      since:
+        Narrows the returned results to just those statuses created
+        after the specified HTTP-formatted date. [optional]
+      since_id:
+        Returns only public statuses with an ID greater than (that is,
+        more recent than) the specified ID. [Optional]
+
+    Returns:
+      A sequence of twitter.Status instances, one for each reply to the user.
+    '''
+    url = '%s/statuses/replies.json' % self.base_url
+    if not self._username:
+      raise TwitterError("The twitter.Api instance must be authenticated.")
+    parameters = {}
+    if since:
+      parameters['since'] = since
+    if since_id:
+      parameters['since_id'] = since_id
+    if page:
+      parameters['page'] = page
+    json = self._FetchUrl(url, parameters=parameters)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return [Status.NewFromJsonDict(x) for x in data]
+
+  def GetFriends(self, user=None, page=None):
+    '''Fetch the sequence of twitter.User instances, one for each friend.
+
+    Args:
+      user: the username or id of the user whose friends you are fetching.  If
+      not specified, defaults to the authenticated user. [optional]
+
+    The twitter.Api instance must be authenticated.
+
+    Returns:
+      A sequence of twitter.User instances, one for each friend
+    '''
+    if not user and not self._username:
+      raise TwitterError("twitter.Api instance must be authenticated")
+    if user:
+      url = '%s/statuses/friends/%s.json' % (self.base_url, user)
+    else:
+      url = '%s/statuses/friends.json' % self.base_url
+    parameters = {}
+    if page:
+      parameters['page'] = page
+    json = self._FetchUrl(url, parameters=parameters)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return [User.NewFromJsonDict(x) for x in data]
+
+  def GetFriendIDs(self, user=None, page=None):
+      '''Returns a list of twitter user id's for every person
+      the specified user is following.
+
+      Args:
+        user:
+          The id or screen_name of the user to retrieve the id list for
+          [optional]
+        page:
+          Specifies the page number of the results beginning at 1.
+          A single page contains 5000 ids. This is recommended for users
+          with large id lists. If not provided all id's are returned. 
+          (Please note that the result set isn't guaranteed to be 5000 
+          every time as suspended users will be filtered.)
+          [optional]
+
+      Returns:
+        A list of integers, one for each user id.
+      '''
+      if not user and not self._username:
+          raise TwitterError("twitter.Api instance must be authenticated")
+      if user:
+          url = '%s/friends/ids/%s.json' % (self.base_url, user)
+      else:
+          url = '%s/friends/ids.json' % self.base_url
+      parameters = {}
+      if page:
+          parameters['page'] = page
+      json = self._FetchUrl(url, parameters=parameters)
+      data = simplejson.loads(json)
+      self._CheckForTwitterError(data)
+      return data
+
+  def GetFollowers(self, page=None):
+    '''Fetch the sequence of twitter.User instances, one for each follower
+
+    The twitter.Api instance must be authenticated.
+
+    Returns:
+      A sequence of twitter.User instances, one for each follower
+    '''
+    if not self._username:
+      raise TwitterError("twitter.Api instance must be authenticated")
+    url = '%s/statuses/followers.json' % self.base_url
+    parameters = {}
+    if page:
+      parameters['page'] = page
+    json = self._FetchUrl(url, parameters=parameters)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return [User.NewFromJsonDict(x) for x in data]
+
+  def GetFeatured(self):
+    '''Fetch the sequence of twitter.User instances featured on twitter.com
+
+    The twitter.Api instance must be authenticated.
+
+    Returns:
+      A sequence of twitter.User instances
+    '''
+    url = '%s/statuses/featured.json' % self.base_url
+    json = self._FetchUrl(url)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return [User.NewFromJsonDict(x) for x in data]
+
+  def GetUser(self, user):
+    '''Returns a single user.
+
+    The twitter.Api instance must be authenticated.
+
+    Args:
+      user: The username or id of the user to retrieve.
+
+    Returns:
+      A twitter.User instance representing that user
+    '''
+    url = '%s/users/show/%s.json' % (self.base_url, user)
+    json = self._FetchUrl(url)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return User.NewFromJsonDict(data)
+
+  def GetDirectMessages(self, since=None, since_id=None, page=None):
+    '''Returns a list of the direct messages sent to the authenticating user.
+
+    The twitter.Api instance must be authenticated.
+
+    Args:
+      since:
+        Narrows the returned results to just those statuses created
+        after the specified HTTP-formatted date. [optional]
+      since_id:
+        Returns only public statuses with an ID greater than (that is,
+        more recent than) the specified ID. [Optional]
+
+    Returns:
+      A sequence of twitter.DirectMessage instances
+    '''
+    url = '%s/direct_messages.json' % self.base_url
+    if not self._username:
+      raise TwitterError("The twitter.Api instance must be authenticated.")
+    parameters = {}
+    if since:
+      parameters['since'] = since
+    if since_id:
+      parameters['since_id'] = since_id
+    if page:
+      parameters['page'] = page 
+    json = self._FetchUrl(url, parameters=parameters)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return [DirectMessage.NewFromJsonDict(x) for x in data]
+
+  def PostDirectMessage(self, user, text):
+    '''Post a twitter direct message from the authenticated user
+
+    The twitter.Api instance must be authenticated.
+
+    Args:
+      user: The ID or screen name of the recipient user.
+      text: The message text to be posted.  Must be less than 140 characters.
+
+    Returns:
+      A twitter.DirectMessage instance representing the message posted
+    '''
+    if not self._username:
+      raise TwitterError("The twitter.Api instance must be authenticated.")
+    url = '%s/direct_messages/new.json' % self.base_url
+    data = {'text': text, 'user': user}
+    json = self._FetchUrl(url, post_data=data)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return DirectMessage.NewFromJsonDict(data)
+
+  def DestroyDirectMessage(self, id):
+    '''Destroys the direct message specified in the required ID parameter.
+
+    The twitter.Api instance must be authenticated, and the
+    authenticating user must be the recipient of the specified direct
+    message.
+
+    Args:
+      id: The id of the direct message to be destroyed
+
+    Returns:
+      A twitter.DirectMessage instance representing the message destroyed
+    '''
+    url = '%s/direct_messages/destroy/%s.json' % (self.base_url, id)
+    json = self._FetchUrl(url, post_data={})
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return DirectMessage.NewFromJsonDict(data)
+
+  def CreateFriendship(self, user):
+    '''Befriends the user specified in the user parameter as the authenticating user.
+
+    The twitter.Api instance must be authenticated.
+
+    Args:
+      The ID or screen name of the user to befriend.
+    Returns:
+      A twitter.User instance representing the befriended user.
+    '''
+    url = '%s/friendships/create/%s.json' % (self.base_url, user)
+    json = self._FetchUrl(url, post_data={})
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return User.NewFromJsonDict(data)
+
+  def DestroyFriendship(self, user):
+    '''Discontinues friendship with the user specified in the user parameter.
+
+    The twitter.Api instance must be authenticated.
+
+    Args:
+      The ID or screen name of the user  with whom to discontinue friendship.
+    Returns:
+      A twitter.User instance representing the discontinued friend.
+    '''
+    url = '%s/friendships/destroy/%s.json' % (self.base_url, user)
+    json = self._FetchUrl(url, post_data={})
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return User.NewFromJsonDict(data)
+
+  def CreateFavorite(self, status):
+    '''Favorites the status specified in the status parameter as the authenticating user.
+    Returns the favorite status when successful.
+
+    The twitter.Api instance must be authenticated.
+
+    Args:
+      The twitter.Status instance to mark as a favorite.
+    Returns:
+      A twitter.Status instance representing the newly-marked favorite.
+    '''
+    url = '%s/favorites/create/%s.json' % (self.base_url, status.id)
+    json = self._FetchUrl(url, post_data={})
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return Status.NewFromJsonDict(data)
+
+  def DestroyFavorite(self, status):
+    '''Un-favorites the status specified in the ID parameter as the authenticating user.
+    Returns the un-favorited status in the requested format when successful.
+
+    The twitter.Api instance must be authenticated.
+
+    Args:
+      The twitter.Status to unmark as a favorite.
+    Returns:
+      A twitter.Status instance representing the newly-unmarked favorite.
+    '''
+    url = '%s/favorites/destroy/%s.json' % (self.base_url, status.id)
+    json = self._FetchUrl(url, post_data={})
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return Status.NewFromJsonDict(data)
+
+  def GetFavorites(self,
+                   user=None,
+                   page=None):
+    '''Return a list of Status objects representing favorited tweets.
+    By default, returns the (up to) 20 most recent tweets for the
+    authenticated user.
+    
+    Args:
+      user:
+        The username or id of the user whose favorites you are fetching.
+        If not specified, defaults to the authenticated user. [optional]
+    
+      page:
+        Retrieves the 20 next most recent favorite statuses. [optional]
+    '''
+    parameters = {}
+
+    if page:
+      parameters['page'] = page
+
+    if user:
+      url = '%s/favorites/%s.json' % (self.base_url, user)
+    elif not user and not self._username:
+      raise TwitterError("User must be specified if API is not authenticated.")
+    else:
+      url = '%s/favorites.json' % self.base_url
+
+    json = self._FetchUrl(url, parameters=parameters)
+    data = simplejson.loads(json)
+
+    self._CheckForTwitterError(data)
+
+    return [Status.NewFromJsonDict(x) for x in data]
+
+  def GetMentions(self,
+                  since_id=None,
+                  max_id=None,
+                  page=None):
+    '''Returns the 20 most recent mentions (status containing @username)
+    for the authenticating user.
+    
+    Args:
+      since_id:
+        Returns only public statuses with an ID greater than
+        (that is, more recent than) the specified ID. [optional]
+    
+      max_id:
+        Returns only statuses with an ID less than
+        (that is, older than) the specified ID.  [optional]
+    
+      page:
+        Retrieves the 20 next most recent replies. [optional]
+    
+    Returns:
+      A sequence of twitter.Status instances, one for each mention of the user.
+      see: http://apiwiki.twitter.com/REST-API-Documentation#statuses/mentions
+    '''
+
+    url = '%s/statuses/mentions.json' % self.base_url
+
+    if not self._username:
+      raise TwitterError("The twitter.Api instance must be authenticated.")
+
+    parameters = {}
+
+    if since_id:
+      parameters['since_id'] = since_id
+    if max_id:
+      parameters['max_id'] = max_id
+    if page:
+      parameters['page'] = page
+
+    json = self._FetchUrl(url, parameters=parameters)
+    data = simplejson.loads(json)
+
+    self._CheckForTwitterError(data)
+
+    return [Status.NewFromJsonDict(x) for x in data]
+
+  def GetUserByEmail(self, email):
+    '''Returns a single user by email address.
+
+    Args:
+      email: The email of the user to retrieve.
+    Returns:
+      A twitter.User instance representing that user
+    '''
+    url = '%s/users/show.json?email=%s' % (self.base_url, email)
+    json = self._FetchUrl(url)
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return User.NewFromJsonDict(data)
+
+  def VerifyCredentials(self):
+    '''Returns a twitter.User instance if the authenticating user is valid.
+
+    Returns: 
+      A twitter.User instance representing that user if the
+      credentials are valid, None otherwise.
+    '''
+    if not self._username:
+      raise TwitterError("Api instance must first be given user credentials.")
+    url = '%s/account/verify_credentials.json' % self.base_url
+    try:
+      json = self._FetchUrl(url, no_cache=True)
+    except urllib2.HTTPError, http_error:
+      if http_error.code == httplib.UNAUTHORIZED:
+        return None
+      else:
+        raise http_error
+    data = simplejson.loads(json)
+    self._CheckForTwitterError(data)
+    return User.NewFromJsonDict(data)
+
+  def SetCredentials(self, username, password):
+    '''Set the username and password for this instance
+
+    Args:
+      username: The twitter username.
+      password: The twitter password.
+    '''
+    self._username = username
+    self._password = password
+
+  def ClearCredentials(self):
+    '''Clear the username and password for this instance
+    '''
+    self._username = None
+    self._password = None
+
+  def SetCache(self, cache):
+    '''Override the default cache.  Set to None to prevent caching.
+
+    Args:
+      cache: an instance that supports the same API as the twitter._FileCache
+    '''
+    if cache == DEFAULT_CACHE:
+      self._cache = _FileCache()
+    else:
+      self._cache = cache
+
+  def SetUrllib(self, urllib):
+    '''Override the default urllib implementation.
+
+    Args:
+      urllib: an instance that supports the same API as the urllib2 module
+    '''
+    self._urllib = urllib
+
+  def SetCacheTimeout(self, cache_timeout):
+    '''Override the default cache timeout.
+
+    Args:
+      cache_timeout: time, in seconds, that responses should be reused.
+    '''
+    self._cache_timeout = cache_timeout
+
+  def SetUserAgent(self, user_agent):
+    '''Override the default user agent
+
+    Args:
+      user_agent: a string that should be send to the server as the User-agent
+    '''
+    self._request_headers['User-Agent'] = user_agent
+
+  def SetXTwitterHeaders(self, client, url, version):
+    '''Set the X-Twitter HTTP headers that will be sent to the server.
+
+    Args:
+      client:
+         The client name as a string.  Will be sent to the server as
+         the 'X-Twitter-Client' header.
+      url:
+         The URL of the meta.xml as a string.  Will be sent to the server
+         as the 'X-Twitter-Client-URL' header.
+      version:
+         The client version as a string.  Will be sent to the server
+         as the 'X-Twitter-Client-Version' header.
+    '''
+    self._request_headers['X-Twitter-Client'] = client
+    self._request_headers['X-Twitter-Client-URL'] = url
+    self._request_headers['X-Twitter-Client-Version'] = version
+
+  def SetSource(self, source):
+    '''Suggest the "from source" value to be displayed on the Twitter web site.
+
+    The value of the 'source' parameter must be first recognized by
+    the Twitter server.  New source values are authorized on a case by
+    case basis by the Twitter development team.
+
+    Args:
+      source:
+        The source name as a string.  Will be sent to the server as
+        the 'source' parameter.
+    '''
+    self._default_params['source'] = source
+
+  def GetRateLimitStatus(self):
+    '''Fetch the rate limit status for the currently authorized user.
+    
+    Returns:
+      A dictionary containing the time the limit will reset (reset_time),
+      the number of remaining hits allowed before the reset (remaining_hits),
+      the number of hits allowed in a 60-minute period (hourly_limit), and the
+      time of the reset in seconds since The Epoch (reset_time_in_seconds).
+    '''
+    url  = '%s/account/rate_limit_status.json' % self.base_url
+    json = self._FetchUrl(url, no_cache=True)
+    data = simplejson.loads(json)
+
+    self._CheckForTwitterError(data)
+
+    return data
+
+  def MaximumHitFrequency(self):
+    '''Determines the minimum number of seconds that a program must wait before
+    hitting the server again without exceeding the rate_limit imposed for the
+    currently authenticated user.
+    
+    Returns:
+      The minimum second interval that a program must use so as to not exceed
+      the rate_limit imposed for the user.
+    '''
+    rate_status = self.GetRateLimitStatus()
+    reset_time  = rate_status.get('reset_time', None)
+    limit       = rate_status.get('remaining_hits', None)
+
+    if reset_time and limit:
+      # put the reset time into a datetime object
+      reset = datetime.datetime(*rfc822.parsedate(reset_time)[:7])
+
+      # find the difference in time between now and the reset time + 1 hour
+      delta = reset + datetime.timedelta(hours=1) - datetime.datetime.utcnow()
+
+      # determine the minimum number of seconds allowed as a regular interval
+      max_frequency = int(delta.seconds / limit)
+
+      # return the number of seconds
+      return max_frequency
+
+    return 0
+
+  def _BuildUrl(self, url, path_elements=None, extra_params=None):
+    # Break url into consituent parts
+    (scheme, netloc, path, params, query, fragment) = urlparse.urlparse(url)
+
+    # Add any additional path elements to the path
+    if path_elements:
+      # Filter out the path elements that have a value of None
+      p = [i for i in path_elements if i]
+      if not path.endswith('/'):
+        path += '/'
+      path += '/'.join(p)
+
+    # Add any additional query parameters to the query string
+    if extra_params and len(extra_params) > 0:
+      extra_query = self._EncodeParameters(extra_params)
+      # Add it to the existing query
+      if query:
+        query += '&' + extra_query
+      else:
+        query = extra_query
+
+    # Return the rebuilt URL
+    return urlparse.urlunparse((scheme, netloc, path, params, query, fragment))
+
+  def _InitializeRequestHeaders(self, request_headers):
+    if request_headers:
+      self._request_headers = request_headers
+    else:
+      self._request_headers = {}
+
+  def _InitializeUserAgent(self):
+    user_agent = 'Python-urllib/%s (python-twitter/%s)' % \
+                 (self._urllib.__version__, __version__)
+    self.SetUserAgent(user_agent)
+
+  def _InitializeDefaultParameters(self):
+    self._default_params = {}
+
+  def _AddAuthorizationHeader(self, username, password):
+    if username and password:
+      basic_auth = base64.encodestring('%s:%s' % (username, password))[:-1]
+      self._request_headers['Authorization'] = 'Basic %s' % basic_auth
+
+  def _RemoveAuthorizationHeader(self):
+    if self._request_headers and 'Authorization' in self._request_headers:
+      del self._request_headers['Authorization']
+
+  def _DecompressGzippedResponse(self, response):
+    raw_data = response.read()
+    if response.headers.get('content-encoding', None) == 'gzip':
+      url_data = gzip.GzipFile(fileobj=StringIO.StringIO(raw_data)).read()
+    else:
+      url_data = raw_data
+    return url_data
+
+  def _GetOpener(self, url, username=None, password=None):
+    if username and password:
+      self._AddAuthorizationHeader(username, password)
+      handler = self._urllib.HTTPBasicAuthHandler()
+      (scheme, netloc, path, params, query, fragment) = urlparse.urlparse(url)
+      handler.add_password(Api._API_REALM, netloc, username, password)
+      opener = self._urllib.build_opener(handler)
+    else:
+      opener = self._urllib.build_opener()
+    opener.addheaders = self._request_headers.items()
+    return opener
+
+  def _Encode(self, s):
+    if self._input_encoding:
+      return unicode(s, self._input_encoding).encode('utf-8')
+    else:
+      return unicode(s).encode('utf-8')
+
+  def _EncodeParameters(self, parameters):
+    '''Return a string in key=value&key=value form
+
+    Values of None are not included in the output string.
+
+    Args:
+      parameters:
+        A dict of (key, value) tuples, where value is encoded as
+        specified by self._encoding
+    Returns:
+      A URL-encoded string in "key=value&key=value" form
+    '''
+    if parameters is None:
+      return None
+    else:
+      return urllib.urlencode(dict([(k, self._Encode(v)) for k, v in parameters.items() if v is not None]))
+
+  def _EncodePostData(self, post_data):
+    '''Return a string in key=value&key=value form
+
+    Values are assumed to be encoded in the format specified by self._encoding,
+    and are subsequently URL encoded.
+
+    Args:
+      post_data:
+        A dict of (key, value) tuples, where value is encoded as
+        specified by self._encoding
+    Returns:
+      A URL-encoded string in "key=value&key=value" form
+    '''
+    if post_data is None:
+      return None
+    else:
+      return urllib.urlencode(dict([(k, self._Encode(v)) for k, v in post_data.items()]))
+
+  def _CheckForTwitterError(self, data):
+    """Raises a TwitterError if twitter returns an error message.
+
+    Args:
+      data: A python dict created from the Twitter json response
+    Raises:
+      TwitterError wrapping the twitter error message if one exists.
+    """
+    # Twitter errors are relatively unlikely, so it is faster
+    # to check first, rather than try and catch the exception
+    if 'error' in data:
+      raise TwitterError(data['error'])
+
+  def _FetchUrl(self,
+                url,
+                post_data=None,
+                parameters=None,
+                no_cache=None,
+                use_gzip_compression=None):
+    '''Fetch a URL, optionally caching for a specified time.
+
+    Args:
+      url:
+        The URL to retrieve
+      post_data:
+        A dict of (str, unicode) key/value pairs.
+        If set, POST will be used.
+      parameters:
+        A dict whose key/value pairs should encoded and added
+        to the query string. [optional]
+      no_cache:
+        If true, overrides the cache on the current request
+      use_gzip_compression:
+        If True, tells the server to gzip-compress the response.
+        It does not apply to POST requests.
+        Defaults to None, which will get the value to use from
+        the instance variable self._use_gzip [optional]
+
+    Returns:
+      A string containing the body of the response.
+    '''
+    # Build the extra parameters dict
+    extra_params = {}
+    if self._default_params:
+      extra_params.update(self._default_params)
+    if parameters:
+      extra_params.update(parameters)
+
+    # Add key/value parameters to the query string of the url
+    url = self._BuildUrl(url, extra_params=extra_params)
+
+    # Get a url opener that can handle basic auth
+    opener = self._GetOpener(url, username=self._username, password=self._password)
+
+    if use_gzip_compression is None:
+      use_gzip = self._use_gzip
+    else:
+      use_gzip = use_gzip_compression
+      
+    # Set up compression
+    if use_gzip and not post_data:
+      opener.addheaders.append(('Accept-Encoding', 'gzip'))
+
+    encoded_post_data = self._EncodePostData(post_data)
+
+    # Open and return the URL immediately if we're not going to cache
+    if encoded_post_data or no_cache or not self._cache or not self._cache_timeout:
+      response = opener.open(url, encoded_post_data)
+      url_data = self._DecompressGzippedResponse(response)
+      opener.close()
+    else:
+      # Unique keys are a combination of the url and the username
+      if self._username:
+        key = self._username + ':' + url
+      else:
+        key = url
+
+      # See if it has been cached before
+      last_cached = self._cache.GetCachedTime(key)
+
+      # If the cached version is outdated then fetch another and store it
+      if not last_cached or time.time() >= last_cached + self._cache_timeout:
+        response = opener.open(url, encoded_post_data)
+        url_data = self._DecompressGzippedResponse(response)
+        opener.close()
+        self._cache.Set(key, url_data)
+      else:
+        url_data = self._cache.Get(key)
+
+    # Always return the latest version
+    return url_data
+
+
+class _FileCacheError(Exception):
+  '''Base exception class for FileCache related errors'''
+
+class _FileCache(object):
+
+  DEPTH = 3
+
+  def __init__(self,root_directory=None):
+    self._InitializeRootDirectory(root_directory)
+
+  def Get(self,key):
+    path = self._GetPath(key)
+    if os.path.exists(path):
+      return open(path).read()
+    else:
+      return None
+
+  def Set(self,key,data):
+    path = self._GetPath(key)
+    directory = os.path.dirname(path)
+    if not os.path.exists(directory):
+      os.makedirs(directory)
+    if not os.path.isdir(directory):
+      raise _FileCacheError('%s exists but is not a directory' % directory)
+    temp_fd, temp_path = tempfile.mkstemp()
+    temp_fp = os.fdopen(temp_fd, 'w')
+    temp_fp.write(data)
+    temp_fp.close()
+    if not path.startswith(self._root_directory):
+      raise _FileCacheError('%s does not appear to live under %s' %
+                            (path, self._root_directory))
+    if os.path.exists(path):
+      os.remove(path)
+    os.rename(temp_path, path)
+
+  def Remove(self,key):
+    path = self._GetPath(key)
+    if not path.startswith(self._root_directory):
+      raise _FileCacheError('%s does not appear to live under %s' %
+                            (path, self._root_directory ))
+    if os.path.exists(path):
+      os.remove(path)
+
+  def GetCachedTime(self,key):
+    path = self._GetPath(key)
+    if os.path.exists(path):
+      return os.path.getmtime(path)
+    else:
+      return None
+
+  def _GetUsername(self):
+    '''Attempt to find the username in a cross-platform fashion.'''
+    try:
+      return os.getenv('USER') or \
+             os.getenv('LOGNAME') or \
+             os.getenv('USERNAME') or \
+             os.getlogin() or \
+             'nobody'
+    except (IOError, OSError), e:
+      return 'nobody'
+
+  def _GetTmpCachePath(self):
+    username = self._GetUsername()
+    cache_directory = 'python.cache_' + username
+    return os.path.join(tempfile.gettempdir(), cache_directory)
+
+  def _InitializeRootDirectory(self, root_directory):
+    if not root_directory:
+      root_directory = self._GetTmpCachePath()
+    root_directory = os.path.abspath(root_directory)
+    if not os.path.exists(root_directory):
+      os.mkdir(root_directory)
+    if not os.path.isdir(root_directory):
+      raise _FileCacheError('%s exists but is not a directory' %
+                            root_directory)
+    self._root_directory = root_directory
+
+  def _GetPath(self,key):
+    try:
+        hashed_key = md5(key).hexdigest()
+    except TypeError:
+        hashed_key = md5.new(key).hexdigest()
+        
+    return os.path.join(self._root_directory,
+                        self._GetPrefix(hashed_key),
+                        hashed_key)
+
+  def _GetPrefix(self,hashed_key):
+    return os.path.sep.join(hashed_key[0:_FileCache.DEPTH])

=== added file 'data/icons/hicolor/scalable/apps/backend_identica.png'
Binary files data/icons/hicolor/scalable/apps/backend_identica.png	1970-01-01 00:00:00 +0000 and data/icons/hicolor/scalable/apps/backend_identica.png	2010-08-25 16:29:48 +0000 differ