| commit | author | age | ||
| 41aeac | 1 | What's New in Pyramid 1.1 |
| 0ee9c2 | 2 | ========================= |
| CM | 3 | |
| 4 | This article explains the new features in Pyramid version 1.1 as compared to | |
| 5 | its predecessor, :app:`Pyramid` 1.0. It also documents backwards | |
| 6 | incompatibilities between the two versions and deprecations added to Pyramid | |
| 7 | 1.1, as well as software dependency changes and notable documentation | |
| 8 | additions. | |
| 9 | ||
| fc950d | 10 | Terminology Changes |
| CM | 11 | ------------------- |
| 12 | ||
| 13 | The term "template" used by the Pyramid documentation used to refer to both | |
| 14 | "paster templates" and "rendered templates" (templates created by a rendering | |
| 15 | engine. i.e. Mako, Chameleon, Jinja, etc.). "Paster templates" will now be | |
| 6714a5 | 16 | referred to as "scaffolds", whereas the name for "rendered templates" will |
| fc950d | 17 | remain as "templates." |
| CM | 18 | |
| 0ee9c2 | 19 | Major Feature Additions |
| CM | 20 | ----------------------- |
| 21 | ||
| 22 | The major feature additions in Pyramid 1.1 are: | |
| 23 | ||
| 24 | - Support for the ``request.response`` attribute. | |
| 25 | ||
| 26 | - New views introspection feature: ``paster pviews``. | |
| 27 | ||
| 28 | - Support for "static" routes. | |
| 29 | ||
| f8f08b | 30 | - Default HTTP exception view. |
| 1ffb8e | 31 | |
| c425a4 | 32 | - ``http_cache`` view configuration parameter causes Pyramid to set HTTP |
| CM | 33 | caching headers. |
| 34 | ||
| 8a8724 | 35 | - Features that make it easier to write scripts that work in a :app:`Pyramid` |
| CM | 36 | environment. |
| 37 | ||
| 0ee9c2 | 38 | ``request.response`` |
| CM | 39 | ~~~~~~~~~~~~~~~~~~~~ |
| 40 | ||
| fc950d | 41 | - Instances of the :class:`pyramid.request.Request` class now have a |
| CM | 42 | ``response`` attribute. |
| 0ee9c2 | 43 | |
| fc950d | 44 | The object passed to a view callable as ``request`` is an instance of |
| CM | 45 | :class:`pyramid.request.Request`. ``request.response`` is an instance of |
| 50218d | 46 | the class :class:`pyramid.response.Response`. View callables that are |
| fc950d | 47 | configured with a :term:`renderer` will return this response object to the |
| CM | 48 | Pyramid router. Therefore, code in a renderer-using view callable can set |
| 49 | response attributes such as ``request.response.content_type`` (before they | |
| 50 | return, e.g. a dictionary to the renderer) and this will influence the HTTP | |
| 51 | return value of the view callable. | |
| 52 | ||
| 53 | ``request.response`` can also be used in view callable code that is not | |
| 54 | configured to use a renderer. For example, a view callable might do | |
| 55 | ``request.response.body = '123'; return request.response``. However, the | |
| 56 | response object that is produced by ``request.response`` must be *returned* | |
| 57 | when a renderer is not in play in order to have any effect on the HTTP | |
| 58 | response (it is not a "global" response, and modifications to it are not | |
| 59 | somehow merged into a separately returned response object). | |
| 60 | ||
| 61 | The ``request.response`` object is lazily created, so its introduction does | |
| 62 | not negatively impact performance. | |
| 0ee9c2 | 63 | |
| CM | 64 | ``paster pviews`` |
| 65 | ~~~~~~~~~~~~~~~~~ | |
| 66 | ||
| 67 | - A new paster command named ``paster pviews`` was added. This command | |
| 68 | prints a summary of potentially matching views for a given path. See | |
| 837c25 | 69 | the section entitled :ref:`displaying_matching_views` for more |
| CDLG | 70 | information. |
| 0ee9c2 | 71 | |
| CM | 72 | Static Routes |
| 73 | ~~~~~~~~~~~~~ | |
| 74 | ||
| 75 | - The ``add_route`` method of the Configurator now accepts a ``static`` | |
| 76 | argument. If this argument is ``True``, the added route will never be | |
| 77 | considered for matching when a request is handled. Instead, it will only | |
| 78 | be useful for URL generation via ``route_url`` and ``route_path``. See the | |
| 79 | section entitled :ref:`static_route_narr` for more information. | |
| 80 | ||
| 1ffb8e | 81 | Default HTTP Exception View |
| CM | 82 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 83 | ||
| 8cbbd9 | 84 | - A default exception view for the interface |
| f8f08b | 85 | :class:`pyramid.interfaces.IExceptionResponse` is now registered by |
| 1ffb8e | 86 | default. This means that an instance of any exception class imported from |
| CM | 87 | :mod:`pyramid.httpexceptions` (such as ``HTTPFound``) can now be raised |
| 88 | from within view code; when raised, this exception view will render the | |
| 89 | exception to a response. | |
| 90 | ||
| 91 | To allow for configuration of this feature, the :term:`Configurator` now | |
| 8cbbd9 | 92 | accepts an additional keyword argument named ``exceptionresponse_view``. |
| CM | 93 | By default, this argument is populated with a default exception view |
| 94 | function that will be used when an HTTP exception is raised. When ``None`` | |
| 95 | is passed for this value, an exception view for HTTP exceptions will not be | |
| 1ffb8e | 96 | registered. Passing ``None`` returns the behavior of raising an HTTP |
| CM | 97 | exception to that of Pyramid 1.0 (the exception will propagate to |
| 37607c | 98 | :term:`middleware` and to the WSGI server). |
| 0ee9c2 | 99 | |
| c425a4 | 100 | ``http_cache`` |
| CM | 101 | ~~~~~~~~~~~~~~ |
| 102 | ||
| 103 | A new value ``http_cache`` can be used as a :term:`view configuration` | |
| 104 | parameter. | |
| 105 | ||
| 106 | When you supply an ``http_cache`` value to a view configuration, the | |
| 107 | ``Expires`` and ``Cache-Control`` headers of a response generated by the | |
| 108 | associated view callable are modified. The value for ``http_cache`` may be | |
| 109 | one of the following: | |
| 110 | ||
| 111 | - A nonzero integer. If it's a nonzero integer, it's treated as a number | |
| 112 | of seconds. This number of seconds will be used to compute the | |
| 113 | ``Expires`` header and the ``Cache-Control: max-age`` parameter of | |
| 114 | responses to requests which call this view. For example: | |
| 115 | ``http_cache=3600`` instructs the requesting browser to 'cache this | |
| 116 | response for an hour, please'. | |
| 117 | ||
| 118 | - A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta`` | |
| 119 | instance, it will be converted into a number of seconds, and that number | |
| 120 | of seconds will be used to compute the ``Expires`` header and the | |
| 121 | ``Cache-Control: max-age`` parameter of responses to requests which call | |
| 122 | this view. For example: ``http_cache=datetime.timedelta(days=1)`` | |
| 123 | instructs the requesting browser to 'cache this response for a day, | |
| 124 | please'. | |
| 125 | ||
| 126 | - Zero (``0``). If the value is zero, the ``Cache-Control`` and | |
| 127 | ``Expires`` headers present in all responses from this view will be | |
| 128 | composed such that client browser cache (and any intermediate caches) are | |
| 129 | instructed to never cache the response. | |
| 130 | ||
| 131 | - A two-tuple. If it's a two tuple (e.g. ``http_cache=(1, | |
| 132 | {'public':True})``), the first value in the tuple may be a nonzero | |
| 133 | integer or a ``datetime.timedelta`` instance; in either case this value | |
| 134 | will be used as the number of seconds to cache the response. The second | |
| 135 | value in the tuple must be a dictionary. The values present in the | |
| 136 | dictionary will be used as input to the ``Cache-Control`` response | |
| 137 | header. For example: ``http_cache=(3600, {'public':True})`` means 'cache | |
| 138 | for an hour, and add ``public`` to the Cache-Control header of the | |
| 139 | response'. All keys and values supported by the | |
| 140 | ``webob.cachecontrol.CacheControl`` interface may be added to the | |
| 141 | dictionary. Supplying ``{'public':True}`` is equivalent to calling | |
| 142 | ``response.cache_control.public = True``. | |
| 143 | ||
| 144 | Providing a non-tuple value as ``http_cache`` is equivalent to calling | |
| 145 | ``response.cache_expires(value)`` within your view's body. | |
| 146 | ||
| 147 | Providing a two-tuple value as ``http_cache`` is equivalent to calling | |
| 148 | ``response.cache_expires(value[0], **value[1])`` within your view's body. | |
| 149 | ||
| 150 | If you wish to avoid influencing, the ``Expires`` header, and instead wish | |
| 151 | to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache`` | |
| 152 | with the first element of ``None``, e.g.: ``(None, {'public':True})``. | |
| 153 | ||
| 154 | The environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and configuration | |
| acd256 | 155 | file value ``prevent_http_cache`` are synonymous and allow you to prevent |
| c425a4 | 156 | HTTP cache headers from being set by Pyramid's ``http_cache`` machinery |
| CM | 157 | globally in a process. see :ref:`influencing_http_caching` and |
| 158 | :ref:`preventing_http_caching`. | |
| 159 | ||
| 8a8724 | 160 | Easier Scripting Writing |
| CM | 161 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 162 | ||
| 163 | A new API function :func:`pyramid.paster.bootstrap` has been added to make | |
| 164 | writing scripts that need to work under Pyramid environment easier, e.g.: | |
| 165 | ||
| 166 | .. code-block:: python | |
| 167 | ||
| 168 | from pyramid.paster import bootstrap | |
| 169 | info = bootstrap('/path/to/my/development.ini') | |
| 170 | request = info['request'] | |
| 171 | print request.route_url('myroute') | |
| 172 | ||
| 173 | See :ref:`writing_a_script` for more details. | |
| 174 | ||
| 0ee9c2 | 175 | Minor Feature Additions |
| CM | 176 | ----------------------- |
| 177 | ||
| 756500 | 178 | - It is now possible to invoke ``paster pshell`` even if the paste ini file |
| CM | 179 | section name pointed to in its argument is not actually a Pyramid WSGI |
| 180 | application. The shell will work in a degraded mode, and will warn the | |
| 181 | user. See "The Interactive Shell" in the "Creating a Pyramid Project" | |
| 182 | narrative documentation section. | |
| 183 | ||
| af0560 | 184 | - The ``paster pshell``, ``paster pviews``, and ``paster proutes`` commands |
| CM | 185 | each now under the hood uses :func:`pyramid.paster.bootstrap`, which makes |
| 186 | it possible to supply an ``.ini`` file without naming the "right" section | |
| 187 | in the file that points at the actual Pyramid application. Instead, you | |
| 188 | can generally just run ``paster {pshell|proutes|pviews} development.ini`` | |
| 189 | and it will do mostly the right thing. | |
| 9c5b83 | 190 | |
| 756500 | 191 | - It is now possible to add a ``[pshell]`` section to your application's .ini |
| CM | 192 | configuration file, which influences the global names available to a pshell |
| 193 | session. See :ref:`extending_pshell`. | |
| 194 | ||
| fca1ef | 195 | - The :meth:`pyramid.config.Configurator.scan` method has grown a ``**kw`` |
| CM | 196 | argument. ``kw`` argument represents a set of keyword arguments to pass to |
| 197 | the Venusian ``Scanner`` object created by Pyramid. (See the | |
| 198 | :term:`Venusian` documentation for more information about ``Scanner``). | |
| 199 | ||
| 6a0602 | 200 | - New request property: ``json_body``. This property will return the |
| CM | 201 | JSON-decoded variant of the request body. If the request body is not |
| 202 | well-formed JSON, this property will raise an exception. | |
| e573d4 | 203 | |
| c1f3d0 | 204 | - A `JSONP <http://en.wikipedia.org/wiki/JSONP>`_ renderer. See |
| 6579f5 | 205 | :ref:`jsonp_renderer` for more details. |
| c1f3d0 | 206 | |
| 0ca4bb | 207 | - New authentication policy: |
| 54064a | 208 | :class:`pyramid.authentication.SessionAuthenticationPolicy`, which uses a |
| 0ca4bb | 209 | session to store credentials. |
| 31d78e | 210 | |
| f8f08b | 211 | - A function named :func:`pyramid.httpexceptions.exception_response` is a |
| CM | 212 | shortcut that can be used to create HTTP exception response objects using |
| 213 | an HTTP integer status code. | |
| 0ca4bb | 214 | |
| 0ee9c2 | 215 | - Integers and longs passed as ``elements`` to |
| CM | 216 | :func:`pyramid.url.resource_url` or |
| 217 | :meth:`pyramid.request.Request.resource_url` e.g. ``resource_url(context, | |
| 218 | request, 1, 2)`` (``1`` and ``2`` are the ``elements``) will now be | |
| 219 | converted implicitly to strings in the result. Previously passing integers | |
| 220 | or longs as elements would cause a TypeError. | |
| 221 | ||
| 0b02c4 | 222 | - ``pyramid_alchemy`` scaffold now uses ``query.get`` rather than |
| 0ee9c2 | 223 | ``query.filter_by`` to take better advantage of identity map caching. |
| CM | 224 | |
| 0b02c4 | 225 | - ``pyramid_alchemy`` scaffold now has unit tests. |
| 0ee9c2 | 226 | |
| CM | 227 | - Added a :func:`pyramid.i18n.make_localizer` API. |
| 228 | ||
| 229 | - An exception raised by a :class:`pyramid.events.NewRequest` event | |
| 230 | subscriber can now be caught by an exception view. | |
| 231 | ||
| 232 | - It is now possible to get information about why Pyramid raised a Forbidden | |
| 233 | exception from within an exception view. The ``ACLDenied`` object returned | |
| 234 | by the ``permits`` method of each stock authorization policy | |
| 235 | (:meth:`pyramid.interfaces.IAuthorizationPolicy.permits`) is now attached | |
| 236 | to the Forbidden exception as its ``result`` attribute. Therefore, if | |
| 237 | you've created a Forbidden exception view, you can see the ACE, ACL, | |
| 238 | permission, and principals involved in the request as | |
| 239 | eg. ``context.result.permission``, ``context.result.acl``, etc within the | |
| 240 | logic of the Forbidden exception view. | |
| 241 | ||
| 242 | - Don't explicitly prevent the ``timeout`` from being lower than the | |
| 243 | ``reissue_time`` when setting up an | |
| 244 | :class:`pyramid.authentication.AuthTktAuthenticationPolicy` (previously | |
| 245 | such a configuration would raise a ``ValueError``, now it's allowed, | |
| 246 | although typically nonsensical). Allowing the nonsensical configuration | |
| 247 | made the code more understandable and required fewer tests. | |
| 8cbbd9 | 248 | |
| CM | 249 | - The :class:`pyramid.request.Request` class now has a ``ResponseClass`` |
| 250 | attribute which points at :class:`pyramid.response.Response`. | |
| 251 | ||
| 252 | - The :class:`pyramid.response.Response` class now has a ``RequestClass`` | |
| 253 | interface which points at :class:`pyramid.request.Request`. | |
| 254 | ||
| 255 | - It is now possible to return an arbitrary object from a Pyramid view | |
| 256 | callable even if a renderer is not used, as long as a suitable adapter to | |
| 257 | :class:`pyramid.interfaces.IResponse` is registered for the type of the | |
| 258 | returned object by using the new | |
| 259 | :meth:`pyramid.config.Configurator.add_response_adapter` API. See the | |
| 260 | section in the Hooks chapter of the documentation entitled | |
| 261 | :ref:`using_iresponse`. | |
| 262 | ||
| 263 | - The Pyramid router will now, by default, call the ``__call__`` method of | |
| 264 | response objects when returning a WSGI response. This means that, among | |
| 265 | other things, the ``conditional_response`` feature response objects | |
| 266 | inherited from WebOb will now behave properly. | |
| 267 | ||
| 268 | - New method named :meth:`pyramid.request.Request.is_response`. This method | |
| 269 | should be used instead of the :func:`pyramid.view.is_response` function, | |
| 270 | which has been deprecated. | |
| 271 | ||
| 272 | - :class:`pyramid.exceptions.NotFound` is now just an alias for | |
| 273 | :class:`pyramid.httpexceptions.HTTPNotFound`. | |
| 274 | ||
| 032e77 | 275 | - :class:`pyramid.exceptions.Forbidden` is now just an alias for |
| CM | 276 | :class:`pyramid.httpexceptions.HTTPForbidden`. |
| 8cbbd9 | 277 | |
| 8bd6cf | 278 | - Added ``mako.preprocessor`` config file parameter; allows for a Mako |
| CM | 279 | preprocessor to be specified as a Python callable or Python dotted name. |
| 280 | See https://github.com/Pylons/pyramid/pull/183 for rationale. | |
| 281 | ||
| 100a57 | 282 | - New API class: :class:`pyramid.static.static_view`. This supersedes the |
| CM | 283 | (now deprecated) :class:`pyramid.view.static` class. |
| 284 | :class:`pyramid.static.static_view`, by default, serves up documents as the | |
| 285 | result of the request's ``path_info``, attribute rather than it's | |
| 286 | ``subpath`` attribute (the inverse was true of | |
| 287 | :class:`pyramid.view.static`, and still is). | |
| 288 | :class:`pyramid.static.static_view` exposes a ``use_subpath`` flag for use | |
| 10408c | 289 | when you want the static view to behave like the older deprecated version. |
| c515d7 | 290 | |
| CM | 291 | - A new api function :func:`pyramid.scripting.prepare` has been added. It is |
| 50218d | 292 | a lower-level analogue of :func:`pyramid.paster.bootstrap` that accepts a |
| c515d7 | 293 | request and a registry instead of a config file argument, and is used for |
| CM | 294 | the same purpose: |
| 295 | ||
| 296 | .. code-block:: python | |
| 297 | ||
| 298 | from pyramid.scripting import prepare | |
| 299 | info = prepare(registry=myregistry) | |
| 300 | request = info['request'] | |
| 301 | print request.route_url('myroute') | |
| 302 | ||
| 303 | - A new API function :func:`pyramid.scripting.make_request` has been added. | |
| 304 | The resulting request will have a ``registry`` attribute. It is meant to | |
| 305 | be used in conjunction with :func:`pyramid.scripting.prepare` and/or | |
| 306 | :func:`pyramid.paster.bootstrap` (both of which accept a request as an | |
| 307 | argument): | |
| 308 | ||
| 309 | .. code-block:: python | |
| 310 | ||
| 311 | from pyramid.scripting import make_request | |
| 312 | request = make_request('/') | |
| 313 | ||
| 314 | - New API attribute :attr:`pyramid.config.global_registries` is an iterable | |
| 315 | object that contains references to every Pyramid registry loaded into the | |
| 50218d | 316 | current process via :meth:`pyramid.config.Configurator.make_wsgi_app`. It also |
| c515d7 | 317 | has a ``last`` attribute containing the last registry loaded. This is used |
| CM | 318 | by the scripting machinery, and is available for introspection. |
| 319 | ||
| 9006b2 | 320 | - Added the :attr:`pyramid.renderers.null_renderer` object as an API. The |
| CM | 321 | null renderer is an object that can be used in advanced integration cases |
| 322 | as input to the view configuration ``renderer=`` argument. When the null | |
| 323 | renderer is used as a view renderer argument, Pyramid avoids converting the | |
| 324 | view callable result into a Response object. This is useful if you want to | |
| 325 | reuse the view configuration and lookup machinery outside the context of | |
| 326 | its use by the Pyramid router. (This feature was added for consumption by | |
| 327 | the ``pyramid_rpc`` package, which uses view configuration and lookup | |
| 328 | outside the context of a router in exactly this way.) | |
| 329 | ||
| 8cbbd9 | 330 | Backwards Incompatibilities |
| CM | 331 | --------------------------- |
| 332 | ||
| 333 | - Pyramid no longer supports Python 2.4. Python 2.5 or better is required to | |
| 334 | run Pyramid 1.1+. Pyramid, however, does not work under any version of | |
| 335 | Python 3 yet. | |
| 336 | ||
| 337 | - The Pyramid router now, by default, expects response objects returned from | |
| 338 | view callables to implement the :class:`pyramid.interfaces.IResponse` | |
| 339 | interface. Unlike the Pyramid 1.0 version of this interface, objects which | |
| 340 | implement IResponse now must define a ``__call__`` method that accepts | |
| 341 | ``environ`` and ``start_response``, and which returns an ``app_iter`` | |
| 342 | iterable, among other things. Previously, it was possible to return any | |
| 343 | object which had the three WebOb ``app_iter``, ``headerlist``, and | |
| 344 | ``status`` attributes as a response, so this is a backwards | |
| 345 | incompatibility. It is possible to get backwards compatibility back by | |
| 346 | registering an adapter to IResponse from the type of object you're now | |
| 347 | returning from view callables. See the section in the Hooks chapter of the | |
| 348 | documentation entitled :ref:`using_iresponse`. | |
| 349 | ||
| 350 | - The :class:`pyramid.interfaces.IResponse` interface is now much more | |
| 351 | extensive. Previously it defined only ``app_iter``, ``status`` and | |
| 352 | ``headerlist``; now it is basically intended to directly mirror the | |
| 353 | ``webob.Response`` API, which has many methods and attributes. | |
| 354 | ||
| 355 | - The :mod:`pyramid.httpexceptions` classes named ``HTTPFound``, | |
| 356 | ``HTTPMultipleChoices``, ``HTTPMovedPermanently``, ``HTTPSeeOther``, | |
| 357 | ``HTTPUseProxy``, and ``HTTPTemporaryRedirect`` now accept ``location`` as | |
| 358 | their first positional argument rather than ``detail``. This means that | |
| 359 | you can do, e.g. ``return pyramid.httpexceptions.HTTPFound('http://foo')`` | |
| 360 | rather than ``return | |
| 361 | pyramid.httpexceptions.HTTPFound(location='http//foo')`` (the latter will | |
| 362 | of course continue to work). | |
| 0ee9c2 | 363 | |
| cc85e7 | 364 | - The pyramid Router attempted to set a value into the key |
| CM | 365 | ``environ['repoze.bfg.message']`` when it caught a view-related exception |
| 366 | for backwards compatibility with applications written for :mod:`repoze.bfg` | |
| 367 | during error handling. It did this by using code that looked like so:: | |
| 368 | ||
| 369 | # "why" is an exception object | |
| 370 | try: | |
| 371 | msg = why[0] | |
| 372 | except: | |
| 373 | msg = '' | |
| 374 | ||
| 375 | environ['repoze.bfg.message'] = msg | |
| 376 | ||
| 377 | Use of the value ``environ['repoze.bfg.message']`` was docs-deprecated in | |
| 378 | Pyramid 1.0. Our standing policy is to not remove features after a | |
| 379 | deprecation for two full major releases, so this code was originally slated | |
| 380 | to be removed in Pyramid 1.2. However, computing the | |
| 381 | ``repoze.bfg.message`` value was the source of at least one bug found in | |
| 382 | the wild (https://github.com/Pylons/pyramid/issues/199), and there isn't a | |
| 383 | foolproof way to both preserve backwards compatibility and to fix the bug. | |
| 384 | Therefore, the code which sets the value has been removed in this release. | |
| 385 | Code in exception views which relies on this value's presence in the | |
| 386 | environment should now use the ``exception`` attribute of the request | |
| 387 | (e.g. ``request.exception[0]``) to retrieve the message instead of relying | |
| 388 | on ``request.environ['repoze.bfg.message']``. | |
| 389 | ||
| 0ee9c2 | 390 | Deprecations and Behavior Differences |
| CM | 391 | ------------------------------------- |
| 392 | ||
| 7cf067 | 393 | .. note:: Under Python 2.7+, it's necessary to pass the Python interpreter |
| CM | 394 | the correct warning flags to see deprecation warnings emitted by Pyramid |
| 395 | when porting your application from an older version of Pyramid. Use the | |
| 396 | ``PYTHONWARNINGS`` environment variable with the value ``all`` in the | |
| 397 | shell you use to invoke ``paster serve`` to see these warnings, e.g. on | |
| 5af300 | 398 | Unix, ``PYTHONWARNINGS=all $VENV/bin/paster serve development.ini``. |
| f73f0e | 399 | Python 2.5 and 2.6 show deprecation warnings by default, |
| 86254f | 400 | so this is unnecessary there. |
| 7cf067 | 401 | All deprecation warnings are emitted to the console. |
| CM | 402 | |
| 100a57 | 403 | - The :class:`pyramid.view.static` class has been deprecated in favor of the |
| CM | 404 | newer :class:`pyramid.static.static_view` class. A deprecation warning is |
| 405 | raised when it is used. You should replace it with a reference to | |
| 406 | :class:`pyramid.static.static_view` with the ``use_subpath=True`` argument. | |
| 407 | ||
| 756500 | 408 | - The ``paster pshell``, ``paster proutes``, and ``paster pviews`` commands |
| CM | 409 | now take a single argument in the form ``/path/to/config.ini#sectionname`` |
| 410 | rather than the previous 2-argument spelling ``/path/to/config.ini | |
| 411 | sectionname``. ``#sectionname`` may be omitted, in which case ``#main`` is | |
| 412 | assumed. | |
| 413 | ||
| 18b25a | 414 | - The default Mako renderer is now configured to escape all HTML in |
| MM | 415 | expression tags. This is intended to help prevent XSS attacks caused by |
| 416 | rendering unsanitized input from users. To revert this behavior in user's | |
| 417 | templates, they need to filter the expression through the 'n' filter:: | |
| 418 | ||
| 419 | ${ myhtml | n }. | |
| 420 | ||
| 421 | See https://github.com/Pylons/pyramid/issues/193. | |
| 422 | ||
| 0ee9c2 | 423 | - Deprecated all assignments to ``request.response_*`` attributes (for |
| CM | 424 | example ``request.response_content_type = 'foo'`` is now deprecated). |
| 425 | Assignments and mutations of assignable request attributes that were | |
| 426 | considered by the framework for response influence are now deprecated: | |
| 427 | ``response_content_type``, ``response_headerlist``, ``response_status``, | |
| 428 | ``response_charset``, and ``response_cache_for``. Instead of assigning | |
| 429 | these to the request object for later detection by the rendering machinery, | |
| 430 | users should use the appropriate API of the Response object created by | |
| 431 | accessing ``request.response`` (e.g. code which does | |
| 432 | ``request.response_content_type = 'abc'`` should be changed to | |
| 433 | ``request.response.content_type = 'abc'``). | |
| 434 | ||
| 435 | - Passing view-related parameters to | |
| 436 | :meth:`pyramid.config.Configurator.add_route` is now deprecated. | |
| 437 | Previously, a view was permitted to be connected to a route using a set of | |
| 438 | ``view*`` parameters passed to the ``add_route`` method of the | |
| 439 | Configurator. This was a shorthand which replaced the need to perform a | |
| 440 | subsequent call to ``add_view``. For example, it was valid (and often | |
| 441 | recommended) to do:: | |
| 442 | ||
| 443 | config.add_route('home', '/', view='mypackage.views.myview', | |
| 444 | view_renderer='some/renderer.pt') | |
| 445 | ||
| 446 | Passing ``view*`` arguments to ``add_route`` is now deprecated in favor of | |
| 447 | connecting a view to a predefined route via | |
| 448 | :meth:`pyramid.config.Configurator.add_view` using the route's | |
| 449 | ``route_name`` parameter. As a result, the above example should now be | |
| 450 | spelled:: | |
| 451 | ||
| 452 | config.add_route('home', '/') | |
| 40369d | 453 | config.add_view('mypackage.views.myview', route_name='home', |
| 0ee9c2 | 454 | renderer='some/renderer.pt') |
| CM | 455 | |
| 456 | This deprecation was done to reduce confusion observed in IRC, as well as | |
| 2033ee | 457 | to (eventually) reduce documentation burden. A deprecation warning is |
| SP | 458 | now issued when any view-related parameter is passed to ``add_route``. |
| 459 | ||
| 460 | .. seealso:: | |
| 461 | ||
| 462 | See also `issue #164 on GitHub | |
| 463 | <https://github.com/Pylons/pyramid/issues/164>`_. | |
| 0ee9c2 | 464 | |
| CM | 465 | - Passing an ``environ`` dictionary to the ``__call__`` method of a |
| 466 | "traverser" (e.g. an object that implements | |
| 467 | :class:`pyramid.interfaces.ITraverser` such as an instance of | |
| 468 | :class:`pyramid.traversal.ResourceTreeTraverser`) as its ``request`` | |
| 469 | argument now causes a deprecation warning to be emitted. Consumer code | |
| 470 | should pass a ``request`` object instead. The fact that passing an environ | |
| 471 | dict is permitted has been documentation-deprecated since ``repoze.bfg`` | |
| 472 | 1.1, and this capability will be removed entirely in a future version. | |
| 473 | ||
| 474 | - The following (undocumented, dictionary-like) methods of the | |
| 475 | :class:`pyramid.request.Request` object have been deprecated: | |
| 476 | ``__contains__``, ``__delitem__``, ``__getitem__``, ``__iter__``, | |
| 477 | ``__setitem__``, ``get``, ``has_key``, ``items``, ``iteritems``, | |
| 478 | ``itervalues``, ``keys``, ``pop``, ``popitem``, ``setdefault``, ``update``, | |
| 479 | and ``values``. Usage of any of these methods will cause a deprecation | |
| 480 | warning to be emitted. These methods were added for internal compatibility | |
| 481 | in ``repoze.bfg`` 1.1 (code that currently expects a request object | |
| 482 | expected an environ object in BFG 1.0 and before). In a future version, | |
| 483 | these methods will be removed entirely. | |
| 484 | ||
| 99edc5 | 485 | - A custom request factory is now required to return a request object that |
| 9f164e | 486 | has a ``response`` attribute (or "reified"/lazy property) if the |
| 0ee9c2 | 487 | request is meant to be used in a view that uses a renderer. This |
| CM | 488 | ``response`` attribute should be an instance of the class |
| 489 | :class:`pyramid.response.Response`. | |
| 490 | ||
| 491 | - The JSON and string renderer factories now assign to | |
| 492 | ``request.response.content_type`` rather than | |
| bf7544 | 493 | ``request.response_content_type``. |
| CM | 494 | |
| 495 | - Each built-in renderer factory now determines whether it should change the | |
| 496 | content type of the response by comparing the response's content type | |
| 497 | against the response's default content type; if the content type is the | |
| 498 | default content type (usually ``text/html``), the renderer changes the | |
| 499 | content type (to ``application/json`` or ``text/plain`` for JSON and string | |
| 500 | renderers respectively). | |
| 0ee9c2 | 501 | |
| CM | 502 | - The :func:`pyramid.wsgi.wsgiapp2` now uses a slightly different method of |
| 503 | figuring out how to "fix" ``SCRIPT_NAME`` and ``PATH_INFO`` for the | |
| 504 | downstream application. As a result, those values may differ slightly from | |
| 505 | the perspective of the downstream application (for example, ``SCRIPT_NAME`` | |
| 506 | will now never possess a trailing slash). | |
| 507 | ||
| 508 | - Previously, :class:`pyramid.request.Request` inherited from | |
| 509 | :class:`webob.request.Request` and implemented ``__getattr__``, | |
| 92cf3d | 510 | ``__setattr__`` and ``__delattr__`` itself in order to override "adhoc |
| 0ee9c2 | 511 | attr" WebOb behavior where attributes of the request are stored in the |
| 654e3d | 512 | environ. Now, :class:`pyramid.request.Request` inherits from (the more |
| CDLG | 513 | recent) :class:`webob.request.BaseRequest` instead of |
| 0ee9c2 | 514 | :class:`webob.request.Request`, which provides the same behavior. |
| CM | 515 | :class:`pyramid.request.Request` no longer implements its own |
| 516 | ``__getattr__``, ``__setattr__`` or ``__delattr__`` as a result. | |
| 517 | ||
| 8cbbd9 | 518 | - Deprecated :func:`pyramid.view.is_response` function in favor of |
| CM | 519 | (newly-added) :meth:`pyramid.request.Request.is_response` method. |
| 520 | Determining if an object is truly a valid response object now requires | |
| 521 | access to the registry, which is only easily available as a request | |
| 522 | attribute. The :func:`pyramid.view.is_response` function will still work | |
| 523 | until it is removed, but now may return an incorrect answer under some | |
| 524 | (very uncommon) circumstances. | |
| 525 | ||
| 526 | - :class:`pyramid.response.Response` is now a *subclass* of | |
| 527 | ``webob.response.Response`` (in order to directly implement the | |
| 528 | :class:`pyramid.interfaces.IResponse` interface, to speed up response | |
| 529 | generation). | |
| 530 | ||
| 531 | - The "exception response" objects importable from ``pyramid.httpexceptions`` | |
| 532 | (e.g. ``HTTPNotFound``) are no longer just import aliases for classes that | |
| 533 | actually live in ``webob.exc``. Instead, we've defined our own exception | |
| 534 | classes within the module that mirror and emulate the ``webob.exc`` | |
| 535 | exception response objects almost entirely. See | |
| 536 | :ref:`http_exception_hierarchy` in the Design Defense chapter for more | |
| 537 | information. | |
| 538 | ||
| 539 | - When visiting a URL that represented a static view which resolved to a | |
| 540 | subdirectory, the ``index.html`` of that subdirectory would not be served | |
| 541 | properly. Instead, a redirect to ``/subdir`` would be issued. This has | |
| 542 | been fixed, and now visiting a subdirectory that contains an ``index.html`` | |
| 2033ee | 543 | within a static view returns the index.html properly. |
| SP | 544 | |
| 545 | .. seealso:: | |
| 546 | ||
| 547 | See also `issue #67 on GitHub | |
| 548 | <https://github.com/Pylons/pyramid/issues/67>`_. | |
| 8cbbd9 | 549 | |
| c6601f | 550 | - Deprecated the ``pyramid.config.Configurator.set_renderer_globals_factory`` |
| CM | 551 | method and the ``renderer_globals`` Configurator constructor parameter. |
| 552 | Users should convert code using this feature to use a BeforeRender event. See | |
| 553 | the section :ref:`beforerender_event` in the Hooks chapter. | |
| b7f33b | 554 | |
| 8519c9 | 555 | - In Pyramid 1.0, the :class:`pyramid.events.subscriber` directive behaved |
| CM | 556 | contrary to the documentation when passed more than one interface object to |
| 557 | its constructor. For example, when the following listener was registered:: | |
| 558 | ||
| 559 | @subscriber(IFoo, IBar) | |
| 560 | def expects_ifoo_events_and_ibar_events(event): | |
| 561 | print event | |
| 562 | ||
| 563 | The Events chapter docs claimed that the listener would be registered and | |
| 564 | listening for both ``IFoo`` and ``IBar`` events. Instead, it registered an | |
| 565 | "object event" subscriber which would only be called if an IObjectEvent was | |
| 566 | emitted where the object interface was ``IFoo`` and the event interface was | |
| 567 | ``IBar``. | |
| 568 | ||
| 569 | The behavior now matches the documentation. If you were relying on the | |
| 570 | buggy behavior of the 1.0 ``subscriber`` directive in order to register an | |
| 571 | object event subscriber, you must now pass a sequence to indicate you'd | |
| 572 | like to register a subscriber for an object event. e.g.:: | |
| 573 | ||
| 574 | @subscriber([IFoo, IBar]) | |
| 575 | def expects_object_event(object, event): | |
| 576 | print object, event | |
| 577 | ||
| 82efa4 | 578 | - In 1.0, if a :class:`pyramid.events.BeforeRender` event subscriber added a |
| CM | 579 | value via the ``__setitem__`` or ``update`` methods of the event object |
| 580 | with a key that already existed in the renderer globals dictionary, a | |
| 581 | ``KeyError`` was raised. With the deprecation of the | |
| 582 | "add_renderer_globals" feature of the configurator, there was no way to | |
| 583 | override an existing value in the renderer globals dictionary that already | |
| 584 | existed. Now, the event object will overwrite an older value that is | |
| 585 | already in the globals dictionary when its ``__setitem__`` or ``update`` is | |
| 586 | called (as well as the new ``setdefault`` method), just like a plain old | |
| 587 | dictionary. As a result, for maximum interoperability with other | |
| 588 | third-party subscribers, if you write an event subscriber meant to be used | |
| 589 | as a BeforeRender subscriber, your subscriber code will now need to (using | |
| 590 | ``.get`` or ``__contains__`` of the event object) ensure no value already | |
| 591 | exists in the renderer globals dictionary before setting an overriding | |
| 592 | value. | |
| 593 | ||
| 94ab24 | 594 | - The :meth:`pyramid.config.Configurator.add_route` method allowed two routes |
| CM | 595 | with the same route to be added without an intermediate call to |
| a03b79 | 596 | :meth:`pyramid.config.Configurator.commit`. If you now receive a |
| 94ab24 | 597 | ``ConfigurationError`` at startup time that appears to be ``add_route`` |
| CM | 598 | related, you'll need to either a) ensure that all of your route names are |
| 599 | unique or b) call ``config.commit()`` before adding a second route with the | |
| 600 | name of a previously added name or c) use a Configurator that works in | |
| 601 | ``autocommit`` mode. | |
| 602 | ||
| 0ee9c2 | 603 | Dependency Changes |
| CM | 604 | ------------------ |
| 605 | ||
| 606 | - Pyramid now depends on :term:`WebOb` >= 1.0.2 as tests depend on the bugfix | |
| 607 | in that release: "Fix handling of WSGI environs with missing | |
| 608 | ``SCRIPT_NAME``". (Note that in reality, everyone should probably be using | |
| 609 | 1.0.4 or better though, as WebOb 1.0.2 and 1.0.3 were effectively brownbag | |
| 610 | releases.) | |
| 611 | ||
| 612 | Documentation Enhancements | |
| 613 | -------------------------- | |
| 614 | ||
| 5fb458 | 615 | - Added a section entitled :ref:`writing_a_script` to the "Command-Line |
| CM | 616 | Pyramid" chapter. |
| 617 | ||
| 0ee9c2 | 618 | - The :ref:`bfg_wiki_tutorial` was updated slightly. |
| CM | 619 | |
| 620 | - The :ref:`bfg_sql_wiki_tutorial` was updated slightly. | |
| 621 | ||
| 622 | - Made :class:`pyramid.interfaces.IAuthenticationPolicy` and | |
| 623 | :class:`pyramid.interfaces.IAuthorizationPolicy` public interfaces, and | |
| 624 | they are now referred to within the :mod:`pyramid.authentication` and | |
| 625 | :mod:`pyramid.authorization` API docs. | |
| 626 | ||
| 627 | - Render the function definitions for each exposed interface in | |
| 628 | :mod:`pyramid.interfaces`. | |
| 629 | ||
| 630 | - Add missing docs reference to | |
| 631 | :meth:`pyramid.config.Configurator.set_view_mapper` and refer to it within | |
| 632 | the documentation section entitled :ref:`using_a_view_mapper`. | |
| 633 | ||
| 634 | - Added section to the "Environment Variables and ``.ini`` File Settings" | |
| 635 | chapter in the narrative documentation section entitled | |
| 636 | :ref:`adding_a_custom_setting`. | |
| 637 | ||
| 638 | - Added documentation for a :term:`multidict` as | |
| 639 | :class:`pyramid.interfaces.IMultiDict`. | |
| 640 | ||
| 641 | - Added a section to the "URL Dispatch" narrative chapter regarding the new | |
| 642 | "static" route feature entitled :ref:`static_route_narr`. | |
| 1ffb8e | 643 | |
| 8cbbd9 | 644 | - Added API docs for :func:`pyramid.httpexceptions.exception_response`. |
| 1ffb8e | 645 | |
| CM | 646 | - Added :ref:`http_exceptions` section to Views narrative chapter including a |
| 8cbbd9 | 647 | description of :func:`pyramid.httpexceptions.exception_response`. |
| CM | 648 | |
| 649 | - Added API docs for | |
| 650 | :class:`pyramid.authentication.SessionAuthenticationPolicy`. | |
