update definingmodels (WIP)

- minor grammar and syntax
- define hashing and its purpose

1 files changed, 30 insertions, 24 deletions

diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 41f36fa26..b0781dfe4 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -20,10 +20,10 @@ Declaring dependencies in our ``setup.py`` file
 
 The models code in our application will depend on a package which is not a
 dependency of the original "tutorial" application.  The original "tutorial"
-application was generated by the ``pcreate`` command; it doesn't know
-about our custom application requirements.
+application was generated by the ``pcreate`` command; it doesn't know about our
+custom application requirements.
 
-We need to add a dependency on the ``bcrypt`` package to our ``tutorial``
+We need to add a dependency, the ``bcrypt`` package, to our ``tutorial``
 package's ``setup.py`` file by assigning this dependency to the ``requires``
 parameter in the ``setup()`` function.
 
@@ -56,7 +56,7 @@ On UNIX:
 
 On Windows:
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\pyramidtut> cd tutorial
    c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
@@ -70,8 +70,8 @@ like this::
 Remove ``mymodel.py``
 ---------------------
 
-The first thing we'll do is delete the file ``tutorial/models/mymodel.py``.
-The ``MyModel`` class is only a sample and we're not going to use it.
+Let's delete the file ``tutorial/models/mymodel.py``. The ``MyModel`` class is
+only a sample and we're not going to use it.
 
 
 Add ``user.py``
@@ -85,26 +85,32 @@ Create a new file ``tutorial/models/user.py`` with the following contents:
 
 This is a very basic model for a user who can authenticate with our wiki.
 
-We discussed briefly in the previous chapter that our models will inherit
-from a SQLAlchemy :func:`sqlalchemy.ext.declarative.declarative_base`. This
-will attach the model to our schema.
+We discussed briefly in the previous chapter that our models will inherit from
+an SQLAlchemy :func:`sqlalchemy.ext.declarative.declarative_base`. This will
+attach the model to our schema.
 
 As you can see, our ``User`` class has a class-level attribute
-``__tablename__`` which equals the string ``users``. Our ``User`` class
-will also have class-level attributes named ``id``, ``name``,
-``password_hash`` and ``role`` (all instances of
-:class:`sqlalchemy.schema.Column`). These will map to columns in the ``users``
-table. The ``id`` attribute will be the primary key in the table. The ``name``
-attribute will be a text column, each value of which needs to be unique within
-the column. The ``password_hash`` is a nullable text attribute that will
-contain a securely hashed password [1]_. Finally, the ``role`` text attribute
-will hold the role of the user.
-
-There are two helper methods that will help us later when using the
-user objects. The first is ``set_password`` which will take a raw password
-and transform it using bcrypt_ into an irreversible representation. The
-``check_password`` method will allow us to compare input passwords to
-see if they resolve to the same hash signifying a match.
+``__tablename__`` which equals the string ``users``. Our ``User`` class will
+also have class-level attributes named ``id``, ``name``, ``password_hash``,
+and ``role`` (all instances of :class:`sqlalchemy.schema.Column`). These will
+map to columns in the ``users`` table. The ``id`` attribute will be the primary
+key in the table. The ``name`` attribute will be a text column, each value of
+which needs to be unique within the column. The ``password_hash`` is a nullable
+text attribute that will contain a securely hashed password [1]_. Finally, the
+``role`` text attribute will hold the role of the user.
+
+There are two helper methods that will help us later when using the user
+objects. The first is ``set_password`` which will take a raw password and
+transform it using bcrypt_ into an irreversible representation, a process known
+as "hashing". The second method, ``check_password``, will allow us to compare
+the hashed value of the submitted password against the hashed value of the
+password stored in the user's record in the database. If the two hashed values
+match, then the submitted password is valid, and we can authenticate the user.
+
+We hash passwords so that it is impossible to decrypt them and use them to
+authenticate in the application. If we stored passwords foolishly in clear
+text, then anyone with access to the database could retrieve any password to
+authenticate as any user.
 
 
 Add ``page.py``