17 files changed, 289 insertions, 88 deletions
diff --git a/docs/api.rst b/docs/api.rst
index d510c0d27..e33fd6a74 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -10,8 +10,6 @@ documentation is organized alphabetically by module name.
 
    api/authorization
    api/authentication
-   api/chameleon_text
-   api/chameleon_zpt
    api/compat
    api/config
    api/events
diff --git a/docs/api/chameleon_text.rst b/docs/api/chameleon_text.rst
deleted file mode 100644
index 494f5b464..000000000
--- a/docs/api/chameleon_text.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-.. _chameleon_text_module:
-
-:mod:`pyramid.chameleon_text`
-----------------------------------
-
-.. automodule:: pyramid.chameleon_text
-
-  .. autofunction:: get_template
-
-  .. autofunction:: render_template
-
-  .. autofunction:: render_template_to_response
-
-These APIs will will work against template files which contain simple
-``${Genshi}`` - style replacement markers.
-
-The API of :mod:`pyramid.chameleon_text` is identical to that of
-:mod:`pyramid.chameleon_zpt`; only its import location is
-different.  If you need to import an API functions from this module as
-well as the :mod:`pyramid.chameleon_zpt` module within the same
-view file, use the ``as`` feature of the Python import statement,
-e.g.:
-
-.. code-block:: python
-   :linenos:
-
-   from pyramid.chameleon_zpt import render_template as zpt_render
-   from pyramid.chameleon_text import render_template as text_render
-
-
-
diff --git a/docs/api/chameleon_zpt.rst b/docs/api/chameleon_zpt.rst
deleted file mode 100644
index df9a36a56..000000000
--- a/docs/api/chameleon_zpt.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-.. _chameleon_zpt_module:
-
-:mod:`pyramid.chameleon_zpt`
--------------------------------
-
-.. automodule:: pyramid.chameleon_zpt
-
-  .. autofunction:: get_template
-
-  .. autofunction:: render_template
-
-  .. autofunction:: render_template_to_response
-
-These APIs will work against files which supply template text which
-matches the :term:`ZPT` specification.
-
-The API of :mod:`pyramid.chameleon_zpt` is identical to that of
-:mod:`pyramid.chameleon_text`; only its import location is
-different.  If you need to import an API functions from this module as
-well as the :mod:`pyramid.chameleon_text` module within the same
-view file, use the ``as`` feature of the Python import statement,
-e.g.:
-
-.. code-block:: python
-   :linenos:
-
-   from pyramid.chameleon_zpt import render_template as zpt_render
-   from pyramid.chameleon_text import render_template as text_render
diff --git a/docs/api/config.rst b/docs/api/config.rst
index cd58e74d3..5d2bce23e 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -36,9 +36,11 @@
      .. automethod:: set_authentication_policy
      .. automethod:: set_authorization_policy
      .. automethod:: set_default_permission
+     .. automethod:: add_permission
 
-   :methodcategory:`Setting Request Properties`
+   :methodcategory:`Extending the Request Object`
 
+     .. automethod:: add_request_method
      .. automethod:: set_request_property
 
    :methodcategory:`Using I18N`
@@ -66,6 +68,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/api/registry.rst b/docs/api/registry.rst
index e62e2ba6f..1d5d52248 100644
--- a/docs/api/registry.rst
+++ b/docs/api/registry.rst
@@ -38,3 +38,17 @@
 
    This class is new as of :app:`Pyramid` 1.3.
 
+.. autoclass:: Deferred
+
+   This class is new as of :app:`Pyramid` 1.4.
+
+.. autofunction:: undefer
+
+   This function is new as of :app:`Pyramid` 1.4.
+
+.. autoclass:: predvalseq
+
+   This class is new as of :app:`Pyramid` 1.4.
+
+
+
diff --git a/docs/api/settings.rst b/docs/api/settings.rst
index 6b12c038c..cd802e138 100644
--- a/docs/api/settings.rst
+++ b/docs/api/settings.rst
@@ -5,8 +5,6 @@
 
 .. automodule:: pyramid.settings
 
-  .. autofunction:: get_settings
-
   .. autofunction:: asbool
 
   .. autofunction:: aslist
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 45a79326f..34cf1b078 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -994,3 +994,10 @@ 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, view, or subscriber predicates to extend the configuration
+      system.  See :ref:`registering_thirdparty_predicates` for more
+      information.
+
diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index 2949dc808..165cf7474 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -294,6 +294,7 @@ These are the methods of the configurator which provide conflict detection:
 :meth:`~pyramid.config.Configurator.add_view`,
 :meth:`~pyramid.config.Configurator.add_route`,
 :meth:`~pyramid.config.Configurator.add_renderer`,
+:meth:`~pyramid.config.Configurator.add_request_method`,
 :meth:`~pyramid.config.Configurator.set_request_factory`,
 :meth:`~pyramid.config.Configurator.set_session_factory`,
 :meth:`~pyramid.config.Configurator.set_request_property`,
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index af53c1f78..3bdf8c5cd 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -349,7 +349,7 @@ setting) orderings using the ``ptweens`` command.  Tween factories
 will show up represented by their standard Python dotted name in the
 ``ptweens`` output.
 
-For example, here's the ``pwteens`` command run against a system
+For example, here's the ``ptweens`` command run against a system
 configured without any explicit tweens:
 
 .. code-block:: text
@@ -367,7 +367,7 @@ configured without any explicit tweens:
    1           pyramid.tweens.excview_tween_factory                excview
    -           -                                                   MAIN
 
-Here's the ``pwteens`` command run against a system configured *with*
+Here's the ``ptweens`` command run against a system configured *with*
 explicit tweens defined in its ``development.ini`` file:
 
 .. code-block:: text
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index a86826d86..ccaa6e9e2 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -127,7 +127,7 @@ defined imports and function definitions, placed within the confines of an
 
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 8-13
+   :lines: 9-15
 
 Let's break this down piece-by-piece.
 
@@ -136,7 +136,7 @@ Configurator Construction
 
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 8-9
+   :lines: 9-10
 
 The ``if __name__ == '__main__':`` line in the code sample above represents a
 Python idiom: the code inside this if clause is not invoked unless the script
@@ -169,7 +169,7 @@ Adding Configuration
 .. ignore-next-block
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 10-11
+   :lines: 11-12
 
 First line above calls the :meth:`pyramid.config.Configurator.add_route`
 method, which registers a :term:`route` to match any URL path that begins
@@ -189,7 +189,7 @@ WSGI Application Creation
 .. ignore-next-block
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 12
+   :lines: 13
 
 After configuring views and ending configuration, the script creates a WSGI
 *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app`
@@ -218,7 +218,7 @@ WSGI Application Serving
 .. ignore-next-block
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 13
+   :lines: 14-15
 
 Finally, we actually serve the application to requestors by starting up a
 WSGI server.  We happen to use the :mod:`wsgiref` ``make_server`` server
diff --git a/docs/narr/helloworld.py b/docs/narr/helloworld.py
index 7c26c8cdc..c01329af9 100644
--- a/docs/narr/helloworld.py
+++ b/docs/narr/helloworld.py
@@ -2,14 +2,15 @@ from wsgiref.simple_server import make_server
 from pyramid.config import Configurator
 from pyramid.response import Response
 
+
 def hello_world(request):
-   return Response('Hello %(name)s!' % request.matchdict)
+    return Response('Hello %(name)s!' % request.matchdict)
 
 if __name__ == '__main__':
-   config = Configurator()
-   config.add_route('hello', '/hello/{name}')
-   config.add_view(hello_world, route_name='hello')
-   app = config.make_wsgi_app()
-   server = make_server('0.0.0.0', 8080, app)
-   server.serve_forever()
+    config = Configurator()
+    config.add_route('hello', '/hello/{name}')
+    config.add_view(hello_world, route_name='hello')
+    app = config.make_wsgi_app()
+    server = make_server('0.0.0.0', 8080, app)
+    server.serve_forever()
    
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 332805152..96fa77a07 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -1232,3 +1232,203 @@ 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, Route, or Subscriber Predicate
+---------------------------------------------------------
+
+.. note::
+
+   Third-party view, route, and subscriber predicates are a feature new as of
+   Pyramid 1.4.
+
+.. _view_and_route_predicates:
+
+View and Route Predicates
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+View and route predicates used during 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 view or route predicate factory.  A view or route
+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.
+
+.. _subscriber_predicates:
+
+Subscriber Predicates
+~~~~~~~~~~~~~~~~~~~~~
+
+Subscriber predicates work almost exactly like view and route predicates.
+They narrow the set of circumstances in which a subscriber will be called.
+There are several minor differences between a subscriber predicate and a
+view/route predicate:
+
+- There are no default subscriber predicates.  You must register one to use
+  one.
+
+- The ``__call__`` method of a subscriber predicate accepts a single
+  ``event`` object instead of a ``context`` and a ``request``.
+
+- Not every subscriber predicate can be used with every event type.  Some
+  subscriber predicates will assume a certain event type.
+
+Here's an example of a subscriber predicate that can be used in conjunction
+with a subscriber that subscribes to the :class:`pyramid.events.NewReqest`
+event type.
+
+.. code-block:: python
+   :linenos:
+
+    class RequestPathStartsWith(object):
+        def __init__(self, val, config):
+            self.val = val
+
+        def text(self):
+            return 'path_startswith = %s' % (self.val,)
+
+        phash = text
+
+        def __call__(self, event):
+            return event.request.path.startswith(self.val)
+
+Once you've created a subscriber predicate, it may registered via
+:meth:`pyramid.config.Configurator.add_subscriber_predicate`.  For example:
+
+.. code-block:: python
+
+    config.add_subscriber_predicate(
+        'request_path_startswith', RequestPathStartsWith)
+
+Once a subscriber predicate is registered, you can use it in a call to
+:meth:`pyramid.config.Configurator.add_subscriber` or to
+:class:`pyramid.events.subscriber`.  Here's an example of using the
+previously registered ``request_path_startswith`` predicate in a call to
+:meth:`~pyramid.config.Configurator.add_subscriber`:
+
+.. code-block:: python
+   :linenos:
+
+    # define a subscriber in your code
+
+    def yosubscriber(event):
+        event.request.yo = 'YO!'
+
+    # and at configuration time
+
+    config.add_subscriber(yosubscriber, NewRequest, 
+           request_path_startswith='/add_yo')
+
+Here's the same subscriber/predicate/event-type combination used via
+:class:`~pyramid.events.subscriber`.
+
+.. code-block:: python
+   :linenos:
+
+    from pyramid.events import subscriber
+
+    @subscriber(NewRequest, request_path_startswith='/add_yo')
+    def yosubscriber(event):
+        event.request.yo = 'YO!'
+
+In either of the above configurations, the ``yosubscriber`` callable will
+only be called if the request path starts with ``/add_yo``.  Otherwise the
+event subscriber will not be called.
+
+Note that the ``request_path_startswith`` subscriber you defined can be used
+with events that have a ``request`` attribute, but not ones that do not.  So,
+for example, the predicate can be used with subscribers registered for
+:class:`pyramid.events.NewRequest` and :class:`pyramid.events.ContextFound`
+events, but it cannot be used with subscribers registered for
+:class:`pyramid.events.ApplicationCreated` because the latter type of event
+has no ``request`` attribute.  The point being: unlike route and view
+predicates, not every type of subscriber predicate will necessarily be
+applicable for use in every subscriber registration.  It is not the
+responsibility of the predicate author to make every predicate make sense for
+every event type; it is the responsibility of the predicate consumer to use
+predicates that make sense for a particular event type registration.
+
+
+
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index b5fa6a9f7..7c0f9223f 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -803,7 +803,7 @@ within a function called when another user uses the
 See also :ref:`add_directive`.
 
 Programmatic Introspection
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you're building a large system that other users may plug code into, it's
 useful to be able to get an enumeration of what code they plugged in *at
@@ -831,7 +831,7 @@ callable:
 See also :ref:`using_introspection`.
 
 Python 3 Compatibility
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 Pyramid and most of its add-ons are Python 3 compatible.  If you develop a
 Pyramid application today, you won't need to worry that five years from now
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 57b5bc65b..63287e2cd 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -306,7 +306,9 @@ See :class:`pyramid.renderers.JSON` and
 JSONP Renderer
 ~~~~~~~~~~~~~~
 
-.. note:: This feature is new in Pyramid 1.1.
+.. note::
+
+   This feature is new in Pyramid 1.1.
 
 :class:`pyramid.renderers.JSONP` is a `JSONP
 <http://en.wikipedia.org/wiki/JSONP>`_ renderer factory helper which
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 860010a1a..656cf4773 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -534,6 +534,33 @@ And ``templates/mytemplate.pt`` might look like so:
       </span>
     </html>
 
+
+Using A Chameleon Macro Name Within a Renderer Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sommetime you'd like to render a macro inside of a Chameleon ZPT template
+instead of the full Chameleon ZPT template. To render the content of a
+``define-macro`` field inside a Chameleon ZPT template, given a Chameleon
+template file named ``foo.pt`` and a macro named ``bar`` defined within it
+(e.g. ``<div metal:define-macro="bar">...</div>``, you can configure the
+template as a :term:`renderer` like so:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import view_config
+
+   @view_config(renderer='foo#bar.pt')
+   def my_view(request):
+       return {'project':'my project'}
+
+The above will render the ``bar`` macro from within the ``foo.pt`` template
+instead of the entire template.
+
+.. note::
+
+   This feature is new in Pyramid 1.4.
+
 .. index::
    single: Chameleon text templates
 
@@ -714,12 +741,13 @@ This template doesn't use any advanced features of Mako, only the
 :term:`renderer globals`.  See the `the Mako documentation
 <http://www.makotemplates.org/>`_ to use more advanced features.
 
-Using def inside Mako Templates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using A Mako def name Within a Renderer Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To use a def inside a Mako template, given a :term:`Mako` template file named 
-``foo.mak`` and a def named ``bar``, you can configure the template as a 
-:term:`renderer` like so:
+Sommetime you'd like to render a ``def`` inside of a Mako template instead of
+the full Mako template. To render a def inside a Mako template, given a
+:term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can
+configure the template as a :term:`renderer` like so:
 
 .. code-block:: python
    :linenos:
@@ -730,6 +758,13 @@ To use a def inside a Mako template, given a :term:`Mako` template file named
    def my_view(request):
        return {'project':'my project'}
 
+The above will render the ``bar`` def from within the ``foo.mak`` template
+instead of the entire template.
+
+.. note::
+
+   This feature is new in Pyramid 1.4.
+
 .. index::
    single: automatic reloading of templates
    single: template automatic reload
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index 5ce2c8a66..50e9d5604 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -52,7 +52,7 @@ The suggested mechanism for unit and integration testing of a :app:`Pyramid`
 application is the Python :mod:`unittest` module.  Although this module is
 named :mod:`unittest`, it is actually capable of driving both unit and
 integration tests.  A good :mod:`unittest` tutorial is available within `Dive
-Into Python <http://diveintopython.nfshost.com/unit_testing/index.html>`_ by Mark
+Into Python <http://www.diveintopython.net/unit_testing/index.html>`_ by Mark
 Pilgrim.
 
 :app:`Pyramid` provides a number of facilities that make unit, integration,
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index f6ee9a8d5..9e41464a6 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -177,7 +177,7 @@ HTTP Exceptions
 ~~~~~~~~~~~~~~~
 
 All classes documented in the :mod:`pyramid.httpexceptions` module documented
-as inheriting from the :class:`pryamid.httpexceptions.HTTPException` are
+as inheriting from the :class:`pyramid.httpexceptions.HTTPException` are
 :term:`http exception` objects.  Instances of an HTTP exception object may
 either be *returned* or *raised* from within view code.  In either case
 (return or raise) the instance will be used as as the view's response.