Merge branch 'master' into exception_only

44 files changed, 255 insertions, 132 deletions

diff --git a/docs/api/authentication.rst b/docs/api/authentication.rst
index 19d08618b..57f32327a 100644
--- a/docs/api/authentication.rst
+++ b/docs/api/authentication.rst
@@ -34,5 +34,10 @@ Helper Classes
   .. autoclass:: AuthTktCookieHelper
      :members:
 
+  .. autoclass:: HTTPBasicCredentials
+     :members:
 
+Helper Functions
+~~~~~~~~~~~~~~~~
 
+  .. autofunction:: extract_http_basic_credentials
diff --git a/docs/conf.py b/docs/conf.py
index 518f7e784..c3a7170fc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -78,7 +78,7 @@ intersphinx_mapping = {
     'webtest': ('http://webtest.pythonpaste.org/en/latest', None),
     'who': ('http://repozewho.readthedocs.org/en/latest', None),
     'zcml': ('http://docs.pylonsproject.org/projects/pyramid-zcml/en/latest', None),
-    'zcomponent': ('http://docs.zope.org/zope.component', None),
+    'zcomponent': ('http://zopecomponent.readthedocs.io/en/stable/', None),
 }
 
 
diff --git a/docs/conventions.rst b/docs/conventions.rst
index 43853882c..de041da04 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -57,23 +57,16 @@ character, e.g.:
 
      $ $VENV/bin/py.test -q
 
-(See :term:`venv` for the meaning of ``$VENV``)
+See :term:`venv` for the meaning of ``$VENV``.
 
-Example blocks representing Windows ``cmd.exe`` commands are prefixed with a
-drive letter and/or a directory name, e.g.:
+Example blocks representing Windows commands are prefixed with a drive letter
+with an optional directory name, e.g.:
 
   .. code-block:: doscon
 
      c:\examples> %VENV%\Scripts\py.test -q
 
-(See :term:`venv` for the meaning of ``%VENV%``)
-
-Sometimes, when it's unknown which directory is current, Windows ``cmd.exe``
-example block commands are prefixed only with a ``>`` character, e.g.:
-
-  .. code-block:: doscon
-
-     > %VENV%\Scripts\py.test -q
+See :term:`venv` for the meaning of ``%VENV%``.
 
 When a command that should be typed on one line is too long to fit on a page,
 the backslash ``\`` is used to indicate that the following printed line should
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 6cd90d42f..242bc7ec7 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -649,6 +649,10 @@ using the :func:`pyramid.paster.bootstrap` command in the body of your script.
 .. versionadded:: 1.1
    :func:`pyramid.paster.bootstrap`
 
+.. versionchanged:: 1.8
+   Added the ability for ``bootstrap`` to cleanup automatically via the
+   ``with`` statement.
+
 In the simplest case, :func:`pyramid.paster.bootstrap` can be used with a
 single argument, which accepts the :term:`PasteDeploy` ``.ini`` file
 representing your Pyramid application's configuration as a single argument:
@@ -656,8 +660,9 @@ representing your Pyramid application's configuration as a single argument:
 .. code-block:: python
 
    from pyramid.paster import bootstrap
-   env = bootstrap('/path/to/my/development.ini')
-   print(env['request'].route_url('home'))
+
+   with bootstrap('/path/to/my/development.ini') as env:
+       print(env['request'].route_url('home'))
 
 :func:`pyramid.paster.bootstrap` returns a dictionary containing
 framework-related information.  This dictionary will always contain a
@@ -723,8 +728,9 @@ load instead of ``main``:
 .. code-block:: python
 
    from pyramid.paster import bootstrap
-   env = bootstrap('/path/to/my/development.ini#another')
-   print(env['request'].route_url('home'))
+
+   with bootstrap('/path/to/my/development.ini#another') as env:
+       print(env['request'].route_url('home'))
 
 The above example specifies the ``another`` ``app``, ``pipeline``, or
 ``composite`` section of your PasteDeploy configuration file. The ``app``
@@ -761,9 +767,9 @@ desired request and passing it into :func:`~pyramid.paster.bootstrap`:
    from pyramid.request import Request
 
    request = Request.blank('/', base_url='https://example.com/prefix')
-   env = bootstrap('/path/to/my/development.ini#another', request=request)
-   print(env['request'].application_url)
-   # will print 'https://example.com/prefix'
+   with bootstrap('/path/to/my/development.ini#another', request=request) as env:
+       print(env['request'].application_url)
+       # will print 'https://example.com/prefix'
 
 Now you can readily use Pyramid's APIs for generating URLs:
 
@@ -776,7 +782,9 @@ Now you can readily use Pyramid's APIs for generating URLs:
 Cleanup
 ~~~~~~~
 
-When your scripting logic finishes, it's good manners to call the ``closer``
+If you're using the ``with``-statement variant then there's nothing to
+worry about. However if you're using the returned environment directly then
+when your scripting logic finishes, it's good manners to call the ``closer``
 callback:
 
 .. code-block:: python
@@ -891,15 +899,12 @@ contains the following code:
        omit = options.omit
        if omit is None:
            omit = []
-       env = bootstrap(config_uri)
-       settings, closer = env['registry'].settings, env['closer']
-       try:
+       with bootstrap(config_uri) as env:
+           settings = env['registry'].settings
            for k, v in settings.items():
                if any([k.startswith(x) for x in omit]):
                    continue
                print('%-40s     %-20s' % (k, v))
-       finally:
-           closer()
 
 This script uses the Python ``optparse`` module to allow us to make sense out
 of extra arguments passed to the script.  It uses the
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index a8491eabd..ad05976c0 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -27,15 +27,15 @@ installed, an HTTP server is started on TCP port 8080.
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/python helloworld.py
 
 On Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   C:\> %VENV%\Scripts\python.exe helloworld.py
+   c:\> %VENV%\Scripts\python helloworld.py
 
 This command will not return and nothing will be printed to the console. When
 port 8080 is visited by a browser on the URL ``/hello/world``, the server will
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 7fbac2080..b22b31bf9 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -26,7 +26,7 @@ Not Found View by using the
    :linenos:
 
    def notfound(request):
-       return Response('Not Found, dude', status='404 Not Found')
+       return Response('Not Found', status='404 Not Found')
 
    def main(globals, **settings):
        config = Configurator()
@@ -45,7 +45,7 @@ and a :term:`scan`, you can replace the Not Found View by using the
 
    @notfound_view_config()
    def notfound(request):
-       return Response('Not Found, dude', status='404 Not Found')
+       return Response('Not Found', status='404 Not Found')
 
    def main(globals, **settings):
        config = Configurator()
@@ -67,11 +67,11 @@ Views can carry predicates limiting their applicability.  For example:
 
    @notfound_view_config(request_method='GET')
    def notfound_get(request):
-       return Response('Not Found during GET, dude', status='404 Not Found')
+       return Response('Not Found during GET', status='404 Not Found')
 
    @notfound_view_config(request_method='POST')
    def notfound_post(request):
-       return Response('Not Found during POST, dude', status='404 Not Found')
+       return Response('Not Found during POST', status='404 Not Found')
 
    def main(globals, **settings):
       config = Configurator()
@@ -1481,7 +1481,7 @@ method. For example:
         phash = text
 
         def __call__(self, context, request):
-            return getattr(context, 'content_type', None) == self.val
+            return request.content_type == self.val
 
 The constructor of a predicate factory takes two arguments: ``val`` and
 ``config``.  The ``val`` argument will be the argument passed to
@@ -1500,13 +1500,28 @@ with the name and the value serialized.  The result of ``phash`` is not seen in
 output anywhere, it just informs the uniqueness constraints for view
 configuration.
 
-The ``__call__`` method of a predicate factory must accept a resource
-(``context``) and a request, and must return ``True`` or ``False``.  It is the
-"meat" of the predicate.
+The ``__call__`` method differs depending on whether the predicate is used as
+a :term:`view predicate` or a :term:`route predicate`:
 
-You can use the same predicate factory as both a view predicate and as a route
-predicate, but you'll need to call ``add_view_predicate`` and
-``add_route_predicate`` separately with the same factory.
+- When used as a route predicate, the ``__call__`` signature is
+  ``(info, request)``. The ``info`` object is a dictionary containing two
+  keys: ``match`` and ``route``. ``info['match']`` is the matchdict containing
+  the patterns matched in the route pattern. ``info['route']`` is the
+  :class:`pyramid.interfaces.IRoute` object for the current route.
+
+- When used as a view predicate, the ``__call__`` signature is
+  ``(context, request)``. The ``context`` is the result of :term:`traversal`
+  performed using either the route's :term:`root factory` or the app's
+  :term:`default root factory`.
+
+In both cases the ``__call__`` method is expected to return ``True`` or
+``False``.
+
+It is possible to use the same predicate factory as both a view predicate and
+as a route predicate, but they'll need to handle the ``info`` or ``context``
+argument specially (many predicates do not need this argument) and you'll need
+to call ``add_view_predicate`` and ``add_route_predicate`` separately with
+the same factory.
 
 .. _subscriber_predicates:
 
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 131832aae..3549b53a5 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -294,7 +294,7 @@ Lingua like so:
 
 .. code-block:: doscon
 
-   C> %VENV%\Scripts\pip install lingua
+   c:\> %VENV%\Scripts\pip install lingua
 
 
 .. index::
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 7d96f4074..570cb2285 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -21,9 +21,8 @@ the following sections.
 
 .. sidebar:: Python Versions
 
-    As of this writing, :app:`Pyramid` has been tested under Python 2.7,
-    Python 3.3, Python 3.4, Python 3.5, PyPy, and PyPy3. :app:`Pyramid` does
-    not run under any version of Python before 2.7.
+    As of this writing, :app:`Pyramid` is tested against Python 2.7,
+    Python 3.4, Python 3.5, PyPy.
 
 :app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux,
 Mac OS X, and FreeBSD, as well as on Windows platforms.  It is also known to
@@ -92,8 +91,24 @@ If your Windows system doesn't have a Python interpreter, you'll need to
 install it by downloading a Python 3.x-series interpreter executable from
 `python.org's download section <https://www.python.org/downloads/>`_ (the files
 labeled "Windows Installer").  Once you've downloaded it, double click on the
-executable and accept the defaults during the installation process. You may
-also need to download and install the Python for Windows extensions.
+executable, and select appropriate options during the installation process. To
+standardize this documentation, we used the GUI installer and selected the
+following options:
+
+- Screen 1: Install Python 3.x.x (32- or 64-bit)
+    - Check "Install launcher for all users (recommended)"
+    - Check "Add Python 3.x to PATH"
+    - Click "Customize installation"
+- Screen 2: Optional Features
+    - Check all options
+    - Click "Next"
+- Screen 3: Advanced Options
+    - Check all options
+    - Customize install location: "C:\\Python3x", where "x" is the minor
+      version of Python
+    - Click "Next"
+
+You might also need to download and install the Python for Windows extensions.
 
 .. seealso:: See the official Python documentation :ref:`Using Python on
    Windows <python:using-on-windows>` for full details.
@@ -104,14 +119,19 @@ also need to download and install the Python for Windows extensions.
    directions. Make sure you get the proper 32- or 64-bit build and Python
    version.
 
+.. seealso:: `Python launcher for Windows
+   <https://docs.python.org/3/using/windows.html#launcher>`_ provides a command
+   ``py`` that allows users to run any installed version of Python.
+
 .. warning::
 
-   After you install Python on Windows, you may need to add the ``C:\Python3x``
-   directory to your environment's ``Path``, where ``x`` is the minor version
-   of installed Python, in order to make it possible to invoke Python from a
-   command prompt by typing ``python``. To do so, right click ``My Computer``,
-   select ``Properties`` --> ``Advanced Tab`` --> ``Environment Variables`` and
-   add that directory to the end of the ``Path`` environment variable.
+   After you install Python on Windows, you might need to add the
+   ``c:\Python3x`` directory to your environment's ``Path``, where ``x`` is the
+   minor version of installed Python, in order to make it possible to invoke
+   Python from a command prompt by typing ``python``. To do so, right click
+   ``My Computer``, select ``Properties`` --> ``Advanced Tab`` -->
+   ``Environment Variables``, and add that directory to the end of the ``Path``
+   environment variable.
 
    .. seealso:: See `Configuring Python (on Windows)
       <https://docs.python.org/3/using/windows.html#configuring-python>`_ for
@@ -171,6 +191,29 @@ After installing Python as described previously in :ref:`for-mac-os-x-users` or
 
       $ $VENV/bin/pip install "pyramid==\ |release|\ "
 
+.. index::
+   single: $VENV/bin/pip vs. source bin/activate
+
+.. _venv-bin-pip-vs-source-bin-activate:
+
+.. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then
+   ``pip``?
+
+   ``$VENV/bin/pip`` clearly specifies that ``pip`` is run from within the
+   virtual environment and not at the system level.
+
+   ``activate`` drops turds into the user's shell environment, leaving them
+   vulnerable to executing commands in the wrong context. ``deactivate`` might
+   not correctly restore previous shell environment variables.
+
+   Although using ``source bin/activate``, then ``pip``, requires fewer key
+   strokes to issue commands once invoked, there are other things to consider.
+   Michael F. Lamb (datagrok) presents a summary in `Virtualenv's bin/activate
+   is Doing It Wrong <https://gist.github.com/datagrok/2199506>`_.
+
+   Ultimately we prefer to keep things clear and simple, so we use
+   ``$VENV/bin/pip``.
+
 
 .. index::
    single: installing on Windows
@@ -190,7 +233,8 @@ After installing Python as described previously in
 
       c:\> set VENV=c:\env
       # replace "x" with your minor version of Python 3
-      c:\> c:\Python3x\Scripts\python3 -m venv %VENV%
+      c:\> c:\Python3x\python -m venv %VENV%
+      c:\> cd %VENV%
 
    You can either follow the use of the environment variable ``%VENV%``, or
    replace it with the root directory of the virtual environment. If you choose
@@ -204,7 +248,10 @@ After installing Python as described previously in
 
    .. parsed-literal::
 
-      c:\\env> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
+      c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
+
+.. note:: See the note above for :ref:`Why use $VENV/bin/pip instead of source
+   bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.
 
 
 What Gets Installed
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index de6ac408b..47638579b 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -860,7 +860,7 @@ Every release of Pyramid has 100% statement coverage via unit and integration
 tests, as measured by the ``coverage`` tool available on PyPI.  It also has
 greater than 95% decision/condition coverage as measured by the
 ``instrumental`` tool available on PyPI. It is automatically tested by Travis,
-and Jenkins on Python 2.7, Python 3.3, Python 3.4, Python 3.5, PyPy, and PyPy3
+and Jenkins on Python 2.7, Python 3.4, Python 3.5, and PyPy
 after each commit to its GitHub repository. Official Pyramid add-ons are held
 to a similar testing standard.  We still find bugs in Pyramid and its official
 add-ons, but we've noticed we find a lot more of them while working on other
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 1ce12a938..71bd176f6 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -87,9 +87,9 @@ On UNIX:
 
 Or on Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   > %VENV%\Scripts\pcreate -s starter MyProject
+   c:\> %VENV%\Scripts\pcreate -s starter MyProject
 
 As a result of invoking the ``pcreate`` command, a directory named
 ``MyProject`` is created.  That directory is a :term:`project` directory. The
@@ -161,8 +161,8 @@ Or on Windows:
 
 .. code-block:: doscon
 
-   > cd MyProject
-   > %VENV%\Scripts\pip install -e .
+   c:\> cd MyProject
+   c:\> %VENV%\Scripts\pip install -e .
 
 Elided output from a run of this command on UNIX is shown below:
 
@@ -199,7 +199,7 @@ On Windows:
 
 .. code-block:: doscon
 
-   > %VENV%\Scripts\pip install -e ".[testing]"
+   c:\> %VENV%\Scripts\pip install -e ".[testing]"
 
 Once the testing requirements are installed, then you can run the tests using
 the ``py.test`` command that was just installed in the ``bin`` directory of
@@ -215,7 +215,7 @@ On Windows:
 
 .. code-block:: doscon
 
-   > %VENV%\Scripts\py.test -q
+   c:\> %VENV%\Scripts\py.test -q
 
 Here's sample output from a test run on UNIX:
 
@@ -282,7 +282,7 @@ On Windows:
 
 .. code-block:: text
 
-   > %VENV%\Scripts\pserve development.ini
+   c:\> %VENV%\Scripts\pserve development.ini
 
 Here's sample output from a run of ``pserve`` on UNIX:
 
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index 21b696775..4e434c3c6 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -205,10 +205,10 @@ On UNIX, you can do that via:
 
 On Windows, you need to issue two commands:
 
-.. code-block:: bash
+.. code-block:: doscon
 
-   C:\> set PYTHONWARNINGS=default
-   C:\> Scripts/pserve.exe development.ini
+   c:\> set PYTHONWARNINGS=default
+   c:\> Scripts/pserve.exe development.ini
 
 At this point, it's ensured that deprecation warnings will be printed to the
 console whenever a codepath is hit that generates one.  You can then click
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 7d37c04df..9ac01e24a 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -850,7 +850,7 @@ application:
    from pyramid.httpexceptions import HTTPNotFound
 
    def notfound(request):
-       return HTTPNotFound('Not found, bro.')
+       return HTTPNotFound()
 
    def no_slash(request):
        return Response('No slash')
@@ -871,7 +871,7 @@ If a request enters the application with the ``PATH_INFO`` value of
 However, if a request enters the application with the ``PATH_INFO`` value of
 ``/no_slash/``, *no* route will match, and the slash-appending not found view
 will not find a matching route with an appended slash.  As a result, the
-``notfound`` view will be called and it will return a "Not found, bro." body.
+``notfound`` view will be called and it will return a "Not found" body.
 
 If a request enters the application with the ``PATH_INFO`` value of
 ``/has_slash/``, the second route will match.  If a request enters the
@@ -892,7 +892,7 @@ exactly the same job:
 
    @notfound_view_config(append_slash=True)
    def notfound(request):
-       return HTTPNotFound('Not found, bro.')
+       return HTTPNotFound()
 
    @view_config(route_name='noslash')
    def no_slash(request):
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index dde91b495..39b4cafb3 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -44,22 +44,24 @@ For Windows:
 .. parsed-literal::
 
     # set an environment variable to where you want your virtual environment
-    c:\> set VENV=c:\env
+    c:\\> set VENV=c:\\env
     # create the virtual environment
-    c:\\> c:\\Python35\\python3 -m venv %VENV%
+    c:\\> %VENV%\\Scripts\\python -m venv %VENV%
     # install pyramid
     c:\\> %VENV%\\Scripts\\pip install pyramid
     # or for a specific released version
     c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
-Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick
+Of course Pyramid runs fine on Python 2.7+, as do the examples in this *Quick
 Tour*. We're showing Python 3 for simplicity. (Pyramid had production support
 for Python 3 in October 2011.) Also for simplicity, the remaining examples will
 show only UNIX commands.
 
 .. seealso:: See also:
     :ref:`Quick Tutorial section on Requirements <qtut_requirements>`,
-    :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`, and
+    :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`,
+    :ref:`Why use $VENV/bin/pip instead of source bin/activate, then pip
+    <venv-bin-pip-vs-source-bin-activate>`, and
     :ref:`Installing Pyramid on a Windows System <installing_windows>`.
 
 
@@ -504,10 +506,10 @@ Pyramid's ``pcreate`` command can list the available scaffolds:
 
     $ pcreate --list
     Available scaffolds:
-      alchemy:                 Pyramid SQLAlchemy project using url dispatch
+      alchemy:                 Pyramid project using SQLAlchemy, SQLite, URL dispatch, and Jinja2
       pyramid_jinja2_starter:  Pyramid Jinja2 starter project
-      starter:                 Pyramid starter project
-      zodb:                    Pyramid ZODB project using traversal
+      starter:                 Pyramid starter project using URL dispatch and Chameleon
+      zodb:                    Pyramid project using ZODB, traversal, and Chameleon
 
 The ``pyramid_jinja2`` add-on gave us a scaffold that we can use. From the
 parent directory of where we want our Python package to be generated, let's use
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/models/meta.py b/docs/quick_tour/sqla_demo/sqla_demo/models/meta.py
index 80ececd8c..03c50ae93 100644
--- a/docs/quick_tour/sqla_demo/sqla_demo/models/meta.py
+++ b/docs/quick_tour/sqla_demo/sqla_demo/models/meta.py
@@ -6,7 +6,7 @@ import zope.sqlalchemy
 
 # Recommended naming convention used by Alembic, as various different database
 # providers will autogenerate vastly different names making migrations more
-# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+# difficult. See: http://alembic.zzzcomputing.com/en/latest/naming.html
 NAMING_CONVENTION = {
     "ix": 'ix_%(column_0_label)s',
     "uq": "uq_%(table_name)s_%(column_0_name)s",
diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst
index acff97f3b..892beb3ec 100644
--- a/docs/quick_tutorial/authentication.rst
+++ b/docs/quick_tutorial/authentication.rst
@@ -1,7 +1,7 @@
 .. _qtut_authentication:
 
 ==============================
-20: Logins With Authentication
+20: Logins with authentication
 ==============================
 
 Login views that authenticate a username and password against a list of users.
@@ -34,6 +34,18 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r view_classes authentication; cd authentication
+
+#. Add ``bcrypt`` as a dependency in ``authentication/setup.py``:
+
+   .. literalinclude:: authentication/setup.py
+    :language: python
+    :emphasize-lines: 5-6
+    :linenos:
+
+#. We can now install our project in development mode:
+
+   .. code-block:: bash
+
     $ $VENV/bin/pip install -e .
 
 #. Put the security hash in the ``authentication/development.ini``
@@ -96,8 +108,8 @@ Unlike many web frameworks, Pyramid includes a built-in but optional security
 model for authentication and authorization. This security system is intended to
 be flexible and support many needs. In this security model, authentication (who
 are you) and authorization (what are you allowed to do) are not just pluggable,
-but de-coupled. To learn one step at a time, we provide a system that
-identifies users and lets them log out.
+but decoupled. To learn one step at a time, we provide a system that identifies
+users and lets them log out.
 
 In this example we chose to use the bundled :ref:`AuthTktAuthenticationPolicy
 <authentication_module>` policy. We enabled it in our configuration and
@@ -108,6 +120,20 @@ returned a login form. When reached via ``POST``, it processed the submitted
 username and password against the "groupfinder" callable that we registered in
 the configuration.
 
+The function ``hash_password`` uses a one-way hashing algorithm with a salt on
+the user's password via ``bcrypt``, instead of storing the password in plain
+text. This is considered to be a "best practice" for security.
+
+.. note::
+    There are alternative libraries to ``bcrypt`` if it is an issue on your
+    system. Just make sure that the library uses an algorithm approved for
+    storing passwords securely.
+
+The function ``check_password`` will compare the two hashed values of the
+submitted password and the user's password stored in the database. If the
+hashed values are equivalent, then the user is authenticated, else
+authentication fails.
+
 In our template, we fetched the ``logged_in`` value from the view class. We use
 this to calculate the logged-in user, if any. In the template we can then
 choose to show a login link to anonymous visitors or a logout link to logged-in
@@ -125,4 +151,5 @@ Extra credit
    request? Use ``import pdb; pdb.set_trace()`` to answer this.
 
 .. seealso:: See also :ref:`security_chapter`,
-   :ref:`AuthTktAuthenticationPolicy <authentication_module>`.
+   :ref:`AuthTktAuthenticationPolicy <authentication_module>`, `bcrypt
+   <https://pypi.python.org/pypi/bcrypt>`_
diff --git a/docs/quick_tutorial/authentication/setup.py b/docs/quick_tutorial/authentication/setup.py
index 2221b72e9..7a6ff4226 100644
--- a/docs/quick_tutorial/authentication/setup.py
+++ b/docs/quick_tutorial/authentication/setup.py
@@ -2,7 +2,8 @@ from setuptools import setup
 
 requires = [
     'pyramid',
-    'pyramid_chameleon'
+    'pyramid_chameleon',
+    'bcrypt'
 ]
 
 setup(name='tutorial',
diff --git a/docs/quick_tutorial/authentication/tutorial/security.py b/docs/quick_tutorial/authentication/tutorial/security.py
index ab90bab2c..e585e2642 100644
--- a/docs/quick_tutorial/authentication/tutorial/security.py
+++ b/docs/quick_tutorial/authentication/tutorial/security.py
@@ -1,5 +1,17 @@
-USERS = {'editor': 'editor',
-         'viewer': 'viewer'}
+import bcrypt
+
+
+def hash_password(pw):
+    pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
+    return pwhash.decode('utf8')
+
+def check_password(pw, hashed_pw):
+    expected_hash = hashed_pw.encode('utf8')
+    return bcrypt.checkpw(pw.encode('utf8'), expected_hash)
+
+
+USERS = {'editor': hash_password('editor'),
+         'viewer': hash_password('viewer')}
 GROUPS = {'editor': ['group:editors']}
 
 
diff --git a/docs/quick_tutorial/authentication/tutorial/views.py b/docs/quick_tutorial/authentication/tutorial/views.py
index ab46eb2dd..b07538d5e 100644
--- a/docs/quick_tutorial/authentication/tutorial/views.py
+++ b/docs/quick_tutorial/authentication/tutorial/views.py
@@ -9,7 +9,10 @@ from pyramid.view import (
     view_defaults
     )
 
-from .security import USERS
+from .security import (
+    USERS,
+    check_password
+)
 
 
 @view_defaults(renderer='home.pt')
@@ -40,7 +43,7 @@ class TutorialViews:
         if 'form.submitted' in request.params:
             login = request.params['login']
             password = request.params['password']
-            if USERS.get(login) == password:
+            if check_password(password, USERS.get(login)):
                 headers = remember(request, login)
                 return HTTPFound(location=came_from,
                                  headers=headers)
diff --git a/docs/quick_tutorial/authorization/setup.py b/docs/quick_tutorial/authorization/setup.py
index 2221b72e9..7a6ff4226 100644
--- a/docs/quick_tutorial/authorization/setup.py
+++ b/docs/quick_tutorial/authorization/setup.py
@@ -2,7 +2,8 @@ from setuptools import setup
 
 requires = [
     'pyramid',
-    'pyramid_chameleon'
+    'pyramid_chameleon',
+    'bcrypt'
 ]
 
 setup(name='tutorial',
diff --git a/docs/quick_tutorial/authorization/tutorial/security.py b/docs/quick_tutorial/authorization/tutorial/security.py
index ab90bab2c..e585e2642 100644
--- a/docs/quick_tutorial/authorization/tutorial/security.py
+++ b/docs/quick_tutorial/authorization/tutorial/security.py
@@ -1,5 +1,17 @@
-USERS = {'editor': 'editor',
-         'viewer': 'viewer'}
+import bcrypt
+
+
+def hash_password(pw):
+    pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
+    return pwhash.decode('utf8')
+
+def check_password(pw, hashed_pw):
+    expected_hash = hashed_pw.encode('utf8')
+    return bcrypt.checkpw(pw.encode('utf8'), expected_hash)
+
+
+USERS = {'editor': hash_password('editor'),
+         'viewer': hash_password('viewer')}
 GROUPS = {'editor': ['group:editors']}
 
 
diff --git a/docs/quick_tutorial/authorization/tutorial/views.py b/docs/quick_tutorial/authorization/tutorial/views.py
index 43d14455a..b2dc905c0 100644
--- a/docs/quick_tutorial/authorization/tutorial/views.py
+++ b/docs/quick_tutorial/authorization/tutorial/views.py
@@ -10,7 +10,10 @@ from pyramid.view import (
     forbidden_view_config
     )
 
-from .security import USERS
+from .security import (
+    USERS,
+    check_password
+)
 
 
 @view_defaults(renderer='home.pt')
@@ -42,7 +45,7 @@ class TutorialViews:
         if 'form.submitted' in request.params:
             login = request.params['login']
             password = request.params['password']
-            if USERS.get(login) == password:
+            if check_password(password, USERS.get(login)):
                 headers = remember(request, login)
                 return HTTPFound(location=came_from,
                                  headers=headers)
diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst
index aaf904390..b02363d40 100644
--- a/docs/quick_tutorial/debugtoolbar.rst
+++ b/docs/quick_tutorial/debugtoolbar.rst
@@ -90,7 +90,7 @@ temporarily.
 .. seealso:: See also :ref:`pyramid_debugtoolbar <toolbar:overview>`.
 
 
-Extra Credit
+Extra credit
 ============
 
 #. Why don't we add ``pyramid_debugtoolbar`` to the list of
diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst
index 66e77491d..84ceb13d6 100644
--- a/docs/quick_tutorial/forms.rst
+++ b/docs/quick_tutorial/forms.rst
@@ -41,6 +41,7 @@ Steps
    pulls in Colander as a dependency:
 
    .. literalinclude:: forms/setup.py
+    :emphasize-lines: 5-6
     :linenos:
 
 #. We can now install our project in development mode:
@@ -74,13 +75,18 @@ Steps
     :language: html
     :linenos:
 
-#. Finally, a template at ``forms/tutorial/wikipage_view.pt`` for viewing a
-   wiki page:
+#. Add a template at ``forms/tutorial/wikipage_view.pt`` for viewing a wiki
+   page:
 
    .. literalinclude:: forms/tutorial/wikipage_view.pt
     :language: html
     :linenos:
 
+#. Our tests in ``forms/tutorial/tests.py`` don't run, so let's modify them:
+
+   .. literalinclude:: forms/tutorial/tests.py
+    :linenos:
+
 #. Run the tests:
 
    .. code-block:: bash
diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst
index 4e35da7bb..56dccde58 100644
--- a/docs/quick_tutorial/hello_world.rst
+++ b/docs/quick_tutorial/hello_world.rst
@@ -88,7 +88,7 @@ Pyramid development. Building an application from loosely-coupled parts via
 revisit regularly in this *Quick Tutorial*.
 
 
-Extra Credit
+Extra credit
 ============
 
 #. Why do we do this:
diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst
index fba5ce29e..9a65d66d1 100644
--- a/docs/quick_tutorial/ini.rst
+++ b/docs/quick_tutorial/ini.rst
@@ -120,7 +120,7 @@ filesystem for changes to relevant code (Python files, the INI file, etc.) and,
 when something changes, restart the application. Very handy during development.
 
 
-Extra Credit
+Extra credit
 ============
 
 #. If you don't like configuration and/or ``.ini`` files, could you do this
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 62dd570fc..afa8ed104 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -19,7 +19,7 @@ virtual environment.)
 
 This *Quick Tutorial* is based on:
 
-* **Python 3.5**. Pyramid fully supports Python 3.3+ and Python 2.7+. This
+* **Python 3.5**. Pyramid fully supports Python 3.4+ and Python 2.7+. This
   tutorial uses **Python 3.5** but runs fine under Python 2.7.
 
 * **venv**. We believe in virtual environments. For this tutorial, we use
@@ -156,7 +156,7 @@ environment variable.
 .. code-block:: doscon
 
     # Windows
-    c:\> c:\Python35\python3 -m venv %VENV%
+    c:\> c:\Python35\python -m venv %VENV%
 
 .. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
    2's `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ package.
@@ -179,6 +179,9 @@ time of its release.
     # Windows
     c:\> %VENV%\Scripts\pip install --upgrade pip setuptools
 
+.. seealso:: See also :ref:`Why use $VENV/bin/pip instead of source
+   bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.
+
 
 .. _install-pyramid:
 
diff --git a/docs/quick_tutorial/routing.rst b/docs/quick_tutorial/routing.rst
index 27c8c2c22..d88adfa1e 100644
--- a/docs/quick_tutorial/routing.rst
+++ b/docs/quick_tutorial/routing.rst
@@ -79,7 +79,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/$VENV/bin/py.test tutorial/tests.py -q
+    $ $VENV/bin/py.test tutorial/tests.py -q
     ..
     2 passed in 0.39 seconds
 
diff --git a/docs/quick_tutorial/scaffolds.rst b/docs/quick_tutorial/scaffolds.rst
index 7845f2b71..ad002f4fd 100644
--- a/docs/quick_tutorial/scaffolds.rst
+++ b/docs/quick_tutorial/scaffolds.rst
@@ -38,9 +38,9 @@ Steps
 
         $ $VENV/bin/pcreate --list
         Available scaffolds:
-          alchemy:                 Pyramid SQLAlchemy project using url dispatch
-          starter:                 Pyramid starter project
-          zodb:                    Pyramid ZODB project using traversal
+          alchemy:  Pyramid project using SQLAlchemy, SQLite, URL dispatch, and Jinja2
+          starter:  Pyramid starter project using URL dispatch and Chameleon
+          zodb:     Pyramid project using ZODB, traversal, and Chameleon
 
 #. Tell ``pcreate`` to use the ``starter`` scaffold to make our project:
 
diff --git a/docs/quick_tutorial/static_assets.rst b/docs/quick_tutorial/static_assets.rst
index 65b34f8f9..b8482492d 100644
--- a/docs/quick_tutorial/static_assets.rst
+++ b/docs/quick_tutorial/static_assets.rst
@@ -47,7 +47,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/$VENV/bin/py.test tutorial/tests.py -q
+    $ $VENV/bin/py.test tutorial/tests.py -q
     ....
     4 passed in 0.50 seconds
 
diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst
index 56fd2b297..7c85d5289 100644
--- a/docs/quick_tutorial/unit_testing.rst
+++ b/docs/quick_tutorial/unit_testing.rst
@@ -92,7 +92,7 @@ necessary when your test needs to make use of the ``config`` object (it's a
 Configurator) to add stuff to the configuration state before calling the view.
 
 
-Extra Credit
+Extra credit
 ============
 
 #. Change the test to assert that the response status code should be ``404``
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index ce67bb9e3..98a14c644 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -114,7 +114,7 @@ Finally ``main`` is finished configuring things, so it uses the
 Route declarations
 ------------------
 
-Open the ``tutorials/routes.py`` file. It should already contain the following:
+Open the ``tutorial/routes.py`` file. It should already contain the following:
 
 .. literalinclude:: src/basiclayout/tutorial/routes.py
   :linenos:
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index a214b1306..0440c2d1d 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -402,13 +402,6 @@ initialize our database.
    already have a database, you should delete it before running
    ``initialize_tutorial_db`` again.
 
-.. note::
-
-   The ``initialize_tutorial_db`` command is not performing a migration but
-   rather simply creating missing tables and adding some dummy data. If you
-   already have a database, you should delete it before running
-   ``initialize_tutorial_db`` again.
-
 Type the following command, making sure you are still in the ``tutorial``
 directory (the directory with a ``development.ini`` in it):
 
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/models/meta.py b/docs/tutorials/wiki2/src/authentication/tutorial/models/meta.py
index fc3e8f1dd..0682247b5 100644
--- a/docs/tutorials/wiki2/src/authentication/tutorial/models/meta.py
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/models/meta.py
@@ -3,7 +3,7 @@ from sqlalchemy.schema import MetaData
 
 # Recommended naming convention used by Alembic, as various different database
 # providers will autogenerate vastly different names making migrations more
-# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+# difficult. See: http://alembic.zzzcomputing.com/en/latest/naming.html
 NAMING_CONVENTION = {
     "ix": 'ix_%(column_0_label)s',
     "uq": "uq_%(table_name)s_%(column_0_name)s",
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py b/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py
index 6fb32a1b2..9228b48f7 100644
--- a/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py
@@ -19,11 +19,10 @@ class User(Base):
 
     def set_password(self, pw):
         pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
-        self.password_hash = pwhash
+        self.password_hash = pwhash.decode('utf8')
 
     def check_password(self, pw):
         if self.password_hash is not None:
             expected_hash = self.password_hash.encode('utf8')
-            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
-            return expected_hash == actual_hash
+            return bcrypt.checkpw(pw.encode('utf8'), expected_hash)
         return False
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models/meta.py b/docs/tutorials/wiki2/src/authorization/tutorial/models/meta.py
index fc3e8f1dd..0682247b5 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/models/meta.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models/meta.py
@@ -3,7 +3,7 @@ from sqlalchemy.schema import MetaData
 
 # Recommended naming convention used by Alembic, as various different database
 # providers will autogenerate vastly different names making migrations more
-# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+# difficult. See: http://alembic.zzzcomputing.com/en/latest/naming.html
 NAMING_CONVENTION = {
     "ix": 'ix_%(column_0_label)s',
     "uq": "uq_%(table_name)s_%(column_0_name)s",
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py b/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py
index 6fb32a1b2..9228b48f7 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py
@@ -19,11 +19,10 @@ class User(Base):
 
     def set_password(self, pw):
         pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
-        self.password_hash = pwhash
+        self.password_hash = pwhash.decode('utf8')
 
     def check_password(self, pw):
         if self.password_hash is not None:
             expected_hash = self.password_hash.encode('utf8')
-            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
-            return expected_hash == actual_hash
+            return bcrypt.checkpw(pw.encode('utf8'), expected_hash)
         return False
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models/meta.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/meta.py
index fc3e8f1dd..0682247b5 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/models/meta.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/meta.py
@@ -3,7 +3,7 @@ from sqlalchemy.schema import MetaData
 
 # Recommended naming convention used by Alembic, as various different database
 # providers will autogenerate vastly different names making migrations more
-# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+# difficult. See: http://alembic.zzzcomputing.com/en/latest/naming.html
 NAMING_CONVENTION = {
     "ix": 'ix_%(column_0_label)s',
     "uq": "uq_%(table_name)s_%(column_0_name)s",
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/models/meta.py b/docs/tutorials/wiki2/src/installation/tutorial/models/meta.py
index fc3e8f1dd..0682247b5 100644
--- a/docs/tutorials/wiki2/src/installation/tutorial/models/meta.py
+++ b/docs/tutorials/wiki2/src/installation/tutorial/models/meta.py
@@ -3,7 +3,7 @@ from sqlalchemy.schema import MetaData
 
 # Recommended naming convention used by Alembic, as various different database
 # providers will autogenerate vastly different names making migrations more
-# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+# difficult. See: http://alembic.zzzcomputing.com/en/latest/naming.html
 NAMING_CONVENTION = {
     "ix": 'ix_%(column_0_label)s',
     "uq": "uq_%(table_name)s_%(column_0_name)s",
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/meta.py b/docs/tutorials/wiki2/src/models/tutorial/models/meta.py
index fc3e8f1dd..0682247b5 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/models/meta.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/meta.py
@@ -3,7 +3,7 @@ from sqlalchemy.schema import MetaData
 
 # Recommended naming convention used by Alembic, as various different database
 # providers will autogenerate vastly different names making migrations more
-# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+# difficult. See: http://alembic.zzzcomputing.com/en/latest/naming.html
 NAMING_CONVENTION = {
     "ix": 'ix_%(column_0_label)s',
     "uq": "uq_%(table_name)s_%(column_0_name)s",
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/user.py b/docs/tutorials/wiki2/src/models/tutorial/models/user.py
index 6fb32a1b2..9228b48f7 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/user.py
@@ -19,11 +19,10 @@ class User(Base):
 
     def set_password(self, pw):
         pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
-        self.password_hash = pwhash
+        self.password_hash = pwhash.decode('utf8')
 
     def check_password(self, pw):
         if self.password_hash is not None:
             expected_hash = self.password_hash.encode('utf8')
-            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
-            return expected_hash == actual_hash
+            return bcrypt.checkpw(pw.encode('utf8'), expected_hash)
         return False
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models/meta.py b/docs/tutorials/wiki2/src/tests/tutorial/models/meta.py
index fc3e8f1dd..0682247b5 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/models/meta.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models/meta.py
@@ -3,7 +3,7 @@ from sqlalchemy.schema import MetaData
 
 # Recommended naming convention used by Alembic, as various different database
 # providers will autogenerate vastly different names making migrations more
-# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+# difficult. See: http://alembic.zzzcomputing.com/en/latest/naming.html
 NAMING_CONVENTION = {
     "ix": 'ix_%(column_0_label)s',
     "uq": "uq_%(table_name)s_%(column_0_name)s",
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models/user.py b/docs/tutorials/wiki2/src/tests/tutorial/models/user.py
index 6fb32a1b2..9228b48f7 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models/user.py
@@ -19,11 +19,10 @@ class User(Base):
 
     def set_password(self, pw):
         pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
-        self.password_hash = pwhash
+        self.password_hash = pwhash.decode('utf8')
 
     def check_password(self, pw):
         if self.password_hash is not None:
             expected_hash = self.password_hash.encode('utf8')
-            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
-            return expected_hash == actual_hash
+            return bcrypt.checkpw(pw.encode('utf8'), expected_hash)
         return False
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models/meta.py b/docs/tutorials/wiki2/src/views/tutorial/models/meta.py
index fc3e8f1dd..0682247b5 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/models/meta.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/models/meta.py
@@ -3,7 +3,7 @@ from sqlalchemy.schema import MetaData
 
 # Recommended naming convention used by Alembic, as various different database
 # providers will autogenerate vastly different names making migrations more
-# difficult. See: http://alembic.readthedocs.org/en/latest/naming.html
+# difficult. See: http://alembic.zzzcomputing.com/en/latest/naming.html
 NAMING_CONVENTION = {
     "ix": 'ix_%(column_0_label)s',
     "uq": "uq_%(table_name)s_%(column_0_name)s",
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models/user.py b/docs/tutorials/wiki2/src/views/tutorial/models/user.py
index 6fb32a1b2..9228b48f7 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/models/user.py
@@ -19,11 +19,10 @@ class User(Base):
 
     def set_password(self, pw):
         pwhash = bcrypt.hashpw(pw.encode('utf8'), bcrypt.gensalt())
-        self.password_hash = pwhash
+        self.password_hash = pwhash.decode('utf8')
 
     def check_password(self, pw):
         if self.password_hash is not None:
             expected_hash = self.password_hash.encode('utf8')
-            actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
-            return expected_hash == actual_hash
+            return bcrypt.checkpw(pw.encode('utf8'), expected_hash)
         return False