Address #1902: Converts example/flaskr to have a setup.py (#1945)

* Converts example/flaskr to have a setup.py

Makes the flaskr app easier to run, ex. workflow:
- pip install --editable .
- export FLASK_APP=flaskr.flaskr
- flask initdb
- flask run

Testing is also easier now:
- python setup.py test

* Fixed an import error in flaskr/tests

- the statement `import flaskr` caused errors in python3
- `from . import flaskr` fixes the issue in 2.7.11 and 3.5.1

* Better project structure and updates the docs

- Re-factors *flaskr*'s project structure a bit
- Updates docs to make sense with the new structure
  - Adds a new step about installing Flask apps with setuptools
  - Switches first-person style writing to second-person (reads better IMO)
  - Adds segments in *testing.rst* for running tests with setuptools

* Remove __init__.py from tests

- py.test recommends not using __init__.py

* Fix testing import errors

docs/tutorial/views.rst

@@ -1,10 +1,10 @@
 .. _tutorial-views:
 
-Step 5: The View Functions
+Step 7: The View Functions
 ==========================
 
-Now that the database connections are working, we can start writing the
-view functions.  We will need four of them:
+Now that the database connections are working, you can start writing the
+view functions.  You will need four of them:
 
 Show Entries
 ------------
@@ -30,7 +30,7 @@ Add New Entry
 
 This view lets the user add new entries if they are logged in.  This only
 responds to ``POST`` requests; the actual form is shown on the
-`show_entries` page.  If everything worked out well, we will
+`show_entries` page.  If everything worked out well, it will
 :func:`~flask.flash` an information message to the next request and
 redirect back to the `show_entries` page::
 
@@ -45,8 +45,8 @@ redirect back to the `show_entries` page::
         flash('New entry was successfully posted')
         return redirect(url_for('show_entries'))
 
-Note that we check that the user is logged in here (the `logged_in` key is
-present in the session and ``True``).
+Note that this view checks that the user is logged in (that is, if the
+`logged_in` key is present in the session and ``True``).
 
 .. admonition:: Security Note
 
@@ -81,11 +81,11 @@ notified about that, and the user is asked again::
         return render_template('login.html', error=error)
 
 The `logout` function, on the other hand, removes that key from the session
-again.  We use a neat trick here: if you use the :meth:`~dict.pop` method
+again.  There is a neat trick here: if you use the :meth:`~dict.pop` method
 of the dict and pass a second parameter to it (the default), the method
 will delete the key from the dictionary if present or do nothing when that
-key is not in there.  This is helpful because now we don't have to check
-if the user was logged in.
+key is not in there.  This is helpful because now it is not necessary to
+check if the user was logged in.
 
 ::
 
@@ -94,11 +94,24 @@ if the user was logged in.
         session.pop('logged_in', None)
         flash('You were logged out')
         return redirect(url_for('show_entries'))
-        
-Note that it is not a good idea to store passwords in plain text. You want to
-protect login credentials if someone happens to have access to your database.
-One way to do this is to use Security Helpers from Werkzeug to hash the
-password. However, the emphasis of this tutorial is to demonstrate the basics
-of Flask and plain text passwords are used for simplicity.
+
+.. admonition:: Security Note
+
+    Passwords should never be stored in plain text in a production
+    system. This tutorial uses plain text passwords for simplicity. If you
+    plan to release a project based off this tutorial out into the world,
+    passwords should be both `hashed and salted`_ before being stored in a
+    database or file.
+
+    Fortunately, there are Flask extensions for the purpose of
+    hashing passwords and verifying passwords against hashes, so adding
+    this functionality is fairly straight forward. There are also
+    many general python libraries that can be used for hashing.
+
+    You can find a list of recommended Flask extensions
+    `here <http://flask.pocoo.org/extensions/>`_
+
 
 Continue with :ref:`tutorial-templates`.
+
+.. _hashed and salted: https://blog.codinghorror.com/youre-probably-storing-passwords-incorrectly/