Merge pull request #118 from GoogleCloudPlatform/appengine-cloudsql-standards

Bringing cloud sql sample up to standards, and fixing a few other sta…

Author: Jonathan Wayne Parrott

appengine/bigquery/README.md

@@ -1,19 +1,25 @@
 ## Google App Engine accessing BigQuery using OAuth2
 
-This sample demonstrates [authenticating to BigQuery in App Engine using OAuth2](https://cloud.google.com/bigquery/authorization).
+This sample demonstrates [authenticating to BigQuery in App Engine using OAuth2](https://cloud.google.com/bigquery/authentication).
 
-### Setup
+### Running the sample
 
-* To install dependencies for this sample, run:
+1. To install dependencies for this sample, run:
 
-    $ pip install -t lib -r requirements.txt
+        $ pip install -t lib -r requirements.txt
 
-* You must then update `main.py` and replace `<myproject_id>` with your project's
-  id.
-* You'll need a client id from your project - instructions
-  [here](https://cloud-dot-devsite.googleplex.com/bigquery/authorization#clientsecrets).
-  Once you've downloaded the client's json secret, copy it to the root directory
-  of this project, and rename it to `client_secrets.json`.
-* You can then run the sample on your development server:
+2. You must then update `main.py` and replace `<your-project-id>` with your project's
+   ID.
 
-    $ dev_appserver.py .
+3. You'll need a client id from your project - instructions
+   [here](https://cloud.google.com/bigquery/authentication#clientsecrets).
+   Once you've downloaded the client's json secret, copy it to the root directory
+   of this project, and rename it to `client_secrets.json`.
+
+3. You can then run the sample on your development server:
+        
+        $ dev_appserver.py .
+
+   Or deploy the application:
+
+        $ appcfg.py update .

appengine/bigquery/main.py

@@ -12,19 +12,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # [START all]
-"""Sample appengine app demonstrating 3-legged oauth."""
+
+"""
+Sample App Engine application that demonstrates authentication to BigQuery
+using User OAuth2 as opposed to OAuth2 Service Accounts.
+
+For more information about BigQuery, see README.md under /bigquery.
+For more information about App Engine, see README.md under /appengine.
+"""
+
 import json
 import os
 
 from googleapiclient.discovery import build
-
 from oauth2client.appengine import OAuth2DecoratorFromClientSecrets
-
 import webapp2
 
 
 # The project id whose datasets you'd like to list
-PROJECTID = '<myproject_id>'
+PROJECTID = '<your-project-id>'
 
 # Create the method decorator for oauth.
 decorator = OAuth2DecoratorFromClientSecrets(
@@ -37,21 +43,23 @@
 
 class MainPage(webapp2.RequestHandler):
 
+    # oauth_required ensures that the user goes through the OAuth2
+    # authorization flow before reaching this handler.
     @decorator.oauth_required
     def get(self):
-        """Lists the datasets in PROJECTID"""
+        # This is an httplib2.Http instance that is signed with the user's
+        # credentials. This allows you to access the BigQuery API on behalf
+        # of the user.
         http = decorator.http()
-        datasets = service.datasets()
 
-        response = datasets.list(projectId=PROJECTID).execute(http)
+        response = service.datasets().list(projectId=PROJECTID).execute(http)
 
         self.response.out.write('<h3>Datasets.list raw response:</h3>')
         self.response.out.write('<pre>%s</pre>' %
                                 json.dumps(response, sort_keys=True, indent=4,
                                            separators=(',', ': ')))
 
 
-# Create the webapp2 application
 app = webapp2.WSGIApplication([
     ('/', MainPage),
     # Create the endpoint to receive oauth flow callbacks

appengine/cloudsql/README.md

@@ -1,7 +1,15 @@
+# Using Cloud SQL from Google App Engine
+
 This is an example program showing how to use the native MySQL connections from Google App Engine to Google Cloud SQL.
 
-## Deploying
+## Running the sample
+
+1. Edit the `CLOUDSQL_INSTANCE` and `CLOUDSQL_PROJECT` values in `main.py`.
+
+2. If you have a local MySQL instance, run the app locally:
+
+        dev_appserver.py .
 
-1. Edit the `unix_socket` in `main.py` to point to a Cloud SQL instance.
+2. Upload the app: 
 
-2. Upload the app: `appcfg.py update .`.
+        appcfg.py update .

appengine/cloudsql/__init__.py

@@ -11,29 +11,48 @@
 # 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.
+
+"""
+Sample App Engine application demonstrating how to connect to Google Cloud SQL
+using App Engine's native unix socket.
+
+For more information about App Engine, see README.md under /appengine.
+"""
+
 import os
 
 import MySQLdb
 import webapp2
 
 
-class IndexPage(webapp2.RequestHandler):
+CLOUDSQL_PROJECT = '<your-project-id>'
+CLOUDSQL_INSTANCE = '<your-cloud-sql-instance>'
+
+
+class MainPage(webapp2.RequestHandler):
     def get(self):
         self.response.headers['Content-Type'] = 'text/plain'
 
+        # When running on Google App Engine, use the special unix socket
+        # to connect to Cloud SQL.
         if os.getenv('SERVER_SOFTWARE', '').startswith('Google App Engine/'):
             db = MySQLdb.connect(
-                unix_socket='/cloudsql/my_project:my_instance',
+                unix_socket='/cloudsql/{}:{}'.format(
+                    CLOUDSQL_PROJECT,
+                    CLOUDSQL_INSTANCE),
                 user='root')
+        # When running locally, you can either connect to a local running
+        # MySQL instance, or connect to your Cloud SQL instance over TCP.
         else:
             db = MySQLdb.connect(host='localhost', user='root')
 
         cursor = db.cursor()
         cursor.execute('SHOW VARIABLES')
+
         for r in cursor.fetchall():
-            self.response.write('%s\n' % str(r))
+            self.response.write('{}\n'.format(r))
 
 
 app = webapp2.WSGIApplication([
-    ('/', IndexPage),
+    ('/', MainPage),
 ], debug=True)

appengine/cloudsql/main.py

@@ -0,0 +1,33 @@
+# Copyright 2015 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.
+import re
+
+import tests
+import webtest
+
+from . import main
+
+
+class TestMySQLSample(tests.AppEngineTestbedCase):
+
+    def setUp(self):
+        super(TestMySQLSample, self).setUp()
+        self.app = webtest.TestApp(main.app)
+
+    def test_get(self):
+        response = self.app.get('/')
+        self.assertEqual(response.status_int, 200)
+        self.assertRegexpMatches(
+            response.body,
+            re.compile(r'.*version.*', re.DOTALL))

appengine/cloudsql/main_test.py

@@ -1,3 +1,19 @@
 ## Google App Engine using Cloud Storage
 
-This sample demonstrates how to use cloud storage from Google App Engine
+This sample demonstrates how to use Google Cloud Storage from Google App Engine
+
+### Running the sample
+
+1. To install dependencies for this sample, run:
+
+        $ pip install -t lib -r requirements.txt
+
+2. You must then update `main.py` and replace `<your-bucket-name>` with your Cloud Storage bucket.
+
+3. You can then run the sample on your development server:
+        
+        $ dev_appserver.py .
+
+   Or deploy the application:
+
+        $ appcfg.py update .

appengine/storage/README.md

@@ -18,6 +18,7 @@ commonargs =
 [testenv:gae]
 deps =
     {[testenv]deps}
+    mysql-python==1.2.5
 commands = 
     nosetests --with-gae \
         --gae-app=tests/resources/app.yaml \