From 9e7162eb7f584e8afdbc2f04846d0d7e1fcf676c Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 7 Jul 2011 02:02:48 -0500 Subject: Updated proutes and pviews docs. --- docs/narr/viewconfig.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index ec42446ff..67ac39259 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -795,10 +795,11 @@ For a big application with several views, it can be hard to keep the view configuration details in your head, even if you defined all the views yourself. You can use the ``paster pviews`` command in a terminal window to print a summary of matching routes and views for a given URL in your -application. The ``paster pviews`` command accepts three arguments. The -first argument to ``pviews`` is the path to your application's ``.ini`` file. -The second is the ``app`` section name inside the ``.ini`` file which points -to your application. The third is the URL to test for matching views. +application. The ``paster pviews`` command accepts two arguments. The +first argument to ``pviews`` is the path to your application's ``.ini`` file +and section name inside the ``.ini`` file which points to your application. +This should be of the format ``config_file#section_name``. The second argument +is the URL to test for matching views. Here is an example for a simple view configuration using :term:`traversal`: @@ -829,7 +830,7 @@ A more complex configuration might generate something like this: .. code-block:: text :linenos: - $ ../bin/paster pviews development.ini shootout /about + $ ../bin/paster pviews development.ini#shootout /about URL = /about -- cgit v1.2.3 From 026da8ec4711d3532e5e4d8265bf445d4a329245 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jul 2011 04:13:38 -0400 Subject: earlier info referenced later info, fix --- docs/narr/viewconfig.rst | 54 +++++++++++++++++++++--------------------------- 1 file changed, 24 insertions(+), 30 deletions(-) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 67ac39259..f7509e9db 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -47,7 +47,7 @@ to be invoked. A view configuration statement is made about information present in the :term:`context` resource and the :term:`request`. -View configuration is performed in one of these ways: +View configuration is performed in one of two ways: - by running a :term:`scan` against application source code which has a :class:`pyramid.view.view_config` decorator attached to a Python object as @@ -56,17 +56,6 @@ View configuration is performed in one of these ways: - by using the :meth:`pyramid.config.Configurator.add_view` method as per :ref:`mapping_views_using_imperative_config_section`. -- By specifying a view within a :term:`route configuration`. View - configuration via a route configuration is performed by using the - :meth:`pyramid.config.Configurator.add_route` method, passing a ``view`` - argument specifying a view callable. This pattern of view configuration is - deprecated as of :app:`Pyramid` 1.1. - -.. 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: View Configuration Parameters @@ -408,26 +397,25 @@ configured view. View Configuration Using the ``@view_config`` Decorator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For better locality of reference, you may use the -:class:`pyramid.view.view_config` decorator to associate your view functions -with URLs instead of using imperative configuration for the same purpose. - .. warning:: Using this feature tends to slows down application startup slightly, as more work is performed at application startup to scan for view - declarations. + declarations. For maximum startup performance, use the view configuration + method described in :ref:`mapping_views_using_imperative_config_section` + instead. Usage of the ``view_config`` decorator is a form of :term:`declarative -configuration` in decorator form. :class:`~pyramid.view.view_config` can be -used to associate :term:`view configuration` information -- as done via the -equivalent imperative code -- with a function that acts as a :app:`Pyramid` -view callable. All arguments to the -:meth:`pyramid.config.Configurator.add_view` method (save for the ``view`` -argument) are available in decorator form and mean precisely the same thing. +configuration`. The :class:`~pyramid.view.view_config` decorator can be used +to associate :term:`view configuration` information with a function that acts +as a :app:`Pyramid` view callable. All arguments to the +:class:`~pyramid.view.view_config` decorator mean precisely the same thing as +they would if they were passed as arguments to the +:meth:`pyramid.config.Configurator.add_view` method save for the ``view`` +argument. -An example of the :class:`~pyramid.view.view_config` decorator might reside in -a :app:`Pyramid` application module ``views.py``: +Here's an example of the :class:`~pyramid.view.view_config` decorator that +lives within a :app:`Pyramid` application module ``views.py``: .. ignore-next-block .. code-block:: python @@ -618,9 +606,10 @@ View Registration Using :meth:`~pyramid.config.Configurator.add_view` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :meth:`pyramid.config.Configurator.add_view` method within -:ref:`configuration_module` is used to configure a view imperatively. The -arguments to this method are very similar to the arguments that you provide -to the ``@view_config`` decorator. For example: +:ref:`configuration_module` is used to configure a view "imperatively" +(without a :class:`~pyramid.view.view_config` decorator. The arguments to +this method are very similar to the arguments that you provide to the +:class:`~pyramid.view.view_config` decorator. For example: .. code-block:: python :linenos: @@ -636,8 +625,13 @@ to the ``@view_config`` decorator. For example: The first argument, ``view``, is required. It must either be a Python object 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. +In the above example, ``view`` is the ``hello_world`` function. All other +arguments are optional. See :meth:`pyramid.config.Configurator.add_view` for +more information. + +When you use only :meth:`~pyramid.config.Configurator.add_view` to add view +configurations, you don't need to issue a :term:`scan` in order for the view +configuration to take effect. .. index:: single: resource interfaces -- cgit v1.2.3 From e81ad8ca6355d85462508f03496fe7b088986601 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jul 2011 04:26:26 -0400 Subject: simplify wording --- docs/narr/viewconfig.rst | 91 ++++++++++++++++++++++-------------------------- 1 file changed, 41 insertions(+), 50 deletions(-) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index f7509e9db..326d97506 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -2,38 +2,23 @@ .. _view_configuration: +.. _view_lookup: + View Configuration ================== .. index:: single: view lookup -:term:`View configuration` controls how :term:`view lookup` operates in -your application. In earlier chapters, you have been exposed to a few -simple view configuration declarations without much explanation. In this -chapter we will explore the subject in detail. - -.. _view_lookup: - -View Lookup and Invocation --------------------------- - :term:`View lookup` is the :app:`Pyramid` subsystem responsible for finding -an invoking a :term:`view callable`. The view lookup subsystem is passed a -:term:`context` and a :term:`request` object. - -:term:`View configuration` information stored within in the -:term:`application registry` is compared against the context and request by -the view lookup subsystem in order to find the "best" view callable for the -set of circumstances implied by the context and request. - -:term:`View predicate` attributes are an important part of view -configuration that enables the :term:`View lookup` subsystem to find and -invoke the appropriate view. Predicate attributes can be thought of -like "narrowers". In general, the greater number of predicate -attributes possessed by a view's configuration, the more specific the -circumstances need to be before the registered view callable will be -invoked. +an invoking a :term:`view callable`. :term:`View configuration` controls how +:term:`view lookup` operates in your application. During any given request, +view configuration information is compared against request data by the view +lookup subsystem in order to find the "best" view callable for that request. + +In earlier chapters, you have been exposed to a few simple view configuration +declarations without much explanation. In this chapter we will explore the +subject in detail. Mapping a Resource or URL Pattern to a View Callable ---------------------------------------------------- @@ -68,12 +53,15 @@ arguments. View predicate arguments used during view configuration are used to narrow the set of circumstances in which :term:`view lookup` will find a particular view callable. -In general, the fewer number of predicates which are supplied to a -particular view configuration, the more likely it is that the associated -view callable will be invoked. The greater the number supplied, the -less likely. A view with five predicates will always be found and -evaluated before a view with two, for example. All predicates must -match for the associated view to be called. +:term:`View predicate` attributes are an important part of view configuration +that enables the :term:`view lookup` subsystem to find and invoke the +appropriate view. The greater number of predicate attributes possessed by a +view's configuration, the more specific the circumstances need to be before +the registered view callable will be invoked. The fewer number of predicates +which are supplied to a particular view configuration, the more likely it is +that the associated view callable will be invoked. A view with five +predicates will always be found and evaluated before a view with two, for +example. All predicates must match for the associated view to be called. This does not mean however, that :app:`Pyramid` "stops looking" when it finds a view registration with predicates that don't match. If one set @@ -88,8 +76,8 @@ the request, :app:`Pyramid` will return an error to the user's browser, representing a "not found" (404) page. See :ref:`changing_the_notfound_view` for more information about changing the default notfound view. -Some view configuration arguments are non-predicate arguments. These tend to -modify the response of the view callable or prevent the view callable from +Other view configuration arguments are non-predicate arguments. These tend +to modify the response of the view callable or prevent the view callable from being invoked due to an authorization policy. The presence of non-predicate arguments in a view configuration does not narrow the circumstances in which the view callable will be invoked. @@ -394,25 +382,20 @@ configured view. .. _mapping_views_using_a_decorator_section: -View Configuration Using the ``@view_config`` Decorator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adding View Configuration Using the ``@view_config`` Decorator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. warning:: Using this feature tends to slows down application startup slightly, as more work is performed at application startup to scan for view - declarations. For maximum startup performance, use the view configuration - method described in :ref:`mapping_views_using_imperative_config_section` - instead. - -Usage of the ``view_config`` decorator is a form of :term:`declarative -configuration`. The :class:`~pyramid.view.view_config` decorator can be used -to associate :term:`view configuration` information with a function that acts -as a :app:`Pyramid` view callable. All arguments to the -:class:`~pyramid.view.view_config` decorator mean precisely the same thing as -they would if they were passed as arguments to the -:meth:`pyramid.config.Configurator.add_view` method save for the ``view`` -argument. + configuration declarations. For maximum startup performance, use the view + configuration method described in + :ref:`mapping_views_using_imperative_config_section` instead. + +The :class:`~pyramid.view.view_config` decorator can be used to associate +:term:`view configuration` information with a function, method, or class that +acts as a :app:`Pyramid` view callable. Here's an example of the :class:`~pyramid.view.view_config` decorator that lives within a :app:`Pyramid` application module ``views.py``: @@ -482,6 +465,14 @@ See :ref:`configuration_module` for additional API arguments to the allows you to supply a ``package`` argument to better control exactly *which* code will be scanned. +All arguments to the :class:`~pyramid.view.view_config` decorator mean +precisely the same thing as they would if they were passed as arguments to +the :meth:`pyramid.config.Configurator.add_view` method save for the ``view`` +argument. Usage of the :class:`~pyramid.view.view_config` decorator is a +form of :term:`declarative configuration`, while +:meth:`pyramid.config.Configurator.add_view` is a form of :term:`imperative +configuration`. However, they both do the same thing. + ``@view_config`` Placement ++++++++++++++++++++++++++ @@ -602,12 +593,12 @@ against the ``amethod`` method could be spelled equivalently as the below: .. _mapping_views_using_imperative_config_section: -View Registration Using :meth:`~pyramid.config.Configurator.add_view` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adding View Configuration Using :meth:`~pyramid.config.Configurator.add_view` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :meth:`pyramid.config.Configurator.add_view` method within :ref:`configuration_module` is used to configure a view "imperatively" -(without a :class:`~pyramid.view.view_config` decorator. The arguments to +(without a :class:`~pyramid.view.view_config` decorator). The arguments to this method are very similar to the arguments that you provide to the :class:`~pyramid.view.view_config` decorator. For example: -- cgit v1.2.3 From e573d4356ed0371f5ba34ff3ff396fefd2e55913 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 12 Jul 2011 20:56:53 -0400 Subject: - New environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and new configuration file value ``prevent_http_cache``. These are synomymous and allow you to prevent HTTP cache headers from being set by Pyramid's ``http_cache`` machinery globally in a process. see the "Influencing HTTP Caching" section of the "View Configuration" narrative chapter and the detailed documentation for this setting in the "Environment Variables and Configuration Settings" narrative chapter. - New documentation section in View Configuration narrative chapter: "Influencing HTTP Caching". --- docs/narr/viewconfig.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 326d97506..1ef40e89f 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -82,6 +82,8 @@ being invoked due to an authorization policy. The presence of non-predicate arguments in a view configuration does not narrow the circumstances in which the view callable will be invoked. +.. _nonpredicate_view_args: + Non-Predicate Arguments +++++++++++++++++++++++ @@ -767,6 +769,54 @@ found will be printed to ``stderr``, and the browser representation of the error will include the same information. See :ref:`environment_chapter` for more information about how, and where to set these values. +.. index:: + single: HTTP caching + +.. _influencing_http_caching: + +Influencing HTTP Caching +------------------------ + +.. note:: This feature is new in Pyramid 1.1. + +When a non-``None`` ``http_cache`` argument is passed to a view +configuration, Pyramid will set ``Expires`` and ``Cache-Control`` response +headers in the resulting response, causing browsers to cache the response +data for some time. See ``http_cache`` in :ref:`nonpredicate_view_args` for +the its allowable values and what they mean. + +Sometimes it's undesirable to have these headers set as the result of +returning a response from a view, even though you'd like to decorate the view +with a view configuration decorator that has ``http_cache``. Perhaps there's +an alternate branch in your view code that returns a response that should +never be cacheable, while the "normal" branch returns something that should +always be cacheable. If this is the case, set the ``prevent_auto`` attribute +of the ``response.cache_control`` object to a non-``False`` value. For +example, the below view callable is configured with a ``@view_config`` +decorator that indicates any response from the view should be cached for 3600 +seconds. However, the view itself prevents caching from taking place unless +there's a ``should_cache`` GET or POST variable: + +.. code-block:: python + + from pyramid.view import view_config + + @view_config(http_cache=3600) + def view(request): + response = Response() + if not 'should_cache' in request.params: + response.cache_control.prevent_auto = True + return response + +Note that the ``http_cache`` machinery will overwrite or add to caching +headers you set within the view itself unless you use ``preserve_auto``. + +You can also turn of the effect of ``http_cache`` entirely for the duration +of a Pyramid application lifetime. To do so, set the +``PYRAMID_PREVENT_HTTP_CACHE`` environment variable or the +``prevent_http_cache`` configuration value setting to a true value. For more +information, see :ref:`preventing_http_caching`. + .. index:: pair: matching views; printing single: paster pviews -- cgit v1.2.3 From 5fa17fdefe848d8004ca9a6daab19e1e1ea17b29 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 12 Jul 2011 20:59:11 -0400 Subject: clarify --- docs/narr/viewconfig.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 1ef40e89f..d33d78752 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -817,6 +817,11 @@ of a Pyramid application lifetime. To do so, set the ``prevent_http_cache`` configuration value setting to a true value. For more information, see :ref:`preventing_http_caching`. +Note that setting ``prevent_http_cache`` will have no effect on caching +headers that your application code itself sets. It will only prevent caching +headers that would have been set by the Pyramid HTTP caching machinery +invoked as the result of the ``http_cache`` argument to view configuration. + .. index:: pair: matching views; printing single: paster pviews -- cgit v1.2.3 From ae4c577d12a16396b45515e81415b2b16f8e93e8 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 13 Jul 2011 20:48:38 -0400 Subject: move all paster commands to a separate chapter --- docs/narr/viewconfig.rst | 103 +++-------------------------------------------- 1 file changed, 6 insertions(+), 97 deletions(-) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index d33d78752..a45ebae32 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -822,101 +822,10 @@ headers that your application code itself sets. It will only prevent caching headers that would have been set by the Pyramid HTTP caching machinery invoked as the result of the ``http_cache`` argument to view configuration. -.. index:: - pair: matching views; printing - single: paster pviews - -.. _displaying_matching_views: - -Displaying Matching Views for a Given URL ------------------------------------------ - -For a big application with several views, it can be hard to keep the view -configuration details in your head, even if you defined all the views -yourself. You can use the ``paster pviews`` command in a terminal window to -print a summary of matching routes and views for a given URL in your -application. The ``paster pviews`` command accepts two arguments. The -first argument to ``pviews`` is the path to your application's ``.ini`` file -and section name inside the ``.ini`` file which points to your application. -This should be of the format ``config_file#section_name``. The second argument -is the URL to test for matching views. - -Here is an example for a simple view configuration using :term:`traversal`: - -.. code-block:: text - :linenos: - - $ ../bin/paster pviews development.ini tutorial /FrontPage - - URL = /FrontPage - - context: - view name: - - View: - ----- - tutorial.views.view_page - required permission = view - -The output always has the requested URL at the top and below that all the -views that matched with their view configuration details. In this example -only one view matches, so there is just a single *View* section. For each -matching view, the full code path to the associated view callable is shown, -along with any permissions and predicates that are part of that view -configuration. - -A more complex configuration might generate something like this: - -.. code-block:: text - :linenos: - - $ ../bin/paster pviews development.ini#shootout /about - - URL = /about - - context: - view name: about - - Route: - ------ - route name: about - route pattern: /about - route path: /about - subpath: - route predicates (request method = GET) - - View: - ----- - shootout.views.about_view - required permission = view - view predicates (request_param testing, header X/header) - - Route: - ------ - route name: about_post - route pattern: /about - route path: /about - subpath: - route predicates (request method = POST) - - View: - ----- - shootout.views.about_view_post - required permission = view - view predicates (request_param test) - - View: - ----- - shootout.views.about_view_post2 - required permission = view - view predicates (request_param test2) - -In this case, we are dealing with a :term:`URL dispatch` application. This -specific URL has two matching routes. The matching route information is -displayed first, followed by any views that are associated with that route. -As you can see from the second matching route output, a route can be -associated with more than one view. - -For a URL that doesn't match any views, ``paster pviews`` will simply print -out a *Not found* message. +Debugging View Configuration +---------------------------- +See :ref:`displaying_matching_views` for information about how to display +each of the view callables that might match for a given URL. This can be an +effective way to figure out why a particular view callable is being called +instead of the one you'd like to be called. -- cgit v1.2.3 From cab6fc74a00f1e205c717ba08012a3ef0f20e0b4 Mon Sep 17 00:00:00 2001 From: AnneGilles Date: Thu, 14 Jul 2011 16:03:40 -0700 Subject: Edited docs/narr/viewconfig.rst via GitHub --- docs/narr/viewconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index a45ebae32..54d3fc4ff 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -11,7 +11,7 @@ View Configuration single: view lookup :term:`View lookup` is the :app:`Pyramid` subsystem responsible for finding -an invoking a :term:`view callable`. :term:`View configuration` controls how +and invoking a :term:`view callable`. :term:`View configuration` controls how :term:`view lookup` operates in your application. During any given request, view configuration information is compared against request data by the view lookup subsystem in order to find the "best" view callable for that request. -- cgit v1.2.3 From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/viewconfig.rst | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 54d3fc4ff..94b80a3f2 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -20,6 +20,10 @@ In earlier chapters, you have been exposed to a few simple view configuration declarations without much explanation. In this chapter we will explore the subject in detail. +.. index:: + pair: resource; mapping to view callable + pair: URL pattern; mapping to view callable + Mapping a Resource or URL Pattern to a View Callable ---------------------------------------------------- @@ -41,6 +45,9 @@ View configuration is performed in one of two ways: - by using the :meth:`pyramid.config.Configurator.add_view` method as per :ref:`mapping_views_using_imperative_config_section`. +.. index:: + single: view configuration parameters + .. _view_configuration_parameters: View Configuration Parameters @@ -475,6 +482,9 @@ form of :term:`declarative configuration`, while :meth:`pyramid.config.Configurator.add_view` is a form of :term:`imperative configuration`. However, they both do the same thing. +.. index:: + single: view_config placement + ``@view_config`` Placement ++++++++++++++++++++++++++ @@ -822,7 +832,10 @@ headers that your application code itself sets. It will only prevent caching headers that would have been set by the Pyramid HTTP caching machinery invoked as the result of the ``http_cache`` argument to view configuration. -Debugging View Configuration +.. index:: + pair: view configuration; debugging + +ebugging View Configuration ---------------------------- See :ref:`displaying_matching_views` for information about how to display -- cgit v1.2.3 From 8cb68208d42899b50025418812bb339f578d553f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 07:16:14 -0400 Subject: - Reordered chapters in narrative section for better new user friendliness. - Added more indexing markers to sections in documentation. --- docs/narr/viewconfig.rst | 133 +++++++---------------------------------------- 1 file changed, 19 insertions(+), 114 deletions(-) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 94b80a3f2..d776887c8 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -235,8 +235,10 @@ arguments that are supplied, the more specific, and narrower the usage of the configured view. ``name`` - The :term:`view name` required to match this view callable. Read - :ref:`traversal_chapter` to understand the concept of a view name. + The :term:`view name` required to match this view callable. A ``name`` + argument is typically only used when your application uses + :term:`traversal`. Read :ref:`traversal_chapter` to understand the concept + of a view name. If ``name`` is not supplied, the empty string is used (implying the default view). @@ -417,8 +419,7 @@ lives within a :app:`Pyramid` application module ``views.py``: from pyramid.view import view_config from pyramid.response import Response - @view_config(name='my_view', request_method='POST', context=MyResource, - permission='read') + @view_config(route_name='ok', request_method='POST', permission='read') def my_view(request): return Response('OK') @@ -429,9 +430,8 @@ configuration stanza: .. code-block:: python :linenos: - config.add_view('mypackage.views.my_view', name='my_view', - request_method='POST', context=MyResource, - permission='read') + config.add_view('mypackage.views.my_view', route_name='ok', + request_method='POST', permission='read') All arguments to ``view_config`` may be omitted. For example: @@ -499,7 +499,7 @@ If your view callable is a function, it may be used as a function decorator: from pyramid.view import view_config from pyramid.response import Response - @view_config(name='edit') + @view_config(route_name='edit') def edit(request): return Response('edited!') @@ -514,7 +514,7 @@ against a class as when they are applied against a function. For example: from pyramid.response import Response from pyramid.view import view_config - @view_config() + @view_config(route_name='hello') class MyView(object): def __init__(self, request): self.request = request @@ -539,7 +539,7 @@ decorator syntactic sugar, if you wish: def __call__(self): return Response('hello') - my_view = view_config()(MyView) + my_view = view_config(route_name='hello')(MyView) More than one :class:`~pyramid.view.view_config` decorator can be stacked on top of any number of others. Each decorator creates a separate view @@ -551,8 +551,8 @@ registration. For example: from pyramid.view import view_config from pyramid.response import Response - @view_config(name='edit') - @view_config(name='change') + @view_config(route_name='edit') + @view_config(route_name='change') def edit(request): return Response('edited!') @@ -570,7 +570,7 @@ The decorator can also be used against a method of a class: def __init__(self, request): self.request = request - @view_config(name='hello') + @view_config(route_name='hello') def amethod(self): return Response('hello') @@ -592,7 +592,7 @@ against the ``amethod`` method could be spelled equivalently as the below: from pyramid.response import Response from pyramid.view import view_config - @view_config(attr='amethod', name='hello') + @view_config(attr='amethod', route_name='hello') class MyView(object): def __init__(self, request): self.request = request @@ -624,7 +624,7 @@ this method are very similar to the arguments that you provide to the # config is assumed to be an instance of the # pyramid.config.Configurator class - config.add_view(hello_world, name='hello.html') + config.add_view(hello_world, route_name='hello') The first argument, ``view``, is required. It must either be a Python object which is the view itself or a :term:`dotted Python name` to such an object. @@ -636,102 +636,6 @@ When you use only :meth:`~pyramid.config.Configurator.add_view` to add view configurations, you don't need to issue a :term:`scan` in order for the view configuration to take effect. -.. index:: - single: resource interfaces - -.. _using_resource_interfaces: - -Using Resource Interfaces In View Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Instead of registering your views with a ``context`` that names a Python -resource *class*, you can optionally register a view callable with a -``context`` which is an :term:`interface`. An interface can be attached -arbitrarily to any resource object. View lookup treats context interfaces -specially, and therefore the identity of a resource can be divorced from that -of the class which implements it. As a result, associating a view with an -interface can provide more flexibility for sharing a single view between two -or more different implementations of a resource type. For example, if two -resource objects of different Python class types share the same interface, -you can use the same view configuration to specify both of them as a -``context``. - -In order to make use of interfaces in your application during view dispatch, -you must create an interface and mark up your resource classes or instances -with interface declarations that refer to this interface. - -To attach an interface to a resource *class*, you define the interface and -use the :func:`zope.interface.implements` function to associate the interface -with the class. - -.. code-block:: python - :linenos: - - from zope.interface import Interface - from zope.interface import implements - - class IHello(Interface): - """ A marker interface """ - - class Hello(object): - implements(IHello) - -To attach an interface to a resource *instance*, you define the interface and -use the :func:`zope.interface.alsoProvides` function to associate the -interface with the instance. This function mutates the instance in such a -way that the interface is attached to it. - -.. code-block:: python - :linenos: - - from zope.interface import Interface - from zope.interface import alsoProvides - - class IHello(Interface): - """ A marker interface """ - - class Hello(object): - pass - - def make_hello(): - hello = Hello() - alsoProvides(hello, IHello) - return hello - -Regardless of how you associate an interface, with a resource instance, or a -resource class, the resulting code to associate that interface with a view -callable is the same. Assuming the above code that defines an ``IHello`` -interface lives in the root of your application, and its module is named -"resources.py", the interface declaration below will associate the -``mypackage.views.hello_world`` view with resources that implement, or -provide, this interface. - -.. code-block:: python - :linenos: - - # config is an instance of pyramid.config.Configurator - - config.add_view('mypackage.views.hello_world', name='hello.html', - context='mypackage.resources.IHello') - -Any time a resource that is determined to be the :term:`context` provides -this interface, and a view named ``hello.html`` is looked up against it as -per the URL, the ``mypackage.views.hello_world`` view callable will be -invoked. - -Note, in cases where a view is registered against a resource class, and a -view is also registered against an interface that the resource class -implements, an ambiguity arises. Views registered for the resource class take -precedence over any views registered for any interface the resource class -implements. Thus, if one view configuration names a ``context`` of both the -class type of a resource, and another view configuration names a ``context`` -of interface implemented by the resource's class, and both view -configurations are otherwise identical, the view registered for the context's -class will "win". - -For more information about defining resources with interfaces for use within -view configuration, see :ref:`resources_which_implement_interfaces`. - .. index:: single: view security pair: security; view @@ -753,8 +657,9 @@ configuration using :meth:`~pyramid.config.Configurator.add_view`: # config is an instance of pyramid.config.Configurator - config.add_view('myproject.views.add_entry', name='add.html', - context='myproject.resources.IBlog', permission='add') + config.add_route('add', '/add.html', factory='mypackage.Blog') + config.add_view('myproject.views.add_entry', route_name='add', + permission='add') When an :term:`authorization policy` is enabled, this view will be protected with the ``add`` permission. The view will *not be called* if the user does @@ -835,7 +740,7 @@ invoked as the result of the ``http_cache`` argument to view configuration. .. index:: pair: view configuration; debugging -ebugging View Configuration +Debugging View Configuration ---------------------------- See :ref:`displaying_matching_views` for information about how to display -- cgit v1.2.3 From 875ded31e7fdd0c85d1c91458248581b9dd729d7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 30 Jul 2011 01:50:24 -0600 Subject: Updated all of the docs to reflect the new pyramid.* settings prefix. --- docs/narr/viewconfig.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/narr/viewconfig.rst') diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index d776887c8..a1b12ad2a 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -679,10 +679,10 @@ per :ref:`protecting_views`. It's useful to be able to debug :exc:`NotFound` error responses when they occur unexpectedly due to an application registry misconfiguration. To debug these errors, use the ``PYRAMID_DEBUG_NOTFOUND`` environment variable or the -``debug_notfound`` configuration file setting. Details of why a view was not -found will be printed to ``stderr``, and the browser representation of the -error will include the same information. See :ref:`environment_chapter` for -more information about how, and where to set these values. +``pyramid.debug_notfound`` configuration file setting. Details of why a view +was not found will be printed to ``stderr``, and the browser representation of +the error will include the same information. See :ref:`environment_chapter` +for more information about how, and where to set these values. .. index:: single: HTTP caching @@ -729,10 +729,10 @@ headers you set within the view itself unless you use ``preserve_auto``. You can also turn of the effect of ``http_cache`` entirely for the duration of a Pyramid application lifetime. To do so, set the ``PYRAMID_PREVENT_HTTP_CACHE`` environment variable or the -``prevent_http_cache`` configuration value setting to a true value. For more -information, see :ref:`preventing_http_caching`. +``pyramid.prevent_http_cache`` configuration value setting to a true value. +For more information, see :ref:`preventing_http_caching`. -Note that setting ``prevent_http_cache`` will have no effect on caching +Note that setting ``pyramid.prevent_http_cache`` will have no effect on caching headers that your application code itself sets. It will only prevent caching headers that would have been set by the Pyramid HTTP caching machinery invoked as the result of the ``http_cache`` argument to view configuration. -- cgit v1.2.3