diff options
| -rw-r--r-- | docs/glossary.rst | 6 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/latexindex.rst | 1 | ||||
| -rw-r--r-- | docs/narr/handlers.rst | 277 | ||||
| -rw-r--r-- | docs/narr/views.rst | 13 |
5 files changed, 10 insertions, 288 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst index 600092f87..3c6f5cb1a 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -859,3 +859,9 @@ Glossary ZCML declaration The concrete use of a :term:`ZCML directive` within a ZCML file. + pyramid_handlers + An add-on package which allows :app:`Pyramid` users to create classes + that are analogues of Pylons 1 "controllers". See + `http://docs.pylonsproject.org/projects/pyramid_handlers/dev/ + <http://docs.pylonsproject.org/projects/pyramid_handlers/dev/>`_. + diff --git a/docs/index.rst b/docs/index.rst index a5fc6f13a..030b4dc1c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,7 +45,6 @@ Narrative documentation in chapter form explaining how to use narr/renderers narr/templates narr/viewconfig - narr/handlers narr/resources narr/assets narr/webob diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 9716e26d0..2426ec4b0 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -38,7 +38,6 @@ Narrative Documentation narr/renderers narr/templates narr/viewconfig - narr/handlers narr/resources narr/assets narr/webob diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst deleted file mode 100644 index edeed2de8..000000000 --- a/docs/narr/handlers.rst +++ /dev/null @@ -1,277 +0,0 @@ -.. _handlers_chapter: - -View Handlers -============= - -:app:`Pyramid` provides the special concept of a :term:`view handler`. View -handlers are view classes that implement a number of methods, each of which -is a :term:`view callable` as a convenience for :term:`URL dispatch` users. - -.. note:: - - View handlers are *not* useful when using :term:`traversal`, only when using - :term:`url dispatch`. If you are not using url dispatch, you can skip this - chapter. - -Using a view handler instead of a plain function or class :term:`view -callable` makes it unnecessary to call -:meth:`pyramid.config.Configurator.add_route` (and/or -:meth:`pyramid.config.Configurator.add_view`) "by hand" multiple times, -making it more pleasant to register a collection of views as a single class -when using :term:`url dispatch`. The view handler machinery also introduces -the concept of an ``action``, which is used as a :term:`view predicate` to -control which method of the handler is called. The method name is the -default *action name* of a handler view callable. - -The concept of a view handler is analogous to a "controller" in Pylons 1.0. - -The view handler class is initialized by :app:`Pyramid` in the same manner as -a "plain" view class. Its ``__init__`` is called with a request object (see -:ref:`class_as_view`). It implements methods, each of which is a :term:`view -callable`. When a request enters the system which corresponds with an -*action* related to one of its view callable methods, this method is called, -and it is expected to return a response. - -Here's an example view handler class: - -.. code-block:: python - :linenos: - - from pyramid.response import Response - - from pyramid.view import action - - class Hello(object): - def __init__(self, request): - self.request = request - - def index(self): - return Response('Hello world!') - - @action(renderer="mytemplate.mak") - def bye(self): - return {} - -The :class:`pyramid.view.action` decorator is used to fine-tune the view -parameters for each potential view callable which is a method of the handler. - -.. _using_add_handler: - -Handler Registration Using :meth:`~pyramid.config.Configurator.add_handler` ---------------------------------------------------------------------------- - -Handlers are added to application configuration via the -:meth:`pyramid.config.Configurator.add_handler` API. The -:meth:`~pyramid.config.Configurator.add_handler` method will scan a -:term:`view handler` class and automatically set up view configurations for -its methods that represent "auto-exposed" view callable, or those that were -decorated explicitly with the :class:`~pyramid.view.action` decorator. This -decorator is used to setup additional view configuration information for -individual methods of the class, and can be used repeatedly for a single view -method to register multiple view configurations for it. - -.. code-block:: python - :linenos: - - from myapp.handlers import Hello - config.add_handler('hello', '/hello/{action}', handler=Hello) - -This example will result in a route being added for the pattern -``/hello/{action}``, and each method of the ``Hello`` class will then be -examined to see if it should be registered as a potential view callable when -the ``/hello/{action}`` pattern matches. The value of ``{action}`` in the -route pattern will be used to determine which view should be called, and each -view in the class will be setup with a view predicate that requires a -specific ``action`` name. By default, the action name for a method of a -handler is the method name. - -If the URL was ``/hello/index``, the above example pattern would match, and, -by default, the ``index`` method of the ``Hello`` class would be called. - -Alternatively, the action can be declared specifically for a URL to be -registered for a *specific* ``action`` name: - -.. code-block:: python - :linenos: - - from myapp.handlers import Hello - config.add_handler('hello_index', '/hello/index', - handler=Hello, action='index') - -This will result one of the methods that are configured for the ``action`` of -'index' in the ``Hello`` handler class to be called. In this case the name of -the method is the same as the action name: ``index``. However, this need not -be the case, as we will see below. - -When calling :meth:`~pyramid.config.Configurator.add_handler`, an ``action`` -is required in either the route pattern or as a keyword argument, but -**cannot appear in both places**. A ``handler`` argument must also be -supplied, which can be either a :term:`asset specification` or a Python -reference to the handler class. Additional keyword arguments are passed -directly through to :meth:`pyramid.config.Configurator.add_route`. - -For example: - -.. code-block:: python - :linenos: - - config.add_handler('hello', '/hello/{action}', - handler='mypackage.handlers.MyHandler') - -Multiple :meth:`~pyramid.config.Configurator.add_handler` calls can specify -the same handler, to register specific route names for different -handler/action combinations. For example: - -.. code-block:: python - :linenos: - - config.add_handler('hello_index', '/hello/index', - handler=Hello, action='index') - config.add_handler('bye_index', '/hello/bye', - handler=Hello, action='bye') - -.. note:: - - Handler configuration may also be added to the system via :term:`ZCML` (see - :ref:`zcml_handler_configuration`). - -View Setup in the Handler Class -------------------------------- - -A handler class can have a single class level attribute called -``__autoexpose__`` which should be a regular expression or the value -``None``. It's used to determine which method names will result in additional -view configurations being registered. - -When :meth:`~pyramid.config.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 was -decorated with :class:`~pyramid.view.action`. - -Every method in the handler class that has a name meeting the -``__autoexpose__`` regular expression will have a view registered for an -``action`` name corresponding to the method name. This functionality can be -disabled by setting the ``__autoexpose__`` attribute to ``None``: - -.. code-block:: python - :linenos: - - from pyramid.view import action - - class Hello(object): - __autoexpose__ = None - - def __init__(self, request): - self.request = request - - @action() - def index(self): - return Response('Hello world!') - - @action(renderer="mytemplate.mak") - def bye(self): - return {} - -With auto-expose effectively disabled, no views will be registered for a -method unless it is specifically decorated with -:class:`~pyramid.view.action`. - -Action Decorators in a Handler ------------------------------- - -The :class:`~pyramid.view.action` decorator registers view configuration -information on the handler method, which is used by -:meth:`~pyramid.config.Configurator.add_handler` to setup the view -configuration. - -All keyword arguments are recorded, and passed to -:meth:`~pyramid.config.Configurator.add_view`. Any valid keyword arguments -for :meth:`~pyramid.config.Configurator.add_view` can thus be used with the -:class:`~pyramid.view.action` decorator to further restrict when the view -will be called. - -One important difference is that a handler method can respond to an -``action`` name that is different from the method name by passing in a -``name`` argument. - -Example: - -.. code-block:: python - :linenos: - - from pyramid.view import action - - class Hello(object): - def __init__(self, request): - self.request = request - - @action(name='index', renderer='created.mak', request_method='POST') - def create(self): - return {} - - @action(renderer="view_all.mak", request_method='GET') - def index(self): - return {} - -This will register two views that require the ``action`` to be ``index``, -with the additional view predicate requiring a specific request method. - -It can be useful to decorate a single method multiple times with -:class:`~pyramid.view.action`. Each action decorator will register a new view -for the method. By specifying different names and renderers for each action, -the same view logic can be exposed and rendered differently on multiple URLs. - -Example: - -.. code-block:: python - :linenos: - - from pyramid.view import action - - class Hello(object): - def __init__(self, request): - self.request = request - - @action(name='home', renderer='home.mak') - @action(name='about', renderer='about.mak') - def show_template(self): - # prep some template vars - return {} - - # in the config - config.add_handler('hello', '/hello/{action}', handler=Hello) - -With this configuration, the url ``/hello/home`` will find a view -configuration that results in calling the ``show_template`` method, then -rendering the template with ``home.mak``, and the url ``/hello/about`` will -call the same method and render the ``about.mak`` template. - -Handler ``__action_decorator__`` Attribute ------------------------------------------- - -If a handler class has an ``__action_decorator__`` attribute, then the -value of the class attribute will be passed in as the ``decorator`` -argument every time a handler action is registered as a view callable. -This means that, like anything passed to ``add_view()`` as the -``decorator`` argument, ``__action_decorator__`` must be a callable -accepting a single argument. This argument will itself be a callable -accepting ``(context, request)`` arguments, and -``__action_decorator__`` must return a replacement callable with the -same call signature. - -Note that, since handler actions are registered as views against the -handler class and not a handler instance, any ``__action_decorator__`` -attribute must *not* be a regular instance method. Defining an -``__action_decorator__`` instance method on a handler class will -result in a :exc:`ConfigurationError`. Instead, ``__action_decorator__`` -can be any other type of callable: a staticmethod, classmethod, function, -or some sort of callable instance. - -.. note:: - - In a Pylons 1.0 controller, it was possible to override the ``__call__()`` - method, which allowed a developer to "wrap" the entire action invocation, - with a try/except or any other arbitrary code. In :app:`Pyramid`, this - can be emulated with the use of an ``__action_decorator__`` classmethod - on your handler class. - diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 3e0451383..e1eacfeae 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -130,15 +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. -.. 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 - multiple view callables similar to "controllers" in Pylons 1.0. See - the :ref:`handlers_chapter` chapter for details. +.. note:: A package named :term:`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. .. index:: single: view calling convention |