the starter scaffold now uses url dispatch; add a minimal section about using another WSGI server; random docs fixes

17 files changed, 83 insertions, 131 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 41c608af5..66761bff7 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -92,7 +92,7 @@ Backwards Incompatibilities
 Dependencies
 ------------
 
-- Pyramid no longer depends on the zope.component package, except as a
+- Pyramid no longer depends on the ``zope.component`` package, except as a
   testing dependency.
 
 - Pyramid now depends on a zope.interface>=3.8.0, WebOb>=1.2dev,
@@ -115,6 +115,10 @@ Documentation
   ``pyramid.config.Configurator.action`` method within custom directives.  It
   also describes how to add introspectable objects.
 
+- A narrative documentation chapter named "Pyramid Configuration
+  Introspection" was added.  It describes how to query the introspection
+  system.
+
 Scaffolds
 ---------
 
@@ -124,3 +128,5 @@ Scaffolds
 - The ``routesalchemy`` scaffold has been renamed ``alchemy``, replacing the
   older (traversal-based) ``alchemy`` scaffold (which has been retired).
 
+- The ``starter`` scaffold now uses URL dispatch by default.
+
diff --git a/TODO.txt b/TODO.txt
index db7a01a14..b7ea305c6 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -4,8 +4,6 @@ Pyramid TODOs
 Must-Have
 ---------
 
-- Change starter scaffold to use URL dispatch?
-
 - Introspection:
 
   * Review narrative docs.
diff --git a/docs/narr/MyProject/README.txt b/docs/narr/MyProject/README.txt
index 5e10949fc..c28d0d94a 100644
--- a/docs/narr/MyProject/README.txt
+++ b/docs/narr/MyProject/README.txt
@@ -1,4 +1 @@
 MyProject README
-
-
-
diff --git a/docs/narr/MyProject/development.ini b/docs/narr/MyProject/development.ini
index 3a4758c44..d61da580f 100644
--- a/docs/narr/MyProject/development.ini
+++ b/docs/narr/MyProject/development.ini
@@ -41,6 +41,6 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s
+format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
 
 # End logging configuration
diff --git a/docs/narr/MyProject/myproject/__init__.py b/docs/narr/MyProject/myproject/__init__.py
index ddcdd7162..31b02cf02 100644
--- a/docs/narr/MyProject/myproject/__init__.py
+++ b/docs/narr/MyProject/myproject/__init__.py
@@ -1,10 +1,10 @@
 from pyramid.config import Configurator
-from .resources import Root
 
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
-    config = Configurator(root_factory=Root, settings=settings)
+    config = Configurator(settings=settings)
     config.add_static_view('static', 'static', cache_max_age=3600)
+    config.add_route('home', '/')
     config.scan()
     return config.make_wsgi_app()
diff --git a/docs/narr/MyProject/myproject/resources.py b/docs/narr/MyProject/myproject/resources.py
deleted file mode 100644
index 3d811895c..000000000
--- a/docs/narr/MyProject/myproject/resources.py
+++ /dev/null
@@ -1,3 +0,0 @@
-class Root(object):
-    def __init__(self, request):
-        self.request = request
diff --git a/docs/narr/MyProject/myproject/static/pyramid-small.png b/docs/narr/MyProject/myproject/static/pyramid-small.png
new file mode 100644
index 000000000..a5bc0ade7
--- /dev/null
+++ b/docs/narr/MyProject/myproject/static/pyramid-small.png
diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py
index a32165471..d8b764041 100644
--- a/docs/narr/MyProject/myproject/tests.py
+++ b/docs/narr/MyProject/myproject/tests.py
@@ -14,5 +14,3 @@ class ViewTests(unittest.TestCase):
         request = testing.DummyRequest()
         info = my_view(request)
         self.assertEqual(info['project'], 'MyProject')
-
-
diff --git a/docs/narr/MyProject/myproject/views.py b/docs/narr/MyProject/myproject/views.py
index 5b5d230f2..f571a5976 100644
--- a/docs/narr/MyProject/myproject/views.py
+++ b/docs/narr/MyProject/myproject/views.py
@@ -1,6 +1,5 @@
 from pyramid.view import view_config
-from .resources import Root
 
-@view_config(context=Root, renderer='templates/mytemplate.pt')
+@view_config(route_name='home', renderer='templates/mytemplate.pt')
 def my_view(request):
     return {'project':'MyProject'}
diff --git a/docs/narr/MyProject/production.ini b/docs/narr/MyProject/production.ini
index 9d025715d..97050e8fe 100644
--- a/docs/narr/MyProject/production.ini
+++ b/docs/narr/MyProject/production.ini
@@ -25,11 +25,11 @@ keys = console
 keys = generic
 
 [logger_root]
-level = INFO
+level = WARN
 handlers = console
 
 [logger_myproject]
-level = INFO
+level = WARN
 handlers =
 qualname = myproject
 
diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst
index 856654377..a57c78105 100644
--- a/docs/narr/extconfig.rst
+++ b/docs/narr/extconfig.rst
@@ -226,8 +226,8 @@ augment Pyramid's configuration introspection system.
 
 .. _introspection:
 
-Configuration Introspection
----------------------------
+Adding Configuration Introspection
+----------------------------------
 
 .. warning::
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 4c528ab58..478e92b7e 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -46,24 +46,17 @@ each other on a number of axes:
 The included scaffolds are these:
 
 ``starter``
-  URL mapping via :term:`traversal` and no persistence mechanism.
+  URL mapping via :term:`URL dispatch` and no persistence mechanism.
 
 ``zodb``
-  URL mapping via :term:`traversal` and persistence via :term:`ZODB`.
+  URL mapping via :term:`traversal` and persistence via :term:`ZODB`.  *Note
+  that, as of this writing, this scaffold will not run under Python 3, only
+  under Python 2.*
 
 ``alchemy``
   URL mapping via :term:`URL dispatch` and persistence via
   :term:`SQLAlchemy`
 
-.. note::
-
-   Rather than use any of the above scaffolds, Pylons 1 users may feel more
-   comfortable installing the :term:`Akhet` development environment, which
-   provides a scaffold named ``akhet``.  This scaffold configures a Pyramid
-   application in a "Pylons-esque" way, including the use of a :term:`view
-   handler` to map URLs to code (a handler is much like a Pylons
-   "controller").
-
 .. index::
    single: creating a project
    single: project
@@ -382,7 +375,6 @@ structure:
   |-- MANIFEST.in
   |-- myproject
   |   |-- __init__.py
-  |   |-- resources.py
   |   |-- static
   |   |   |-- favicon.ico
   |   |   |-- logo.png
@@ -682,8 +674,6 @@ The ``myproject`` :term:`package` lives inside the ``MyProject``
    ``main`` function which is used as a entry point for commands such as
    ``pserve``, ``pshell``, ``pviews``, and others.
 
-#. A ``resources.py`` module, which contains :term:`resource` code.
-
 #. A ``templates`` directory, which contains :term:`Chameleon` (or
    other types of) templates.
 
@@ -719,23 +709,23 @@ also informs Python that the directory which contains it is a *package*.
 #. Line 1 imports the :term:`Configurator` class from :mod:`pyramid.config`
    that we use later.
 
-#. Line 2 imports the ``Root`` class from :mod:`myproject.resources` that we
-   use later.
-
-#. Lines 4-10 define a function named ``main`` that returns a :app:`Pyramid`
+#. Lines 3-16 define a function named ``main`` that returns a :app:`Pyramid`
    WSGI application.  This function is meant to be called by the
    :term:`PasteDeploy` framework as a result of running ``pserve``.
 
    Within this function, application configuration is performed.
 
-   Line 7 creates an instance of a :term:`Configurator`.
+   Line 6 creates an instance of a :term:`Configurator`.
 
-   Line 8 registers a static view, which will serve up the files from the
+   Line 7 registers a static view, which will serve up the files from the
    ``mypackage:static`` :term:`asset specification` (the ``static``
    directory of the ``mypackage`` package).
 
+   Line 8 adds a :term:`route` to the configuration.  This route is later
+   used by a view in the ``views`` module.
+
    Line 9 calls ``config.scan()``, which picks up view registrations declared
-   elsewhere in the package (in this case, in the ``view.py`` module).
+   elsewhere in the package (in this case, in the ``views.py`` module).
 
    Line 10 returns a :term:`WSGI` application to the caller of the function
    (Pyramid's pserve).
@@ -755,20 +745,22 @@ and which returns a :term:`response`.
    :language: python
    :linenos:
 
-Lines 4-6 define and register a :term:`view callable` named ``my_view``.  The
+Lines 3-5 define and register a :term:`view callable` named ``my_view``.  The
 function named ``my_view`` is decorated with a ``view_config`` decorator
 (which is processed by the ``config.scan()`` line in our ``__init__.py``).
-The view_config decorator asserts that this view be found when the
-:term:`context` of the request is an instance of the
-:class:`myproject.resources.Root` class.  The view_config decorator also
-names a ``renderer``, which in this case is a template that will be used to
-render the result of the view callable.  This particular view declaration
-points at ``templates/mytemplate.pt``, which is a :term:`asset specification`
-that specifies the ``mytemplate.pt`` file within the ``templates`` directory
-of the ``myproject`` package.  The asset specification could have also been
-specified as ``myproject:templates/mytemplate.pt``; the leading package name
-and colon is optional.  The template file it actually points to is a
-:term:`Chameleon` ZPT template file.
+The view_config decorator asserts that this view be found when a
+:term:`route` named ``home`` is matched.  In our case, because our
+``__init__.py`` maps the route named ``home`` to the URL pattern ``/``, this
+route will match when a visitor visits the root URL.  The view_config
+decorator also names a ``renderer``, which in this case is a template that
+will be used to render the result of the view callable.  This particular view
+declaration points at ``templates/mytemplate.pt``, which is a :term:`asset
+specification` that specifies the ``mytemplate.pt`` file within the
+``templates`` directory of the ``myproject`` package.  The asset
+specification could have also been specified as
+``myproject:templates/mytemplate.pt``; the leading package name and colon is
+optional.  The template file it actually points to is a :term:`Chameleon` ZPT
+template file.
 
 This view callable function is handed a single piece of information: the
 :term:`request`.  The *request* is an instance of the :term:`WebOb`
@@ -778,8 +770,7 @@ This view returns a dictionary.  When this view is invoked, a
 :term:`renderer` converts the dictionary returned by the view into HTML, and
 returns the result as the :term:`response`.  This view is configured to
 invoke a renderer which uses a :term:`Chameleon` ZPT template
-(``mypackage:templates/my_template.pt``, as specified in the ``__init__.py``
-file call to ``add_view``).
+(``templates/my_template.pt``).
 
 See :ref:`views_which_use_a_renderer` for more information about how views,
 renderers, and templates relate and cooperate.
@@ -795,35 +786,6 @@ renderers, and templates relate and cooperate.
    the speed at which templates may be rendered.
 
 .. index::
-   single: resources.py
-
-.. _resourcespy_project_section:
-
-``resources.py``
-~~~~~~~~~~~~~~~~
-
-The ``resources.py`` module provides the :term:`resource` data and behavior
-for our application.  Resources are objects which exist to provide site
-structure in applications which use :term:`traversal` to map URLs to code.
-We write a class named ``Root`` that provides the behavior for the root
-resource.
-
-.. literalinclude:: MyProject/myproject/resources.py
-   :language: python
-   :linenos:
-
-#. Lines 1-3 define the Root class.  The Root class is a "root resource
-   factory" function that will be called by the :app:`Pyramid` *Router* for
-   each request when it wants to find the root of the resource tree.
-
-In a "real" application, the Root object would likely not be such a simple
-object.  Instead, it might be an object that could access some persistent
-data store, such as a database.  :app:`Pyramid` doesn't make any assumption
-about which sort of data storage you'll want to use, so the sample
-application uses an instance of :class:`myproject.resources.Root` to
-represent the root.
-
-.. index::
    single: static directory
 
 ``static``
@@ -904,39 +866,12 @@ named ``views`` instead of within a single ``views.py`` file, you might:
   can be empty, this just tells Python that the ``views`` directory is a
   *package*.
 
-Then change the __init__.py of your myproject project (*not* the
-``__init__.py`` you just created in the ``views`` directory, the one in its
-parent directory).  For example, from something like:
-
-.. code-block:: python
-    :linenos:
-
-    config.add_view('myproject.views.my_view',
-                    renderer='myproject:templates/mytemplate.pt')
-
-To this:
-
-.. code-block:: python
-    :linenos:
-
-    config.add_view('myproject.views.blog.my_view',
-                    renderer='myproject:templates/mytemplate.pt')
-
-You can then continue to add files to the ``views`` directory, and refer to
-view classes or functions within those files via the dotted name passed as
-the first argument to ``add_view``.  For example, if you added a file named
-``anothermodule.py`` to the ``views`` subdirectory, and added a view callable
-named ``my_view`` to it:
-
-.. code-block:: python
-    :linenos:
-
-    config.add_view('myproject.views.anothermodule.my_view',
-                    renderer='myproject:templates/anothertemplate.pt')
-
-This pattern can be used to rearrage code referred to by any Pyramid API
-argument which accepts a :term:`dotted Python name` or direct object
-reference.
+You can then continue to add view callable functions to the ``blog.py``
+module, but you can also add other ``.py`` files which contain view callable
+functions to the ``views`` directory.  As long as you use the
+``@view_config`` directive to register views in conjuction with
+``config.scan()`` they will be picked up automatically when the application
+is restarted.
 
 Using the Interactive Shell
 ---------------------------
@@ -949,13 +884,34 @@ via ``pserve``.  This can be a useful debugging tool.  See
 Using an Alternate WSGI Server
 ------------------------------
 
-The code generated by a :app:`Pyramid` scaffold assumes that you will be
+The code generated by :app:`Pyramid` scaffolding assumes that you will be
 using the ``pserve`` command to start your application while you do
-development.  However, ``pserve`` is by no means the only way to start up and
-serve a :app:`Pyramid` application.  As we saw in :ref:`firstapp_chapter`,
-``pserve`` needn't be invoked at all to run a :app:`Pyramid` application.
-The use of ``pserve`` to run a :app:`Pyramid` application is purely
-conventional based on the output of its scaffold.
+development.  The default rendering of Pyramid scaffolding uses the *wsgiref*
+WSGI server, which is a server that is ill-suited for production usage: its
+main feature is that it works on all platforms and all systems, making it a
+good choice as a default server from the perspective of Pyramid's developers.
+
+To use a server more suitable for production, you have a number of choices.
+Replace the ``use = egg:pyramid#wsgref`` line in your ``production.ini`` with
+one of the following.
+
+``use = egg:Paste#http``
+
+  ``paste.httpserver`` is Windows, UNIX, and Python 2 compatible.  You'll
+  need to ``easy_install Paste`` into your Pyramid virtualenv for this server
+  to work.
+
+``use = egg:pyramid#cherrypy``
+
+  The ``CherryPy`` WSGI server is Windows, UNIX, Python 2, and Python 3
+  compatible.  You'll need to ``easy_install CherryPy`` into your Pyramid
+  virtualenv for this server to work.
+
+``pserve`` is by no means the only way to start up and serve a :app:`Pyramid`
+application.  As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be
+invoked at all to run a :app:`Pyramid` application.  The use of ``pserve`` to
+run a :app:`Pyramid` application is purely conventional based on the output
+of its scaffold.
 
 Any :term:`WSGI` server is capable of running a :app:`Pyramid` application.
 Some WSGI servers don't require the :term:`PasteDeploy` framework's
diff --git a/pyramid/scaffolds/__init__.py b/pyramid/scaffolds/__init__.py
index 50c04017a..73df62522 100644
--- a/pyramid/scaffolds/__init__.py
+++ b/pyramid/scaffolds/__init__.py
@@ -41,7 +41,8 @@ class AlchemyProjectTemplate(PyramidTemplate):
         val = PyramidTemplate.post(self, command, output_dir, vars)
         self.out('')
         self.out('Please run the "populate_%(package)s" script to set up the '
-                 'SQL database before starting the application (e.g. '
+                 'SQL database after installing (but before starting) the '
+                 'application (e.g. '
                  '"$myvirtualenv/bin/populate_%(package)s development.ini".)'
                  % vars)
         return val
diff --git a/pyramid/scaffolds/starter/+package+/__init__.py b/pyramid/scaffolds/starter/+package+/__init__.py
index ddcdd7162..31b02cf02 100644
--- a/pyramid/scaffolds/starter/+package+/__init__.py
+++ b/pyramid/scaffolds/starter/+package+/__init__.py
@@ -1,10 +1,10 @@
 from pyramid.config import Configurator
-from .resources import Root
 
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
-    config = Configurator(root_factory=Root, settings=settings)
+    config = Configurator(settings=settings)
     config.add_static_view('static', 'static', cache_max_age=3600)
+    config.add_route('home', '/')
     config.scan()
     return config.make_wsgi_app()
diff --git a/pyramid/scaffolds/starter/+package+/resources.py b/pyramid/scaffolds/starter/+package+/resources.py
deleted file mode 100644
index 3d811895c..000000000
--- a/pyramid/scaffolds/starter/+package+/resources.py
+++ /dev/null
@@ -1,3 +0,0 @@
-class Root(object):
-    def __init__(self, request):
-        self.request = request
diff --git a/pyramid/scaffolds/starter/+package+/views.py_tmpl b/pyramid/scaffolds/starter/+package+/views.py_tmpl
index b02b2e79e..7a0d2f386 100644
--- a/pyramid/scaffolds/starter/+package+/views.py_tmpl
+++ b/pyramid/scaffolds/starter/+package+/views.py_tmpl
@@ -1,6 +1,5 @@
 from pyramid.view import view_config
-from .resources import Root
 
-@view_config(context=Root, renderer='templates/mytemplate.pt')
+@view_config(route_name='home', renderer='templates/mytemplate.pt')
 def my_view(request):
     return {'project':'{{project}}'}
diff --git a/pyramid/scaffolds/tests.py b/pyramid/scaffolds/tests.py
index 8efbb934b..04e802396 100644
--- a/pyramid/scaffolds/tests.py
+++ b/pyramid/scaffolds/tests.py
@@ -39,6 +39,10 @@ class TemplateTest(object):
             os.chdir('Dingle')
             py = os.path.join(self.directory, 'bin', 'python')
             subprocess.check_call([py, 'setup.py', 'install'])
+            if tmpl_name == 'alchemy':
+                populate = os.path.join(self.directory, 'bin',
+                                        'populate_Dingle')
+                subprocess.check_call([populate, 'development.ini'])
             subprocess.check_call([py, 'setup.py', 'test'])
             pserve = os.path.join(self.directory, 'bin', 'pserve')
             for ininame, hastoolbar in (('development.ini', True),