Merge remote-tracking branch 'upstream/master' into shentonfreude/bug.sqltut-test-populate-settings

12 files changed, 323 insertions, 35 deletions

diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst
index cdf3b6092..982d6ea74 100644
--- a/docs/tutorials/wiki/definingmodels.rst
+++ b/docs/tutorials/wiki/definingmodels.rst
@@ -88,7 +88,8 @@ View the Application in a Browser
 
 We can't.  At this point, our system is in a "non-runnable" state; we'll need
 to change view-related files in the next chapter to be able to start the
-application successfully.  If you try to start the application, you'll wind
+application successfully.  If you try to start the application (See
+:ref:`wiki-start-the-application`), you'll wind
 up with a Python traceback on your console that ends with this exception:
 
 .. code-block:: text
diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index 371cae8eb..53e60fda3 100644
--- a/docs/tutorials/wiki/definingviews.rst
+++ b/docs/tutorials/wiki/definingviews.rst
@@ -301,8 +301,8 @@ subdirectories) and are just referred to by URL.
 Viewing the Application in a Browser
 ====================================
 
-We can finally examine our application in a
-browser.  The views we'll try are as follows:
+We can finally examine our application in a browser (See
+:ref:`wiki-start-the-application`).  The views we'll try are as follows:
 
 - Visiting ``http://localhost:6543/`` in a browser invokes the ``view_wiki``
   view.  This always redirects to the ``view_page`` view of the ``FrontPage``
diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst
new file mode 100644
index 000000000..ea7076f60
--- /dev/null
+++ b/docs/tutorials/wiki/design.rst
@@ -0,0 +1,134 @@
+==========
+Design
+==========
+
+Following is a quick overview of our wiki application, to help
+us understand the changes that we will be doing next in our
+default files generated by the paster scafffold.
+
+Overall
+-------
+
+We choose to use ``reStructuredText`` markup in the wiki text.
+Translation from reStructuredText to HTML is provided by the
+widely used docutils Python module.  We will add this module
+in the dependency list on the project ``setup.py`` file.
+
+Models
+------
+
+The root resource, named *Wiki*, will be a mapping of wiki page
+names to page resources.  The page resources will be instances
+of a *Page* class and they store the text content.
+
+URLs like ``/PageName`` will be traversed using  Wiki[
+*PageName* ] => page, and the context that results is the page
+resource of an existing page.
+
+To add a page to the wiki, a new instance of the page resource
+is created and its name and reference are added to the Wiki
+mapping.
+
+A page named *FrontPage* containing the text *This is the front
+page*, will be created when the storage is initialized, and will
+be used as the wiki home page.
+
+Views
+-----
+
+There will be four views to handle the normal operations of
+viewing, editing and adding wiki pages.  Two additional views
+will handle the login and logout tasks related to security.
+
+Security
+--------
+
+- USERS, a dictionary mapping users names to their
+  corresponding passwords.
+- GROUPS, a dictionary mapping user names to a 
+  list of groups they belong to.
+- *groupfinder*, an *authorization callback* that looks up
+  USERS and GROUPS.  It will be provided in a new
+  *security.py* file.
+- An :term:`ACL` is attached to the root resource.  Each
+  row below details an :term:`ACE`:
+
+  +----------+----------------+----------------+
+  | Action   | Principal      | Permission     |
+  +==========+================+================+
+  | Allow    | Everyone       | View           |
+  +----------+----------------+----------------+
+  | Allow    | group:editors  | Edit           |
+  +----------+----------------+----------------+
+
+- Permission declarations for the views.
+
+
+Summary
+-------
+
+The URL, context, actions, template and permission associated to each view are
+listed in the following table:
+
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| URL                  |  View       |  Context        |  Action               |  Template  | Permission |
+|                      |             |                 |                       |            |            |
++======================+=============+=================+=======================+============+============+
+| /                    |  view_wiki  |  Wiki           |  Redirect to          |            |            |
+|                      |             |                 |  /FrontPage           |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /PageName            |  view_page  |  Page           |  Display existing     |  view.pt   |  view      |
+|                      |  [1]_       |                 |  page [2]_            |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |                       |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /PageName/edit_page  |  edit_page  |  Page           |  Display edit form    |  edit.pt   |  edit      |
+|                      |             |                 |  with existing        |            |            |
+|                      |             |                 |  content.             |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted, redirect  |            |            |
+|                      |             |                 |  to /PageName         |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /add_page/PageName   |  add_page   |  Wiki           |  Create the page      |  edit.pt   |  edit      |
+|                      |             |                 |  *PageName* in        |            |            |
+|                      |             |                 |  storage,  display    |            |            |
+|                      |             |                 |  the edit form        |            |            |
+|                      |             |                 |  without content.     |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted,           |            |            |
+|                      |             |                 |  redirect to          |            |            |
+|                      |             |                 |  /PageName            |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /login               |  login      |  Wiki,          |  Display login form.  |  login.pt  |            |
+|                      |             |  Forbidden [3]_ |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted,           |            |            |
+|                      |             |                 |  authenticate.        |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  - If authentication  |            |            |
+|                      |             |                 |    successful,        |            |            |
+|                      |             |                 |    redirect to the    |            |            |
+|                      |             |                 |    page that we       |            |            |
+|                      |             |                 |    came from.         |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  - If authentication  |            |            |
+|                      |             |                 |    fails, display     |            |            |
+|                      |             |                 |    login form with    |            |            |
+|                      |             |                 |    "login failed"     |            |            |
+|                      |             |                 |    message.           |            |            |
+|                      |             |                 |                       |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /logout              |  logout     |  Wiki           |  Redirect to          |            |            |
+|                      |             |                 |  /FrontPage           |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+
+.. [1] This is the default view for a Page context
+       when there is no view name.
+.. [2] Pyramid will return a default 404 Not Found page
+       if the page *PageName* does not exist yet.
+.. [3] pyramid.exceptions.Forbidden is reached when a
+       user tries to invoke a view that is
+       not authorized by the authorization policy.
diff --git a/docs/tutorials/wiki/index.rst b/docs/tutorials/wiki/index.rst
index 3edc6ba04..f07f45bd0 100644
--- a/docs/tutorials/wiki/index.rst
+++ b/docs/tutorials/wiki/index.rst
@@ -18,6 +18,7 @@ tutorial can be browsed at
    :maxdepth: 2
 
    background
+   design
    installation
    basiclayout
    definingmodels
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index 330b17c86..63b30da5a 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -228,6 +228,8 @@ Looks like the code in the ``zodb`` scaffold for ZODB projects is
 missing some test coverage, particularly in the file named
 ``models.py``.
 
+.. _wiki-start-the-application:
+
 Start the Application
 =====================
 
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 900bf0975..5c60640b7 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -189,7 +189,13 @@ visit ``/login``.
 We'll need to import some stuff to service the needs of these two functions:
 the ``pyramid.view.forbidden_view_config`` class, a number of values from the
 ``pyramid.security`` module, and a value from our newly added
-``tutorial.security`` package.
+``tutorial.security`` package.  Add the following import statements to the
+head of the ``views.py`` file:
+
+.. literalinclude:: src/authorization/tutorial/views.py
+   :lines: 9-18,24-25
+   :linenos:
+   :language: python
 
 Changing Existing Views
 -----------------------
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index e4200ae0f..0fca0edf9 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -16,8 +16,10 @@ Application Configuration with ``__init__.py``
 A directory on disk can be turned into a Python :term:`package` by containing
 an ``__init__.py`` file.  Even if empty, this marks a directory as a Python
 package.  We use ``__init__.py`` both as a marker indicating the directory
-it's contained within is a package, and to contain configuration code.  Our
-``__init__.py`` file will look like this:
+it's contained within is a package, and to contain configuration code.
+
+Open ``tutorial/tutorial/__init__.py``.  It should already contain
+the following:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :linenos:
@@ -41,9 +43,7 @@ the ``main`` function we've defined in our ``__init__.py``:
 
 When you invoke the ``pserve development.ini`` command, the ``main`` function
 above is executed.  It accepts some settings and returns a :term:`WSGI`
-application.  You can read :ref:`startup_chapter` for details about *how*
-this function is found and called when you run ``pserve``, but for purposes
-of brevity, we'll elide the details here.
+application.  (See :ref:`startup_chapter` for more about ``pserve``.)
 
 The main function first creates a SQLAlchemy database engine using
 ``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the
@@ -128,30 +128,27 @@ pattern matches is done by registering a :term:`view configuration`. Our
 application uses the :meth:`pyramid.view.view_config` decorator to map view
 callables to each route, thereby mapping URL patterns to code.
 
-Here is the entirety of code in the ``views.py`` file within our package:
+Open ``tutorial/tutorial/views.py``.  It should already contain the following:
 
    .. literalinclude:: src/basiclayout/tutorial/views.py
       :linenos:
       :language: py
 
-The important part to point out here is the ``@view_config`` decorator which
-sits atop the ``my_view`` function.  In fact, ``@view_config`` is so
-important that we're going to ignore the rest of the code in the module at
-this point just to explain it.  The ``@view_config`` decorator associates the
-function it decorates with a :term:`view configuration`. The view
-configuration names a ``route_name`` (``home``), and names a ``renderer``,
-which is a template which lives in the ``templates`` subdirectory of the
-package.
+The important part here is that the ``@view_config`` decorator associates the
+function it decorates (``my_view``) with a :term:`view configuration`, 
+consisting of:
+
+   * a ``route_name`` (``home``)
+   * a ``renderer``, which is a template from the ``templates`` subdirectory 
+     of the package.
 
-As the result of this view configuration, when the pattern associated with
-the view named ``home`` is matched during a request, the function named
-``my_view`` will be executed.  The function named ``my_view`` returns a
-dictionary; the renderer will use the ``templates/mytemplate.pt`` template to
-create a response based on the values in the dictionary.
+When the pattern associated with the ``home`` view is matched during a request,
+``my_view()`` will be executed.  ``my_view()`` returns a dictionary; the 
+renderer will use the ``templates/mytemplate.pt`` template to create a response
+based on the values in the dictionary.
 
-Note that the decorated function named ``my_view`` accepts a single argument
-named ``request``.  This is the standard call signature for a Pyramid
-:term:`view callable`.
+Note that ``my_view()`` accepts a single argument named ``request``.  This is
+the standard call signature for a Pyramid :term:`view callable`.
 
 Remember in our ``__init__.py`` when we executed the
 :meth:`pyramid.config.Configurator.scan` method, e.g. ``config.scan()``?  The
@@ -168,13 +165,13 @@ In a SQLAlchemy-based application, a *model* object is an object composed by
 querying the SQL database. The ``models.py`` file is where the ``alchemy``
 scaffold put the classes that implement our models.
 
-Here is the complete source for ``models.py``:
+Open ``tutorial/tutorial/models.py``.  It should already contain the following:
 
    .. literalinclude:: src/basiclayout/tutorial/models.py
       :linenos:
       :language: py
 
-Let's take a look. First, we need some imports to support later code.
+Let's examine this in detail. First, we need some imports to support later code:
 
    .. literalinclude:: src/basiclayout/tutorial/models.py
       :end-before: DBSession
diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 2b8932a98..0810ad1c5 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -21,11 +21,15 @@ Making Edits to ``models.py``
   (or they may live in a Python subpackage of your application package named
   ``models``) , but this is only by convention.
 
-Here's what our ``models.py`` file should look like after this step:
+Open ``tutorial/tutorial/models.py`` file and edit it to look like the 
+following:
 
 .. literalinclude:: src/models/tutorial/models.py
    :linenos:
    :language: py
+   :emphasize-lines: 19-21,24,26,28
+
+(The highlighted lines are the ones that need to be changed.)
 
 The first thing we've done is to do is remove the stock ``MyModel`` class
 from the generated ``models.py`` file.  The ``MyModel`` class is only a
@@ -63,12 +67,15 @@ script.  In particular, we'll replace our import of ``MyModel`` with one of
 ``Page`` and we'll change the very end of the script to create a ``Page``
 rather than a ``MyModel`` and add it to our ``DBSession``.
 
-The result of all of our edits to ``populate.py`` will end up looking
-something like this:
+Open ``tutorial/tutorial/scripts/populate.py`` and edit it to look like the 
+following:
 
 .. literalinclude:: src/models/tutorial/scripts/populate.py
    :linenos:
    :language: python
+   :emphasize-lines: 14,34
+
+(Only the highlighted lines need to be changed.)
 
 Repopulating the Database
 -------------------------
@@ -122,7 +129,8 @@ Viewing the Application in a Browser
 
 We can't.  At this point, our system is in a "non-runnable" state; we'll need
 to change view-related files in the next chapter to be able to start the
-application successfully.  If you try to start the application, you'll wind
+application successfully.  If you try to start the application (See
+:ref:`wiki2-start-the-application`), you'll wind
 up with a Python traceback on your console that ends with this exception:
 
 .. code-block:: text
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index a067dbd66..5f7526b24 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -28,15 +28,18 @@ 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.  We need to add a dependency on
 the ``docutils`` package to our ``tutorial`` package's ``setup.py`` file by
-assigning this dependency to the ``install_requires`` parameter in the
+assigning this dependency to the ``requires`` parameter in the
 ``setup`` function.
 
-Our resulting ``setup.py`` should look like so:
+Open ``tutorial/setup.py`` and edit it to look like the following:
 
 .. literalinclude:: src/views/setup.py
    :linenos:
+   :emphasize-lines: 17
    :language: python
 
+(Only the highlighted line needs to be added)
+
 Running ``setup.py develop``
 ============================
 
@@ -323,7 +326,8 @@ something like so:
 Viewing the Application in a Browser
 ====================================
 
-We can finally examine our application in a browser.  The views we'll try are
+We can finally examine our application in a browser (See
+:ref:`wiki2-start-the-application`).  The views we'll try are
 as follows:
 
 - Visiting ``http://localhost:6543`` in a browser invokes the
diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst
new file mode 100644
index 000000000..ade40ab18
--- /dev/null
+++ b/docs/tutorials/wiki2/design.rst
@@ -0,0 +1,132 @@
+==========
+Design
+==========
+
+Following is a quick overview of our wiki application, to help
+us understand the changes that we will be doing next in our
+default files generated by the paster scafffold.
+
+Overall
+-------
+
+We choose to use ``reStructuredText`` markup in the wiki text.
+Translation from reStructuredText to HTML is provided by the
+widely used docutils Python module.  We will add this module
+in the dependency list on the project ``setup.py`` file.
+
+Models
+------
+
+We define a single table named `tables`, whose elements will
+store the wiki pages.  There are two columns: `name` and 
+`data`.
+
+URLs like ``/PageName`` will try to find an element in 
+the table whose `name` corresponds.
+
+To add a page to the wiki, a new row is created and the text
+is stored in `data`.
+
+A page named *FrontPage* containing the text *This is the front
+page*, will be created when the storage is initialized, and will
+be used as the wiki home page.
+
+Views
+-----
+
+There will be four views to handle the normal operations of
+viewing, editing and adding wiki pages.  Two additional views
+will handle the login and logout tasks related to security.
+
+Security
+--------
+
+- USERS, a dictionary mapping users names to their
+  corresponding passwords.
+- GROUPS, a dictionary mapping user names to a 
+  list of groups they belong to.
+- *groupfinder*, an *authorization callback* that looks up
+  USERS and GROUPS.  It will be provided in a new
+  *security.py* file.
+- An :term:`ACL` is attached to the root resource.  Each
+  row below details an :term:`ACE`:
+
+  +----------+----------------+----------------+
+  | Action   | Principal      | Permission     |
+  +==========+================+================+
+  | Allow    | Everyone       | View           |
+  +----------+----------------+----------------+
+  | Allow    | group:editors  | Edit           |
+  +----------+----------------+----------------+
+
+- Permission declarations for the views.
+
+
+Summary
+-------
+
+The URL, context, actions, template and permission associated to each view are
+listed in the following table:
+
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| URL                  |  View       |  Context        |  Action               |  Template  | Permission |
+|                      |             |                 |                       |            |            |
++======================+=============+=================+=======================+============+============+
+| /                    |  view_wiki  |  Wiki           |  Redirect to          |            |            |
+|                      |             |                 |  /FrontPage           |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /PageName            |  view_page  |  Page           |  Display existing     |  view.pt   |  view      |
+|                      |  [1]_       |                 |  page [2]_            |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |                       |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /edit_page/PageName  |  edit_page  |  Page           |  Display edit form    |  edit.pt   |  edit      |
+|                      |             |                 |  with existing        |            |            |
+|                      |             |                 |  content.             |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted, redirect  |            |            |
+|                      |             |                 |  to /PageName         |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /add_page/PageName   |  add_page   |  Wiki           |  Create the page      |  edit.pt   |  edit      |
+|                      |             |                 |  *PageName* in        |            |            |
+|                      |             |                 |  storage,  display    |            |            |
+|                      |             |                 |  the edit form        |            |            |
+|                      |             |                 |  without content.     |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted,           |            |            |
+|                      |             |                 |  redirect to          |            |            |
+|                      |             |                 |  /PageName            |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /login               |  login      |  Wiki,          |  Display login form.  |  login.pt  |            |
+|                      |             |  Forbidden [3]_ |                       |            |            |
+|                      |             |                 |  If the form was      |            |            |
+|                      |             |                 |  submitted,           |            |            |
+|                      |             |                 |  authenticate.        |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  - If authentication  |            |            |
+|                      |             |                 |    successful,        |            |            |
+|                      |             |                 |    redirect to the    |            |            |
+|                      |             |                 |    page that we       |            |            |
+|                      |             |                 |    came from.         |            |            |
+|                      |             |                 |                       |            |            |
+|                      |             |                 |  - If authentication  |            |            |
+|                      |             |                 |    fails, display     |            |            |
+|                      |             |                 |    login form with    |            |            |
+|                      |             |                 |    "login failed"     |            |            |
+|                      |             |                 |    message.           |            |            |
+|                      |             |                 |                       |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+| /logout              |  logout     |  Wiki           |  Redirect to          |            |            |
+|                      |             |                 |  /FrontPage           |            |            |
++----------------------+-------------+-----------------+-----------------------+------------+------------+
+
+.. [1] This is the default view for a Page context
+       when there is no view name.
+.. [2] Pyramid will return a default 404 Not Found page
+       if the page *PageName* does not exist yet.
+.. [3] pyramid.exceptions.Forbidden is reached when a
+       user tries to invoke a view that is
+       not authorized by the authorization policy.
diff --git a/docs/tutorials/wiki2/index.rst b/docs/tutorials/wiki2/index.rst
index d05d70f3c..3a165291a 100644
--- a/docs/tutorials/wiki2/index.rst
+++ b/docs/tutorials/wiki2/index.rst
@@ -18,6 +18,7 @@ tutorial can be browsed at
    :maxdepth: 2
 
    background
+   design
    installation
    basiclayout
    definingmodels
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index be97f1cb3..e5d2a0b5b 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -215,6 +215,8 @@ If successful, you will see output something like this::
 
 Looks like our package doesn't quite have 100% test coverage.
 
+.. _wiki2-start-the-application:
+
 Starting the Application
 ========================