Merge branch 'master' into feature.signed-cookie-session

8 files changed, 145 insertions, 118 deletions

diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 58b9bdd21..0984b4daf 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -474,6 +474,17 @@ input of the ``prequest`` process is used as the ``POST`` body::
 
    $ $VENV/bin/prequest -mPOST development.ini / < somefile
 
+Using Custom Arguments to Python when Running ``p*`` Scripts
+------------------------------------------------------------
+
+.. versionadded:: 1.5
+
+Each of Pyramid's console scripts (``pserve``, ``pviews``, etc) can be run
+directly using ``python -m``, allowing custom arguments to be sent to the
+python interpreter at runtime. For example::
+
+      python -3 -m pyramid.scripts.pserve development.ini
+
 Showing All Installed Distributions and their Versions
 ------------------------------------------------------
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index f3f736df6..e419a8b20 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -289,9 +289,9 @@ Installing :app:`Pyramid` Into the Virtual Python Environment
 After you've got your virtualenv installed, you may install :app:`Pyramid`
 itself using the following commands:
 
-.. code-block:: text
-
-   $ $VENV/bin/easy_install pyramid
+.. parsed-literal::
+      
+   $ $VENV/bin/easy_install "pyramid==\ |release|\ "
 
 The ``easy_install`` command will take longer than the previous ones to
 complete, as it downloads and installs a number of dependencies.
@@ -368,9 +368,9 @@ You can use Pyramid on Windows under Python 2 or 3.
 #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
    installed:
 
-   .. code-block:: text
-
-      c:\env> %VENV%\Scripts\easy_install pyramid
+   .. parsed-literal::
+      
+      c:\\env> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ "
 
 What Gets Installed
 -------------------
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 032f4be6b..a9c5fdfbd 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -176,8 +176,13 @@ static file server in production without changing any code.
 
 Example: :ref:`static_assets_section`.
 
-Debug Toolbar
-~~~~~~~~~~~~~
+Fully Interactive Development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When developing a Pyramid application, several interactive features are
+available. Pyramid can automatically utilize changed templates when rendering
+pages and automatically restart the application to incorporate changed python
+code. Plain old ``print()`` calls used for debugging can display to a console.
 
 Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to
 render a project.  This toolbar overlays your application in the browser, and
@@ -321,7 +326,14 @@ assertion instead that the view returns "the right stuff" in the dictionary
 it returns.  You can write "real" unit tests instead of functionally testing
 all of your views.
 
-For example, instead of:
+.. index::
+   pair: renderer; explicitly calling
+   pair: view renderer; explictly calling
+
+.. _example_render_to_response_call:
+
+For example, instead of returning a ``Response`` object from a
+``render_to_response`` call:
 
 .. code-block:: python
    :linenos:
@@ -332,7 +344,7 @@ For example, instead of:
         return render_to_response('myapp:templates/mytemplate.pt', {'a':1},
                                   request=request)
 
-You can do this:
+You can return a Python dictionary:
 
 .. code-block:: python
    :linenos:
@@ -405,12 +417,12 @@ Sessions
 
 Pyramid has built-in HTTP sessioning.  This allows you to associate data with
 otherwise anonymous users between requests.  Lots of systems do this.  But
-Pyramid also allows you to plug in your own sessioning system by creating
-some code that adheres to a documented interface.  Currently there is a
-binding package for the third-party Beaker sessioning system that does exactly
-this.  But if you have a specialized need (perhaps you want to store your
-session data in MongoDB), you can.  You can even switch between
-implementations without changing your application code.
+Pyramid also allows you to plug in your own sessioning system by creating some
+code that adheres to a documented interface.  Currently there is a binding
+package for the third-party Redis sessioning system that does exactly this.
+But if you have a specialized need (perhaps you want to store your session data
+in MongoDB), you can.  You can even switch between implementations without
+changing your application code.
 
 Example: :ref:`sessions_chapter`.
 
@@ -777,7 +789,7 @@ automate some of the tedium away:
        for method in ('GET', 'POST', 'HEAD'):
            view = getattr(module, 'xhr_%s_view' % method, None)
            if view is not None:
-               config.add_view(view, route_name='xhr_route', xhr=True, 
+               config.add_view(view, route_name='xhr_route', xhr=True,
                               permission='view', request_method=method)
 
    config = Configurator()
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index f3050f805..d7292d187 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -144,9 +144,9 @@ contains no space characters, so it's wise to *avoid* a path that contains
 i.e. ``My Documents``.  As a result, the author, when he uses Windows, just
 puts his projects in ``C:\projects``.
 
-.. warning:: 
+.. warning::
 
-   You’ll need to avoid using ``pcreate`` to create a project with the same
+   You'll need to avoid using ``pcreate`` to create a project with the same
    name as a Python standard library component. In particular, this means you
    should avoid using the names ``site`` or ``test``, both of which
    conflict with Python standard library packages.  You should also avoid
@@ -193,10 +193,10 @@ Elided output from a run of this command on UNIX is shown below:
    ...
    Finished processing dependencies for MyProject==0.0
 
-This will install a :term:`distribution` representing your project into the
-interpreter's library set so it can be found by ``import`` statements and by
-other console scripts such as ``pserve``, ``pshell``, ``proutes`` and
-``pviews``.
+This will install a :term:`distribution` representing your project
+into the virtual environment interpreter's library set so it can be
+found by ``import`` statements and by other console scripts such as
+``pserve``, ``pshell``, ``proutes`` and ``pviews``.
 
 .. index::
    single: running tests
@@ -243,22 +243,24 @@ Here's sample output from a test run on UNIX:
 
    OK
 
-.. note::
-
-   The ``-q`` option is passed to the ``setup.py test`` command to limit the
-   output to a stream of dots.  If you don't pass ``-q``, you'll see more
-   verbose test result output (which normally isn't very useful).
-
 The tests themselves are found in the ``tests.py`` module in your ``pcreate``
 generated project.  Within a project generated by the ``starter`` scaffold, a
 single sample test exists.
 
+.. note::
+
+    The ``-q`` option is passed to the ``setup.py test`` command to limit the
+    output to a stream of dots.  If you don't pass ``-q``, you'll see more
+    verbose test result output (which normally isn't very useful).
+
 .. index::
    single: running an application
    single: pserve
    single: reload
    single: startup
 
+.. _running_the_project_application:
+
 Running The Project Application
 -------------------------------
 
@@ -600,6 +602,8 @@ server which listens on TCP port 6543.  It is configured to listen on all
 interfaces (``0.0.0.0``).  This means that any remote system which has TCP
 access to your system can see your Pyramid application.
 
+.. _MyProject_ini_logging:
+
 The sections that live between the markers ``# Begin logging configuration``
 and ``# End logging configuration`` represent Python's standard library
 :mod:`logging` module configuration for your application.  The sections
@@ -696,11 +700,11 @@ testing, packaging, and distributing your application.
 
 .. note::
 
-  ``setup.py`` is the de facto standard which Python developers use to
-  distribute their reusable code.  You can read more about ``setup.py`` files
-  and their usage in the `Setuptools documentation
-  <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `The
-  Hitchhiker's Guide to Packaging <http://guide.python-distribute.org/>`_.
+    ``setup.py`` is the de facto standard which Python developers use to
+    distribute their reusable code.  You can read more about ``setup.py`` files
+    and their usage in the `Setuptools documentation
+    <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `The
+    Hitchhiker's Guide to Packaging <http://guide.python-distribute.org/>`_.
 
 Our generated ``setup.py`` looks like this:
 
@@ -871,31 +875,48 @@ 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.
+optional.  The template file pointed to is a :term:`Chameleon` ZPT
+template file (``templates/my_template.pt``).
 
 This view callable function is handed a single piece of information: the
 :term:`request`.  The *request* is an instance of the :term:`WebOb`
 ``Request`` class representing the browser's request to our server.
 
-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
-(``templates/my_template.pt``).
-
-See :ref:`views_which_use_a_renderer` for more information about how views,
-renderers, and templates relate and cooperate.
-
-.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates =
-   true`` directive indicating that templates should be reloaded when
-   they change, you won't need to restart the application server to
-   see changes you make to templates.  During development, this is
-   handy.  If this directive had been ``false`` (or if the directive
-   did not exist), you would need to restart the application server
-   for each template change.  For production applications, you should
-   set your project's ``pyramid.reload_templates`` to ``false`` to increase
-   the speed at which templates may be rendered.
+This view is configured to invoke a :term:`renderer` on a template.  The
+dictionary the view returns (on line 6) provides the value the renderer
+substitutes into the template when generating HTML.  The renderer then
+returns the HTML in a :term:`response`.
+
+.. note:: Dictionaries provide values to :term:`template`\s.
+
+.. note:: When the application is run with the scaffold's :ref:`default
+   development.ini <MyProject_ini>` configuration :ref:`logging is set up
+   <MyProject_ini_logging>` to aid debugging.  If an exception is raised,
+   uncaught tracebacks are displayed after the startup messages on :ref:`the
+   console running the server <running_the_project_application>`. Also
+   ``print()`` statements may be inserted into the application for debugging
+   to send output to this console.
+
+.. note:: ``development.ini`` has a setting that controls how templates are
+   reloaded, ``pyramid.reload_templates``.
+
+   - When set to ``True`` (as in the scaffold ``development.ini``) changed
+     templates automatically reload without a server restart.  This is
+     convenient while developing, but slows template rendering speed.
+
+   - When set to ``False`` (the default value), changing templates requires
+     a server restart to reload them.  Production applications should use
+     ``pyramid.reload_templates = False``.
+
+.. seealso:: See also :ref:`views_which_use_a_renderer` for more information
+    about how views, renderers, and templates relate and cooperate.
+
+.. seealso:: Pyramid can also dynamically reload changed Python files.  For
+    more on this see :ref:`reloading_code`.
+
+.. seealso:: The :ref:`debug_toolbar` provides interactive access to your
+   application's internals and, should an exception occur, allows interactive
+   access to traceback execution stack frames from the Python interpreter.
 
 .. index::
    single: static directory
@@ -971,12 +992,15 @@ named ``views`` instead of within a single ``views.py`` file, you might:
 - Create a ``views`` directory inside your ``myproject`` package directory
   (the same directory which holds ``views.py``).
 
-- *Move* the existing ``views.py`` file to a file inside the new ``views``
-  directory named, say, ``blog.py``.
+- Create a file within the new ``views`` directory named ``__init__.py``.  (It
+  can be empty.  This just tells Python that the ``views`` directory is a
+  *package*.)
 
-- Create a file within the new ``views`` directory named ``__init__.py`` (it
-  can be empty, this just tells Python that the ``views`` directory is a
-  *package*.
+- *Move* the content from the existing ``views.py`` file to a file inside the
+  new ``views`` directory named, say, ``blog.py``.  Because the ``templates``
+  directory remains in the ``myproject`` package, the template :term:`asset
+  specification` values in ``blog.py`` must now be fully qualified with the
+  project's package name (``myproject:templates/blog.pt``).
 
 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
@@ -1025,7 +1049,7 @@ server.  Waitress is a server that is suited for development and light
 production usage.  It's not the fastest nor the most featureful WSGI server.
 Instead, its main feature is that it works on all platforms that Pyramid
 needs to run on, making it a good choice as a default server from the
-perspective of Pyramid's developers.  
+perspective of Pyramid's developers.
 
 Any WSGI server is capable of running a :app:`Pyramid` application.  But we
 suggest you stick with the default server for development, and that you wait
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 3059aef35..740c81555 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -49,15 +49,19 @@ Writing View Callables Which Use a Renderer
 -------------------------------------------
 
 As we've seen, a view callable needn't always return a Response object.
-Instead, it may return an arbitrary Python object, with the expectation
-that a :term:`renderer` will convert that object into a response instance on
-your behalf.  Some renderers use a templating system; other renderers use
-object serialization techniques.
-
-View configuration can vary the renderer associated with a view callable via
-the ``renderer`` attribute.  For example, this call to
-:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` renderer
-with a view callable:
+Instead, it may return an arbitrary Python object, with the expectation that
+a :term:`renderer` will convert that object into a response instance on your
+behalf.  Some renderers use a templating system; other renderers use object
+serialization techniques.  In practice, renderers obtain application data
+values from Python dictionaries so, in practice, view callables which use
+renderers return Python dictionaries.
+
+View callables can :ref:`explicitly call <example_render_to_response_call>`
+renderers, but typically don't.  Instead view configuration declares the
+renderer used to render a view callable's results.  This is done with the
+``renderer`` attribute.  For example, this call to
+:meth:`~pyramid.config.Configurator.add_view` associates the ``json``
+renderer with a view callable:
 
 .. code-block:: python
 
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 1d914f9ea..fb5035373 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -98,6 +98,11 @@ example:
        else:
            return Response('Fred was not in the session')
 
+The first time this view is invoked produces ``Fred was not in the
+session``.  Subsequent invocations produce ``Fred was in the
+session``, assuming of course that the client side maintains the
+session's identity across multiple requests.
+
 You can use a session much like a Python dictionary.  It supports all
 dictionary methods, along with some extra attributes, and methods.
 
@@ -145,8 +150,6 @@ Some gotchas:
   you've changed sessioning data.
 
 .. index::
-   single: pyramid_beaker
-   single: Beaker
    single: pyramid_redis_sessions
    single: session factory (alternates)
 
@@ -155,19 +158,10 @@ Some gotchas:
 Using Alternate Session Factories
 ---------------------------------
 
-At the time of this writing, exactly two alternate session factories
-exist.
-
-The first is named ``pyramid_redis_sessions``.  It can be downloaded from PyPI.
-It uses Redis as a backend.  It is the recommended persistent session solution
-at the time of this writing.
-
-The second is named ``pyramid_beaker``. This is a session factory that uses the
-`Beaker <http://beaker.groovie.org/>`_ library as a backend.  Beaker has
-support for file-based sessions, database based sessions, and encrypted
-cookie-based sessions.  See `the pyramid_beaker documentation
-<http://docs.pylonsproject.org/projects/pyramid_beaker/en/latest/>`_ for more
-information about ``pyramid_beaker``.
+At the time of this writing, exactly one project-endorsed alternate session
+factory exists named :term:`pyramid_redis_sessions`.  It can be downloaded from
+PyPI.  It uses the Redis database as a backend.  It is the recommended 
+persistent session solution at the time of this writing.
 
 .. index::
    single: session factory (custom)
@@ -368,25 +362,27 @@ Or, include it as a header in a jQuery AJAX request:
 The handler for the URL that receives the request
 should then require that the correct CSRF token is supplied.
 
-Using the ``session.check_csrf_token`` Method
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Checking CSRF Tokens Manually
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In request handling code, you can check the presence and validity of a CSRF
-token with ``session.check_csrf_token(request)``. If the token is valid,
-it will return True, otherwise it will raise ``HTTPBadRequest``.
+token with :func:`pyramid.session.check_csrf_token(request)``. If the token is
+valid, it will return ``True``, otherwise it will raise ``HTTPBadRequest``.
+Optionally, you can specify ``raises=False`` to have the check return ``False``
+instead of raising an exception.
 
 By default, it checks for a GET or POST parameter named ``csrf_token`` or a
 header named ``X-CSRF-Token``.
 
 .. code-block:: python
 
-    def myview(request):
-        session = request.session
+    from pyramid.session import check_csrf_token
 
+    def myview(request):
         # Require CSRF Token
-        session.check_csrf_token(request):
+        check_csrf_token(request)
 
-        ...
+        # ...
 
 .. index::
    single: session.new_csrf_token
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index a60c5ba56..454bb5620 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -146,35 +146,15 @@ refer to a root factory defined in a different module.
 
 If no :term:`root factory` is passed to the :app:`Pyramid`
 :term:`Configurator` constructor, or if the ``root_factory`` value
-specified is ``None``, a *default* root factory is used.  The default
+specified is ``None``, a :term:`default root factory` is used.  The default
 root factory always returns a resource that has no child resources; it
 is effectively empty.
 
 Usually a root factory for a traversal-based application will be more
-complicated than the above ``Root`` class; in particular it may be
-associated with a database connection or another persistence mechanism.
-
-.. sidebar:: Emulating the Default Root Factory
-
-   For purposes of understanding the default root factory better, we'll note
-   that you can emulate the default root factory by using this code as an
-   explicit root factory in your application setup:
-
-   .. code-block:: python
-      :linenos:
-
-      class Root(object):
-          def __init__(self, request):
-              pass
-
-      config = Configurator(root_factory=Root)
-
-   The default root factory is just a really stupid object that has no
-   behavior or state.  Using :term:`traversal` against an application that
-   uses the resource tree supplied by the default root resource is not very
-   interesting, because the default root resource has no children.  Its
-   availability is more useful when you're developing an application using
-   :term:`URL dispatch`.
+complicated than the above ``Root`` class; in particular it may be associated
+with a database connection or another persistence mechanism.  The above
+``Root`` class is analogous to the default root factory present in Pyramid. The
+default root factory is very simple and not very useful.
 
 .. note::
 
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index ca6dc565b..64343ca3e 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -150,7 +150,7 @@ do things the newer way:
 .. code-block:: python
    :linenos:
 
-    from pyramid.view. import view_config
+    from pyramid.view import view_config
 
     from pyramid.static import static_view
     myview = static_view('static', 'static', use_subpath=True)