Update docs, add functionality to get_lastfunction_header per @devdave

HISTORY.rst

@@ -22,6 +22,7 @@ History
 - Pass ``client_args`` to the Twython ``__init__`` to manipulate request variables. ``client_args`` accepts a dictionary of keywords and values that accepted by ``requests`` (`Session API <http://docs.python-requests.org/en/latest/api/#sessionapi>`_) [ex. headers, proxies, verify(SSL verification)] and the "request" section directly below it.
 - Added ``get_application_rate_limit_status`` API method for returning the current rate limits for the specified source
 - Added ``invalidate_token`` API method which allows registed apps to revoke an access token presenting its client credentials
+- ``get_lastfunction_header`` now accepts a ``default_return_value`` parameter. This means that if you pass a second value (ex. ``Twython.get_lastfunction_header('x-rate-limit-remaining', 0)``) and the value is not found, it returns your default value
 
 2.10.1 (2013-05-29)
 ++++++++++++++++++

docs/usage/advanced_usage.rst

@@ -132,5 +132,21 @@ or both (and set a timeout variable):
                       OAUTH_TOKEN, OAUTH_TOKEN_SECRET
                       client_args=client_args)
 
+Access Headers of Previous Call
+-------------------------------
+
+There are times when you may want to check headers from the previous call.
+If you wish to access headers (ex. x-rate-limit-remaining, x-rate-limit-reset, content-type), you'll use the ``get_lastfunction_header`` method.
+
+.. code-block:: python
+
+    from twython import Twython
+
+    twitter = Twython(APP_KEY, APP_SECRET
+                      OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
+
+    twitter.get_home_timeline()
+    twitter.get_lastfunction_header('x-rate-limit-remaining')
+
 
 So now you can authenticate, update your status (with or without an image), search Twitter, and a few other things! Good luck!

twython/api.py

@@ -222,7 +222,7 @@ class Twython(EndpointsMixin, object):
         """Shortcut for POST requests via :class:`request`"""
         return self.request(endpoint, 'POST', params=params, version=version)
 
-    def get_lastfunction_header(self, header):
+    def get_lastfunction_header(self, header, default_return_value=None):
         """Returns a specific header from the last API call
         This will return None if the header is not present
 
@@ -238,10 +238,7 @@ class Twython(EndpointsMixin, object):
         if self._last_call is None:
             raise TwythonError('This function must be called after an API call.  It delivers header information.')
 
-        if header in self._last_call['headers']:
-            return self._last_call['headers'][header]
-        else:
-            return None
+        return self._last_call['headers'].get(header, default_return_value)
 
     def get_authentication_tokens(self, callback_url=None, force_login=False, screen_name=''):
         """Returns a dict including an authorization URL, ``auth_url``, to direct a user to