fix merge conflict

13 files changed, 43 insertions, 243 deletions

diff --git a/docs/api/config.rst b/docs/api/config.rst
index 3f37e739c..b4f85c248 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -48,8 +48,6 @@
 
      .. automethod:: add_translation_dirs
 
-     .. automethod:: add_handler
-
      .. automethod:: add_view
 
      .. automethod:: derive_view
@@ -76,6 +74,8 @@
 
      .. automethod:: set_renderer_globals_factory
 
+     .. automethod:: add_directive
+
      .. automethod:: testing_securitypolicy
 
      .. automethod:: testing_resources
diff --git a/docs/glossary.rst b/docs/glossary.rst
index a7e3a7884..93d6253cc 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -285,7 +285,7 @@ Glossary
    WSGI
      `Web Server Gateway Interface <http://wsgi.org/>`_.  This is a
      Python standard for connecting web applications to web servers,
-     similar to the concept of Java Servlets.  ``pyramid`` requires
+     similar to the concept of Java Servlets.  :app:`Pyramid` requires
      that your application be served as a WSGI application.
 
    middleware
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index e5a83bfff..2e6be2f3f 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -126,7 +126,6 @@ ZCML Directive Reference
    zcml/configure
    zcml/default_permission
    zcml/forbidden
-   zcml/handler
    zcml/include
    zcml/localenegotiator
    zcml/notfound
diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index f8b3ee191..eb9b70b12 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -301,9 +301,6 @@ These are the methods of the configurator which provide conflict detection:
 Some other methods of the configurator also indirectly provide conflict
 detection, because they're implemented in terms of conflict-aware methods:
 
-- :meth:`~pyramid.config.Configurator.add_handler`, a frontend for
-  ``add_route`` and ``add_view``.
-
 - :meth:`~pyramid.config.Configurator.add_route` does a second type of
   conflict detection when a ``view`` parameter is passed (it calls
   ``add_view``).
@@ -338,6 +335,23 @@ Instead, use :meth:`pyramid.config.Configuration.include`:
 Using ``include`` rather than calling the function directly will allow
 :ref:`automatic_conflict_resolution` to work.
 
+:meth:`pyramid.config.Configuration.include` can also accept a :term:`module`
+as an argument:
+
+.. code-block:: python
+   :linenos:
+
+   import myapp
+
+   config.include(myapp)
+
+For this to work properly, the ``myapp`` module must contain a callable with
+the special name ``includeme``, which should perform configuration (like the
+``add_routes`` callable we showed above as an example).
+
+:meth:`pyramid.config.Configuration.include` can also accept a :term:`dotted
+Python name` to a function or a module.
+
 .. note: See :ref:`the_include_tag` for a declarative alternative to
    :meth:`pyramid.config.Configurator.include`.
 
@@ -387,8 +401,7 @@ used, two-phase configuration is disabled, and configuration statements must
 be ordered in dependency order.
 
 Some configuration methods, such as
-:meth:`pyramid.config.Configurator.add_route` and
-:meth:`pyramid.config.Configurator.add_handler` have internal ordering
+:meth:`pyramid.config.Configurator.add_route` have internal ordering
 constraints: they routes they imply require relative ordering.  Such ordering
 constraints are not absolved by two-phase configuration.  Routes are still
 added in configuration execution order.
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index f73ff231a..b1c1c419c 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -345,7 +345,7 @@ application's startup code.
 .. code-block:: python
    :linenos:
 
-   # .. every other add_route and/or add_handler declaration should come
+   # .. every other add_route declaration should come
    # before this one, as it will, by default, catch all requests
 
    config.add_route('catchall_static', '/*subpath', 'myapp.static.static_view')
diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst
index 5c731ab06..5c01ff491 100644
--- a/docs/narr/declarative.rst
+++ b/docs/narr/declarative.rst
@@ -704,46 +704,6 @@ is the order that they appear relative to each other in the ZCML file.
 See :ref:`route_directive` for full ``route`` ZCML directive
 documentation.
 
-.. _zcml_handler_configuration:
-
-Configuring a Handler via ZCML
-------------------------------
-
-Instead of using the imperative
-:meth:`pyramid.config.Configurator.add_handler` method to add a new
-route, you can alternately use :term:`ZCML`.  :ref:`handler_directive`
-statements in a :term:`ZCML` file used by your application is a sign that
-you're using :term:`URL dispatch`.  For example, the following :term:`ZCML
-declaration` causes a route to be added to the application.
-
-.. code-block:: xml
-   :linenos:
-
-   <handler
-     route_name="myroute"
-     pattern="/prefix/{action}"
-     handler=".handlers.MyHandler"
-    />
-
-.. note::
-
-   Values prefixed with a period (``.``) within the values of ZCML attributes
-   such as the ``handler`` attribute of a ``handler`` directive mean
-   "relative to the Python package directory in which this :term:`ZCML` file
-   is stored".  So if the above ``handler`` declaration was made inside a
-   ``configure.zcml`` file that lived in the ``hello`` package, you could
-   replace the relative ``.views.MyHandler`` with the absolute
-   ``hello.views.MyHandler`` Either the relative or absolute form is
-   functionally equivalent.  It's often useful to use the relative form, in
-   case your package's name changes.  It's also shorter to type.
-
-The order that the routes attached to handlers are evaluated when declarative
-configuration is used is the order that they appear relative to each other in
-the ZCML file.
-
-See :ref:`handler_directive` for full ``handler`` ZCML directive
-documentation.
-
 .. index::
    triple: view; zcml; static resource
 
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index 524dcb2ac..eb7f0b24e 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -121,9 +121,9 @@ ZCML ``<route>`` directive).  Views are declarations made using the
 directive).  Assets are files that are accessed by :app:`Pyramid` using the
 :term:`pkg_resources` API such as static files and templates via a
 :term:`asset specification`.  Other directives and configurator methods also
-deal in routes, views, and assets.  For example,
-:meth:`pyramid.config.Configurator.add_handler` adds a single route, and some
-number of views.
+deal in routes, views, and assets.  For example, ``add_handler`` directive of
+the ``pyramid_handlers`` package adds a single route, and some number of
+views.
 
 .. index::
    single: extending an existing application
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index c12a5abb4..96515c195 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -611,6 +611,7 @@ A user might make use of these framework components like so:
 
    from webob import Response
    from pyramid.config import Configurator
+   import pyramid_handlers
    from paste.httpserver import serve
 
    class MyController(BaseController):
@@ -619,6 +620,7 @@ A user might make use of these framework components like so:
 
    if __name__ == '__main__':
        config = Configurator()
+       config.include(pyramid_handlers)
        config.add_handler('one', '/{id}', MyController, action='index')
        config.add_handler('two', '/{action}/{id}', MyController)
        serve(config.make_wsgi_app())
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 46de560c2..a76a8ce51 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -30,9 +30,6 @@ and so therefore they are often referred to as "paster templates".
    single: pyramid_zodb paster template
    single: pyramid_alchemy paster template
    single: pyramid_routesalchemy paster template
-   single: pylons_minimal paster template
-   single: pylons_basic paster template
-   single: pylons_sqla paster template
 
 .. _additional_paster_templates:
 
@@ -74,20 +71,6 @@ The included templates are these:
   URL mapping via :term:`traversal` and persistence via
   :term:`SQLAlchemy`
 
-``pylons_minimal``
-  URL mapping via :term:`URL dispatch` and Pylons-style view handlers,
-  minimal setup, uses ``pyramid_beaker`` as a sessioning implementation.
-
-``pylons_basic``
-  URL mapping via :term:`URL dispatch` and Pylons-style view handlers, and
-  some extra functionality, uses ``pyramid_beaker`` as a sessioning
-  implementation.
-
-``pylons_sqla``
-  URL mapping via :term:`URL dispatch` and Pylons-style view handlers, some
-  extra functionality, and SQLAlchemy set up, uses ``pyramid_beaker`` as a
-  sessioning implementation.
-
 .. index::
    single: creating a project
    single: project
@@ -965,10 +948,10 @@ To this:
                     renderer='myproject:templates/mytemplate.pt')
 
 You can then continue to add files to the ``views`` directory, and refer to
-views or handler classes/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:
+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:
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 2e0068e63..9b2074a70 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -63,14 +63,15 @@ View configuration is performed in one of these ways:
   :meth:`pyramid.config.Configurator.add_route` method, passing a ``view``
   argument specifying a view callable.
 
-- by using the :meth:`pyramid.config.Configurator.add_handler` against a
-  :term:`view handler` class (useful only for :term:`URL dispatch`
-  applications).
+.. note:: You can also add view configuration by adding a ``<view>`` or
+   ``<route>`` declaration to :term:`ZCML` used by your application as per
+   :ref:`mapping_views_using_zcml_section`, :ref:`view_directive` or
+   :ref:`route_directive`.
 
-.. note:: You can also add view configuration by adding a ``<view>``,
-   ``<route>`` or ``<handler>`` declaration to :term:`ZCML` used by your
-   application as per :ref:`mapping_views_using_zcml_section`,
-   :ref:`view_directive`, :ref:`route_directive` or :ref:`handler_directive`.
+.. note:: A package named ``pyramid_handlers`` (available from PyPI) provides
+   an analogue of :term:`Pylons` -style "controllers", which are a special
+   kind of view class which provides more automation when your application
+   uses :term:`URL dispatch` solely.
 
 .. _view_configuration_parameters:
 
@@ -599,7 +600,6 @@ which is the view itself or a :term:`dotted Python name` to such an object.
 All other arguments are optional.  See
 :meth:`pyramid.config.Configurator.add_view` for more information.
 
-
 .. index::
    single: resource interfaces
 
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 4a54a6b16..3e0451383 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -130,8 +130,10 @@ method expected to return a response, you can either:
   values, each pointing at a different method of the class if you'd like the
   class to represent a collection of related view callables.
 
-- treat the class as a :term:`view handler` by using it as the ``handler=``
-  argument of a call to :meth:`pyramid.config.Configurator.add_handler`.
+.. note:: A package named ``pyramid_handlers`` (available from PyPI) provides
+   an analogue of :term:`Pylons` -style "controllers", which are a special
+   kind of view class which provides more automation when your application
+   uses :term:`URL dispatch` solely.
 
 .. note::
    You can also create :term:`view handler` classes that define
diff --git a/docs/zcml.rst b/docs/zcml.rst
index e5bbe5d4b..caced5c16 100644
--- a/docs/zcml.rst
+++ b/docs/zcml.rst
@@ -17,7 +17,6 @@ documentation is organized alphabetically by directive name.
    zcml/configure
    zcml/default_permission
    zcml/forbidden
-   zcml/handler
    zcml/include
    zcml/localenegotiator
    zcml/notfound
diff --git a/docs/zcml/handler.rst b/docs/zcml/handler.rst
deleted file mode 100644
index 64aac7e78..000000000
--- a/docs/zcml/handler.rst
+++ /dev/null
@@ -1,158 +0,0 @@
-.. _handler_directive:
-
-``handler``
------------
-
-The ``handler`` directive adds the configuration of a :term:`view handler` to
-the :term:`application registry`.
-
-Attributes
-~~~~~~~~~~
-
-``route_name``
-  The name of the route, e.g. ``myroute``.  This attribute is required.  It
-  must be unique among all defined handler and route names in a given
-  configuration.
-
-``pattern``
-  The pattern of the route e.g. ``ideas/{idea}``.  This attribute is
-  required.  See :ref:`route_pattern_syntax` for information about the syntax
-  of route patterns.  The name ``{action}`` is treated specially in handler
-  patterns.  See :ref:`using_add_handler` for a discussion of how
-  ``{action}`` in handler patterns is treated.
-
-``action``
-  If the action name is not specified in the ``pattern``, use this name as the 
-  handler action (method name).
-
-``factory``
-  The :term:`dotted Python name` to a function that will generate a
-  :app:`Pyramid` context object when the associated route matches.
-  e.g. ``mypackage.resources.MyResource``.  If this argument is not
-  specified, a default root factory will be used.
-
-``xhr``
-  This value should be either ``True`` or ``False``.  If this value is
-  specified and is ``True``, the :term:`request` must possess an
-  ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this
-  route to match.  This is useful for detecting AJAX requests issued
-  from jQuery, Prototype and other Javascript libraries.  If this
-  predicate returns false, route matching continues.
-
-``traverse``
-  If you would like to cause the :term:`context` to be something other
-  than the :term:`root` object when this route matches, you can spell
-  a traversal pattern as the ``traverse`` argument.  This traversal
-  pattern will be used as the traversal path: traversal will begin at
-  the root object implied by this route (either the global root, or
-  the object returned by the ``factory`` associated with this route).
-
-  The syntax of the ``traverse`` argument is the same as it is for
-  ``pattern``. For example, if the ``pattern`` provided to the
-  ``route`` directive is ``articles/{article}/edit``, and the
-  ``traverse`` argument provided to the ``route`` directive is
-  ``/{article}``, when a request comes in that causes the route to
-  match in such a way that the ``article`` match value is '1' (when
-  the request URI is ``/articles/1/edit``), the traversal path will be
-  generated as ``/1``.  This means that the root object's
-  ``__getitem__`` will be called with the name ``1`` during the
-  traversal phase.  If the ``1`` object exists, it will become the
-  :term:`context` of the request.  :ref:`traversal_chapter` has more
-  information about traversal.
-
-  If the traversal path contains segment marker names which are not
-  present in the ``pattern`` argument, a runtime error will occur.
-  The ``traverse`` pattern should not contain segment markers that do
-  not exist in the ``pattern``.
-
-  A similar combining of routing and traversal is available when a
-  route is matched which contains a ``*traverse`` remainder marker in
-  its ``pattern`` (see :ref:`using_traverse_in_a_route_pattern`).  The
-  ``traverse`` argument to the ``route`` directive allows you to
-  associate route patterns with an arbitrary traversal path without
-  using a a ``*traverse`` remainder marker; instead you can use other
-  match information.
-
-  Note that the ``traverse`` argument to the ``handler`` directive is
-  ignored when attached to a route that has a ``*traverse`` remainder
-  marker in its pattern.
-
-``request_method``
-  A string representing an HTTP method name, e.g. ``GET``, ``POST``,
-  ``HEAD``, ``DELETE``, ``PUT``.  If this argument is not specified,
-  this route will match if the request has *any* request method.  If
-  this predicate returns false, route matching continues.
-
-``path_info``
-  The value of this attribute represents a regular expression pattern
-  that will be tested against the ``PATH_INFO`` WSGI environment
-  variable.  If the regex matches, this predicate will be true.  If
-  this predicate returns false, route matching continues.
-
-``request_param``
-  This value can be any string.  A view declaration with this
-  attribute ensures that the associated route will only match when the
-  request has a key in the ``request.params`` dictionary (an HTTP
-  ``GET`` or ``POST`` variable) that has a name which matches the
-  supplied value.  If the value supplied to the attribute has a ``=``
-  sign in it, e.g. ``request_params="foo=123"``, then the key
-  (``foo``) must both exist in the ``request.params`` dictionary, and
-  the value must match the right hand side of the expression (``123``)
-  for the route to "match" the current request.  If this predicate
-  returns false, route matching continues.
-
-``header``
-  The value of this attribute represents an HTTP header name or a
-  header name/value pair.  If the value contains a ``:`` (colon), it
-  will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
-  or ``Host:localhost``).  The *value* of an attribute that represent
-  a name/value pair should be a regular expression.  If the value does
-  not contain a colon, the entire value will be considered to be the
-  header name (e.g. ``If-Modified-Since``).  If the value evaluates to
-  a header name only without a value, the header specified by the name
-  must be present in the request for this predicate to be true.  If
-  the value evaluates to a header name/value pair, the header
-  specified by the name must be present in the request *and* the
-  regular expression specified as the value must match the header
-  value.  Whether or not the value represents a header name or a
-  header name/value pair, the case of the header name is not
-  significant.  If this predicate returns false, route matching
-  continues.
-
-``accept``
-  The value of this attribute represents a match query for one or more
-  mimetypes in the ``Accept`` HTTP request header.  If this value is
-  specified, it must be in one of the following forms: a mimetype
-  match token in the form ``text/plain``, a wildcard mimetype match
-  token in the form ``text/*`` or a match-all wildcard mimetype match
-  token in the form ``*/*``.  If any of the forms matches the
-  ``Accept`` header of the request, this predicate will be true.  If
-  this predicate returns false, route matching continues.
-
-``custom_predicates``
-  This value should be a sequence of references to custom predicate
-  callables.  Use custom predicates when no set of predefined
-  predicates does what you need.  Custom predicates can be combined
-  with predefined predicates as necessary.  Each custom predicate
-  callable should accept two arguments: ``info`` and ``request``
-  and should return either ``True`` or ``False`` after doing arbitrary
-  evaluation of the info and/or the request.  If all custom and
-  non-custom predicate callables return ``True`` the associated route
-  will be considered viable for a given request.  If any predicate
-  callable returns ``False``, route matching continues.  Note that the
-  value ``info`` passed to a custom route predicate is a dictionary
-  containing matching information; see :ref:`custom_route_predicates`
-  for more information about ``info``.
-
-
-Alternatives
-~~~~~~~~~~~~
-
-You can also add a :term:`route configuration` via:
-
-- Using the :meth:`pyramid.config.Configurator.add_handler` method.
-
-See Also
-~~~~~~~~
-
-See also :ref:`views_chapter`.