Merge branch 'master' of github.com:Pylons/pyramid

17 files changed, 215 insertions, 134 deletions

diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst
index 3cc182d13..c66786b11 100644
--- a/docs/tutorials/modwsgi/index.rst
+++ b/docs/tutorials/modwsgi/index.rst
@@ -18,7 +18,7 @@ specific path information for commands and files.
    ``mod_wsgi``.  If you have experience with :app:`Pyramid` and ``mod_wsgi``
    on Windows systems, please help us document this experience by submitting
    documentation to the `Pylons-devel maillist
-   <http://groups.google.com/group/pylons-devel>`_.
+   <https://groups.google.com/forum/#!forum/pylons-devel>`_.
 
 #.  The tutorial assumes you have Apache already installed on your
     system.  If you do not, install Apache 2.X for your platform in
@@ -29,7 +29,7 @@ specific path information for commands and files.
 
 #.  Once you have Apache installed, install ``mod_wsgi``.  Use the
     (excellent) `installation instructions
-    <http://code.google.com/p/modwsgi/wiki/InstallationInstructions>`_
+    <https://code.google.com/archive/p/modwsgi/wikis/InstallationInstructions.wiki>`_
     for your platform into your system's Apache installation.
 
 #.  Create a :term:`virtual environment` which we'll use to install our
@@ -44,11 +44,11 @@ specific path information for commands and files.
 
 #.  Install :app:`Pyramid` into the newly created virtual environment:
 
-    .. code-block:: text
+    .. parsed-literal::
 
        $ cd ~/modwsgi/env
-       $ $VENV/bin/pip install pyramid
-    
+       $ $VENV/bin/pip install "pyramid==\ |release|\ "
+
 #.  Create and install your :app:`Pyramid` application.  For the purposes of
     this tutorial, we'll just be using the ``pyramid_starter`` application as
     a baseline application.  Substitute your existing :app:`Pyramid`
@@ -119,9 +119,8 @@ specific path information for commands and files.
 #.  Visit ``http://localhost/myapp`` in a browser.  You should see the
     sample application rendered in your browser.
 
-:term:`mod_wsgi` has many knobs and a great variety of deployment
-modes.  This is just one representation of how you might use it to
-serve up a :app:`Pyramid` application.  See the `mod_wsgi
-configuration documentation
-<http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines>`_ for
-more in-depth configuration information.
+:term:`mod_wsgi` has many knobs and a great variety of deployment modes. This
+is just one representation of how you might use it to serve up a :app:`Pyramid`
+application.  See the `mod_wsgi configuration documentation
+<https://code.google.com/archive/p/modwsgi/wikis/ConfigurationGuidelines.wiki>`_
+for more in-depth configuration information.
diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst
index c3037f396..386b880e6 100644
--- a/docs/tutorials/wiki/distributing.rst
+++ b/docs/tutorials/wiki/distributing.rst
@@ -36,6 +36,6 @@ Note that this command creates a tarball in the "dist" subdirectory named
 ``tutorial-0.0.tar.gz``.  You can send this file to your friends to show them
 your cool new application.  They should be able to install it by pointing the
 ``pip install .`` command directly at it. Or you can upload it to `PyPI
-<http://pypi.python.org>`_ and share it with the rest of the world, where it
-can be downloaded via ``pip install`` remotely like any other package people
+<https://pypi.python.org/pypi>`_ and share it with the rest of the world, where
+it can be downloaded via ``pip install`` remotely like any other package people
 download from PyPI.
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index dbf995595..6172b122b 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -97,16 +97,17 @@ Install Pyramid into the virtual Python environment
 On UNIX
 ^^^^^^^
 
-.. code-block:: bash
+.. parsed-literal::
 
-   $ $VENV/bin/pip install pyramid
+   $ $VENV/bin/pip install "pyramid==\ |release|\ "
 
 On Windows
 ^^^^^^^^^^
 
-.. code-block:: doscon
+.. parsed-literal::
+
+   c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
-   c:\> %VENV%\Scripts\pip install pyramid
 
 Change directory to your virtual Python environment
 ---------------------------------------------------
@@ -128,6 +129,7 @@ On Windows
 
    c:\> cd pyramidtut
 
+
 .. _making_a_project:
 
 Making a project
@@ -208,7 +210,7 @@ packages. Success executing this command will show a line like the following:
    zc.lockfile-1.1.0 zdaemon-4.1.0 zodbpickle-0.6.0 zodburi-2.0
 
 
-.. _install-testing-requirements_zodb:
+.. _install-testing-requirements-zodb:
 
 Install testing requirements
 ----------------------------
@@ -251,21 +253,23 @@ Run the tests
 -------------
 
 After you've installed the project in development mode as well as the testing
-requirements, you may run the tests for the project.
+requirements, you may run the tests for the project. The following commands
+provide options to py.test that specify the module for which its tests shall be
+run, and to run py.test in quiet mode.
 
 On UNIX
 ^^^^^^^
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test tutorial/tests.py -q
+   $ $VENV/bin/py.test -q
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: doscon
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test -q
 
 For a successful test run, you should see output that ends like this:
 
@@ -291,15 +295,15 @@ On UNIX
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py
+   $ $VENV/bin/py.test --cov --cov-report=term-missing
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: doscon
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
-       --cov-report=term-missing tutorial\tests.py
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov \
+       --cov-report=term-missing
 
 If successful, you will see output something like this:
 
@@ -327,6 +331,40 @@ If successful, you will see output something like this:
 Our package doesn't quite have 100% test coverage.
 
 
+.. _test_and_coverage_scaffold_defaults_zodb:
+
+Test and coverage scaffold defaults
+-----------------------------------
+
+Scaffolds include configuration defaults for ``py.test`` and test coverage.
+These configuration files are ``pytest.ini`` and ``.coveragerc``, located at
+the root of your package. Without these defaults, we would need to specify the
+path to the module on which we want to run tests and coverage.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov=tutorial tutorial/tests.py -q
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
+       --cov-report=term-missing tutorial\tests.py -q
+
+py.test follows :ref:`conventions for Python test discovery
+<pytest:test discovery>`, and the configuration defaults from the scaffold
+tell ``py.test`` where to find the module on which we want to run tests and
+coverage.
+
+.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke
+   ``py.test -h`` to see its full set of options.
+
+
 .. _wiki-start-the-application:
 
 Start the application
@@ -357,9 +395,9 @@ If successful, you will see something like this on your console:
 
 .. code-block:: text
 
-    Starting subprocess with file monitor
-    Starting server in PID 95736.
-    serving on http://127.0.0.1:6543
+   Starting subprocess with file monitor
+   Starting server in PID 82349.
+   serving on http://127.0.0.1:6543
 
 This means the server is ready to accept requests.
 
@@ -386,9 +424,28 @@ assumptions:
 
 - You are willing to use :term:`traversal` to map URLs to code.
 
+- You want to use pyramid_zodbconn_, pyramid_tm_, and the transaction_ packages
+  to manage connections and transactions with :term:`ZODB`.
+
+- You want to use pyramid_chameleon_ to render your templates. Different
+  templating engines can be used, but we had to choose one to make this
+  tutorial. See :ref:`available_template_system_bindings` for some options.
+
 .. note::
 
-   :app:`Pyramid` supports any persistent storage mechanism (e.g., a SQL
-   database or filesystem files).  It also supports an additional
-   mechanism to map URLs to code (:term:`URL dispatch`).  However, for the
-   purposes of this tutorial, we'll only be using traversal and ZODB.
+   :app:`Pyramid` supports any persistent storage mechanism (e.g., an SQL
+   database or filesystem files). It also supports an additional mechanism to
+   map URLs to code (:term:`URL dispatch`). However, for the purposes of this
+   tutorial, we'll only be using :term:`traversal` and :term:`ZODB`.
+
+.. _pyramid_chameleon:
+   http://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/
+
+.. _pyramid_tm:
+   http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/
+
+.. _pyramid_zodbconn:
+   http://docs.pylonsproject.org/projects/pyramid-zodbconn/en/latest/
+
+.. _transaction:
+   http://zodb.readthedocs.org/en/latest/transactions.html
diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst
index 788ec595b..85a023cc9 100644
--- a/docs/tutorials/wiki/tests.rst
+++ b/docs/tutorials/wiki/tests.rst
@@ -52,20 +52,21 @@ Running the tests
 =================
 
 We can run these tests by using ``py.test`` similarly to how we did in
-:ref:`running_tests`. Our testing dependencies have already been satisfied,
-courtesy of the scaffold, so we can jump right to running tests.
+:ref:`running_tests`. Courtesy of the scaffold, our testing dependencies have
+already been satisfied and ``py.test`` and coverage have already been
+configured, so we can jump right to running tests.
 
 On UNIX:
 
 .. code-block:: text
 
-   $ $VENV/bin/py.test tutorial/tests.py -q
+   $ $VENV/bin/py.test -q
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial/tests.py -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test -q
 
 The expected result should look like the following:
 
diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 6520613ea..9f7b82d1d 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -191,49 +191,49 @@ Success will look something like this:
 
 .. code-block:: bash
 
-   2016-04-09 02:49:51,711 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
-   2016-04-09 02:49:51,711 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
-   2016-04-09 02:49:51,712 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
-   2016-04-09 02:49:51,712 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
-   2016-04-09 02:49:51,713 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("pages")
-   2016-04-09 02:49:51,714 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-04-09 02:49:51,714 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("users")
-   2016-04-09 02:49:51,714 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-04-09 02:49:51,715 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
+   2016-05-22 04:12:09,226 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
+   2016-05-22 04:12:09,226 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-05-22 04:12:09,226 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
+   2016-05-22 04:12:09,227 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-05-22 04:12:09,227 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("users")
+   2016-05-22 04:12:09,227 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-05-22 04:12:09,228 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("pages")
+   2016-05-22 04:12:09,228 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-05-22 04:12:09,229 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
    CREATE TABLE users (
-           id INTEGER NOT NULL,
-           name TEXT NOT NULL,
-           role TEXT NOT NULL,
-           password_hash TEXT,
-           CONSTRAINT pk_users PRIMARY KEY (id),
-           CONSTRAINT uq_users_name UNIQUE (name)
+       id INTEGER NOT NULL,
+       name TEXT NOT NULL,
+       role TEXT NOT NULL,
+       password_hash TEXT,
+       CONSTRAINT pk_users PRIMARY KEY (id),
+       CONSTRAINT uq_users_name UNIQUE (name)
    )
 
 
-   2016-04-09 02:49:51,715 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-04-09 02:49:51,716 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
-   2016-04-09 02:49:51,716 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
+   2016-05-22 04:12:09,229 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-05-22 04:12:09,230 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-05-22 04:12:09,230 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
    CREATE TABLE pages (
-           id INTEGER NOT NULL,
-           name TEXT NOT NULL,
-           data INTEGER NOT NULL,
-           creator_id INTEGER NOT NULL,
-           CONSTRAINT pk_pages PRIMARY KEY (id),
-           CONSTRAINT uq_pages_name UNIQUE (name),
-           CONSTRAINT fk_pages_creator_id_users FOREIGN KEY(creator_id) REFERENCES users (id)
+       id INTEGER NOT NULL,
+       name TEXT NOT NULL,
+       data TEXT NOT NULL,
+       creator_id INTEGER NOT NULL,
+       CONSTRAINT pk_pages PRIMARY KEY (id),
+       CONSTRAINT uq_pages_name UNIQUE (name),
+       CONSTRAINT fk_pages_creator_id_users FOREIGN KEY(creator_id) REFERENCES users (id)
    )
 
 
-   2016-04-09 02:49:51,716 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-04-09 02:49:51,717 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
-   2016-04-09 02:49:52,256 INFO  [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit)
-   2016-04-09 02:49:52,257 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO users (name, role, password_hash) VALUES (?, ?, ?)
-   2016-04-09 02:49:52,257 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('editor', 'editor', b'$2b$12$APUPJvI/kKxrbQPyQehkR.ggoOM6fFYCZ07SFCkWGltl1wJsKB98y')
-   2016-04-09 02:49:52,258 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO users (name, role, password_hash) VALUES (?, ?, ?)
-   2016-04-09 02:49:52,258 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('basic', 'basic', b'$2b$12$GeFnypuQpZyxZLH.sN0akOrPdZMcQjqVTCim67u6f89lOFH/0ddc6')
-   2016-04-09 02:49:52,259 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO pages (name, data, creator_id) VALUES (?, ?, ?)
-   2016-04-09 02:49:52,259 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('FrontPage', 'This is the front page', 1)
-   2016-04-09 02:49:52,259 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-05-22 04:12:09,231 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-05-22 04:12:09,231 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-05-22 04:12:09,782 INFO  [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit)
+   2016-05-22 04:12:09,783 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO users (name, role, password_hash) VALUES (?, ?, ?)
+   2016-05-22 04:12:09,784 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('editor', 'editor', b'$2b$12$K/WLVKRl5fMAb6UM58ueTetXlE3rlc5cRK5zFPimK598scXBR/xWC')
+   2016-05-22 04:12:09,784 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO users (name, role, password_hash) VALUES (?, ?, ?)
+   2016-05-22 04:12:09,784 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('basic', 'basic', b'$2b$12$JfwLyCJGv3t.RTSmIrh3B.FKXRT9FevkAqafWdK5oq7Hl4mgAQORe')
+   2016-05-22 04:12:09,785 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO pages (name, data, creator_id) VALUES (?, ?, ?)
+   2016-05-22 04:12:09,785 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('FrontPage', 'This is the front page', 1)
+   2016-05-22 04:12:09,786 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
 
 
 View the application in a browser
diff --git a/docs/tutorials/wiki2/distributing.rst b/docs/tutorials/wiki2/distributing.rst
index f264448b0..f38a733f4 100644
--- a/docs/tutorials/wiki2/distributing.rst
+++ b/docs/tutorials/wiki2/distributing.rst
@@ -35,6 +35,6 @@ Note that this command creates a tarball in the "dist" subdirectory named
 ``tutorial-0.0.tar.gz``.  You can send this file to your friends to show them
 your cool new application.  They should be able to install it by pointing the
 ``easy_install`` command directly at it. Or you can upload it to `PyPI
-<http://pypi.python.org>`_ and share it with the rest of the world, where it
-can be downloaded via ``easy_install`` remotely like any other package people
-download from PyPI.
+<https://pypi.python.org/pypi>`_ and share it with the rest of the world, where
+it can be downloaded via ``easy_install`` remotely like any other package
+people download from PyPI.
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index f4676345e..a214b1306 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -97,16 +97,16 @@ Install Pyramid into the virtual Python environment
 On UNIX
 ^^^^^^^
 
-.. code-block:: bash
+.. parsed-literal::
 
-   $ $VENV/bin/pip install pyramid
+   $ $VENV/bin/pip install "pyramid==\ |release|\ "
 
 On Windows
 ^^^^^^^^^^
 
-.. code-block:: doscon
+.. parsed-literal::
 
-   c:\> %VENV%\Scripts\pip install pyramid
+   c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
 
 Install SQLite3 and its development packages
@@ -270,21 +270,23 @@ Run the tests
 -------------
 
 After you've installed the project in development mode as well as the testing
-requirements, you may run the tests for the project.
+requirements, you may run the tests for the project. The following commands
+provide options to py.test that specify the module for which its tests shall be
+run, and to run py.test in quiet mode.
 
 On UNIX
 ^^^^^^^
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test tutorial/tests.py -q
+   $ $VENV/bin/py.test -q
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: doscon
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test -q
 
 For a successful test run, you should see output that ends like this:
 
@@ -310,15 +312,15 @@ On UNIX
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py
+   $ $VENV/bin/py.test --cov --cov-report=term-missing
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: doscon
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
-       --cov-report=term-missing tutorial\tests.py
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov \
+       --cov-report=term-missing
 
 If successful, you will see output something like this:
 
@@ -338,21 +340,53 @@ If successful, you will see output something like this:
    tutorial/models/__init__.py           22      0   100%
    tutorial/models/meta.py                5      0   100%
    tutorial/models/mymodel.py             8      0   100%
-   tutorial/routes.py                     3      3     0%   1-3
+   tutorial/routes.py                     3      2    33%   2-3
    tutorial/scripts/__init__.py           0      0   100%
-   tutorial/scripts/initializedb.py      26     26     0%   1-45
-   tutorial/tests.py                     39      0   100%
+   tutorial/scripts/initializedb.py      26     16    38%   22-25, 29-45
    tutorial/views/__init__.py             0      0   100%
    tutorial/views/default.py             12      0   100%
-   tutorial/views/notfound.py             4      4     0%   1-7
+   tutorial/views/notfound.py             4      2    50%   6-7
    ----------------------------------------------------------------
-   TOTAL                                127     39    69%
-
+   TOTAL                                 88     26    70%
    ===================== 2 passed in 0.57 seconds ======================
 
 Our package doesn't quite have 100% test coverage.
 
 
+.. _test_and_coverage_scaffold_defaults_sql:
+
+Test and coverage scaffold defaults
+-----------------------------------
+
+Scaffolds include configuration defaults for ``py.test`` and test coverage.
+These configuration files are ``pytest.ini`` and ``.coveragerc``, located at
+the root of your package. Without these defaults, we would need to specify the
+path to the module on which we want to run tests and coverage.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov=tutorial tutorial/tests.py -q
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
+       --cov-report=term-missing tutorial\tests.py -q
+
+py.test follows :ref:`conventions for Python test discovery
+<pytest:test discovery>`, and the configuration defaults from the scaffold
+tell ``py.test`` where to find the module on which we want to run tests and
+coverage.
+
+.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke
+   ``py.test -h`` to see its full set of options.
+
+
 .. _initialize_db_wiki2:
 
 Initializing the database
@@ -396,30 +430,30 @@ The output to your console should be something like this:
 
 .. code-block:: bash
 
-   2016-04-09 00:53:37,801 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
-   2016-04-09 00:53:37,801 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
-   2016-04-09 00:53:37,802 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
-   2016-04-09 00:53:37,802 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
-   2016-04-09 00:53:37,802 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("models")
-   2016-04-09 00:53:37,803 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-04-09 00:53:37,803 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
+   2016-05-22 04:03:28,888 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
+   2016-05-22 04:03:28,888 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-05-22 04:03:28,888 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
+   2016-05-22 04:03:28,889 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-05-22 04:03:28,890 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("models")
+   2016-05-22 04:03:28,890 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-05-22 04:03:28,892 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
    CREATE TABLE models (
-           id INTEGER NOT NULL,
-           name TEXT,
-           value INTEGER,
-           CONSTRAINT pk_models PRIMARY KEY (id)
+       id INTEGER NOT NULL,
+       name TEXT,
+       value INTEGER,
+       CONSTRAINT pk_models PRIMARY KEY (id)
    )
 
 
-   2016-04-09 00:53:37,803 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-04-09 00:53:37,804 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
-   2016-04-09 00:53:37,805 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] CREATE UNIQUE INDEX my_index ON models (name)
-   2016-04-09 00:53:37,805 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-04-09 00:53:37,806 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
-   2016-04-09 00:53:37,807 INFO  [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit)
-   2016-04-09 00:53:37,808 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO models (name, value) VALUES (?, ?)
-   2016-04-09 00:53:37,808 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('one', 1)
-   2016-04-09 00:53:37,809 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-05-22 04:03:28,892 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-05-22 04:03:28,893 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-05-22 04:03:28,893 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] CREATE UNIQUE INDEX my_index ON models (name)
+   2016-05-22 04:03:28,893 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-05-22 04:03:28,894 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-05-22 04:03:28,896 INFO  [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit)
+   2016-05-22 04:03:28,897 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO models (name, value) VALUES (?, ?)
+   2016-05-22 04:03:28,897 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('one', 1)
+   2016-05-22 04:03:28,898 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
 
 Success!  You should now have a ``tutorial.sqlite`` file in your current
 working directory. This is an SQLite database with a single table defined in it
@@ -451,7 +485,9 @@ On Windows
    Your OS firewall, if any, may pop up a dialog asking for authorization
    to allow python to accept incoming network connections.
 
-If successful, you will see something like this on your console::
+If successful, you will see something like this on your console:
+
+.. code-block:: text
 
    Starting subprocess with file monitor
    Starting server in PID 82349.
@@ -463,7 +499,7 @@ This means the server is ready to accept requests.
 Visit the application in a browser
 ----------------------------------
 
-In a browser, visit http://localhost:6543/.  You will see the generated
+In a browser, visit http://localhost:6543/. You will see the generated
 application's default page.
 
 One thing you'll notice is the "debug toolbar" icon on right hand side of the
@@ -494,19 +530,7 @@ assumptions:
    :app:`Pyramid` supports any persistent storage mechanism (e.g., object
    database or filesystem files). It also supports an additional mechanism to
    map URLs to code (:term:`traversal`). However, for the purposes of this
-   tutorial, we'll only be using URL dispatch and SQLAlchemy.
-
-.. _pyramid_jinja2:
-   http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/
-
-.. _pyramid_tm:
-   http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/
-
-.. _zope.sqlalchemy:
-   https://pypi.python.org/pypi/zope.sqlalchemy
-
-.. _transaction:
-   http://zodb.readthedocs.org/en/latest/transactions.html
+   tutorial, we'll only be using :term:`URL dispatch` and :term:`SQLAlchemy`.
 
 .. _pyramid_jinja2:
    http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/models/page.py b/docs/tutorials/wiki2/src/authentication/tutorial/models/page.py
index 4dd5b5721..74ff1faf8 100644
--- a/docs/tutorials/wiki2/src/authentication/tutorial/models/page.py
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/models/page.py
@@ -14,7 +14,7 @@ class Page(Base):
     __tablename__ = 'pages'
     id = Column(Integer, primary_key=True)
     name = Column(Text, nullable=False, unique=True)
-    data = Column(Integer, nullable=False)
+    data = Column(Text, nullable=False)
 
     creator_id = Column(ForeignKey('users.id'), nullable=False)
     creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py b/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py
index 6bd3315d6..6fb32a1b2 100644
--- a/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/models/user.py
@@ -23,7 +23,7 @@ class User(Base):
 
     def check_password(self, pw):
         if self.password_hash is not None:
-            expected_hash = self.password_hash
+            expected_hash = self.password_hash.encode('utf8')
             actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
             return expected_hash == actual_hash
         return False
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models/page.py b/docs/tutorials/wiki2/src/authorization/tutorial/models/page.py
index 4dd5b5721..74ff1faf8 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/models/page.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models/page.py
@@ -14,7 +14,7 @@ class Page(Base):
     __tablename__ = 'pages'
     id = Column(Integer, primary_key=True)
     name = Column(Text, nullable=False, unique=True)
-    data = Column(Integer, nullable=False)
+    data = Column(Text, nullable=False)
 
     creator_id = Column(ForeignKey('users.id'), nullable=False)
     creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py b/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py
index 6bd3315d6..6fb32a1b2 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models/user.py
@@ -23,7 +23,7 @@ class User(Base):
 
     def check_password(self, pw):
         if self.password_hash is not None:
-            expected_hash = self.password_hash
+            expected_hash = self.password_hash.encode('utf8')
             actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
             return expected_hash == actual_hash
         return False
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/page.py b/docs/tutorials/wiki2/src/models/tutorial/models/page.py
index 4dd5b5721..74ff1faf8 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/models/page.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/page.py
@@ -14,7 +14,7 @@ class Page(Base):
     __tablename__ = 'pages'
     id = Column(Integer, primary_key=True)
     name = Column(Text, nullable=False, unique=True)
-    data = Column(Integer, nullable=False)
+    data = Column(Text, nullable=False)
 
     creator_id = Column(ForeignKey('users.id'), nullable=False)
     creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/user.py b/docs/tutorials/wiki2/src/models/tutorial/models/user.py
index 6bd3315d6..6fb32a1b2 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/user.py
@@ -23,7 +23,7 @@ class User(Base):
 
     def check_password(self, pw):
         if self.password_hash is not None:
-            expected_hash = self.password_hash
+            expected_hash = self.password_hash.encode('utf8')
             actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
             return expected_hash == actual_hash
         return False
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models/page.py b/docs/tutorials/wiki2/src/tests/tutorial/models/page.py
index 4dd5b5721..74ff1faf8 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/models/page.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models/page.py
@@ -14,7 +14,7 @@ class Page(Base):
     __tablename__ = 'pages'
     id = Column(Integer, primary_key=True)
     name = Column(Text, nullable=False, unique=True)
-    data = Column(Integer, nullable=False)
+    data = Column(Text, nullable=False)
 
     creator_id = Column(ForeignKey('users.id'), nullable=False)
     creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models/user.py b/docs/tutorials/wiki2/src/tests/tutorial/models/user.py
index 6bd3315d6..6fb32a1b2 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models/user.py
@@ -23,7 +23,7 @@ class User(Base):
 
     def check_password(self, pw):
         if self.password_hash is not None:
-            expected_hash = self.password_hash
+            expected_hash = self.password_hash.encode('utf8')
             actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
             return expected_hash == actual_hash
         return False
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models/page.py b/docs/tutorials/wiki2/src/views/tutorial/models/page.py
index 4dd5b5721..74ff1faf8 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/models/page.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/models/page.py
@@ -14,7 +14,7 @@ class Page(Base):
     __tablename__ = 'pages'
     id = Column(Integer, primary_key=True)
     name = Column(Text, nullable=False, unique=True)
-    data = Column(Integer, nullable=False)
+    data = Column(Text, nullable=False)
 
     creator_id = Column(ForeignKey('users.id'), nullable=False)
     creator = relationship('User', backref='created_pages')
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models/user.py b/docs/tutorials/wiki2/src/views/tutorial/models/user.py
index 6bd3315d6..6fb32a1b2 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/models/user.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/models/user.py
@@ -23,7 +23,7 @@ class User(Base):
 
     def check_password(self, pw):
         if self.password_hash is not None:
-            expected_hash = self.password_hash
+            expected_hash = self.password_hash.encode('utf8')
             actual_hash = bcrypt.hashpw(pw.encode('utf8'), expected_hash)
             return expected_hash == actual_hash
         return False