Update handlers section to not reference __exposed__, and mention resource ...

Ben Bangert

2010-11-04 91f710f4716d0b9fff60c52502543548aef9135e

Update handlers section to not reference __exposed__, and mention
resource spec.

 docs/narr/handlers.rst

@@ -28,7 +28,7 @@

The :meth:`pyramid.configuration.Configurator.add_handler` method will scan
the handler class and automatically set up views for methods that are
auto-exposed or have an ``__exposed__`` attribute. The
auto-exposed or were decorated with :class:`~pyramid.view.action`. The
:class:`~pyramid.view.action` decorator is used to setup additional view
configuration information for individual class methods, and can be used
repeatedly for a single method to register multiple view configurations that
@@ -89,8 +89,21 @@

When calling :meth:`~pyramid.configuration.Configurator.add_handler`, an
``action`` is required in either the route pattern or as a keyword argument,
but **cannot appear in both places**. Additional keyword arguments are passed
but **cannot appear in both places**. A ``handler`` argument must also be
supplied, which can be either a :term:`resource specification` or a Python
reference to the handler class. Additional keyword arguments are passed
directly through to :meth:`pyramid.configuration.Configurator.add_route`.

For example:

.. code-block:: python
    
    config.add_handler('hello', '/hello/:action',
                       handler='mypackage.handlers:MyHandler')

In larger applications, it is advised to use a :term:`resource specification`
with :meth:`~pyramid.configuration.Configurator.add_handler` to avoid having
to import every handler class.

Multiple :meth:`~pyramid.configuration.Configurator.add_handler` calls can
specify the same handler, to register specific route names for different
@@ -115,9 +128,7 @@
When :meth:`~pyramid.configuration.Configurator.add_handler` runs, every
method in the handler class will be searched and a view registered if the
method name matches the ``__autoexpose__`` regular expression, or if the
method has a ``__exposed__`` attribute. The ``__exposed__`` attribute for a
function should never be set manually, the :class:`~pyramid.view.action`
decorator will configure it.
method was decorated with :class:`~pyramid.view.action`.

Auto-exposed Views
------------------
@@ -152,13 +163,13 @@
----------------

The :class:`~pyramid.view.action` decorator registers view configuration
information on the method's ``__exposed__`` attribute, which is used by
information on the handler method which is used by
:meth:`~pyramid.configuration.Configurator.add_handler` to setup the view
configuration.

All keyword arguments are recorded, and passed to
:meth:`pyramid.configuration.Configurator.add_view`. Any valid keyword
arguments for :meth:`pyramid.configuration.Configurator.add_view` can thus be
:meth:`!pyramid.configuration.Configurator.add_view`. Any valid keyword
arguments for :meth:`!pyramid.configuration.Configurator.add_view` can thus be
used with the :class:`~pyramid.view.action` decorator to further restrict when
the view will be called.