engelke review fixes

Change-Id: I027093776bce1958279bc66b097c03a5af1d7988

Author: wescpy

README.md

@@ -21,7 +21,7 @@ Use of Google Cloud Platform (GCP) products & APIs is not free. While you may no
 
 It's important to note that for App Engine (Standard), Python 2 is only supported as a first-generation ("Gen1") runtime whereas Python3 is only supported as a second-generation ("Gen2") runtime. This means that porting application from Python 2 to 3 also means migrating from Gen1 to Gen2 where things are different.
 
-The most notable changes for developers are that bundled App Engine built-in services are absent from Gen2. The Gen1 bundled services have "grown-up" to become standalone products or have been deprecated. Gen2 also expects web apps to perform their own routing.
+The most notable changes for developers are that bundled App Engine built-in services are absent from Gen2. The Gen1 bundled services have "grown-up" to become standalone products or have been deprecated. Gen2 also expects web apps to perform their own application (not network) routing.
 
 > **NOTE:** App Engine ([Flexible](https://cloud.google.com/appengine/docs/flexible/python/runtime?hl=en#interpreter)) is a Gen2 service but is not within the scope of these tutorials. Developers who curious can compare App Engine [Standard vs. Flexible](https://cloud.google.com/appengine/docs/the-appengine-environments).
 
@@ -33,7 +33,7 @@ The sample app does not address complexities in your apps but serves as a guide
 
 > **NOTE:**
 > 1. It is also possible your app does not have a user interface, i.e., mobile backends, etc., so migrating the web framework (step 1) can be skipped.
-> 1. Users interested in bringing back their dead apps that originally ran on the [deprecated Python 2.5 runtime](http://googleappengine.blogspot.com/2013/03/python-25-thanks-for-good-times.html) (shutdown in 2017) need to [migrate from `db` to `ndb`](http://cloud.google.com/appengine/docs/standard/python/ndb/db_to_ndb) before attempting this tutorial.
+> 1. Users interested in bringing back their dead apps that originally ran on the [deprecated Python 2.5 runtime](http://googleappengine.blogspot.com/2013/03/python-25-thanks-for-good-times.html) (shutdown in 2017) need to [migrate from `db` to `ndb`](http://cloud.google.com/appengine/docs/standard/python/ndb/db_to_ndb) before attempting the techniques shown in this tutorial.
 
 As mentioned above, some steps are more critical while others are *optional*. We recommend incremental updates. We designed each step to be relatively easy, so you experience each migration individually. However, there are some of you for whom the migration process may be easier where you may be able to take larger migration leaps.
 
@@ -44,18 +44,21 @@ We suggest considering where you want to end up eventually, playing with each mi
 Each of the migration steps have their own codelabs & corresponding overview videos:
 
 1. Migrate from `webapp2` to Flask
-    - Recommended if you have a web UI
+    - Stongly recommended if you have a web UI
     - You can use another web framework as long as it supports routing
 1. Migrate from App Engine NDB to Cloud NDB
     - Stongly recommended
     - Can migrate from Python 2 to 3 after this step
     - Can migrate directly to Cloud Run after this step (see Step "2a" below)
     - Remaining datastore migration steps optional
 1. Migrate from Cloud NDB to Cloud Datastore
-    - Recommended if you have non-App Engine code accessing Cloud Datastore
+    - Cloud NDB works on both Python 2 & 3 App Engine runtimes (old & new), so it is optional
+    - Recommended if already using Cloud Datastore in other (App Engine *and* non-App Engine) apps & want a consistent/reusable codebase plus reduce maintenance costs
+    - If all you have are App Engine apps using Cloud NDB, there's no need to do this migration
 1. Migrate from Cloud Datastore to (native) Cloud Firestore
-    - Recommended if you have mobile apps using Firebase+Cloud Firestore
+    - If your app (Cloud project) uses Datastore, you cannot use Firestore.
     - Requires new project as Cloud Datastore & Cloud Firestore mutually-exclusive
+    - Most developers will NOT do this migration unless you *must have* Firestore's Firebase features
 1. Migrate from App Engine to Cloud Run (using Cloud Datastore)
     - Migrate your app to a container with Docker
     - Alternative container migration with Buildpacks (see Step "5a" below)

step1-flask-gaendb-py2/README.md

@@ -202,81 +202,6 @@ AFTER:
 
 ---
 
-## Summary
-
-For the sample app in this tutorial, the overall contextual set of `diff`s look like this:
-
-    $ diff -c step[01]*
-    Only in step1-flask-gaendb-py2: README.md
-    Only in step1-flask-gaendb-py2: appengine_config.py
-    Only in step0-webapp2-gaendb-py2: index.html
-    diff -c step0-webapp2-gaendb-py2/main.py step1-flask-gaendb-py2/main.py
-    *** step0-webapp2-gaendb-py2/main.py    2020-07-29 13:56:27.000000000 -0700
-    --- step1-flask-gaendb-py2/main.py      2020-07-25 13:58:18.000000000 -0700
-    ***************
-    *** 1,7 ****
-    ! import os
-    ! import webapp2
-      from google.appengine.ext import ndb
-    ! from google.appengine.ext.webapp import template
-      
-      class Visit(ndb.Model):
-          visitor   = ndb.StringProperty()
-    --- 1,7 ----
-    ! from flask import Flask, render_template, request
-      from google.appengine.ext import ndb
-    ! 
-    ! app = Flask(__name__)
-      
-      class Visit(ndb.Model):
-          visitor   = ndb.StringProperty()
-    ***************
-    *** 14,26 ****
-          return (v.to_dict() for v in Visit.query().order(
-              -Visit.timestamp).fetch_page(limit)[0])
-      
-    ! class MainHandler(webapp2.RequestHandler):
-    !     def get(self):
-    !         store_visit(self.request.remote_addr, self.request.user_agent)
-    !         visits = fetch_visits(10) or ()  # empty sequence if None
-    !         tmpl = os.path.join(os.path.dirname(__file__), 'index.html')
-    !         self.response.out.write(template.render(tmpl, {'visits': visits}))
-    ! 
-    ! app = webapp2.WSGIApplication([
-    !     ('/', MainHandler),
-    ! ], debug=True)
-    --- 14,21 ----
-          return (v.to_dict() for v in Visit.query().order(
-              -Visit.timestamp).fetch_page(limit)[0])
-      
-    ! @app.route('/')
-    ! def root():
-    !     store_visit(request.remote_addr, request.user_agent)
-    !     visits = fetch_visits(10) or ()  # empty sequence if None
-    !     return render_template('index.html', visits=visits)
-    Only in step1-flask-gaendb-py2: requirements.txt
-    Only in step1-flask-gaendb-py2: templates
-
-The `diff` for the index HTML file isn't shown above as it changed folders, but here is an explcit contextual `diff`:
-
-    $ diff -c step0*/index.html step1*/templates/index.html
-    *** step0-webapp2-gaendb-py2/index.html 2020-08-05 00:12:42.000000000 -0700
-    --- step1-flask-gaendb-py2/templates/index.html 2020-08-05 00:13:06.000000000 -0700
-    ***************
-    *** 8,14 ****
-      <h3>Last 10 visits</h3>
-      <ul>
-      {% for visit in visits %}
-    !     <li>{{ visit.timestamp.ctime }} from {{ visit.visitor }}</li>
-      {% endfor %}
-      </ul>
-      
-    --- 8,14 ----
-      <h3>Last 10 visits</h3>
-      <ul>
-      {% for visit in visits %}
-    !     <li>{{ visit.timestamp.ctime() }} from {{ visit.visitor }}</li>
-      {% endfor %}
-      </ul>
+## Next
 
 In the next step, we will migrate from App Engine NDB to Google Cloud NDB, a key step because after you complete *that*, you can either stop there or be presented with a variety of options to choose from.

step2-flask-cloudndb-py2/README.md

@@ -18,6 +18,7 @@ App Engine services have blossomed into their own products, and App Engine's Dat
 1. Update `requirements.txt` to include the Cloud NDB library (`google-cloud-ndb`).
 1. Update `app.yaml` to reference a pair of 3rd-party bundled packages: `grpcio` and `setuptools`
 1. Update `appengine_config.py` to use the `pkg_resources` tool (which comes with `setuptools`) so App Engine can access [3rd-party libraries already available on Google servers](https://cloud.google.com/appengine/docs/standard/python/tools/built-in-libraries-27) so users don't have to list them in `requirements.txt` nor `pip install` them.
+1. Similarly, [gRPC](http://grpc.io) is used by all [*Google Cloud* client libraries](https://cloud.google.com/apis/docs/cloud-client-libraries), and `grpcio` is the gRPC package for Python and thus required.
 1. Switch application code to use the Cloud NDB client library
 
 ### Configuration
@@ -155,95 +156,7 @@ def fetch_visits(limit):
 
 ---
 
-## Summary
-
-For this migration step, here are the contextual `diff`s:
-
-    $ diff -c step[12]*py2
-    diff -c step1-flask-gaendb-py2/app.yaml step2-flask-cloudndb-py2/app.yaml
-    *** step1-flask-gaendb-py2/app.yaml     2020-07-25 14:10:53.000000000 -0700
-    --- step2-flask-cloudndb-py2/app.yaml   2020-08-05 00:09:42.000000000 -0700
-    ***************
-    *** 5,7 ****
-    --- 5,13 ----
-      handlers:
-      - url: /.*
-        script: main.app
-    + 
-    + libraries:
-    + - name: grpcio
-    +   version: 1.0.0
-    + - name: setuptools
-    +   version: 36.6.0
-    diff -c step1-flask-gaendb-py2/appengine_config.py step2-flask-cloudndb-py2/appengine_config.py
-    *** step1-flask-gaendb-py2/appengine_config.py  2020-07-24 23:09:45.000000000 -0700
-    --- step2-flask-cloudndb-py2/appengine_config.py        2020-07-24 22:50:57.000000000 -0700
-    ***************
-    *** 1,6 ****
-    --- 1,9 ----
-    + import pkg_resources
-      from google.appengine.ext import vendor
-      
-      # Set PATH to your libraries folder.
-      PATH = 'lib'
-      # Add libraries installed in the PATH folder.
-      vendor.add(PATH)
-    + # Add libraries to pkg_resources working set to find the distribution.
-    + pkg_resources.working_set.add_entry(PATH)
-    diff -c step1-flask-gaendb-py2/main.py step2-flask-cloudndb-py2/main.py
-    *** step1-flask-gaendb-py2/main.py      2020-07-25 13:58:18.000000000 -0700
-    --- step2-flask-cloudndb-py2/main.py    2020-07-25 14:00:56.000000000 -0700
-    ***************
-    *** 1,18 ****
-      from flask import Flask, render_template, request
-    ! from google.appengine.ext import ndb
-      
-      app = Flask(__name__)
-      
-      class Visit(ndb.Model):
-          visitor   = ndb.StringProperty()
-          timestamp = ndb.DateTimeProperty(auto_now_add=True)
-      
-      def store_visit(remote_addr, user_agent):
-    !     Visit(visitor='{}: {}'.format(remote_addr, user_agent)).put()
-      
-      def fetch_visits(limit):
-    !     return (v.to_dict() for v in Visit.query().order(
-    !         -Visit.timestamp).fetch_page(limit)[0])
-      
-      @app.route('/')
-      def root():
-    --- 1,21 ----
-      from flask import Flask, render_template, request
-    ! from google.cloud import ndb
-      
-      app = Flask(__name__)
-    + ds_client = ndb.Client()
-      
-      class Visit(ndb.Model):
-          visitor   = ndb.StringProperty()
-          timestamp = ndb.DateTimeProperty(auto_now_add=True)
-      
-      def store_visit(remote_addr, user_agent):
-    !     with ds_client.context():
-    !         Visit(visitor='{}: {}'.format(remote_addr, user_agent)).put()
-      
-      def fetch_visits(limit):
-    !     with ds_client.context():
-    !         return (v.to_dict() for v in Visit.query().order(
-    !                 -Visit.timestamp).fetch_page(limit)[0])
-      
-      @app.route('/')
-      def root():
-    diff -c step1-flask-gaendb-py2/requirements.txt step2-flask-cloudndb-py2/requirements.txt
-    *** step1-flask-gaendb-py2/requirements.txt     2020-07-24 19:27:45.000000000 -0700
-    --- step2-flask-cloudndb-py2/requirements.txt   2020-07-24 21:59:58.000000000 -0700
-    ***************
-    *** 1 ****
-    --- 1,2 ----
-      Flask
-    + google-cloud-ndb
-    Common subdirectories: step1-flask-gaendb-py2/templates and step2-flask-cloudndb-py2/templates
+## Next
 
 From here, you have some flexibility as to your next move. You can...
 

step2-flask-cloudndb-py3/README.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-We recommend developers migrate to Python 3 to access the latest App Engine runtimes & features. Developers can make this migration as soon as they've migrated to Cloud NDB (now). However since this is a large undertaking, you can move to Py3 after any of the datastore migration steps, not just this one. One of the outstanding features of the App Engine second generation runtimes (Gen2) is that neither "vendored" nor bundled 3rd-party packages are required to be uploaded to the service. They are automatically installed directly from `requirements.txt`.
+We recommend developers migrate to Python 3 to access the latest App Engine runtimes & features. Developers can make this migration as soon as they've migrated to Cloud NDB (now). However since this can be a large undertaking, you can move to Py3 after any of the datastore migration steps, not just this one. One of the outstanding features of the App Engine second generation runtimes (Gen2) is that neither "vendored" nor bundled 3rd-party packages are required to be uploaded to the service. They are automatically installed directly from `requirements.txt`.
 
 ---
 
@@ -31,37 +31,7 @@ handlers:
 
 ---
 
-## Summary
-
-For the sample app in this tutorial, the overall contextual set of `diff`s (skipping this `README.md` and nonessential files) looks like this:
-
-    $ diff -c step2-flask-cloudndb-py?
-    diff -c step2-flask-cloudndb-py2/app.yaml step2-flask-cloudndb-py3/app.yaml
-    *** step2-flask-cloudndb-py2/app.yaml   2020-08-05 00:09:42.000000000 -0700
-    --- step2-flask-cloudndb-py3/app.yaml   2020-07-24 23:59:03.000000000 -0700
-    ***************
-    *** 1,13 ****
-    ! runtime: python27
-    ! threadsafe: yes
-    ! api_version: 1
-      
-      handlers:
-      - url: /.*
-    !   script: main.app
-    ! 
-    ! libraries:
-    ! - name: grpcio
-    !   version: 1.0.0
-    ! - name: setuptools
-    !   version: 36.6.0
-    --- 1,5 ----
-    ! runtime: python38
-      
-      handlers:
-      - url: /.*
-    !   script: auto
-    Only in step2-flask-cloudndb-py2: appengine_config.py
-    Common subdirectories: step2-flask-cloudndb-py2/templates and step2-flask-cloudndb-py3/templates
+## Next
 
 From here, your options are:
 

step2a-flask-cloudndb-py2-cloudrun/README.md

@@ -42,36 +42,7 @@ if __name__ == '__main__':
 
 ---
 
-## Summary
-
-For the sample app in this tutorial, the overall contextual set of `diff`s (skipping this `README.md` and nonessential files) looks like this:
-
-    $ diff -c step2*py2*
-    Only in step2a-flask-cloudndb-py2-cloudrun: .dockerignore
-    Only in step2a-flask-cloudndb-py2-cloudrun: Dockerfile
-    Only in step2-flask-cloudndb-py2: app.yaml
-    Only in step2-flask-cloudndb-py2: appengine_config.py
-    diff -c step2-flask-cloudndb-py2/main.py step2a-flask-cloudndb-py2-cloudrun/main.py
-    *** step2-flask-cloudndb-py2/main.py    2020-07-25 14:00:56.000000000 -0700
-    --- step2a-flask-cloudndb-py2-cloudrun/main.py  2020-08-11 19:17:15.000000000 -0700
-    ***************
-    *** 1,3 ****
-    --- 1,4 ----
-    + import os
-      from flask import Flask, render_template, request
-      from google.cloud import ndb
-      
-    ***************
-    *** 22,24 ****
-    --- 23,29 ----
-          store_visit(request.remote_addr, request.user_agent)
-          visits = fetch_visits(10) or ()  # empty sequence if None
-          return render_template('index.html', visits=visits)
-    + 
-    + if __name__ == '__main__':
-    +     app.run(debug=True, threaded=True, host='0.0.0.0',
-    +             port=int(os.environ.get('PORT', 8080)))
-    Common subdirectories: step2-flask-cloudndb-py2/templates and step2a-flask-cloudndb-py2-cloudrun/templates
+## Next
 
 From here, you have some flexibility as to your next move. You can...