Merge branch 'master' into viewderiver

1 files changed, 93 insertions, 80 deletions

diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst
index f317d31dd..f201f6dc7 100644
--- a/docs/tutorials/wiki/definingmodels.rst
+++ b/docs/tutorials/wiki/definingmodels.rst
@@ -20,71 +20,67 @@ The source code for this tutorial stage can be browsed via
 Deleting the Database
 ---------------------
 
-We're going to remove the ``MyModel`` Python model class from our
-``models.py`` file.  Since this class is referred to within our
-persistent storage (represented on disk as a file named ``Data.fs``),
+In a subsequent step, we're going to remove the ``MyModel`` Python model
+class from our ``models.py`` file.  Since this class is referred to within
+our persistent storage (represented on disk as a file named ``Data.fs``),
 we'll have strange things happen the next time we want to visit the
-application in a browser.  Remove the ``Data.fs`` from the
-``tutorial`` directory before proceeding any further.  It's always
-fine to do this as long as you don't care about the content of the
-database; the database itself will be recreated as necessary.
+application in a browser.  Remove the ``Data.fs`` from the ``tutorial``
+directory before proceeding any further.  It's always fine to do this as long
+as you don't care about the content of the database; the database itself will
+be recreated as necessary.
 
 Adding Model Classes
 --------------------
 
 The next thing we want to do is remove the ``MyModel`` class from the
-generated ``models.py`` file.  The ``MyModel`` class is only a sample
-and we're not going to use it.
+generated ``models.py`` file.  The ``MyModel`` class is only a sample and
+we're not going to use it.
 
 .. note::
 
-  There is nothing automagically special about the filename
-  ``models.py``.  A project may have many models throughout its
-  codebase in arbitrarily-named files.  Files implementing models
-  often have ``model`` in their filenames (or they may live in a
-  Python subpackage of your application package named ``models``) ,
-  but this is only by convention.
-
-Then, we'll add a ``Wiki`` class.  Because this is a ZODB application,
-this class should inherit from
-:class:`persistent.mapping.PersistentMapping`.  We want it to inherit
-from the :class:`persistent.mapping.PersistentMapping` class because
-our Wiki class will be a mapping of wiki page names to ``Page``
-objects.  The :class:`persistent.mapping.PersistentMapping` class
-provides our class with mapping behavior, and makes sure that our Wiki
-page is stored as a "first-class" persistent object in our ZODB
-database.
-
-Our ``Wiki`` class should also have a ``__name__`` attribute set to
-``None`` at class scope, and should have a ``__parent__`` attribute
-set to ``None`` at class scope as well.  If a model has a
-``__parent__`` attribute of ``None`` in a traversal-based
-:app:`Pyramid` application, it means that it's the :term:`root`
-model.  The ``__name__`` of the root model is also always ``None``.
+  There is nothing automagically special about the filename ``models.py``.  A
+  project may have many models throughout its codebase in arbitrarily-named
+  files.  Files implementing models often have ``model`` in their filenames,
+  or they may live in a Python subpackage of your application package named
+  ``models``, but this is only by convention.
+
+Then, we'll add a ``Wiki`` class.  Because this is a ZODB application, this
+class should inherit from :class:`persistent.mapping.PersistentMapping`.  We
+want it to inherit from the :class:`persistent.mapping.PersistentMapping`
+class because our Wiki class will be a mapping of wiki page names to ``Page``
+objects.  The :class:`persistent.mapping.PersistentMapping` class provides
+our class with mapping behavior, and makes sure that our Wiki page is stored
+as a "first-class" persistent object in our ZODB database.
+
+Our ``Wiki`` class should also have a ``__name__`` attribute set to ``None``
+at class scope, and should have a ``__parent__`` attribute set to ``None`` at
+class scope as well.  If a model has a ``__parent__`` attribute of ``None``
+in a traversal-based :app:`Pyramid` application, it means that it's the
+:term:`root` model.  The ``__name__`` of the root model is also always
+``None``.
 
 Then we'll add a ``Page`` class.  This class should inherit from the
-:class:`persistent.Persistent` class.  We'll also give it an
-``__init__`` method that accepts a single parameter named ``data``.
-This parameter will contain the :term:`ReStructuredText` body
-representing the wiki page content.  Note that ``Page`` objects don't
-have an initial ``__name__`` or ``__parent__`` attribute.  All objects
-in a traversal graph must have a ``__name__`` and a ``__parent__``
-attribute.  We don't specify these here because both ``__name__`` and
-``__parent__`` will be set by by a :term:`view` function when a Page
-is added to our Wiki mapping.
-
-Add an Appmaker
----------------
-
-We're using a mini-framework callable named
-``PersistentApplicationFinder`` in our application (see ``__init__.py``).
-A ``PersistentApplicationFinder`` accepts a ZODB URL as well as an
-"appmaker" callback.  This callback typically lives in the
-``models.py`` file.
-
-We want to change the appmaker function in our ``models.py`` file so
-that our application root is a Wiki instance, and we'll also slot a
-single page object (the front page) into the wiki.
+:class:`persistent.Persistent` class.  We'll also give it an ``__init__``
+method that accepts a single parameter named ``data``.  This parameter will
+contain the :term:`ReStructuredText` body representing the wiki page content.
+Note that ``Page`` objects don't have an initial ``__name__`` or
+``__parent__`` attribute.  All objects in a traversal graph must have a
+``__name__`` and a ``__parent__`` attribute.  We don't specify these here
+because both ``__name__`` and ``__parent__`` will be set by by a :term:`view`
+function when a Page is added to our Wiki mapping.
+
+As a last step, we want to change the ``appmaker`` function in our
+``models.py`` file so that the :term:`root` :term:`resource` of our
+application is a Wiki instance.  We'll also slot a single page object (the
+front page) into the Wiki within the ``appmaker``.  This will provide
+:term:`traversal` a :term:`resource tree` to work against when it attempts to
+resolve URLs to resources.
+
+We're using a mini-framework callable named ``PersistentApplicationFinder``
+in our application (see ``__init__.py``).  A ``PersistentApplicationFinder``
+accepts a ZODB URL as well as an "appmaker" callback.  This callback
+typically lives in the ``models.py`` file.  We'll just change this function,
+making the necessary edits.
 
 Looking at the Result of Our Edits to ``models.py``
 ---------------------------------------------------
@@ -96,19 +92,37 @@ something like this:
    :linenos:
    :language: python
 
+Removing View Configuration
+---------------------------
+
+In a previous step in this chapter, we removed the
+``tutorial.models.MyModel`` class.  However, our ``views.py`` module still
+attempts to import this class.  Temporarily, we'll change ``views.py`` so
+that it no longer references ``MyModel`` by removing its imports and removing
+a reference to it from the arguments passed to the ``@view_config``
+:term:`configuration decoration` decorator which sits atop the ``my_view``
+view callable.
+
+The result of all of our edits to ``views.py`` will end up looking
+something like this:
+
+.. literalinclude:: src/models/tutorial/views.py
+   :linenos:
+   :language: python
+
 Testing the Models
 ------------------
 
-To make sure the code we just wrote works, we write tests for the
-model classes and the appmaker.  Changing ``tests.py``, we'll write a
-separate test class for each model class, and we'll write a test class
-for the ``appmaker``.
+To make sure the code we just wrote works, we write tests for the model
+classes and the appmaker.  Changing ``tests.py``, we'll write a separate test
+class for each model class, and we'll write a test class for the
+``appmaker``.
 
-To do so, we'll retain the ``tutorial.tests.ViewTests`` class provided
-as a result of the ``pyramid_zodb`` project generator.  We'll add
-three test classes: one for the ``Page`` model named
-``PageModelTests``, one for the ``Wiki`` model named
-``WikiModelTests``, and one for the appmaker named ``AppmakerTests``.
+To do so, we'll retain the ``tutorial.tests.ViewTests`` class provided as a
+result of the ``pyramid_zodb`` project generator.  We'll add three test
+classes: one for the ``Page`` model named ``PageModelTests``, one for the
+``Wiki`` model named ``WikiModelTests``, and one for the appmaker named
+``AppmakerTests``.
 
 When we're done changing ``tests.py``, it will look something like so:
 
@@ -116,6 +130,22 @@ When we're done changing ``tests.py``, it will look something like so:
    :linenos:
    :language: python
 
+Declaring Dependencies in Our ``setup.py`` File
+-----------------------------------------------
+
+Our application now depends on packages which are not dependencies of the
+original "tutorial" application as it was generated by the ``paster create``
+command.  We'll add these dependencies to our ``tutorial`` package's
+``setup.py`` file by assigning these dependencies to both the
+``install_requires`` and the ``tests_require`` parameters to the ``setup``
+function.  In particular, we require the ``docutils`` package.
+
+Our resulting ``setup.py`` should look like so:
+
+.. literalinclude:: src/models/setup.py
+   :linenos:
+   :language: python
+
 Running the Tests
 -----------------
 
@@ -145,20 +175,3 @@ The expected output is something like this:
 
   OK
 
-Declaring Dependencies in Our ``setup.py`` File
------------------------------------------------
-
-Our application depends on packages which are not dependencies of the
-original "tutorial" application as it was generated by the ``paster
-create`` command.  We'll add these dependencies to our ``tutorial``
-package's ``setup.py`` file by assigning these dependencies to both
-the ``install_requires`` and the ``tests_require`` parameters to the
-``setup`` function.  In particular, we require the ``docutils``
-package.
-
-Our resulting ``setup.py`` should look like so:
-
-.. literalinclude:: src/models/setup.py
-   :linenos:
-   :language: python
-