From 2fa5764cb1fd001550ae7c985333718667b86b1c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 16 Jan 2011 17:41:10 -0500 Subject: - The ``pylons_minimal``, ``pylons_basic`` and ``pylons_sqla`` paster templates were removed. Use ``pyramid_sqla`` (available from PyPI) as a generic replacement for Pylons-esque development. - All references to ``add_handler`` and the ``handler`` ZCML directive have been removed from the docs, and stubs which point to ``pylons_handlers`` package have replaced them. --- docs/narr/advconfig.rst | 6 +- docs/narr/assets.rst | 2 +- docs/narr/declarative.rst | 40 ------- docs/narr/extending.rst | 6 +- docs/narr/hooks.rst | 2 + docs/narr/project.rst | 25 +--- docs/narr/viewconfig.rst | 286 ++-------------------------------------------- docs/narr/views.rst | 6 +- 8 files changed, 23 insertions(+), 350 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index c983bbb57..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``). @@ -404,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: - - - -.. 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 ```` 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 c11fc1697..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 ```` or + ```` 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 ````, - ```` or ```` 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,277 +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. -.. _using_add_handler: - -Handler Registration Using :meth:`~pyramid.config.Configurator.add_handler` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -: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`. - -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. - -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. - .. index:: single: resource interfaces diff --git a/docs/narr/views.rst b/docs/narr/views.rst index e8cf2f83c..6ab8e9e45 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. .. index:: single: view calling convention -- cgit v1.2.3