Merge pull request #383 from IntegersOfK/google-app-engine

Added Google's monkeypatch, disabled caching for now.

GAE.rst

@@ -0,0 +1,55 @@
+================================================
+How to use python-twitter with Google App Engine
+================================================
+
+**********
+Background
+**********
+
+Google App Engine uses virtual machines to do work and serve your application's content. In order to make a 'regular' external web request, the instance must use the built-in urlfetch library provided by Google in addition to the traditional python requests library. As a result, a few extra steps must be followed to use python-twitter on App Engine.
+
+
+*************
+Prerequisites
+*************
+
+Follow the `third party vendor library install instructions <https://cloud.google.com/appengine/docs/python/tools/using-libraries-python-27#vendoring>`_ to include the two dependency libraries listed in ``requirements.txt``: ``requests`` and ``requests_oauthlib``, as well as this ``python-twitter`` library. Typically you can just place the three module folders into the same place as your app.yaml file; it might look something like this:
+
+| myapp/
+| ├── twitter/
+| ├── requests_oauthlib/
+| ├── requests_toolbelt/
+| ├── main.py 
+| └── app.yaml
+
+
+********
+app.yaml
+********
+
+In order to use HTTPS, you'll have to make sure the built-in SSL library is properly imported in your ``app.yaml`` file. Here's what that section of your ``app.yaml`` file might look like:
+
+| libraries:
+| - name: jinja2
+|  version: latest
+| - name: webapp2
+|  version: latest
+| - name: ssl
+|  version: latest
+
+
+****************************
+Limitations & Considerations
+****************************
+
+Caching
+^^^^^^^
+When using twitter-python on App Engine, caching is disabled. You'll have to add and manage App Engine's memcache logic on your own if you require any caching beyond what is probably already setup on App Engine by default.
+
+Datastore
+^^^^^^^^^
+If you plan to store tweets or other information returned by the API in Datastore, you'll probably want to make your own NDP models to store the desired components of the response rather than shoving the whole response into an entity.
+
+Sockets
+^^^^^^^^^
+When urllib3 is imported on App Engine it will throw a warning about sockets: ``AppEnginePlatformWarning: urllib3 is using URLFetch on Google App Engine sandbox...`` This is just a warning that you'd have to use the Sockets API if you intend to use the sockets feature of the library, which we don't use in python-twitter so it can be ignored.

README.rst

@@ -44,6 +44,10 @@ You can install python-twitter using::
 
     $ pip install python-twitter
 
+	
+If you are using python-twitter on Google App Engine, see `more information <GAE.rst>`_ about including 3rd party vendor library dependencies in your App Engine project.
+
+
 ================
 Getting the code
 ================

twitter/api.py

@@ -30,6 +30,7 @@
 import io
 import warnings
 from uuid import uuid4
+import os
 
 try:
     # python 3
@@ -53,6 +54,7 @@
     parse_media_file,
     enf_type)
 
+
 warnings.simplefilter('always', DeprecationWarning)
 
 CHARACTER_LIMIT = 140
@@ -173,6 +175,15 @@ def __init__(self,
             Set timeout (in seconds) of the http/https requests. If None the
             requests lib default will be used.  Defaults to None. [Optional]
         """
+
+        # check to see if the library is running on a Google App Engine instance
+        # see GAE.rst for more information
+        if os.environ:
+            if 'Google App Engine' in os.environ.get('SERVER_SOFTWARE', ''):
+                import requests_toolbelt.adapters.appengine  # Adapter ensures requests use app engine's urlfetch
+                requests_toolbelt.adapters.appengine.monkeypatch()
+                cache = None  # App Engine does not like this caching strategy, disable caching
+
         self.SetCache(cache)
         self._cache_timeout = Api.DEFAULT_CACHE_TIMEOUT
         self._input_encoding = input_encoding