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

11 files changed, 125 insertions, 19 deletions

diff --git a/docs/api/config.rst b/docs/api/config.rst
index cd58e74d3..bc9e067b1 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -66,6 +66,8 @@
      .. automethod:: add_response_adapter
      .. automethod:: add_traverser
      .. automethod:: add_tween
+     .. automethod:: add_route_predicate
+     .. automethod:: add_view_predicate
      .. automethod:: set_request_factory
      .. automethod:: set_root_factory
      .. automethod:: set_session_factory
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 45a79326f..ba3203f89 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -994,3 +994,9 @@ Glossary
       Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under
       Python 2.5+ (although at the time of this writing does not support
       Python 3).  See http://gunicorn.org/ for detailed information.
+
+   predicate factory
+      A callable which is used by a third party during the registration of a
+      route or view predicates to extend the view and route configuration
+      system.  See :ref:`registering_thirdparty_predicates` for more
+      information.
diff --git a/docs/index.rst b/docs/index.rst
index 31c2fde6b..c84314274 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,15 +13,9 @@ Here is one of the simplest :app:`Pyramid` applications you can make:
 
 .. literalinclude:: narr/helloworld.py
 
-When saved to ``helloworld.py``, the above application can be run via:
-
-.. code-block:: text
-
-   $ easy_install pyramid
-   $ python helloworld.py
-
-When you visit ``http://localhost:8080/hello/world`` in a browser, you will
-see the text ``Hello, world!``.
+After you install :app:`Pyramid` and run this application, when you visit
+``http://localhost:8080/hello/world`` in a browser, you will see the text
+``Hello, world!``
 
 See :ref:`firstapp_chapter` for a full explanation of how this application
 works. Read the :ref:`html_narrative_documentation` to understand how
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 1ca188d7e..a86826d86 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -8,7 +8,8 @@ Creating Your First :app:`Pyramid` Application
 
 In this chapter, we will walk through the creation of a tiny :app:`Pyramid`
 application.  After we're finished creating the application, we'll explain in
-more detail how it works.
+more detail how it works. It assumes you already have :app:`Pyramid` installed.
+If you do not, head over to the :ref:`installing_chapter` section.
 
 .. _helloworld_imperative:
 
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 332805152..2c15cd690 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -1232,3 +1232,101 @@ Displaying Tween Ordering
 The ``ptweens`` command-line utility can be used to report the current
 implict and explicit tween chains used by an application.  See
 :ref:`displaying_tweens`.
+
+.. _registering_thirdparty_predicates:
+
+Adding A Third Party View or Route Predicate
+--------------------------------------------
+
+.. note::
+
+   Third-party predicates are a feature new as of Pyramid 1.4.
+
+View and route predicates used during view configuration allow you to narrow
+the set of circumstances under which a view or route will match.  For
+example, the ``request_method`` view predicate can be used to ensure a view
+callable is only invoked when the request's method is ``POST``:
+
+.. code-block:: python
+
+    @view_config(request_method='POST')
+    def someview(request):
+        ...
+
+Likewise, a similar predicate can be used as a *route* predicate:
+
+.. code-block:: python
+
+    config.add_route('name', '/foo', request_method='POST')
+
+Many other built-in predicates exists (``request_param``, and others).  You
+can add third-party predicates to the list of available predicates by using
+one of :meth:`pyramid.config.Configurator.add_view_predicate` or
+:meth:`pyramid.config.Configurator.add_route_predicate`.  The former adds a
+view predicate, the latter a route predicate.
+
+When using one of those APIs, you pass a *name* and a *factory* to add a
+predicate during Pyramid's configuration stage.  For example:
+
+.. code-block:: python
+
+    config.add_view_predicate('content_type', ContentTypePredicate)
+
+The above example adds a new predicate named ``content_type`` to the list of
+available predicates for views.  This will allow the following view
+configuration statement to work:
+
+.. code-block:: python
+   :linenos:
+
+   @view_config(content_type='File')
+   def aview(request): ...
+
+The first argument to :meth:`pyramid.config.Configurator.add_view_predicate`,
+the name, is a string representing the name that is expected to be passed to
+``view_config`` (or its imperative analogue ``add_view``).
+
+The second argument is a predicate factory.  A predicate factory is most
+often a class with a constructor (``__init__``), a ``text`` method, a
+``phash`` method and a ``__call__`` method.  For example:
+
+.. code-block:: python
+   :linenos:
+
+    class ContentTypePredicate(object):
+        def __init__(self, val, config):
+            self.val = val
+
+        def text(self):
+            return 'content_type = %s' % (self.val,)
+
+        phash = text
+
+        def __call__(self, context, request):
+            return getattr(context, 'content_type', None) == self.val
+
+The constructor of a predicate factory takes two arguments: ``val`` and
+``config``.  The ``val`` argument will be the argument passed to
+``view_config`` (or ``add_view``).  In the example above, it will be the
+string ``File``.  The second arg, ``config`` will be the Configurator
+instance at the time of configuration.
+
+The ``text`` method must return a string.  It should be useful to describe
+the behavior of the predicate in error messages.
+
+The ``phash`` method must return a string or a sequence of strings.  It's
+most often the same as ``text``, as long as ``text`` uniquely describes the
+predicate's name and the value passed to the constructor.  If ``text`` is
+more general, or doesn't describe things that way, ``phash`` should return a
+string with the name and the value serialized.  The result of ``phash`` is
+not seen in output anywhere, it just informs the uniqueness constraints for
+view configuration.
+
+The ``__call__`` method of a predicate factory must accept a resource
+(``context``) and a request, and must return ``True`` or ``False``.  It is
+the "meat" of the predicate.
+
+You can use the same predicate factory as both a view predicate and as a
+route predicate, but you'll need to call ``add_view_predicate`` and
+``add_route_predicate`` separately with the same factory.
+
diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst
index e070f8eda..d11167344 100644
--- a/docs/tutorials/modwsgi/index.rst
+++ b/docs/tutorials/modwsgi/index.rst
@@ -73,9 +73,10 @@ commands and files.
 
     .. code-block:: python
 
-       from pyramid.paster import get_app
-       application = get_app(
-         '/Users/chrism/modwsgi/env/myapp/production.ini', 'main')
+       from pyramid.paster import get_app, setup_logging
+       ini_path = '/Users/chrism/modwsgi/env/myapp/production.ini'
+       setup_logging(ini_path)
+       application = get_app(ini_path, 'main')
 
     The first argument to ``get_app`` is the project configuration file
     name.  It's best to use the ``production.ini`` file provided by your
@@ -85,6 +86,10 @@ commands and files.
     ``application`` is important: mod_wsgi requires finding such an
     assignment when it opens the file.
 
+    The call to ``setup_logging`` initializes the standard library's
+    `logging` module to allow logging within your application.
+    See :ref:`logging_config`.
+
 #.  Make the ``pyramid.wsgi`` script executable.
 
     .. code-block:: text
diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index 28cecb787..529603546 100644
--- a/docs/tutorials/wiki/definingviews.rst
+++ b/docs/tutorials/wiki/definingviews.rst
@@ -251,7 +251,7 @@ wiki page. It includes:
 - A ``div`` element that is replaced with the ``content``
   value provided by the view (rows 45-47).  ``content``
   contains HTML, so the ``structure`` keyword is used
-  to prevent escaping it (i.e. changing ">" to >, etc.)
+  to prevent escaping it (i.e. changing ">" to ">", etc.)
 - A link that points
   at the "edit" URL which invokes the ``edit_page`` view for
   the page being viewed (rows 49-51).
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 2ef55d15b..d7bd24a53 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -353,7 +353,7 @@ when we're done:
 
 .. literalinclude:: src/authorization/tutorial/views.py
    :linenos:
-   :emphasize-lines: 11,14-18,31,37,58,61,73,76,88,91-117,119-123
+   :emphasize-lines: 11,14-18,25,31,37,58,61,73,76,88,91-117,119-123
    :language: python
 
 (Only the highlighted lines need to be added.)
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index 5f4ea671c..b3184c4fc 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -100,7 +100,7 @@ used when the URL is ``/``:
       :language: py
 
 Since this route has a ``pattern`` equalling ``/`` it is the route that will
-be matched when the URL ``/`` is visted, e.g. ``http://localhost:6543/``.
+be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``.
 
 ``main`` next calls the ``scan`` method of the configurator, which will
 recursively scan our ``tutorial`` package, looking for ``@view_config`` (and
@@ -190,7 +190,7 @@ Next we set up a SQLAlchemy "DBSession" object:
 ``scoped_session`` allows us to access our database connection globally.
 ``sessionmaker`` creates a database session object.  We pass to
 ``sessionmaker`` the ``extension=ZopeTransactionExtension()`` extension
-option in order to allow the system to automatically manage datbase
+option in order to allow the system to automatically manage database
 transactions.  With ``ZopeTransactionExtension`` activated, our application
 will automatically issue a transaction commit after every request unless an
 exception is raised, in which case the transaction will be aborted.
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index efb72230e..24ac4338d 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -248,7 +248,7 @@ wiki page. It includes:
 - A ``div`` element that is replaced with the ``content``
   value provided by the view (rows 45-47).  ``content``
   contains HTML, so the ``structure`` keyword is used
-  to prevent escaping it (i.e. changing ">" to >, etc.)
+  to prevent escaping it (i.e. changing ">" to ">", etc.)
 - A link that points
   at the "edit" URL which invokes the ``edit_page`` view for
   the page being viewed (rows 49-51).
diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst
index 2e6fc0e77..deaf32ef6 100644
--- a/docs/tutorials/wiki2/design.rst
+++ b/docs/tutorials/wiki2/design.rst
@@ -20,7 +20,7 @@ Models
 We'll be using a SQLite database to hold our wiki data, and we'll be using
 :term:`SQLAlchemy` to access the data in this database.
 
-Within the database, we define a single table named `tables`, whose elements
+Within the database, we define a single table named `pages`, whose elements
 will store the wiki pages.  There are two columns: `name` and `data`.
 
 URLs like ``/PageName`` will try to find an element in