| commit | author | age | ||
| 8a1b50 | 1 | .. _view_config_chapter: |
| CD | 2 | |
| 3 | .. _view_configuration: | |
| 4 | ||
| e81ad8 | 5 | .. _view_lookup: |
| CM | 6 | |
| 8a1b50 | 7 | View Configuration |
| CD | 8 | ================== |
| 9 | ||
| 10 | .. index:: | |
| 11 | single: view lookup | |
| 12 | ||
| 13 | :term:`View lookup` is the :app:`Pyramid` subsystem responsible for finding | |
| cab6fc | 14 | and invoking a :term:`view callable`. :term:`View configuration` controls how |
| e81ad8 | 15 | :term:`view lookup` operates in your application. During any given request, |
| CM | 16 | view configuration information is compared against request data by the view |
| 17 | lookup subsystem in order to find the "best" view callable for that request. | |
| 8a1b50 | 18 | |
| e81ad8 | 19 | In earlier chapters, you have been exposed to a few simple view configuration |
| CM | 20 | declarations without much explanation. In this chapter we will explore the |
| 21 | subject in detail. | |
| 8a1b50 | 22 | |
| 6ce1e0 | 23 | .. index:: |
| CM | 24 | pair: resource; mapping to view callable |
| 25 | pair: URL pattern; mapping to view callable | |
| 26 | ||
| 8a1b50 | 27 | Mapping a Resource or URL Pattern to a View Callable |
| CD | 28 | ---------------------------------------------------- |
| 29 | ||
| 30 | A developer makes a :term:`view callable` available for use within a | |
| 31 | :app:`Pyramid` application via :term:`view configuration`. A view | |
| 32 | configuration associates a view callable with a set of statements that | |
| 33 | determine the set of circumstances which must be true for the view callable | |
| 34 | to be invoked. | |
| 35 | ||
| 36 | A view configuration statement is made about information present in the | |
| 37 | :term:`context` resource and the :term:`request`. | |
| 38 | ||
| 026da8 | 39 | View configuration is performed in one of two ways: |
| 8a1b50 | 40 | |
| 03e38b | 41 | - By running a :term:`scan` against application source code which has a |
| 8a1b50 | 42 | :class:`pyramid.view.view_config` decorator attached to a Python object as |
| 70acd2 | 43 | per :ref:`mapping_views_using_a_decorator_section`. |
| 8a1b50 | 44 | |
| 03e38b | 45 | - By using the :meth:`pyramid.config.Configurator.add_view` method as per |
| 8a1b50 | 46 | :ref:`mapping_views_using_imperative_config_section`. |
| 6ce1e0 | 47 | |
| CM | 48 | .. index:: |
| 49 | single: view configuration parameters | |
| 8a1b50 | 50 | |
| CD | 51 | .. _view_configuration_parameters: |
| 52 | ||
| 53 | View Configuration Parameters | |
| 54 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 55 | ||
| 56 | All forms of view configuration accept the same general types of arguments. | |
| 57 | ||
| 58 | Many arguments supplied during view configuration are :term:`view predicate` | |
| 59 | arguments. View predicate arguments used during view configuration are used | |
| db14e3 | 60 | to narrow the set of circumstances in which :term:`view lookup` will find a |
| 2e3f70 | 61 | particular view callable. |
| 8a1b50 | 62 | |
| e81ad8 | 63 | :term:`View predicate` attributes are an important part of view configuration |
| CM | 64 | that enables the :term:`view lookup` subsystem to find and invoke the |
| 2605e0 | 65 | appropriate view. The greater the number of predicate attributes possessed by a |
| e81ad8 | 66 | view's configuration, the more specific the circumstances need to be before |
| 2605e0 | 67 | the registered view callable will be invoked. The fewer the number of predicates |
| e81ad8 | 68 | which are supplied to a particular view configuration, the more likely it is |
| CM | 69 | that the associated view callable will be invoked. A view with five |
| 70 | predicates will always be found and evaluated before a view with two, for | |
| 1fbbb4 | 71 | example. |
| 8a1b50 | 72 | |
| CD | 73 | This does not mean however, that :app:`Pyramid` "stops looking" when it |
| 74 | finds a view registration with predicates that don't match. If one set | |
| 75 | of view predicates does not match, the "next most specific" view (if | |
| 76 | any) is consulted for predicates, and so on, until a view is found, or | |
| 77 | no view can be matched up with the request. The first view with a set | |
| 78 | of predicates all of which match the request environment will be | |
| 79 | invoked. | |
| 80 | ||
| 81 | If no view can be found with predicates which allow it to be matched up with | |
| 82 | the request, :app:`Pyramid` will return an error to the user's browser, | |
| 83 | representing a "not found" (404) page. See :ref:`changing_the_notfound_view` | |
| cec2b0 | 84 | for more information about changing the default :term:`Not Found View`. |
| 8a1b50 | 85 | |
| e81ad8 | 86 | Other view configuration arguments are non-predicate arguments. These tend |
| CM | 87 | to modify the response of the view callable or prevent the view callable from |
| 8a1b50 | 88 | being invoked due to an authorization policy. The presence of non-predicate |
| CD | 89 | arguments in a view configuration does not narrow the circumstances in which |
| 90 | the view callable will be invoked. | |
| 91 | ||
| e573d4 | 92 | .. _nonpredicate_view_args: |
| CM | 93 | |
| 8a1b50 | 94 | Non-Predicate Arguments |
| CD | 95 | +++++++++++++++++++++++ |
| 96 | ||
| 97 | ``permission`` | |
| 98 | The name of a :term:`permission` that the user must possess in order to | |
| 99 | invoke the :term:`view callable`. See :ref:`view_security_section` for | |
| 100 | more information about view security and permissions. | |
| 2e3f70 | 101 | |
| 8a1b50 | 102 | If ``permission`` is not supplied, no permission is registered for this |
| CD | 103 | view (it's accessible by any caller). |
| 104 | ||
| 105 | ``attr`` | |
| 106 | The view machinery defaults to using the ``__call__`` method of the | |
| 107 | :term:`view callable` (or the function itself, if the view callable is a | |
| 108 | function) to obtain a response. The ``attr`` value allows you to vary the | |
| 109 | method attribute used to obtain the response. For example, if your view | |
| 110 | was a class, and the class has a method named ``index`` and you wanted to | |
| 111 | use this method instead of the class' ``__call__`` method to return the | |
| 112 | response, you'd say ``attr="index"`` in the view configuration for the | |
| 113 | view. This is most useful when the view definition is a class. | |
| 114 | ||
| 115 | If ``attr`` is not supplied, ``None`` is used (implying the function itself | |
| 116 | if the view is a function, or the ``__call__`` callable attribute if the | |
| 117 | view is a class). | |
| 118 | ||
| 119 | ``renderer`` | |
| 120 | Denotes the :term:`renderer` implementation which will be used to construct | |
| 121 | a :term:`response` from the associated view callable's return value. (see | |
| 122 | also :ref:`renderers_chapter`). | |
| 123 | ||
| 124 | This is either a single string term (e.g. ``json``) or a string implying a | |
| 125 | path or :term:`asset specification` (e.g. ``templates/views.pt``) naming a | |
| 126 | :term:`renderer` implementation. If the ``renderer`` value does not | |
| 127 | contain a dot (``.``), the specified string will be used to look up a | |
| 128 | renderer implementation, and that renderer implementation will be used to | |
| 129 | construct a response from the view return value. If the ``renderer`` value | |
| 130 | contains a dot (``.``), the specified term will be treated as a path, and | |
| 131 | the filename extension of the last element in the path will be used to look | |
| 132 | up the renderer implementation, which will be passed the full path. | |
| 133 | ||
| 134 | When the renderer is a path, although a path is usually just a simple | |
| 135 | relative pathname (e.g. ``templates/foo.pt``, implying that a template | |
| 136 | named "foo.pt" is in the "templates" directory relative to the directory of | |
| 137 | the current :term:`package`), a path can be absolute, starting with a slash | |
| 138 | on UNIX or a drive letter prefix on Windows. The path can alternately be a | |
| 139 | :term:`asset specification` in the form | |
| 140 | ``some.dotted.package_name:relative/path``, making it possible to address | |
| 141 | template assets which live in a separate package. | |
| 142 | ||
| 143 | The ``renderer`` attribute is optional. If it is not defined, the "null" | |
| 144 | renderer is assumed (no rendering is performed and the value is passed back | |
| 7a2ab7 | 145 | to the upstream :app:`Pyramid` machinery unchanged). Note that if the |
| 8a1b50 | 146 | view callable itself returns a :term:`response` (see :ref:`the_response`), |
| CD | 147 | the specified renderer implementation is never called. |
| 148 | ||
| 0fa199 | 149 | ``http_cache`` |
| CM | 150 | When you supply an ``http_cache`` value to a view configuration, the |
| 151 | ``Expires`` and ``Cache-Control`` headers of a response generated by the | |
| 152 | associated view callable are modified. The value for ``http_cache`` may be | |
| 153 | one of the following: | |
| 154 | ||
| 155 | - A nonzero integer. If it's a nonzero integer, it's treated as a number | |
| 156 | of seconds. This number of seconds will be used to compute the | |
| 157 | ``Expires`` header and the ``Cache-Control: max-age`` parameter of | |
| 158 | responses to requests which call this view. For example: | |
| 159 | ``http_cache=3600`` instructs the requesting browser to 'cache this | |
| 160 | response for an hour, please'. | |
| 161 | ||
| 162 | - A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta`` | |
| 163 | instance, it will be converted into a number of seconds, and that number | |
| 164 | of seconds will be used to compute the ``Expires`` header and the | |
| 165 | ``Cache-Control: max-age`` parameter of responses to requests which call | |
| 166 | this view. For example: ``http_cache=datetime.timedelta(days=1)`` | |
| 167 | instructs the requesting browser to 'cache this response for a day, | |
| 168 | please'. | |
| 169 | ||
| 170 | - Zero (``0``). If the value is zero, the ``Cache-Control`` and | |
| 171 | ``Expires`` headers present in all responses from this view will be | |
| 172 | composed such that client browser cache (and any intermediate caches) are | |
| 173 | instructed to never cache the response. | |
| 174 | ||
| 175 | - A two-tuple. If it's a two tuple (e.g. ``http_cache=(1, | |
| 176 | {'public':True})``), the first value in the tuple may be a nonzero | |
| 177 | integer or a ``datetime.timedelta`` instance; in either case this value | |
| 178 | will be used as the number of seconds to cache the response. The second | |
| 179 | value in the tuple must be a dictionary. The values present in the | |
| 180 | dictionary will be used as input to the ``Cache-Control`` response | |
| 181 | header. For example: ``http_cache=(3600, {'public':True})`` means 'cache | |
| 182 | for an hour, and add ``public`` to the Cache-Control header of the | |
| 183 | response'. All keys and values supported by the | |
| 184 | ``webob.cachecontrol.CacheControl`` interface may be added to the | |
| 185 | dictionary. Supplying ``{'public':True}`` is equivalent to calling | |
| 186 | ``response.cache_control.public = True``. | |
| 187 | ||
| 188 | Providing a non-tuple value as ``http_cache`` is equivalent to calling | |
| 189 | ``response.cache_expires(value)`` within your view's body. | |
| 190 | ||
| 191 | Providing a two-tuple value as ``http_cache`` is equivalent to calling | |
| 192 | ``response.cache_expires(value[0], **value[1])`` within your view's body. | |
| 193 | ||
| 194 | If you wish to avoid influencing, the ``Expires`` header, and instead wish | |
| 195 | to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` | |
| 196 | with the first element of ``None``, e.g.: ``(None, {'public':True})``. | |
| 197 | ||
| 8a1b50 | 198 | ``wrapper`` |
| CD | 199 | The :term:`view name` of a different :term:`view configuration` which will |
| 200 | receive the response body of this view as the ``request.wrapped_body`` | |
| 201 | attribute of its own :term:`request`, and the :term:`response` returned by | |
| 202 | this view as the ``request.wrapped_response`` attribute of its own request. | |
| 203 | Using a wrapper makes it possible to "chain" views together to form a | |
| 204 | composite response. The response of the outermost wrapper view will be | |
| 205 | returned to the user. The wrapper view will be found as any view is found: | |
| 206 | see :ref:`view_lookup`. The "best" wrapper view will be found based on the | |
| 207 | lookup ordering: "under the hood" this wrapper view is looked up via | |
| 208 | ``pyramid.view.render_view_to_response(context, request, | |
| 209 | 'wrapper_viewname')``. The context and request of a wrapper view is the | |
| 210 | same context and request of the inner view. | |
| 211 | ||
| 212 | If ``wrapper`` is not supplied, no wrapper view is used. | |
| 213 | ||
| f7f0dd | 214 | ``decorator`` |
| 86fc0c | 215 | A :term:`dotted Python name` to a function (or the function itself) which |
| f7f0dd | 216 | will be used to decorate the registered :term:`view callable`. The |
| CM | 217 | decorator function will be called with the view callable as a single |
| 218 | argument. The view callable it is passed will accept ``(context, | |
| 219 | request)``. The decorator must return a replacement view callable which | |
| 220 | also accepts ``(context, request)``. | |
| 2e3f70 | 221 | |
| f7f0dd | 222 | ``mapper`` |
| CM | 223 | A Python object or :term:`dotted Python name` which refers to a :term:`view |
| 224 | mapper`, or ``None``. By default it is ``None``, which indicates that the | |
| 225 | view should use the default view mapper. This plug-point is useful for | |
| 226 | Pyramid extension developers, but it's not very useful for 'civilians' who | |
| 227 | are just developing stock Pyramid applications. Pay no attention to the man | |
| 228 | behind the curtain. | |
| 229 | ||
| 8a1b50 | 230 | Predicate Arguments |
| CD | 231 | +++++++++++++++++++ |
| 232 | ||
| 233 | These arguments modify view lookup behavior. In general, the more predicate | |
| 234 | arguments that are supplied, the more specific, and narrower the usage of the | |
| 235 | configured view. | |
| 236 | ||
| 237 | ``name`` | |
| 8cb682 | 238 | The :term:`view name` required to match this view callable. A ``name`` |
| CM | 239 | argument is typically only used when your application uses |
| 240 | :term:`traversal`. Read :ref:`traversal_chapter` to understand the concept | |
| 241 | of a view name. | |
| 8a1b50 | 242 | |
| CD | 243 | If ``name`` is not supplied, the empty string is used (implying the default |
| 244 | view). | |
| 245 | ||
| 246 | ``context`` | |
| 247 | An object representing a Python class that the :term:`context` resource | |
| 248 | must be an instance of *or* the :term:`interface` that the :term:`context` | |
| 249 | resource must provide in order for this view to be found and called. This | |
| 250 | predicate is true when the :term:`context` resource is an instance of the | |
| 251 | represented class or if the :term:`context` resource provides the | |
| 252 | represented interface; it is otherwise false. | |
| 253 | ||
| 254 | If ``context`` is not supplied, the value ``None``, which matches any | |
| 255 | resource, is used. | |
| 256 | ||
| 257 | ``route_name`` | |
| 258 | If ``route_name`` is supplied, the view callable will be invoked only when | |
| 259 | the named route has matched. | |
| 260 | ||
| 261 | This value must match the ``name`` of a :term:`route configuration` | |
| 262 | declaration (see :ref:`urldispatch_chapter`) that must match before this | |
| 263 | view will be called. Note that the ``route`` configuration referred to by | |
| 264 | ``route_name`` will usually have a ``*traverse`` token in the value of its | |
| 265 | ``pattern``, representing a part of the path that will be used by | |
| 266 | :term:`traversal` against the result of the route's :term:`root factory`. | |
| 267 | ||
| 2e3f70 | 268 | If ``route_name`` is not supplied, the view callable will only have a chance |
| 8a1b50 | 269 | of being invoked if no other route was matched. This is when the |
| CD | 270 | request/context pair found via :term:`resource location` does not indicate |
| 271 | it matched any configured route. | |
| 272 | ||
| 273 | ``request_type`` | |
| 274 | This value should be an :term:`interface` that the :term:`request` must | |
| 275 | provide in order for this view to be found and called. | |
| 276 | ||
| 277 | If ``request_type`` is not supplied, the value ``None`` is used, implying | |
| 278 | any request type. | |
| 279 | ||
| 280 | *This is an advanced feature, not often used by "civilians"*. | |
| 281 | ||
| 282 | ``request_method`` | |
| 73d3a8 | 283 | This value can be a string (typically ``"GET"``, ``"POST"``, ``"PUT"``, |
| PW | 284 | ``"DELETE"``, or ``"HEAD"``) representing an HTTP ``REQUEST_METHOD``. A view |
| 8a1b50 | 285 | declaration with this argument ensures that the view will only be called |
| CD | 286 | when the request's ``method`` attribute (aka the ``REQUEST_METHOD`` of the |
| 287 | WSGI environment) string matches the supplied value. | |
| 288 | ||
| 289 | If ``request_method`` is not supplied, the view will be invoked regardless | |
| 290 | of the ``REQUEST_METHOD`` of the :term:`WSGI` environment. | |
| 291 | ||
| 292 | ``request_param`` | |
| a62912 | 293 | This value can be any string or a sequence of strings. A view declaration |
| SP | 294 | with this argument ensures that the view will only be called when the |
| 295 | :term:`request` has a key in the ``request.params`` dictionary (an HTTP | |
| c0e0ac | 296 | ``GET`` or ``POST`` variable) that has a name which matches the |
| 06a904 | 297 | supplied value. |
| 8a1b50 | 298 | |
| 06a904 | 299 | If any value supplied has a ``=`` sign in it, |
| fe164c | 300 | e.g. ``request_param="foo=123"``, then the key (``foo``) must both exist |
| 8a1b50 | 301 | in the ``request.params`` dictionary, *and* the value must match the right |
| CD | 302 | hand side of the expression (``123``) for the view to "match" the current |
| 303 | request. | |
| 304 | ||
| 305 | If ``request_param`` is not supplied, the view will be invoked without | |
| 306 | consideration of keys and values in the ``request.params`` dictionary. | |
| 307 | ||
| c0e6e6 | 308 | ``match_param`` |
| CM | 309 | This param may be either a single string of the format "key=value" or a |
| 310 | dict of key/value pairs. | |
| 311 | ||
| 312 | This argument ensures that the view will only be called when the | |
| 313 | :term:`request` has key/value pairs in its :term:`matchdict` that equal | |
| dd1c53 | 314 | those supplied in the predicate. e.g. ``match_param="action=edit"`` would |
| c0e6e6 | 315 | require the ``action`` parameter in the :term:`matchdict` match the right |
| dd1c53 | 316 | hand side of the expression (``edit``) for the view to "match" the current |
| c0e6e6 | 317 | request. |
| CM | 318 | |
| 319 | If the ``match_param`` is a dict, every key/value pair must match for the | |
| 320 | predicate to pass. | |
| 321 | ||
| 322 | If ``match_param`` is not supplied, the view will be invoked without | |
| 323 | consideration of the keys and values in ``request.matchdict``. | |
| a62912 | 324 | |
| SP | 325 | .. versionadded:: 1.2 |
| c0e6e6 | 326 | |
| 8a1b50 | 327 | ``containment`` |
| CD | 328 | This value should be a reference to a Python class or :term:`interface` |
| 329 | that a parent object in the context resource's :term:`lineage` must provide | |
| 330 | in order for this view to be found and called. The resources in your | |
| 331 | resource tree must be "location-aware" to use this feature. | |
| 332 | ||
| 333 | If ``containment`` is not supplied, the interfaces and classes in the | |
| 334 | lineage are not considered when deciding whether or not to invoke the view | |
| 335 | callable. | |
| 336 | ||
| 337 | See :ref:`location_aware` for more information about location-awareness. | |
| 338 | ||
| 339 | ``xhr`` | |
| 340 | This value should be either ``True`` or ``False``. If this value is | |
| 341 | specified and is ``True``, the :term:`WSGI` environment must possess an | |
| 342 | ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header that has the | |
| 343 | value ``XMLHttpRequest`` for the associated view callable to be found and | |
| 344 | called. This is useful for detecting AJAX requests issued from jQuery, | |
| 345 | Prototype and other Javascript libraries. | |
| 346 | ||
| 347 | If ``xhr`` is not specified, the ``HTTP_X_REQUESTED_WITH`` HTTP header is | |
| 348 | not taken into consideration when deciding whether or not to invoke the | |
| 349 | associated view callable. | |
| 350 | ||
| 351 | ``accept`` | |
| 352 | The value of this argument represents a match query for one or more | |
| 353 | mimetypes in the ``Accept`` HTTP request header. If this value is | |
| 354 | specified, it must be in one of the following forms: a mimetype match token | |
| 355 | in the form ``text/plain``, a wildcard mimetype match token in the form | |
| 356 | ``text/*`` or a match-all wildcard mimetype match token in the form | |
| 357 | ``*/*``. If any of the forms matches the ``Accept`` header of the request, | |
| 358 | this predicate will be true. | |
| 359 | ||
| 360 | If ``accept`` is not specified, the ``HTTP_ACCEPT`` HTTP header is not | |
| 361 | taken into consideration when deciding whether or not to invoke the | |
| 362 | associated view callable. | |
| 363 | ||
| 364 | ``header`` | |
| 365 | This value represents an HTTP header name or a header name/value pair. | |
| 366 | ||
| 367 | If ``header`` is specified, it must be a header name or a | |
| 368 | ``headername:headervalue`` pair. | |
| 369 | ||
| 370 | If ``header`` is specified without a value (a bare header name only, | |
| 371 | e.g. ``If-Modified-Since``), the view will only be invoked if the HTTP | |
| 372 | header exists with any value in the request. | |
| 373 | ||
| 374 | If ``header`` is specified, and possesses a name/value pair | |
| 375 | (e.g. ``User-Agent:Mozilla/.*``), the view will only be invoked if the HTTP | |
| 376 | header exists *and* the HTTP header matches the value requested. When the | |
| 377 | ``headervalue`` contains a ``:`` (colon), it will be considered a | |
| 378 | name/value pair (e.g. ``User-Agent:Mozilla/.*`` or ``Host:localhost``). | |
| 379 | The value portion should be a regular expression. | |
| 380 | ||
| 381 | Whether or not the value represents a header name or a header name/value | |
| 382 | pair, the case of the header name is not significant. | |
| 383 | ||
| 384 | If ``header`` is not specified, the composition, presence or absence of | |
| 385 | HTTP headers is not taken into consideration when deciding whether or not | |
| 386 | to invoke the associated view callable. | |
| 387 | ||
| 388 | ``path_info`` | |
| 389 | This value represents a regular expression pattern that will be tested | |
| 390 | against the ``PATH_INFO`` WSGI environment variable to decide whether or | |
| 391 | not to call the associated view callable. If the regex matches, this | |
| 392 | predicate will be ``True``. | |
| 393 | ||
| 394 | If ``path_info`` is not specified, the WSGI ``PATH_INFO`` is not taken into | |
| 395 | consideration when deciding whether or not to invoke the associated view | |
| 396 | callable. | |
| 397 | ||
| 643a83 | 398 | ``check_csrf`` |
| CM | 399 | If specified, this value should be one of ``None``, ``True``, ``False``, or |
| 400 | a string representing the 'check name'. If the value is ``True`` or a | |
| 401 | string, CSRF checking will be performed. If the value is ``False`` or | |
| 402 | ``None``, CSRF checking will not be performed. | |
| 403 | ||
| 404 | If the value provided is a string, that string will be used as the 'check | |
| 405 | name'. If the value provided is ``True``, ``csrf_token`` will be used as | |
| 406 | the check name. | |
| 407 | ||
| 408 | If CSRF checking is performed, the checked value will be the value of | |
| 409 | ``request.params[check_name]``. This value will be compared against the | |
| 410 | value of ``request.session.get_csrf_token()``, and the check will pass if | |
| 411 | these two values are the same. If the check passes, the associated view | |
| 412 | will be permitted to execute. If the check fails, the associated view | |
| 413 | will not be permitted to execute. | |
| 414 | ||
| 415 | Note that using this feature requires a :term:`session factory` to have | |
| 416 | been configured. | |
| 417 | ||
| 418 | .. versionadded:: 1.4a2 | |
| 419 | ||
| c25a8f | 420 | ``physical_path`` |
| CM | 421 | If specified, this value should be a string or a tuple representing the |
| 422 | :term:`physical path` of the context found via traversal for this predicate | |
| 423 | to match as true. For example: ``physical_path='/'`` or | |
| 424 | ``physical_path='/a/b/c'`` or ``physical_path=('', 'a', 'b', 'c')``. This is | |
| 425 | not a path prefix match or a regex, it's a whole-path match. It's useful | |
| 426 | when you want to always potentially show a view when some object is traversed | |
| 427 | to, but you can't be sure about what kind of object it will be, so you can't | |
| 428 | use the ``context`` predicate. The individual path elements inbetween slash | |
| 429 | characters or in tuple elements should be the Unicode representation of the | |
| 430 | name of the resource and should not be encoded in any way. | |
| 431 | ||
| 432 | .. versionadded:: 1.4a3 | |
| 433 | ||
| c7337b | 434 | ``effective_principals`` |
| CM | 435 | |
| 436 | If specified, this value should be a :term:`principal` identifier or a | |
| 437 | sequence of principal identifiers. If the | |
| 438 | :func:`pyramid.security.effective_principals` method indicates that every | |
| 439 | principal named in the argument list is present in the current request, this | |
| 440 | predicate will return True; otherwise it will return False. For example: | |
| 441 | ``effective_principals=pyramid.security.Authenticated`` or | |
| 442 | ``effective_principals=('fred', 'group:admins')``. | |
| 443 | ||
| 444 | .. versionadded:: 1.4a4 | |
| 445 | ||
| 8a1b50 | 446 | ``custom_predicates`` |
| CD | 447 | If ``custom_predicates`` is specified, it must be a sequence of references |
| 448 | to custom predicate callables. Use custom predicates when no set of | |
| 449 | predefined predicates do what you need. Custom predicates can be combined | |
| 450 | with predefined predicates as necessary. Each custom predicate callable | |
| 451 | should accept two arguments: ``context`` and ``request`` and should return | |
| 452 | either ``True`` or ``False`` after doing arbitrary evaluation of the | |
| 453 | context resource and/or the request. If all callables return ``True``, the | |
| 454 | associated view callable will be considered viable for a given request. | |
| 455 | ||
| 456 | If ``custom_predicates`` is not specified, no custom predicates are | |
| 457 | used. | |
| 458 | ||
| 643a83 | 459 | ``predicates`` |
| CM | 460 | Pass a key/value pair here to use a third-party predicate registered via |
| 461 | :meth:`pyramid.config.Configurator.add_view_predicate`. More than one | |
| 462 | key/value pair can be used at the same time. See | |
| 463 | :ref:`view_and_route_predicates` for more information about third-party | |
| 464 | predicates. | |
| 465 | ||
| 466 | .. versionadded:: 1.4a1 | |
| 467 | ||
| 8a1b50 | 468 | .. index:: |
| CD | 469 | single: view_config decorator |
| 470 | ||
| 471 | .. _mapping_views_using_a_decorator_section: | |
| 472 | ||
| e81ad8 | 473 | Adding View Configuration Using the ``@view_config`` Decorator |
| CM | 474 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 8a1b50 | 475 | |
| CD | 476 | .. warning:: |
| 477 | ||
| 58661e | 478 | Using this feature tends to slow down application startup slightly, as |
| 8a1b50 | 479 | more work is performed at application startup to scan for view |
| e81ad8 | 480 | configuration declarations. For maximum startup performance, use the view |
| CM | 481 | configuration method described in |
| 482 | :ref:`mapping_views_using_imperative_config_section` instead. | |
| 8a1b50 | 483 | |
| e81ad8 | 484 | The :class:`~pyramid.view.view_config` decorator can be used to associate |
| CM | 485 | :term:`view configuration` information with a function, method, or class that |
| 486 | acts as a :app:`Pyramid` view callable. | |
| 8a1b50 | 487 | |
| 026da8 | 488 | Here's an example of the :class:`~pyramid.view.view_config` decorator that |
| CM | 489 | lives within a :app:`Pyramid` application module ``views.py``: |
| 8a1b50 | 490 | |
| CD | 491 | .. code-block:: python |
| 492 | :linenos: | |
| 493 | ||
| 494 | from resources import MyResource | |
| 495 | from pyramid.view import view_config | |
| 496 | from pyramid.response import Response | |
| 497 | ||
| 8cb682 | 498 | @view_config(route_name='ok', request_method='POST', permission='read') |
| 8a1b50 | 499 | def my_view(request): |
| CD | 500 | return Response('OK') |
| 501 | ||
| 502 | Using this decorator as above replaces the need to add this imperative | |
| 503 | configuration stanza: | |
| 504 | ||
| 505 | .. code-block:: python | |
| 506 | :linenos: | |
| 507 | ||
| a62912 | 508 | config.add_view('mypackage.views.my_view', route_name='ok', |
| 8cb682 | 509 | request_method='POST', permission='read') |
| 8a1b50 | 510 | |
| CD | 511 | All arguments to ``view_config`` may be omitted. For example: |
| 512 | ||
| 513 | .. code-block:: python | |
| 514 | :linenos: | |
| 515 | ||
| 516 | from pyramid.response import Response | |
| 517 | from pyramid.view import view_config | |
| 518 | ||
| 519 | @view_config() | |
| 520 | def my_view(request): | |
| 521 | """ My view """ | |
| 522 | return Response() | |
| 523 | ||
| 524 | Such a registration as the one directly above implies that the view name will | |
| 525 | be ``my_view``, registered with a ``context`` argument that matches any | |
| 526 | resource type, using no permission, registered against requests with any | |
| 527 | request method, request type, request param, route name, or containment. | |
| 528 | ||
| 529 | The mere existence of a ``@view_config`` decorator doesn't suffice to perform | |
| 530 | view configuration. All that the decorator does is "annotate" the function | |
| 531 | with your configuration declarations, it doesn't process them. To make | |
| 532 | :app:`Pyramid` process your :class:`pyramid.view.view_config` declarations, | |
| 86fc0c | 533 | you *must* use the ``scan`` method of a |
| 8a1b50 | 534 | :class:`pyramid.config.Configurator`: |
| CD | 535 | |
| 536 | .. code-block:: python | |
| 537 | :linenos: | |
| 538 | ||
| 539 | # config is assumed to be an instance of the | |
| 540 | # pyramid.config.Configurator class | |
| 541 | config.scan() | |
| 542 | ||
| 543 | Please see :ref:`decorations_and_code_scanning` for detailed information | |
| 544 | about what happens when code is scanned for configuration declarations | |
| 70acd2 | 545 | resulting from use of decorators like :class:`~pyramid.view.view_config`. |
| 8a1b50 | 546 | |
| CD | 547 | See :ref:`configuration_module` for additional API arguments to the |
| 70acd2 | 548 | :meth:`~pyramid.config.Configurator.scan` method. For example, the method |
| 8a1b50 | 549 | allows you to supply a ``package`` argument to better control exactly *which* |
| CD | 550 | code will be scanned. |
| e81ad8 | 551 | |
| CM | 552 | All arguments to the :class:`~pyramid.view.view_config` decorator mean |
| 553 | precisely the same thing as they would if they were passed as arguments to | |
| 554 | the :meth:`pyramid.config.Configurator.add_view` method save for the ``view`` | |
| 555 | argument. Usage of the :class:`~pyramid.view.view_config` decorator is a | |
| 556 | form of :term:`declarative configuration`, while | |
| 557 | :meth:`pyramid.config.Configurator.add_view` is a form of :term:`imperative | |
| 558 | configuration`. However, they both do the same thing. | |
| 8a1b50 | 559 | |
| 32333e | 560 | Inverting Predicate Values |
| CM | 561 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 562 | ||
| 5fc0d3 | 563 | You can invert the meaning of a supported predicate value by wrapping it in a |
| CM | 564 | call to :class:`pyramid.config.not_`. |
| 32333e | 565 | |
| CM | 566 | .. code-block:: python |
| 567 | :linenos: | |
| 568 | ||
| 569 | from pyramid.config import not_ | |
| 570 | ||
| 571 | config.add_view( | |
| 572 | 'mypackage.views.my_view', | |
| a62912 | 573 | route_name='ok', |
| 5fc0d3 | 574 | header=not_('X-Foo') |
| 32333e | 575 | ) |
| CM | 576 | |
| 577 | The above example will ensure that the view is called if the request method | |
| 5fc0d3 | 578 | does not have the ``X-Foo`` header, at least if no other view is more specific. |
| CM | 579 | |
| 580 | A predicate must be *negatable* to use ``not_`` against its value. The current | |
| 581 | set of built-in negatable predicates are: ``path_info``, ``request_param``, | |
| 582 | ``header``, ``containment``, ``request_type``, ``match_param``, | |
| 583 | ``physical_path``, and ``effective_principals``. If you try to use ``not_`` | |
| 584 | against a non-negatable predicate, an error will be raised at startup time. | |
| 585 | ||
| 586 | You can make sure a custom view predicate added via | |
| 587 | :meth:`pyramid.config.Configurator.add_view_predicate` is negatable by adding a | |
| 588 | ``negatable`` attribute to it that is True. | |
| 32333e | 589 | |
| CM | 590 | This technique of wrapping a predicate value in ``not_`` can be used anywhere |
| 591 | predicate values are accepted: | |
| 592 | ||
| 593 | - :meth:`pyramid.config.Configurator.add_view` | |
| 594 | ||
| 595 | - :meth:`pyramid.view.view_config` | |
| 596 | ||
| bb9948 | 597 | .. versionadded:: 1.5 |
| CM | 598 | |
| 6ce1e0 | 599 | .. index:: |
| CM | 600 | single: view_config placement |
| 601 | ||
| bb93cb | 602 | .. _view_config_placement: |
| CM | 603 | |
| 8a1b50 | 604 | ``@view_config`` Placement |
| CD | 605 | ++++++++++++++++++++++++++ |
| 606 | ||
| 70acd2 | 607 | A :class:`~pyramid.view.view_config` decorator can be placed in various points |
| 8a1b50 | 608 | in your application. |
| CD | 609 | |
| 610 | If your view callable is a function, it may be used as a function decorator: | |
| 611 | ||
| 612 | .. code-block:: python | |
| 613 | :linenos: | |
| 614 | ||
| 615 | from pyramid.view import view_config | |
| 616 | from pyramid.response import Response | |
| 617 | ||
| 8cb682 | 618 | @view_config(route_name='edit') |
| 8a1b50 | 619 | def edit(request): |
| CD | 620 | return Response('edited!') |
| 621 | ||
| 622 | If your view callable is a class, the decorator can also be used as a class | |
| 136a1e | 623 | decorator. All the arguments to the decorator are the same when applied |
| 8a1b50 | 624 | against a class as when they are applied against a function. For example: |
| CD | 625 | |
| 626 | .. code-block:: python | |
| 627 | :linenos: | |
| 628 | ||
| 629 | from pyramid.response import Response | |
| 630 | from pyramid.view import view_config | |
| 631 | ||
| 8cb682 | 632 | @view_config(route_name='hello') |
| 8a1b50 | 633 | class MyView(object): |
| CD | 634 | def __init__(self, request): |
| 635 | self.request = request | |
| 636 | ||
| 637 | def __call__(self): | |
| 638 | return Response('hello') | |
| 639 | ||
| 70acd2 | 640 | More than one :class:`~pyramid.view.view_config` decorator can be stacked on |
| 8a1b50 | 641 | top of any number of others. Each decorator creates a separate view |
| CD | 642 | registration. For example: |
| 643 | ||
| 644 | .. code-block:: python | |
| 645 | :linenos: | |
| 646 | ||
| 647 | from pyramid.view import view_config | |
| 648 | from pyramid.response import Response | |
| 649 | ||
| 8cb682 | 650 | @view_config(route_name='edit') |
| CM | 651 | @view_config(route_name='change') |
| 8a1b50 | 652 | def edit(request): |
| CD | 653 | return Response('edited!') |
| 654 | ||
| 655 | This registers the same view under two different names. | |
| 656 | ||
| 2e3f70 | 657 | The decorator can also be used against a method of a class: |
| 8a1b50 | 658 | |
| CD | 659 | .. code-block:: python |
| 660 | :linenos: | |
| 661 | ||
| 662 | from pyramid.response import Response | |
| 663 | from pyramid.view import view_config | |
| 664 | ||
| 665 | class MyView(object): | |
| 666 | def __init__(self, request): | |
| 667 | self.request = request | |
| 668 | ||
| 8cb682 | 669 | @view_config(route_name='hello') |
| 8a1b50 | 670 | def amethod(self): |
| CD | 671 | return Response('hello') |
| 672 | ||
| 2e3f70 | 673 | When the decorator is used against a method of a class, a view is registered |
| CZ | 674 | for the *class*, so the class constructor must accept an argument list in one |
| 675 | of two forms: either it must accept a single argument ``request`` or it must | |
| 8a1b50 | 676 | accept two arguments, ``context, request``. |
| CD | 677 | |
| 678 | The method which is decorated must return a :term:`response`. | |
| 679 | ||
| 680 | Using the decorator against a particular method of a class is equivalent to | |
| 681 | using the ``attr`` parameter in a decorator attached to the class itself. | |
| 682 | For example, the above registration implied by the decorator being used | |
| 683 | against the ``amethod`` method could be spelled equivalently as the below: | |
| 684 | ||
| 685 | .. code-block:: python | |
| 686 | :linenos: | |
| 687 | ||
| 688 | from pyramid.response import Response | |
| 689 | from pyramid.view import view_config | |
| 690 | ||
| 8cb682 | 691 | @view_config(attr='amethod', route_name='hello') |
| 8a1b50 | 692 | class MyView(object): |
| CD | 693 | def __init__(self, request): |
| 694 | self.request = request | |
| 695 | ||
| 696 | def amethod(self): | |
| 697 | return Response('hello') | |
| 698 | ||
| 4375cf | 699 | |
| 8a1b50 | 700 | .. index:: |
| CD | 701 | single: add_view |
| 702 | ||
| 703 | .. _mapping_views_using_imperative_config_section: | |
| 704 | ||
| e81ad8 | 705 | Adding View Configuration Using :meth:`~pyramid.config.Configurator.add_view` |
| CM | 706 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 8a1b50 | 707 | |
| CD | 708 | The :meth:`pyramid.config.Configurator.add_view` method within |
| 026da8 | 709 | :ref:`configuration_module` is used to configure a view "imperatively" |
| e81ad8 | 710 | (without a :class:`~pyramid.view.view_config` decorator). The arguments to |
| 026da8 | 711 | this method are very similar to the arguments that you provide to the |
| CM | 712 | :class:`~pyramid.view.view_config` decorator. For example: |
| 8a1b50 | 713 | |
| CD | 714 | .. code-block:: python |
| 715 | :linenos: | |
| 716 | ||
| 717 | from pyramid.response import Response | |
| 718 | ||
| 719 | def hello_world(request): | |
| 720 | return Response('hello!') | |
| 721 | ||
| 722 | # config is assumed to be an instance of the | |
| 723 | # pyramid.config.Configurator class | |
| 8cb682 | 724 | config.add_view(hello_world, route_name='hello') |
| 8a1b50 | 725 | |
| 8b9643 | 726 | The first argument, a :term:`view callable`, is the only required argument. |
| TL | 727 | It must either be a Python object which is the view itself or a |
| 728 | :term:`dotted Python name` to such an object. | |
| 729 | In the above example, the ``view callable`` is the ``hello_world`` function. | |
| 026da8 | 730 | |
| CM | 731 | When you use only :meth:`~pyramid.config.Configurator.add_view` to add view |
| 732 | configurations, you don't need to issue a :term:`scan` in order for the view | |
| 733 | configuration to take effect. | |
| 8a1b50 | 734 | |
| CD | 735 | .. index:: |
| 4375cf | 736 | single: view_defaults class decorator |
| CM | 737 | |
| 738 | .. _view_defaults: | |
| 739 | ||
| 740 | ``@view_defaults`` Class Decorator | |
| 741 | ---------------------------------- | |
| 742 | ||
| 40dbf4 | 743 | .. versionadded:: 1.3 |
| 4375cf | 744 | |
| CM | 745 | If you use a class as a view, you can use the |
| 746 | :class:`pyramid.view.view_defaults` class decorator on the class to provide | |
| 747 | defaults to the view configuration information used by every ``@view_config`` | |
| 748 | decorator that decorates a method of that class. | |
| 749 | ||
| 750 | For instance, if you've got a class that has methods that represent "REST | |
| 751 | actions", all which are mapped to the same route, but different request | |
| 752 | methods, instead of this: | |
| 753 | ||
| 754 | .. code-block:: python | |
| 755 | :linenos: | |
| 756 | ||
| 757 | from pyramid.view import view_config | |
| 758 | from pyramid.response import Response | |
| 759 | ||
| 760 | class RESTView(object): | |
| 761 | def __init__(self, request): | |
| 762 | self.request = request | |
| 763 | ||
| 764 | @view_config(route_name='rest', request_method='GET') | |
| 765 | def get(self): | |
| 766 | return Response('get') | |
| 767 | ||
| 768 | @view_config(route_name='rest', request_method='POST') | |
| 769 | def post(self): | |
| 770 | return Response('post') | |
| 771 | ||
| 772 | @view_config(route_name='rest', request_method='DELETE') | |
| 773 | def delete(self): | |
| 774 | return Response('delete') | |
| 775 | ||
| 776 | You can do this: | |
| 777 | ||
| 778 | .. code-block:: python | |
| 779 | :linenos: | |
| 780 | ||
| 781 | from pyramid.view import view_defaults | |
| 782 | from pyramid.view import view_config | |
| 783 | from pyramid.response import Response | |
| 784 | ||
| 785 | @view_defaults(route_name='rest') | |
| 786 | class RESTView(object): | |
| 787 | def __init__(self, request): | |
| 788 | self.request = request | |
| 789 | ||
| 790 | @view_config(request_method='GET') | |
| 791 | def get(self): | |
| 792 | return Response('get') | |
| 793 | ||
| 794 | @view_config(request_method='POST') | |
| 795 | def post(self): | |
| 796 | return Response('post') | |
| 797 | ||
| 798 | @view_config(request_method='DELETE') | |
| 799 | def delete(self): | |
| 800 | return Response('delete') | |
| 801 | ||
| 802 | In the above example, we were able to take the ``route_name='rest'`` argument | |
| 803 | out of the call to each individual ``@view_config`` statement, because we | |
| 804 | used a ``@view_defaults`` class decorator to provide the argument as a | |
| 805 | default to each view method it possessed. | |
| 806 | ||
| 807 | Arguments passed to ``@view_config`` will override any default passed to | |
| 808 | ``@view_defaults``. | |
| 809 | ||
| 810 | The ``view_defaults`` class decorator can also provide defaults to the | |
| 811 | :meth:`pyramid.config.Configurator.add_view` directive when a decorated class | |
| 812 | is passed to that directive as its ``view`` argument. For example, instead | |
| 813 | of this: | |
| 814 | ||
| 815 | .. code-block:: python | |
| 816 | :linenos: | |
| 817 | ||
| 818 | from pyramid.response import Response | |
| 819 | from pyramid.config import Configurator | |
| 820 | ||
| 821 | class RESTView(object): | |
| 822 | def __init__(self, request): | |
| 823 | self.request = request | |
| 824 | ||
| 825 | def get(self): | |
| 826 | return Response('get') | |
| 827 | ||
| 828 | def post(self): | |
| 829 | return Response('post') | |
| 830 | ||
| 831 | def delete(self): | |
| 832 | return Response('delete') | |
| 833 | ||
| 834 | if __name__ == '__main__': | |
| 835 | config = Configurator() | |
| 836 | config.add_route('rest', '/rest') | |
| 837 | config.add_view( | |
| 838 | RESTView, route_name='rest', attr='get', request_method='GET') | |
| 839 | config.add_view( | |
| 840 | RESTView, route_name='rest', attr='post', request_method='POST') | |
| 841 | config.add_view( | |
| 842 | RESTView, route_name='rest', attr='delete', request_method='DELETE') | |
| 843 | ||
| 844 | To reduce the amount of repetion in the ``config.add_view`` statements, we | |
| 845 | can move the ``route_name='rest'`` argument to a ``@view_default`` class | |
| 846 | decorator on the RESTView class: | |
| 847 | ||
| 848 | .. code-block:: python | |
| 849 | :linenos: | |
| 850 | ||
| 73ea91 | 851 | from pyramid.view import view_defaults |
| 4375cf | 852 | from pyramid.response import Response |
| CM | 853 | from pyramid.config import Configurator |
| 854 | ||
| 855 | @view_defaults(route_name='rest') | |
| 856 | class RESTView(object): | |
| 857 | def __init__(self, request): | |
| 858 | self.request = request | |
| 859 | ||
| 860 | def get(self): | |
| 861 | return Response('get') | |
| 862 | ||
| 863 | def post(self): | |
| 864 | return Response('post') | |
| 865 | ||
| 866 | def delete(self): | |
| 867 | return Response('delete') | |
| 868 | ||
| 869 | if __name__ == '__main__': | |
| 870 | config = Configurator() | |
| 871 | config.add_route('rest', '/rest') | |
| 872 | config.add_view(RESTView, attr='get', request_method='GET') | |
| 873 | config.add_view(RESTView, attr='post', request_method='POST') | |
| 874 | config.add_view(RESTView, attr='delete', request_method='DELETE') | |
| 875 | ||
| 876 | :class:`pyramid.view.view_defaults` accepts the same set of arguments that | |
| 877 | :class:`pyramid.view.view_config` does, and they have the same meaning. Each | |
| 878 | argument passed to ``view_defaults`` provides a default for the view | |
| 879 | configurations of methods of the class it's decorating. | |
| 880 | ||
| 881 | Normal Python inheritance rules apply to defaults added via | |
| 882 | ``view_defaults``. For example: | |
| 883 | ||
| 884 | .. code-block:: python | |
| 885 | :linenos: | |
| 886 | ||
| 887 | @view_defaults(route_name='rest') | |
| 888 | class Foo(object): | |
| 889 | pass | |
| 890 | ||
| 891 | class Bar(Foo): | |
| 892 | pass | |
| 893 | ||
| 894 | The ``Bar`` class above will inherit its view defaults from the arguments | |
| 895 | passed to the ``view_defaults`` decorator of the ``Foo`` class. To prevent | |
| 896 | this from happening, use a ``view_defaults`` decorator without any arguments | |
| 897 | on the subclass: | |
| 898 | ||
| 899 | .. code-block:: python | |
| 900 | :linenos: | |
| 901 | ||
| 902 | @view_defaults(route_name='rest') | |
| 903 | class Foo(object): | |
| 904 | pass | |
| 905 | ||
| 906 | @view_defaults() | |
| 907 | class Bar(Foo): | |
| 908 | pass | |
| 909 | ||
| 910 | The ``view_defaults`` decorator only works as a class decorator; using it | |
| 911 | against a function or a method will produce nonsensical results. | |
| 912 | ||
| 913 | .. index:: | |
| 8a1b50 | 914 | single: view security |
| CD | 915 | pair: security; view |
| 916 | ||
| 917 | .. _view_security_section: | |
| 918 | ||
| 919 | Configuring View Security | |
| 920 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 921 | ||
| 922 | If an :term:`authorization policy` is active, any :term:`permission` attached | |
| 923 | to a :term:`view configuration` found during view lookup will be verified. | |
| 924 | This will ensure that the currently authenticated user possesses that | |
| 925 | permission against the :term:`context` resource before the view function is | |
| 926 | actually called. Here's an example of specifying a permission in a view | |
| 70acd2 | 927 | configuration using :meth:`~pyramid.config.Configurator.add_view`: |
| 8a1b50 | 928 | |
| CD | 929 | .. code-block:: python |
| 930 | :linenos: | |
| 931 | ||
| 932 | # config is an instance of pyramid.config.Configurator | |
| 933 | ||
| 8cb682 | 934 | config.add_route('add', '/add.html', factory='mypackage.Blog') |
| CM | 935 | config.add_view('myproject.views.add_entry', route_name='add', |
| 936 | permission='add') | |
| 8a1b50 | 937 | |
| CD | 938 | When an :term:`authorization policy` is enabled, this view will be protected |
| 939 | with the ``add`` permission. The view will *not be called* if the user does | |
| 940 | not possess the ``add`` permission relative to the current :term:`context`. | |
| 941 | Instead the :term:`forbidden view` result will be returned to the client as | |
| 942 | per :ref:`protecting_views`. | |
| 943 | ||
| 944 | .. index:: | |
| 945 | single: debugging not found errors | |
| 946 | single: not found error (debugging) | |
| 947 | ||
| 948 | .. _debug_notfound_section: | |
| 949 | ||
| f758ec | 950 | :exc:`~pyramid.exceptions.NotFound` Errors |
| TL | 951 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 8a1b50 | 952 | |
| f758ec | 953 | It's useful to be able to debug :exc:`~pyramid.exceptions.NotFound` |
| TL | 954 | error responses when they |
| 8a1b50 | 955 | occur unexpectedly due to an application registry misconfiguration. To debug |
| CD | 956 | these errors, use the ``PYRAMID_DEBUG_NOTFOUND`` environment variable or the |
| 875ded | 957 | ``pyramid.debug_notfound`` configuration file setting. Details of why a view |
| MM | 958 | was not found will be printed to ``stderr``, and the browser representation of |
| 959 | the error will include the same information. See :ref:`environment_chapter` | |
| 960 | for more information about how, and where to set these values. | |
| 8a1b50 | 961 | |
| 8abf0a | 962 | .. index:: |
| e573d4 | 963 | single: HTTP caching |
| CM | 964 | |
| 965 | .. _influencing_http_caching: | |
| 966 | ||
| 967 | Influencing HTTP Caching | |
| 968 | ------------------------ | |
| 969 | ||
| 40dbf4 | 970 | .. versionadded:: 1.1 |
| e573d4 | 971 | |
| CM | 972 | When a non-``None`` ``http_cache`` argument is passed to a view |
| 973 | configuration, Pyramid will set ``Expires`` and ``Cache-Control`` response | |
| 974 | headers in the resulting response, causing browsers to cache the response | |
| 975 | data for some time. See ``http_cache`` in :ref:`nonpredicate_view_args` for | |
| 283494 | 976 | the allowable values and what they mean. |
| e573d4 | 977 | |
| CM | 978 | Sometimes it's undesirable to have these headers set as the result of |
| 979 | returning a response from a view, even though you'd like to decorate the view | |
| 980 | with a view configuration decorator that has ``http_cache``. Perhaps there's | |
| 981 | an alternate branch in your view code that returns a response that should | |
| 982 | never be cacheable, while the "normal" branch returns something that should | |
| 983 | always be cacheable. If this is the case, set the ``prevent_auto`` attribute | |
| 984 | of the ``response.cache_control`` object to a non-``False`` value. For | |
| 985 | example, the below view callable is configured with a ``@view_config`` | |
| 986 | decorator that indicates any response from the view should be cached for 3600 | |
| 987 | seconds. However, the view itself prevents caching from taking place unless | |
| 988 | there's a ``should_cache`` GET or POST variable: | |
| 989 | ||
| 990 | .. code-block:: python | |
| 991 | ||
| 992 | from pyramid.view import view_config | |
| 993 | ||
| 994 | @view_config(http_cache=3600) | |
| 995 | def view(request): | |
| 996 | response = Response() | |
| 997 | if not 'should_cache' in request.params: | |
| 998 | response.cache_control.prevent_auto = True | |
| 999 | return response | |
| 1000 | ||
| 1001 | Note that the ``http_cache`` machinery will overwrite or add to caching | |
| 7eefb6 | 1002 | headers you set within the view itself unless you use ``prevent_auto``. |
| e573d4 | 1003 | |
| f71723 | 1004 | You can also turn off the effect of ``http_cache`` entirely for the duration |
| e573d4 | 1005 | of a Pyramid application lifetime. To do so, set the |
| CM | 1006 | ``PYRAMID_PREVENT_HTTP_CACHE`` environment variable or the |
| 875ded | 1007 | ``pyramid.prevent_http_cache`` configuration value setting to a true value. |
| MM | 1008 | For more information, see :ref:`preventing_http_caching`. |
| e573d4 | 1009 | |
| 875ded | 1010 | Note that setting ``pyramid.prevent_http_cache`` will have no effect on caching |
| 5fa17f | 1011 | headers that your application code itself sets. It will only prevent caching |
| CM | 1012 | headers that would have been set by the Pyramid HTTP caching machinery |
| 1013 | invoked as the result of the ``http_cache`` argument to view configuration. | |
| 1014 | ||
| 6ce1e0 | 1015 | .. index:: |
| CM | 1016 | pair: view configuration; debugging |
| 1017 | ||
| 8cb682 | 1018 | Debugging View Configuration |
| ae4c57 | 1019 | ---------------------------- |
| 8abf0a | 1020 | |
| ae4c57 | 1021 | See :ref:`displaying_matching_views` for information about how to display |
| CM | 1022 | each of the view callables that might match for a given URL. This can be an |
| 1023 | effective way to figure out why a particular view callable is being called | |
| 1024 | instead of the one you'd like to be called. | |
