diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/assets.rst | 430 | ||||
| -rw-r--r-- | docs/narr/viewconfig.rst | 557 |
2 files changed, 487 insertions, 500 deletions
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 1beabe8de..4c0013298 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -7,8 +7,8 @@ Static Assets ============= -An :term:`asset` is any file contained within a Python :term:`package` which -is *not* a Python source code file. For example, each of the following is an +An :term:`asset` is any file contained within a Python :term:`package` which is +*not* a Python source code file. For example, each of the following is an asset: - a GIF image file contained within a Python package or contained within any @@ -20,20 +20,20 @@ asset: - a JavaScript source file contained within a Python package or contained within any subdirectory of a Python package. -- A directory within a package that does not have an ``__init__.py`` - in it (if it possessed an ``__init__.py`` it would *be* a package). +- A directory within a package that does not have an ``__init__.py`` in it (if + it possessed an ``__init__.py`` it would *be* a package). - a :term:`Chameleon` or :term:`Mako` template file contained within a Python package. The use of assets is quite common in most web development projects. For example, when you create a :app:`Pyramid` application using one of the -available scaffolds, as described in :ref:`creating_a_project`, the -directory representing the application contains a Python :term:`package`. -Within that Python package, there are directories full of files which are -static assets. For example, there's a ``static`` directory which contains -``.css``, ``.js``, and ``.gif`` files. These asset files are delivered when -a user visits an application URL. +available scaffolds, as described in :ref:`creating_a_project`, the directory +representing the application contains a Python :term:`package`. Within that +Python package, there are directories full of files which are static assets. +For example, there's a ``static`` directory which contains ``.css``, ``.js``, +and ``.gif`` files. These asset files are delivered when a user visits an +application URL. .. index:: single: asset specifications @@ -45,10 +45,10 @@ Understanding Asset Specifications Let's imagine you've created a :app:`Pyramid` application that uses a :term:`Chameleon` ZPT template via the -:func:`pyramid.renderers.render_to_response` API. For example, the -application might address the asset using the :term:`asset specification` -``myapp:templates/some_template.pt`` using that API within a ``views.py`` -file inside a ``myapp`` package: +:func:`pyramid.renderers.render_to_response` API. For example, the application +might address the asset using the :term:`asset specification` +``myapp:templates/some_template.pt`` using that API within a ``views.py`` file +inside a ``myapp`` package: .. code-block:: python :linenos: @@ -66,23 +66,23 @@ two parts: - The *asset name* (``templates/some_template.pt``), relative to the package directory. -The two parts are separated by the colon character. +The two parts are separated by a colon ``:`` character. -:app:`Pyramid` uses the Python :term:`pkg_resources` API to resolve the -package name and asset name to an absolute (operating-system-specific) file -name. It eventually passes this resolved absolute filesystem path to the -Chameleon templating engine, which then uses it to load, parse, and execute -the template file. +:app:`Pyramid` uses the Python :term:`pkg_resources` API to resolve the package +name and asset name to an absolute (operating system-specific) file name. It +eventually passes this resolved absolute filesystem path to the Chameleon +templating engine, which then uses it to load, parse, and execute the template +file. There is a second form of asset specification: a *relative* asset specification. Instead of using an "absolute" asset specification which includes the package name, in certain circumstances you can omit the package name from the specification. For example, you might be able to use ``templates/mytemplate.pt`` instead of ``myapp:templates/some_template.pt``. -Such asset specifications are usually relative to a "current package." The +Such asset specifications are usually relative to a "current package". The "current package" is usually the package which contains the code that *uses* the asset specification. :app:`Pyramid` APIs which accept relative asset -specifications typically describe what the asset is relative to in their +specifications typically describe to what the asset is relative in their individual documentation. .. index:: @@ -96,17 +96,17 @@ Serving Static Assets :app:`Pyramid` makes it possible to serve up static asset files from a directory on a filesystem to an application user's browser. Use the -:meth:`pyramid.config.Configurator.add_static_view` to instruct -:app:`Pyramid` to serve static assets such as JavaScript and CSS files. This -mechanism makes a directory of static files available at a name relative to -the application root URL, e.g. ``/static`` or as an external URL. +:meth:`pyramid.config.Configurator.add_static_view` to instruct :app:`Pyramid` +to serve static assets, such as JavaScript and CSS files. This mechanism makes +a directory of static files available at a name relative to the application +root URL, e.g., ``/static``, or as an external URL. .. note:: - :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a - single file, nor can it serve a directory of static files directly - relative to the root URL of a :app:`Pyramid` application. For these - features, see :ref:`advanced_static`. + :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a single + file, nor can it serve a directory of static files directly relative to the + root URL of a :app:`Pyramid` application. For these features, see + :ref:`advanced_static`. Here's an example of a use of :meth:`~pyramid.config.Configurator.add_static_view` that will serve files up @@ -121,11 +121,11 @@ from the ``/var/www/static`` directory of the computer which runs the The ``name`` represents a URL *prefix*. In order for files that live in the ``path`` directory to be served, a URL that requests one of them must begin -with that prefix. In the example above, ``name`` is ``static``, and ``path`` -is ``/var/www/static``. In English, this means that you wish to serve the -files that live in ``/var/www/static`` as sub-URLs of the ``/static`` URL -prefix. Therefore, the file ``/var/www/static/foo.css`` will be returned -when the user visits your application's URL ``/static/foo.css``. +with that prefix. In the example above, ``name`` is ``static`` and ``path`` is +``/var/www/static``. In English this means that you wish to serve the files +that live in ``/var/www/static`` as sub-URLs of the ``/static`` URL prefix. +Therefore, the file ``/var/www/static/foo.css`` will be returned when the user +visits your application's URL ``/static/foo.css``. A static directory named at ``path`` may contain subdirectories recursively, and any subdirectories may hold files; these will be resolved by the static @@ -134,16 +134,16 @@ view for each particular type of file is dependent upon its file extension. By default, all files made available via :meth:`~pyramid.config.Configurator.add_static_view` are accessible by -completely anonymous users. Simple authorization can be required, however. -To protect a set of static files using a permission, in addition to passing -the required ``name`` and ``path`` arguments, also pass the ``permission`` -keyword argument to :meth:`~pyramid.config.Configurator.add_static_view`. -The value of the ``permission`` argument represents the :term:`permission` -that the user must have relative to the current :term:`context` when the -static view is invoked. A user will be required to possess this permission -to view any of the files represented by ``path`` of the static view. If your -static assets must be protected by a more complex authorization scheme, -see :ref:`advanced_static`. +completely anonymous users. Simple authorization can be required, however. To +protect a set of static files using a permission, in addition to passing the +required ``name`` and ``path`` arguments, also pass the ``permission`` keyword +argument to :meth:`~pyramid.config.Configurator.add_static_view`. The value of +the ``permission`` argument represents the :term:`permission` that the user +must have relative to the current :term:`context` when the static view is +invoked. A user will be required to possess this permission to view any of the +files represented by ``path`` of the static view. If your static assets must +be protected by a more complex authorization scheme, see +:ref:`advanced_static`. Here's another example that uses an :term:`asset specification` instead of an absolute path as the ``path`` argument. To convince @@ -163,14 +163,14 @@ may be a fully qualified :term:`asset specification` or an *absolute path*. Instead of representing a URL prefix, the ``name`` argument of a call to :meth:`~pyramid.config.Configurator.add_static_view` can alternately be a -*URL*. Each of examples we've seen so far have shown usage of the ``name`` -argument as a URL prefix. However, when ``name`` is a *URL*, static assets -can be served from an external webserver. In this mode, the ``name`` is used -as the URL prefix when generating a URL using +*URL*. Each of the examples we've seen so far have shown usage of the ``name`` +argument as a URL prefix. However, when ``name`` is a *URL*, static assets can +be served from an external webserver. In this mode, the ``name`` is used as +the URL prefix when generating a URL using :meth:`pyramid.request.Request.static_url`. -For example, :meth:`~pyramid.config.Configurator.add_static_view` may -be fed a ``name`` argument which is ``http://example.com/images``: +For example, :meth:`~pyramid.config.Configurator.add_static_view` may be fed a +``name`` argument which is ``http://example.com/images``: .. code-block:: python :linenos: @@ -179,15 +179,15 @@ be fed a ``name`` argument which is ``http://example.com/images``: config.add_static_view(name='http://example.com/images', path='mypackage:images') -Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with -a ``name`` argument that is the URL ``http://example.com/images``, subsequent -calls to :meth:`~pyramid.request.Request.static_url` with paths that start -with the ``path`` argument passed to +Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with a +``name`` argument that is the URL ``http://example.com/images``, subsequent +calls to :meth:`~pyramid.request.Request.static_url` with paths that start with +the ``path`` argument passed to :meth:`~pyramid.config.Configurator.add_static_view` will generate a URL -something like ``http://example.com/images/logo.png``. The external -webserver listening on ``example.com`` must be itself configured to respond -properly to such a request. The :meth:`~pyramid.request.Request.static_url` -API is discussed in more detail later in this chapter. +something like ``http://example.com/images/logo.png``. The external webserver +listening on ``example.com`` must be itself configured to respond properly to +such a request. The :meth:`~pyramid.request.Request.static_url` API is +discussed in more detail later in this chapter. .. index:: single: generating static asset urls @@ -199,11 +199,11 @@ API is discussed in more detail later in this chapter. Generating Static Asset URLs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a :meth:`~pyramid.config.Configurator.add_static_view` method is used to +When an :meth:`~pyramid.config.Configurator.add_static_view` method is used to register a static asset directory, a special helper API named :meth:`pyramid.request.Request.static_url` can be used to generate the -appropriate URL for an asset that lives in one of the directories named by -the static registration ``path`` attribute. +appropriate URL for an asset that lives in one of the directories named by the +static registration ``path`` attribute. For example, let's assume you create a set of static declarations like so: @@ -213,12 +213,12 @@ For example, let's assume you create a set of static declarations like so: config.add_static_view(name='static1', path='mypackage:assets/1') config.add_static_view(name='static2', path='mypackage:assets/2') -These declarations create URL-accessible directories which have URLs that -begin with ``/static1`` and ``/static2``, respectively. The assets in the +These declarations create URL-accessible directories which have URLs that begin +with ``/static1`` and ``/static2``, respectively. The assets in the ``assets/1`` directory of the ``mypackage`` package are consulted when a user -visits a URL which begins with ``/static1``, and the assets in the -``assets/2`` directory of the ``mypackage`` package are consulted when a user -visits a URL which begins with ``/static2``. +visits a URL which begins with ``/static1``, and the assets in the ``assets/2`` +directory of the ``mypackage`` package are consulted when a user visits a URL +which begins with ``/static2``. You needn't generate the URLs to static assets "by hand" in such a configuration. Instead, use the :meth:`~pyramid.request.Request.static_url` @@ -238,8 +238,8 @@ API to generate them for you. For example: If the request "application URL" of the running system is ``http://example.com``, the ``css_url`` generated above would be: -``http://example.com/static1/foo.css``. The ``js_url`` generated -above would be ``http://example.com/static2/foo.js``. +``http://example.com/static1/foo.css``. The ``js_url`` generated above would +be ``http://example.com/static2/foo.js``. One benefit of using the :meth:`~pyramid.request.Request.static_url` function rather than constructing static URLs "by hand" is that if you need to change @@ -249,10 +249,9 @@ resolve properly after the rename. URLs may also be generated by :meth:`~pyramid.request.Request.static_url` to static assets that live *outside* the :app:`Pyramid` application. This will happen when the :meth:`~pyramid.config.Configurator.add_static_view` API -associated with the path fed to :meth:`~pyramid.request.Request.static_url` -is a *URL* instead of a view name. For example, the ``name`` argument may be -``http://example.com`` while the ``path`` given may be -``mypackage:images``: +associated with the path fed to :meth:`~pyramid.request.Request.static_url` is +a *URL* instead of a view name. For example, the ``name`` argument may be +``http://example.com`` while the ``path`` given may be ``mypackage:images``: .. code-block:: python :linenos: @@ -260,8 +259,8 @@ is a *URL* instead of a view name. For example, the ``name`` argument may be config.add_static_view(name='http://example.com/images', path='mypackage:images') -Under such a configuration, the URL generated by ``static_url`` for -assets which begin with ``mypackage:images`` will be prefixed with +Under such a configuration, the URL generated by ``static_url`` for assets +which begin with ``mypackage:images`` will be prefixed with ``http://example.com/images``: .. code-block:: python @@ -271,16 +270,16 @@ assets which begin with ``mypackage:images`` will be prefixed with # -> http://example.com/images/logo.png Using :meth:`~pyramid.request.Request.static_url` in conjunction with a -:meth:`~pyramid.config.Configurator.add_static_view` makes it possible -to put static media on a separate webserver during production (if the -``name`` argument to :meth:`~pyramid.config.Configurator.add_static_view` is -a URL), while keeping static media package-internal and served by the -development webserver during development (if the ``name`` argument to +:meth:`~pyramid.config.Configurator.add_static_view` makes it possible to put +static media on a separate webserver during production (if the ``name`` +argument to :meth:`~pyramid.config.Configurator.add_static_view` is a URL), +while keeping static media package-internal and served by the development +webserver during development (if the ``name`` argument to :meth:`~pyramid.config.Configurator.add_static_view` is a URL prefix). For example, we may define a :ref:`custom setting <adding_a_custom_setting>` -named ``media_location`` which we can set to an external URL in production -when our assets are hosted on a CDN. +named ``media_location`` which we can set to an external URL in production when +our assets are hosted on a CDN. .. code-block:: python :linenos: @@ -305,18 +304,19 @@ It is also possible to serve assets that live outside of the source by referring to an absolute path on the filesystem. There are two ways to accomplish this. -First, :meth:`~pyramid.config.Configurator.add_static_view` -supports taking an absolute path directly instead of an asset spec. This works -as expected, looking in the file or folder of files and serving them up at -some URL within your application or externally. Unfortunately, this technique -has a drawback that it is not possible to use the -:meth:`~pyramid.request.Request.static_url` method to generate URLs, since it -works based on an asset spec. +First, :meth:`~pyramid.config.Configurator.add_static_view` supports taking an +absolute path directly instead of an asset spec. This works as expected, +looking in the file or folder of files and serving them up at some URL within +your application or externally. Unfortunately, this technique has a drawback in +that it is not possible to use the :meth:`~pyramid.request.Request.static_url` +method to generate URLs, since it works based on an asset specification. -The second approach, available in Pyramid 1.6+, uses the asset overriding -APIs described in the :ref:`overriding_assets_section` section. It is then -possible to configure a "dummy" package which then serves its file or folder -from an absolute path. +.. versionadded:: 1.6 + +The second approach, available in Pyramid 1.6+, uses the asset overriding APIs +described in the :ref:`overriding_assets_section` section. It is then possible +to configure a "dummy" package which then serves its file or folder from an +absolute path. .. code-block:: python @@ -325,13 +325,13 @@ from an absolute path. override_with='/abs/path/to/images/') From this configuration it is now possible to use -:meth:`~pyramid.request.Request.static_url` to generate URLs to the data -in the folder by doing something like +:meth:`~pyramid.request.Request.static_url` to generate URLs to the data in the +folder by doing something like ``request.static_url('myapp:static_images/foo.png')``. While it is not necessary that the ``static_images`` file or folder actually exist in the -``myapp`` package, it is important that the ``myapp`` portion points to a -valid package. If the folder does exist then the overriden folder is given -priority if the file's name exists in both locations. +``myapp`` package, it is important that the ``myapp`` portion points to a valid +package. If the folder does exist, then the overriden folder is given priority, +if the file's name exists in both locations. .. index:: single: Cache Busting @@ -343,31 +343,30 @@ Cache Busting .. versionadded:: 1.6 -In order to maximize performance of a web application, you generally want to +In order to maximize performance of a web application, you generally want to limit the number of times a particular client requests the same static asset. -Ideally a client would cache a particular static asset "forever", requiring -it to be sent to the client a single time. The HTTP protocol allows you to -send headers with an HTTP response that can instruct a client to cache a -particular asset for an amount of time. As long as the client has a copy of -the asset in its cache and that cache hasn't expired, the client will use the -cached copy rather than request a new copy from the server. The drawback to -sending cache headers to the client for a static asset is that at some point -the static asset may change, and then you'll want the client to load a new copy -of the asset. Under normal circumstances you'd just need to wait for the -client's cached copy to expire before they get the new version of the static -resource. - -A commonly used workaround to this problem is a technique known as "cache -busting". Cache busting schemes generally involve generating a URL for a +Ideally a client would cache a particular static asset "forever", requiring it +to be sent to the client a single time. The HTTP protocol allows you to send +headers with an HTTP response that can instruct a client to cache a particular +asset for an amount of time. As long as the client has a copy of the asset in +its cache and that cache hasn't expired, the client will use the cached copy +rather than request a new copy from the server. The drawback to sending cache +headers to the client for a static asset is that at some point the static asset +may change, and then you'll want the client to load a new copy of the asset. +Under normal circumstances you'd just need to wait for the client's cached copy +to expire before they get the new version of the static resource. + +A commonly used workaround to this problem is a technique known as "cache +busting". Cache busting schemes generally involve generating a URL for a static asset that changes when the static asset changes. This way headers can be sent along with the static asset instructing the client to cache the asset for a very long time. When a static asset is changed, the URL used to refer to -it in a web page also changes, so the client sees it as a new resource and -requests a copy, regardless of any caching policy set for the resource's old +it in a web page also changes, so the client sees it as a new resource and +requests the asset, regardless of any caching policy set for the resource's old URL. -:app:`Pyramid` can be configured to produce cache busting URLs for static -assets by passing the optional argument, ``cachebust`` to +:app:`Pyramid` can be configured to produce cache busting URLs for static +assets by passing the optional argument, ``cachebust`` to :meth:`~pyramid.config.Configurator.add_static_view`: .. code-block:: python @@ -377,7 +376,7 @@ assets by passing the optional argument, ``cachebust`` to config.add_static_view(name='static', path='mypackage:folder/static', cachebust=True) -Setting the ``cachebust`` argument instructs :app:`Pyramid` to use a cache +Setting the ``cachebust`` argument instructs :app:`Pyramid` to use a cache busting scheme which adds the md5 checksum for a static asset as a path segment in the asset's URL: @@ -385,7 +384,7 @@ in the asset's URL: :linenos: js_url = request.static_url('mypackage:folder/static/js/myapp.js') - # Returns: 'http://www.example.com/static/c9658b3c0a314a1ca21e5988e662a09e/js/myapp.js` + # Returns: 'http://www.example.com/static/c9658b3c0a314a1ca21e5988e662a09e/js/myapp.js' When the asset changes, so will its md5 checksum, and therefore so will its URL. Supplying the ``cachebust`` argument also causes the static view to set @@ -394,17 +393,17 @@ headers instructing clients to cache the asset for ten years, unless the .. note:: - md5 checksums are cached in RAM so if you change a static resource without + md5 checksums are cached in RAM, so if you change a static resource without restarting your application, you may still generate URLs with a stale md5 - checksum. + checksum. Disabling the Cache Buster ~~~~~~~~~~~~~~~~~~~~~~~~~~ -It can be useful in some situations (e.g. development) to globally disable all +It can be useful in some situations (e.g., development) to globally disable all configured cache busters without changing calls to -:meth:`~pyramid.config.Configurator.add_static_view`. To do this set the -``PYRAMID_PREVENT_CACHEBUST`` environment variable or the +:meth:`~pyramid.config.Configurator.add_static_view`. To do this set the +``PYRAMID_PREVENT_CACHEBUST`` environment variable or the ``pyramid.prevent_cachebust`` configuration value to a true value. Customizing the Cache Buster @@ -420,8 +419,8 @@ Revisiting from the previous section: cachebust=True) Setting ``cachebust`` to ``True`` instructs :app:`Pyramid` to use a default -cache busting implementation that should work for many situations. The -``cachebust`` may be set to any object that implements the interface, +cache busting implementation that should work for many situations. The +``cachebust`` may be set to any object that implements the interface :class:`~pyramid.interfaces.ICacheBuster`. The above configuration is exactly equivalent to: @@ -440,7 +439,7 @@ checksum token in the path portion of the asset's URL, :class:`~pyramid.static.QueryStringMd5CacheBuster`, which adds an md5 checksum token to the query string of the asset's URL, and :class:`~pyramid.static.QueryStringConstantCacheBuster`, which adds an -arbitrary token you provide to the query string of the asset's URL. +arbitrary token you provide to the query string of the asset's URL. In order to implement your own cache buster, you can write your own class from scratch which implements the :class:`~pyramid.interfaces.ICacheBuster` @@ -461,9 +460,9 @@ the hash of the currently checked out code: class GitCacheBuster(PathSegmentCacheBuster): """ - Assuming your code is installed as a Git checkout, as opposed to as an - egg from an egg repository like PYPI, you can use this cachebuster to - get the current commit's SHA1 to use as the cache bust token. + Assuming your code is installed as a Git checkout, as opposed to an egg + from an egg repository like PYPI, you can use this cachebuster to get + the current commit's SHA1 to use as the cache bust token. """ def __init__(self): here = os.path.dirname(os.path.abspath(__file__)) @@ -477,25 +476,25 @@ the hash of the currently checked out code: Choosing a Cache Buster ~~~~~~~~~~~~~~~~~~~~~~~ -The default cache buster implementation, -:class:`~pyramid.static.PathSegmentMd5CacheBuster`, works very well assuming +The default cache buster implementation, +:class:`~pyramid.static.PathSegmentMd5CacheBuster`, works very well assuming that you're using :app:`Pyramid` to serve your static assets. The md5 checksum -is fine grained enough that browsers should only request new versions of -specific assets that have changed. Many caching HTTP proxies will fail to -cache a resource if the URL contains a query string. In general, therefore, -you should prefer a cache busting strategy which modifies the path segment to -a strategy which adds a query string. +is fine grained enough that browsers should only request new versions of +specific assets that have changed. Many caching HTTP proxies will fail to +cache a resource if the URL contains a query string. In general, therefore, +you should prefer a cache busting strategy which modifies the path segment to a +strategy which adds a query string. It is possible, however, that your static assets are being served by another web server or externally on a CDN. In these cases modifying the path segment for a static asset URL would cause the external service to fail to find the -asset, causing your customer to get a 404. In these cases you would need to -fall back to a cache buster which adds a query string. It is even possible +asset, causing your customer to get a 404. In these cases you would need to +fall back to a cache buster which adds a query string. It is even possible that there isn't a copy of your static assets available to the :app:`Pyramid` application, so a cache busting implementation that generates md5 checksums -would fail since it can't access the assets. In such a case, -:class:`~pyramid.static.QueryStringConstantCacheBuster` is a reasonable -fallback. The following code would set up a cachebuster that just uses the +would fail since it can't access the assets. In such a case, +:class:`~pyramid.static.QueryStringConstantCacheBuster` is a reasonable +fallback. The following code would set up a cachebuster that just uses the time at start up as a cachebust token: .. code-block:: python @@ -516,10 +515,10 @@ CSS and JavaScript source and cache busting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Often one needs to refer to images and other static assets inside CSS and -JavaScript files. If cache busting is active, the final static asset URL is -not available until the static assets have been assembled. These URLs cannot -be handwritten. Thus, when having static asset references in CSS and -JavaScript, one needs to perform one of the following tasks. +JavaScript files. If cache busting is active, the final static asset URL is not +available until the static assets have been assembled. These URLs cannot be +handwritten. Thus, when having static asset references in CSS and JavaScript, +one needs to perform one of the following tasks. * Process the files by using a precompiler which rewrites URLs to their final cache busted form. @@ -536,8 +535,8 @@ packages. Relative cache busted URLs in CSS +++++++++++++++++++++++++++++++++ -Consider a CSS file ``/static/theme/css/site.css`` which contains the -following CSS code. +Consider a CSS file ``/static/theme/css/site.css`` which contains the following +CSS code. .. code-block:: css @@ -572,8 +571,8 @@ The browser would interpret this as having the CSS file hash in URL:: The downside of this approach is that if the background image changes, one needs to bump the CSS file. The CSS file hash change signals the caches that the relative URL to the image in the CSS has been changed. When updating CSS -and related image assets, updates usually happen hand in hand, so this does -not add extra effort to theming workflow. +and related image assets, updates usually happen hand in hand, so this does not +add extra effort to theming workflow. Passing cache busted URLs to JavaScript +++++++++++++++++++++++++++++++++++++++ @@ -593,7 +592,7 @@ relevant page. "{{ '/theme/img/background.jpg'|static_url() }}"; </script> -Then in your main ``site.js`` file put the following code. +Then in your main ``site.js`` file, put the following code. .. code-block:: javascript @@ -606,13 +605,13 @@ Advanced: Serving Static Assets Using a View Callable For more flexibility, static assets can be served by a :term:`view callable` which you register manually. For example, if you're using :term:`URL -dispatch`, you may want static assets to only be available as a fallback if -no previous route matches. Alternately, you might like to serve a particular +dispatch`, you may want static assets to only be available as a fallback if no +previous route matches. Alternatively, you might like to serve a particular static asset manually, because its download requires authentication. -Note that you cannot use the :meth:`~pyramid.request.Request.static_url` API -to generate URLs against assets made accessible by registering a custom -static view. +Note that you cannot use the :meth:`~pyramid.request.Request.static_url` API to +generate URLs against assets made accessible by registering a custom static +view. Root-Relative Custom Static View (URL Dispatch Only) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -626,19 +625,19 @@ its behavior is almost exactly the same once it's configured. .. warning:: The following example *will not work* for applications that use - :term:`traversal`, it will only work if you use :term:`URL dispatch` + :term:`traversal`; it will only work if you use :term:`URL dispatch` exclusively. The root-relative route we'll be registering will always be matched before traversal takes place, subverting any views registered via ``add_view`` (at least those without a ``route_name``). A :class:`~pyramid.static.static_view` static view cannot be made - root-relative when you use traversal unless it's registered as a - :term:`Not Found View`. + root-relative when you use traversal unless it's registered as a :term:`Not + Found View`. To serve files within a directory located on your filesystem at ``/path/to/static/dir`` as the result of a "catchall" route hanging from the root that exists at the end of your routing table, create an instance of the -:class:`~pyramid.static.static_view` class inside a ``static.py`` file in -your application root as below. +:class:`~pyramid.static.static_view` class inside a ``static.py`` file in your +application root as below. .. code-block:: python :linenos: @@ -648,10 +647,10 @@ your application root as below. .. note:: - For better cross-system flexibility, use an :term:`asset - specification` as the argument to :class:`~pyramid.static.static_view` - instead of a physical absolute filesystem path, e.g. ``mypackage:static`` - instead of ``/path/to/mypackage/static``. + For better cross-system flexibility, use an :term:`asset specification` as + the argument to :class:`~pyramid.static.static_view` instead of a physical + absolute filesystem path, e.g., ``mypackage:static``, instead of + ``/path/to/mypackage/static``. Subsequently, you may wire the files that are served by this view up to be accessible as ``/<filename>`` using a configuration method in your @@ -670,11 +669,11 @@ The special name ``*subpath`` above is used by the :class:`~pyramid.static.static_view` view callable to signify the path of the file relative to the directory you're serving. -Registering A View Callable to Serve a "Static" Asset +Registering a View Callable to Serve a "Static" Asset ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can register a simple view callable to serve a single static asset. To -do so, do things "by hand". First define the view callable. +You can register a simple view callable to serve a single static asset. To do +so, do things "by hand". First define the view callable. .. code-block:: python :linenos: @@ -687,17 +686,16 @@ do so, do things "by hand". First define the view callable. icon = os.path.join(here, 'static', 'favicon.ico') return FileResponse(icon, request=request) -The above bit of code within ``favicon_view`` computes "here", which is a -path relative to the Python file in which the function is defined. It then -creates a :class:`pyramid.response.FileResponse` using the file path as the -response's ``path`` argument and the request as the response's ``request`` -argument. :class:`pyramid.response.FileResponse` will serve the file as -quickly as possible when it's used this way. It makes sure to set the right -content length and content_type too based on the file extension of the file -you pass. +The above bit of code within ``favicon_view`` computes "here", which is a path +relative to the Python file in which the function is defined. It then creates +a :class:`pyramid.response.FileResponse` using the file path as the response's +``path`` argument and the request as the response's ``request`` argument. +:class:`pyramid.response.FileResponse` will serve the file as quickly as +possible when it's used this way. It makes sure to set the right content +length and content_type, too, based on the file extension of the file you pass. -You might register such a view via configuration as a view callable that -should be called as the result of a traversal: +You might register such a view via configuration as a view callable that should +be called as the result of a traversal: .. code-block:: python :linenos: @@ -730,13 +728,12 @@ It can often be useful to override specific assets from "outside" a given :app:`Pyramid` application more or less unchanged. However, some specific template file owned by the application might have inappropriate HTML, or some static asset (such as a logo file or some CSS file) might not be appropriate. -You *could* just fork the application entirely, but it's often more -convenient to just override the assets that are inappropriate and reuse the -application "as is". This is particularly true when you reuse some "core" -application over and over again for some set of customers (such as a CMS -application, or some bug tracking application), and you want to make -arbitrary visual modifications to a particular application deployment without -forking the underlying code. +You *could* just fork the application entirely, but it's often more convenient +to just override the assets that are inappropriate and reuse the application +"as is". This is particularly true when you reuse some "core" application over +and over again for some set of customers (such as a CMS application, or some +bug tracking application), and you want to make arbitrary visual modifications +to a particular application deployment without forking the underlying code. To this end, :app:`Pyramid` contains a feature that makes it possible to "override" one asset with one or more other assets. In support of this @@ -754,8 +751,8 @@ feature, a :term:`Configurator` API exists named - A directory of static files served up by an instance of the ``pyramid.static.static_view`` helper class. -- Any other asset (or set of assets) addressed by code that uses the - setuptools :term:`pkg_resources` API. +- Any other asset (or set of assets) addressed by code that uses the setuptools + :term:`pkg_resources` API. .. index:: single: override_asset @@ -765,8 +762,8 @@ feature, a :term:`Configurator` API exists named The ``override_asset`` API ~~~~~~~~~~~~~~~~~~~~~~~~~~ -An individual call to :meth:`~pyramid.config.Configurator.override_asset` -can override a single asset. For example: +An individual call to :meth:`~pyramid.config.Configurator.override_asset` can +override a single asset. For example: .. code-block:: python :linenos: @@ -776,11 +773,11 @@ can override a single asset. For example: override_with='another.package:othertemplates/anothertemplate.pt') The string value passed to both ``to_override`` and ``override_with`` sent to -the ``override_asset`` API is called an :term:`asset specification`. The -colon separator in a specification separates the *package name* from the -*asset name*. The colon and the following asset name are optional. If they -are not specified, the override attempts to resolve every lookup into a -package from the directory of another package. For example: +the ``override_asset`` API is called an :term:`asset specification`. The colon +separator in a specification separates the *package name* from the *asset +name*. The colon and the following asset name are optional. If they are not +specified, the override attempts to resolve every lookup into a package from +the directory of another package. For example: .. code-block:: python :linenos: @@ -796,27 +793,25 @@ Individual subdirectories within a package can also be overridden: config.override_asset(to_override='some.package:templates/', override_with='another.package:othertemplates/') - -If you wish to override a directory with another directory, you *must* -make sure to attach the slash to the end of both the ``to_override`` -specification and the ``override_with`` specification. If you fail to -attach a slash to the end of a specification that points to a directory, -you will get unexpected results. +If you wish to override a directory with another directory, you *must* make +sure to attach the slash to the end of both the ``to_override`` specification +and the ``override_with`` specification. If you fail to attach a slash to the +end of a specification that points to a directory, you will get unexpected +results. You cannot override a directory specification with a file specification, and -vice versa: a startup error will occur if you try. You cannot override an -asset with itself: a startup error will occur if you try. +vice versa; a startup error will occur if you try. You cannot override an +asset with itself; a startup error will occur if you try. Only individual *package* assets may be overridden. Overrides will not -traverse through subpackages within an overridden package. This means that -if you want to override assets for both ``some.package:templates``, and +traverse through subpackages within an overridden package. This means that if +you want to override assets for both ``some.package:templates``, and ``some.package.views:templates``, you will need to register two overrides. -The package name in a specification may start with a dot, meaning that -the package is relative to the package in which the configuration -construction file resides (or the ``package`` argument to the -:class:`~pyramid.config.Configurator` class construction). -For example: +The package name in a specification may start with a dot, meaning that the +package is relative to the package in which the configuration construction file +resides (or the ``package`` argument to the +:class:`~pyramid.config.Configurator` class construction). For example: .. code-block:: python :linenos: @@ -824,18 +819,19 @@ For example: config.override_asset(to_override='.subpackage:templates/', override_with='another.package:templates/') -Multiple calls to ``override_asset`` which name a shared ``to_override`` but -a different ``override_with`` specification can be "stacked" to form a search -path. The first asset that exists in the search path will be used; if no -asset exists in the override path, the original asset is used. +Multiple calls to ``override_asset`` which name a shared ``to_override`` but a +different ``override_with`` specification can be "stacked" to form a search +path. The first asset that exists in the search path will be used; if no asset +exists in the override path, the original asset is used. Asset overrides can actually override assets other than templates and static files. Any software which uses the :func:`pkg_resources.get_resource_filename`, -:func:`pkg_resources.get_resource_stream` or +:func:`pkg_resources.get_resource_stream`, or :func:`pkg_resources.get_resource_string` APIs will obtain an overridden file when an override is used. -As of Pyramid 1.6, it is also possible to override an asset by supplying an -absolute path to a file or directory. This may be useful if the assets are -not distributed as part of a Python package. +.. versionadded:: 1.6 + As of Pyramid 1.6, it is also possible to override an asset by supplying an + absolute path to a file or directory. This may be useful if the assets are + not distributed as part of a Python package. diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 484350b31..a7d0848ca 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -10,8 +10,8 @@ View Configuration .. index:: single: view lookup -:term:`View lookup` is the :app:`Pyramid` subsystem responsible for finding -and invoking a :term:`view callable`. :term:`View configuration` controls how +:term:`View lookup` is the :app:`Pyramid` subsystem responsible for finding 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. @@ -30,8 +30,8 @@ Mapping a Resource or URL Pattern to a View Callable A developer makes a :term:`view callable` available for use within a :app:`Pyramid` application via :term:`view configuration`. A view configuration associates a view callable with a set of statements that -determine the set of circumstances which must be true for the view callable -to be invoked. +determine the set of circumstances which must be true for the view callable to +be invoked. A view configuration statement is made about information present in the :term:`context` resource and the :term:`request`. @@ -56,35 +56,34 @@ View Configuration Parameters All forms of view configuration accept the same general types of arguments. Many arguments supplied during view configuration are :term:`view predicate` -arguments. View predicate arguments used during view configuration are used -to narrow the set of circumstances in which :term:`view lookup` will find a +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. :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 the 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 the 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 +appropriate view. The greater the 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 the 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. -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 -of view predicates does not match, the "next most specific" view (if -any) is consulted for predicates, and so on, until a view is found, or -no view can be matched up with the request. The first view with a set -of predicates all of which match the request environment will be -invoked. +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 of view +predicates does not match, the "next most specific" view (if any) is consulted +for predicates, and so on, until a view is found, or no view can be matched up +with the request. The first view with a set of predicates all of which match +the request environment will be invoked. If no view can be found with predicates which allow it to be matched up with 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 :term:`Not Found View`. -Other 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. @@ -96,56 +95,55 @@ Non-Predicate Arguments ``permission`` The name of a :term:`permission` that the user must possess in order to - invoke the :term:`view callable`. See :ref:`view_security_section` for - more information about view security and permissions. + invoke the :term:`view callable`. See :ref:`view_security_section` for more + information about view security and permissions. - If ``permission`` is not supplied, no permission is registered for this - view (it's accessible by any caller). + If ``permission`` is not supplied, no permission is registered for this view + (it's accessible by any caller). ``attr`` The view machinery defaults to using the ``__call__`` method of the :term:`view callable` (or the function itself, if the view callable is a function) to obtain a response. The ``attr`` value allows you to vary the - method attribute used to obtain the response. For example, if your view - was a class, and the class has a method named ``index`` and you wanted to - use this method instead of the class's ``__call__`` method to return the - response, you'd say ``attr="index"`` in the view configuration for the - view. This is most useful when the view definition is a class. + method attribute used to obtain the response. For example, if your view was + a class, and the class has a method named ``index`` and you wanted to use + this method instead of the class's ``__call__`` method to return the + response, you'd say ``attr="index"`` in the view configuration for the view. + This is most useful when the view definition is a class. If ``attr`` is not supplied, ``None`` is used (implying the function itself - if the view is a function, or the ``__call__`` callable attribute if the - view is a class). + if the view is a function, or the ``__call__`` callable attribute if the view + is a class). ``renderer`` - Denotes the :term:`renderer` implementation which will be used to construct - a :term:`response` from the associated view callable's return value. + Denotes the :term:`renderer` implementation which will be used to construct a + :term:`response` from the associated view callable's return value. .. seealso:: See also :ref:`renderers_chapter`. - This is either a single string term (e.g. ``json``) or a string implying a - path or :term:`asset specification` (e.g. ``templates/views.pt``) naming a - :term:`renderer` implementation. If the ``renderer`` value does not - contain a dot (``.``), the specified string will be used to look up a - renderer implementation, and that renderer implementation will be used to - construct a response from the view return value. If the ``renderer`` value - contains a dot (``.``), the specified term will be treated as a path, and - the filename extension of the last element in the path will be used to look - up the renderer implementation, which will be passed the full path. - - When the renderer is a path, although a path is usually just a simple - relative pathname (e.g. ``templates/foo.pt``, implying that a template - named "foo.pt" is in the "templates" directory relative to the directory of - the current :term:`package`), a path can be absolute, starting with a slash - on UNIX or a drive letter prefix on Windows. The path can alternately be a - :term:`asset specification` in the form - ``some.dotted.package_name:relative/path``, making it possible to address - template assets which live in a separate package. + This is either a single string term (e.g., ``json``) or a string implying a + path or :term:`asset specification` (e.g., ``templates/views.pt``) naming a + :term:`renderer` implementation. If the ``renderer`` value does not contain + a dot (``.``), the specified string will be used to look up a renderer + implementation, and that renderer implementation will be used to construct a + response from the view return value. If the ``renderer`` value contains a + dot (``.``), the specified term will be treated as a path, and the filename + extension of the last element in the path will be used to look up the + renderer implementation, which will be passed the full path. + + When the renderer is a path—although a path is usually just a simple relative + pathname (e.g., ``templates/foo.pt``, implying that a template named "foo.pt" + is in the "templates" directory relative to the directory of the current + :term:`package`)—the path can be absolute, starting with a slash on UNIX or a + drive letter prefix on Windows. The path can alternatively be a :term:`asset + specification` in the form ``some.dotted.package_name:relative/path``, making + it possible to address template assets which live in a separate package. The ``renderer`` attribute is optional. If it is not defined, the "null" renderer is assumed (no rendering is performed and the value is passed back - to the upstream :app:`Pyramid` machinery unchanged). Note that if the - view callable itself returns a :term:`response` (see :ref:`the_response`), - the specified renderer implementation is never called. + to the upstream :app:`Pyramid` machinery unchanged). Note that if the view + callable itself returns a :term:`response` (see :ref:`the_response`), the + specified renderer implementation is never called. ``http_cache`` When you supply an ``http_cache`` value to a view configuration, the @@ -153,38 +151,36 @@ Non-Predicate Arguments associated view callable are modified. The value for ``http_cache`` may be one of the following: - - A nonzero integer. If it's a nonzero integer, it's treated as a number - of seconds. This number of seconds will be used to compute the - ``Expires`` header and the ``Cache-Control: max-age`` parameter of - responses to requests which call this view. For example: - ``http_cache=3600`` instructs the requesting browser to 'cache this - response for an hour, please'. + - A nonzero integer. If it's a nonzero integer, it's treated as a number of + seconds. This number of seconds will be used to compute the ``Expires`` + header and the ``Cache-Control: max-age`` parameter of responses to + requests which call this view. For example: ``http_cache=3600`` instructs + the requesting browser to 'cache this response for an hour, please'. - A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta`` - instance, it will be converted into a number of seconds, and that number - of seconds will be used to compute the ``Expires`` header and the + instance, it will be converted into a number of seconds, and that number of + seconds will be used to compute the ``Expires`` header and the ``Cache-Control: max-age`` parameter of responses to requests which call this view. For example: ``http_cache=datetime.timedelta(days=1)`` instructs the requesting browser to 'cache this response for a day, please'. - - Zero (``0``). If the value is zero, the ``Cache-Control`` and - ``Expires`` headers present in all responses from this view will be - composed such that client browser cache (and any intermediate caches) are - instructed to never cache the response. - - - A two-tuple. If it's a two tuple (e.g. ``http_cache=(1, - {'public':True})``), the first value in the tuple may be a nonzero - integer or a ``datetime.timedelta`` instance; in either case this value - will be used as the number of seconds to cache the response. The second - value in the tuple must be a dictionary. The values present in the - dictionary will be used as input to the ``Cache-Control`` response - header. For example: ``http_cache=(3600, {'public':True})`` means 'cache - for an hour, and add ``public`` to the Cache-Control header of the - response'. All keys and values supported by the - ``webob.cachecontrol.CacheControl`` interface may be added to the - dictionary. Supplying ``{'public':True}`` is equivalent to calling - ``response.cache_control.public = True``. + - Zero (``0``). If the value is zero, the ``Cache-Control`` and ``Expires`` + headers present in all responses from this view will be composed such that + client browser cache (and any intermediate caches) are instructed to never + cache the response. + + - A two-tuple. If it's a two-tuple (e.g., ``http_cache=(1, + {'public':True})``), the first value in the tuple may be a nonzero integer + or a ``datetime.timedelta`` instance. In either case this value will be + used as the number of seconds to cache the response. The second value in + the tuple must be a dictionary. The values present in the dictionary will + be used as input to the ``Cache-Control`` response header. For example: + ``http_cache=(3600, {'public':True})`` means 'cache for an hour, and add + ``public`` to the Cache-Control header of the response'. All keys and + values supported by the ``webob.cachecontrol.CacheControl`` interface may + be added to the dictionary. Supplying ``{'public':True}`` is equivalent to + calling ``response.cache_control.public = True``. Providing a non-tuple value as ``http_cache`` is equivalent to calling ``response.cache_expires(value)`` within your view's body. @@ -192,9 +188,9 @@ Non-Predicate Arguments Providing a two-tuple value as ``http_cache`` is equivalent to calling ``response.cache_expires(value[0], **value[1])`` within your view's body. - If you wish to avoid influencing, the ``Expires`` header, and instead wish - to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` - with the first element of ``None``, e.g.: ``(None, {'public':True})``. + If you wish to avoid influencing the ``Expires`` header, and instead wish to + only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` with + the first element of ``None``, i.e., ``(None, {'public':True})``. ``wrapper`` The :term:`view name` of a different :term:`view configuration` which will @@ -203,24 +199,24 @@ Non-Predicate Arguments this view as the ``request.wrapped_response`` attribute of its own request. Using a wrapper makes it possible to "chain" views together to form a composite response. The response of the outermost wrapper view will be - returned to the user. The wrapper view will be found as any view is found: - see :ref:`view_lookup`. The "best" wrapper view will be found based on the - lookup ordering: "under the hood" this wrapper view is looked up via + returned to the user. The wrapper view will be found as any view is found. + See :ref:`view_lookup`. The "best" wrapper view will be found based on the + lookup ordering. "Under the hood" this wrapper view is looked up via ``pyramid.view.render_view_to_response(context, request, - 'wrapper_viewname')``. The context and request of a wrapper view is the - same context and request of the inner view. + 'wrapper_viewname')``. The context and request of a wrapper view is the same + context and request of the inner view. If ``wrapper`` is not supplied, no wrapper view is used. ``decorator`` A :term:`dotted Python name` to a function (or the function itself) which - will be used to decorate the registered :term:`view callable`. The - decorator function will be called with the view callable as a single - argument. The view callable it is passed will accept ``(context, - request)``. The decorator must return a replacement view callable which - also accepts ``(context, request)``. The ``decorator`` may also be an - iterable of decorators, in which case they will be applied one after the - other to the view, in reverse order. For example:: + will be used to decorate the registered :term:`view callable`. The decorator + function will be called with the view callable as a single argument. The + view callable it is passed will accept ``(context, request)``. The decorator + must return a replacement view callable which also accepts ``(context, + request)``. The ``decorator`` may also be an iterable of decorators, in which + case they will be applied one after the other to the view, in reverse order. + For example:: @view_config(..., decorator=(decorator2, decorator1)) def myview(request): @@ -253,33 +249,32 @@ Non-Predicate Arguments A Python object or :term:`dotted Python name` which refers to a :term:`view mapper`, or ``None``. By default it is ``None``, which indicates that the view should use the default view mapper. This plug-point is useful for - Pyramid extension developers, but it's not very useful for 'civilians' who + Pyramid extension developers, but it's not very useful for "civilians" who are just developing stock Pyramid applications. Pay no attention to the man behind the curtain. Predicate Arguments +++++++++++++++++++ -These arguments modify view lookup behavior. In general, the more predicate -arguments that are supplied, the more specific, and narrower the usage of the +These arguments modify view lookup behavior. In general the more predicate +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. 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. + 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). ``context`` - An object representing a Python class that the :term:`context` resource - must be an instance of *or* the :term:`interface` that the :term:`context` + An object representing a Python class of which the :term:`context` resource + must be an instance *or* the :term:`interface` that the :term:`context` resource must provide in order for this view to be found and called. This predicate is true when the :term:`context` resource is an instance of the - represented class or if the :term:`context` resource provides the - represented interface; it is otherwise false. + represented class or if the :term:`context` resource provides the represented + interface; it is otherwise false. If ``context`` is not supplied, the value ``None``, which matches any resource, is used. @@ -289,68 +284,68 @@ configured view. the named route has matched. This value must match the ``name`` of a :term:`route configuration` - declaration (see :ref:`urldispatch_chapter`) that must match before this - view will be called. Note that the ``route`` configuration referred to by + declaration (see :ref:`urldispatch_chapter`) that must match before this view + will be called. Note that the ``route`` configuration referred to by ``route_name`` will usually have a ``*traverse`` token in the value of its ``pattern``, representing a part of the path that will be used by :term:`traversal` against the result of the route's :term:`root factory`. If ``route_name`` is not supplied, the view callable will only have a chance of being invoked if no other route was matched. This is when the - request/context pair found via :term:`resource location` does not indicate - it matched any configured route. + request/context pair found via :term:`resource location` does not indicate it + matched any configured route. ``request_type`` This value should be an :term:`interface` that the :term:`request` must provide in order for this view to be found and called. - If ``request_type`` is not supplied, the value ``None`` is used, implying - any request type. + If ``request_type`` is not supplied, the value ``None`` is used, implying any + request type. *This is an advanced feature, not often used by "civilians"*. ``request_method`` This value can be either a string (such as ``"GET"``, ``"POST"``, - ``"PUT"``, ``"DELETE"``, ``"HEAD"`` or ``"OPTIONS"``) representing an - HTTP ``REQUEST_METHOD``, or a tuple containing one or more of these - strings. A view declaration with this argument ensures that the - view will only be called when the ``method`` attribute of the - request (aka the ``REQUEST_METHOD`` of the WSGI environment) matches - a supplied value. Note that use of ``"GET"`` also implies that the - view will respond to ``"HEAD"`` as of Pyramid 1.4. - - If ``request_method`` is not supplied, the view will be invoked regardless - of the ``REQUEST_METHOD`` of the :term:`WSGI` environment. + ``"PUT"``, ``"DELETE"``, ``"HEAD"``, or ``"OPTIONS"``) representing an HTTP + ``REQUEST_METHOD`` or a tuple containing one or more of these strings. A + view declaration with this argument ensures that the view will only be called + when the ``method`` attribute of the request (i.e., the ``REQUEST_METHOD`` of + the WSGI environment) matches a supplied value. + + .. versionchanged:: 1.4 + The use of ``"GET"`` also implies that the view will respond to ``"HEAD"``. + + If ``request_method`` is not supplied, the view will be invoked regardless of + the ``REQUEST_METHOD`` of the :term:`WSGI` environment. ``request_param`` This value can be any string or a sequence of strings. A view declaration with this argument ensures that the view will only be called when the :term:`request` has a key in the ``request.params`` dictionary (an HTTP - ``GET`` or ``POST`` variable) that has a name which matches the - supplied value. + ``GET`` or ``POST`` variable) that has a name which matches the supplied + value. - If any value supplied has a ``=`` sign in it, - e.g. ``request_param="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 view to "match" the current - request. + If any value supplied has an ``=`` sign in it, e.g., + ``request_param="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 view to "match" the current request. If ``request_param`` is not supplied, the view will be invoked without consideration of keys and values in the ``request.params`` dictionary. ``match_param`` - This param may be either a single string of the format "key=value" or a - tuple containing one or more of these strings. + This param may be either a single string of the format "key=value" or a tuple + containing one or more of these strings. This argument ensures that the view will only be called when the - :term:`request` has key/value pairs in its :term:`matchdict` that equal - those supplied in the predicate. e.g. ``match_param="action=edit"`` would + :term:`request` has key/value pairs in its :term:`matchdict` that equal those + supplied in the predicate. For example, ``match_param="action=edit"`` would require the ``action`` parameter in the :term:`matchdict` match the right hand side of the expression (``edit``) for the view to "match" the current request. - If the ``match_param`` is a tuple, every key/value pair must match - for the predicate to pass. + If the ``match_param`` is a tuple, every key/value pair must match for the + predicate to pass. If ``match_param`` is not supplied, the view will be invoked without consideration of the keys and values in ``request.matchdict``. @@ -358,41 +353,40 @@ configured view. .. versionadded:: 1.2 ``containment`` - This value should be a reference to a Python class or :term:`interface` - that a parent object in the context resource's :term:`lineage` must provide - in order for this view to be found and called. The resources in your - resource tree must be "location-aware" to use this feature. + This value should be a reference to a Python class or :term:`interface` that + a parent object in the context resource's :term:`lineage` must provide in + order for this view to be found and called. The resources in your resource + tree must be "location-aware" to use this feature. - If ``containment`` is not supplied, the interfaces and classes in the - lineage are not considered when deciding whether or not to invoke the view - callable. + If ``containment`` is not supplied, the interfaces and classes in the lineage + are not considered when deciding whether or not to invoke the view callable. See :ref:`location_aware` for more information about location-awareness. ``xhr`` This value should be either ``True`` or ``False``. If this value is specified and is ``True``, the :term:`WSGI` environment must possess an - ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header that has the + ``HTTP_X_REQUESTED_WITH`` header (i.e., ``X-Requested-With``) that has the value ``XMLHttpRequest`` for the associated view callable to be found and called. This is useful for detecting AJAX requests issued from jQuery, - Prototype and other Javascript libraries. + Prototype, and other Javascript libraries. - If ``xhr`` is not specified, the ``HTTP_X_REQUESTED_WITH`` HTTP header is - not taken into consideration when deciding whether or not to invoke the + If ``xhr`` is not specified, the ``HTTP_X_REQUESTED_WITH`` HTTP header is not + taken into consideration when deciding whether or not to invoke the associated view callable. ``accept`` - The value of this argument 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 ``accept`` is not specified, the ``HTTP_ACCEPT`` HTTP header is not - taken into consideration when deciding whether or not to invoke the - associated view callable. + The value of this argument 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 ``accept`` is not specified, the ``HTTP_ACCEPT`` HTTP header is not taken + into consideration when deciding whether or not to invoke the associated view + callable. ``header`` This value represents an HTTP header name or a header name/value pair. @@ -400,94 +394,92 @@ configured view. If ``header`` is specified, it must be a header name or a ``headername:headervalue`` pair. - If ``header`` is specified without a value (a bare header name only, - e.g. ``If-Modified-Since``), the view will only be invoked if the HTTP - header exists with any value in the request. + If ``header`` is specified without a value (a bare header name only, e.g., + ``If-Modified-Since``), the view will only be invoked if the HTTP header + exists with any value in the request. - If ``header`` is specified, and possesses a name/value pair - (e.g. ``User-Agent:Mozilla/.*``), the view will only be invoked if the HTTP - header exists *and* the HTTP header matches the value requested. When the - ``headervalue`` contains a ``:`` (colon), it will be considered a - name/value pair (e.g. ``User-Agent:Mozilla/.*`` or ``Host:localhost``). - The value portion should be a regular expression. + If ``header`` is specified, and possesses a name/value pair (e.g., + ``User-Agent:Mozilla/.*``), the view will only be invoked if the HTTP header + exists *and* the HTTP header matches the value requested. When the + ``headervalue`` contains a ``:`` (colon), it will be considered a name/value + pair (e.g., ``User-Agent:Mozilla/.*`` or ``Host:localhost``). The value + portion should be a regular expression. 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 ``header`` is not specified, the composition, presence or absence of - HTTP headers is not taken into consideration when deciding whether or not - to invoke the associated view callable. + If ``header`` is not specified, the composition, presence, or absence of HTTP + headers is not taken into consideration when deciding whether or not to + invoke the associated view callable. ``path_info`` This value represents a regular expression pattern that will be tested - against the ``PATH_INFO`` WSGI environment variable to decide whether or - not to call the associated view callable. If the regex matches, this - predicate will be ``True``. + against the ``PATH_INFO`` WSGI environment variable to decide whether or not + to call the associated view callable. If the regex matches, this predicate + will be ``True``. If ``path_info`` is not specified, the WSGI ``PATH_INFO`` is not taken into consideration when deciding whether or not to invoke the associated view callable. ``check_csrf`` - If specified, this value should be one of ``None``, ``True``, ``False``, or - a string representing the 'check name'. If the value is ``True`` or a - string, CSRF checking will be performed. If the value is ``False`` or - ``None``, CSRF checking will not be performed. + If specified, this value should be one of ``None``, ``True``, ``False``, or a + string representing the "check name". If the value is ``True`` or a string, + CSRF checking will be performed. If the value is ``False`` or ``None``, CSRF + checking will not be performed. - If the value provided is a string, that string will be used as the 'check - name'. If the value provided is ``True``, ``csrf_token`` will be used as - the check name. + If the value provided is a string, that string will be used as the "check + name". If the value provided is ``True``, ``csrf_token`` will be used as the + check name. If CSRF checking is performed, the checked value will be the value of ``request.params[check_name]``. This value will be compared against the value of ``request.session.get_csrf_token()``, and the check will pass if - these two values are the same. If the check passes, the associated view - will be permitted to execute. If the check fails, the associated view - will not be permitted to execute. + these two values are the same. If the check passes, the associated view will + be permitted to execute. If the check fails, the associated view will not be + permitted to execute. - Note that using this feature requires a :term:`session factory` to have - been configured. + Note that using this feature requires a :term:`session factory` to have been + configured. .. versionadded:: 1.4a2 ``physical_path`` If specified, this value should be a string or a tuple representing the :term:`physical path` of the context found via traversal for this predicate - to match as true. For example: ``physical_path='/'`` or - ``physical_path='/a/b/c'`` or ``physical_path=('', 'a', 'b', 'c')``. This is - not a path prefix match or a regex, it's a whole-path match. It's useful + to match as true. For example, ``physical_path='/'``, + ``physical_path='/a/b/c'``, or ``physical_path=('', 'a', 'b', 'c')``. This + is not a path prefix match or a regex, but a whole-path match. It's useful when you want to always potentially show a view when some object is traversed to, but you can't be sure about what kind of object it will be, so you can't - use the ``context`` predicate. The individual path elements inbetween slash + use the ``context`` predicate. The individual path elements between slash characters or in tuple elements should be the Unicode representation of the name of the resource and should not be encoded in any way. .. versionadded:: 1.4a3 ``effective_principals`` - If specified, this value should be a :term:`principal` identifier or a sequence of principal identifiers. If the - :meth:`pyramid.request.Request.effective_principals` method indicates that every - principal named in the argument list is present in the current request, this - predicate will return True; otherwise it will return False. For example: - ``effective_principals=pyramid.security.Authenticated`` or + :meth:`pyramid.request.Request.effective_principals` method indicates that + every principal named in the argument list is present in the current request, + this predicate will return True; otherwise it will return False. For + example: ``effective_principals=pyramid.security.Authenticated`` or ``effective_principals=('fred', 'group:admins')``. .. versionadded:: 1.4a4 ``custom_predicates`` - If ``custom_predicates`` is specified, it must be a sequence of references - to custom predicate callables. Use custom predicates when no set of - predefined predicates do what you need. Custom predicates can be combined - with predefined predicates as necessary. Each custom predicate callable - should accept two arguments: ``context`` and ``request`` and should return - either ``True`` or ``False`` after doing arbitrary evaluation of the - context resource and/or the request. If all callables return ``True``, the + If ``custom_predicates`` is specified, it must be a sequence of references to + custom predicate callables. Use custom predicates when no set of predefined + predicates do what you need. Custom predicates can be combined with + predefined predicates as necessary. Each custom predicate callable should + accept two arguments, ``context`` and ``request``, and should return either + ``True`` or ``False`` after doing arbitrary evaluation of the context + resource and/or the request. If all callables return ``True``, the associated view callable will be considered viable for a given request. - If ``custom_predicates`` is not specified, no custom predicates are - used. + If ``custom_predicates`` is not specified, no custom predicates are used. ``predicates`` Pass a key/value pair here to use a third-party predicate registered via @@ -515,8 +507,8 @@ You can invert the meaning of any predicate value by wrapping it in a call to request_method=not_('POST') ) -The above example will ensure that the view is called if the request method -is *not* ``POST``, at least if no other view is more specific. +The above example will ensure that the view is called if the request method is +*not* ``POST``, at least if no other view is more specific. This technique of wrapping a predicate value in ``not_`` can be used anywhere predicate values are accepted: @@ -538,11 +530,11 @@ Adding View Configuration Using the ``@view_config`` Decorator .. warning:: - Using this feature tends to slow down application startup slightly, as - more work is performed at application startup to scan for view - configuration declarations. For maximum startup performance, use the view - configuration method described in - :ref:`mapping_views_using_imperative_config_section` instead. + Using this feature tends to slow down application startup slightly, as more + work is performed at application startup to scan for view 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 @@ -592,9 +584,8 @@ request method, request type, request param, route name, or containment. The mere existence of a ``@view_config`` decorator doesn't suffice to perform view configuration. All that the decorator does is "annotate" the function with your configuration declarations, it doesn't process them. To make -:app:`Pyramid` process your :class:`pyramid.view.view_config` declarations, -you *must* use the ``scan`` method of a -:class:`pyramid.config.Configurator`: +:app:`Pyramid` process your :class:`pyramid.view.view_config` declarations, you +*must* use the ``scan`` method of a :class:`pyramid.config.Configurator`: .. code-block:: python :linenos: @@ -603,9 +594,9 @@ you *must* use the ``scan`` method of a # pyramid.config.Configurator class config.scan() -Please see :ref:`decorations_and_code_scanning` for detailed information -about what happens when code is scanned for configuration declarations -resulting from use of decorators like :class:`~pyramid.view.view_config`. +Please see :ref:`decorations_and_code_scanning` for detailed information about +what happens when code is scanned for configuration declarations resulting from +use of decorators like :class:`~pyramid.view.view_config`. See :ref:`configuration_module` for additional API arguments to the :meth:`~pyramid.config.Configurator.scan` method. For example, the method @@ -613,10 +604,10 @@ 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 +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. @@ -644,8 +635,8 @@ If your view callable is a function, it may be used as a function decorator: return Response('edited!') If your view callable is a class, the decorator can also be used as a class -decorator. All the arguments to the decorator are the same when applied -against a class as when they are applied against a function. For example: +decorator. All the arguments to the decorator are the same when applied against +a class as when they are applied against a function. For example: .. code-block:: python :linenos: @@ -696,15 +687,15 @@ The decorator can also be used against a method of a class: When the decorator is used against a method of a class, a view is registered for the *class*, so the class constructor must accept an argument list in one -of two forms: either it must accept a single argument ``request`` or it must -accept two arguments, ``context, request``. +of two forms: either a single argument, ``request``, or two arguments, +``context, request``. The method which is decorated must return a :term:`response`. Using the decorator against a particular method of a class is equivalent to -using the ``attr`` parameter in a decorator attached to the class itself. -For example, the above registration implied by the decorator being used -against the ``amethod`` method could be spelled equivalently as the below: +using the ``attr`` parameter in a decorator attached to the class itself. For +example, the above registration implied by the decorator being used against the +``amethod`` method could be written equivalently as follows: .. code-block:: python :linenos: @@ -730,9 +721,9 @@ 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 -this method are very similar to the arguments that you provide to the +: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 @@ -747,10 +738,10 @@ this method are very similar to the arguments that you provide to the # pyramid.config.Configurator class config.add_view(hello_world, route_name='hello') -The first argument, a :term:`view callable`, is the only required argument. -It must either be a Python object which is the view itself or a -:term:`dotted Python name` to such an object. -In the above example, the ``view callable`` is the ``hello_world`` function. +The first argument, a :term:`view callable`, is the only required argument. It +must either be a Python object which is the view itself or a :term:`dotted +Python name` to such an object. In the above example, the ``view callable`` is +the ``hello_world`` function. 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 @@ -772,7 +763,7 @@ defaults to the view configuration information used by every ``@view_config`` decorator that decorates a method of that class. For instance, if you've got a class that has methods that represent "REST -actions", all which are mapped to the same route, but different request +actions", all of which are mapped to the same route but different request methods, instead of this: .. code-block:: python @@ -824,17 +815,17 @@ You can do this: return Response('delete') In the above example, we were able to take the ``route_name='rest'`` argument -out of the call to each individual ``@view_config`` statement, because we -used a ``@view_defaults`` class decorator to provide the argument as a -default to each view method it possessed. +out of the call to each individual ``@view_config`` statement because we used a +``@view_defaults`` class decorator to provide the argument as a default to each +view method it possessed. Arguments passed to ``@view_config`` will override any default passed to ``@view_defaults``. The ``view_defaults`` class decorator can also provide defaults to the :meth:`pyramid.config.Configurator.add_view` directive when a decorated class -is passed to that directive as its ``view`` argument. For example, instead -of this: +is passed to that directive as its ``view`` argument. For example, instead of +this: .. code-block:: python :linenos: @@ -868,7 +859,7 @@ of this: To reduce the amount of repetition in the ``config.add_view`` statements, we can move the ``route_name='rest'`` argument to a ``@view_defaults`` class -decorator on the RESTView class: +decorator on the ``RESTView`` class: .. code-block:: python :linenos: @@ -904,8 +895,8 @@ decorator on the RESTView class: argument passed to ``view_defaults`` provides a default for the view configurations of methods of the class it's decorating. -Normal Python inheritance rules apply to defaults added via -``view_defaults``. For example: +Normal Python inheritance rules apply to defaults added via ``view_defaults``. +For example: .. code-block:: python :linenos: @@ -919,8 +910,8 @@ Normal Python inheritance rules apply to defaults added via The ``Bar`` class above will inherit its view defaults from the arguments passed to the ``view_defaults`` decorator of the ``Foo`` class. To prevent -this from happening, use a ``view_defaults`` decorator without any arguments -on the subclass: +this from happening, use a ``view_defaults`` decorator without any arguments on +the subclass: .. code-block:: python :linenos: @@ -946,11 +937,11 @@ Configuring View Security ~~~~~~~~~~~~~~~~~~~~~~~~~ If an :term:`authorization policy` is active, any :term:`permission` attached -to a :term:`view configuration` found during view lookup will be verified. -This will ensure that the currently authenticated user possesses that -permission against the :term:`context` resource before the view function is -actually called. Here's an example of specifying a permission in a view -configuration using :meth:`~pyramid.config.Configurator.add_view`: +to a :term:`view configuration` found during view lookup will be verified. This +will ensure that the currently authenticated user possesses that permission +against the :term:`context` resource before the view function is actually +called. Here's an example of specifying a permission in a view configuration +using :meth:`~pyramid.config.Configurator.add_view`: .. code-block:: python :linenos: @@ -964,8 +955,8 @@ configuration using :meth:`~pyramid.config.Configurator.add_view`: 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 not possess the ``add`` permission relative to the current :term:`context`. -Instead the :term:`forbidden view` result will be returned to the client as -per :ref:`protecting_views`. +Instead the :term:`forbidden view` result will be returned to the client as per +:ref:`protecting_views`. .. index:: single: debugging not found errors @@ -976,14 +967,14 @@ per :ref:`protecting_views`. :exc:`~pyramid.exceptions.NotFound` Errors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It's useful to be able to debug :exc:`~pyramid.exceptions.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 -``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. +It's useful to be able to debug :exc:`~pyramid.exceptions.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 ``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 @@ -995,23 +986,23 @@ Influencing HTTP Caching .. versionadded:: 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 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: +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 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 +alternative 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 @@ -1024,19 +1015,19 @@ there's a ``should_cache`` GET or POST variable: 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 ``prevent_auto``. +Note that the ``http_cache`` machinery will overwrite or add to caching headers +you set within the view itself, unless you use ``prevent_auto``. -You can also turn off the effect of ``http_cache`` entirely for the duration -of a Pyramid application lifetime. To do so, set the +You can also turn off 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 -``pyramid.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 ``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. +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: view configuration; debugging |