| commit | author | age | ||
| 0ee9c2 | 1 | What's New In Pyramid 1.1 |
| CM | 2 | ========================= |
| 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 | |
| 16 | refered to as "scaffolds", whereas the name for "rendered templates" will | |
| 17 | remain as "templates." | |
| 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 | |
| 0ee9c2 | 32 | ``request.response`` |
| CM | 33 | ~~~~~~~~~~~~~~~~~~~~ |
| 34 | ||
| fc950d | 35 | - Instances of the :class:`pyramid.request.Request` class now have a |
| CM | 36 | ``response`` attribute. |
| 0ee9c2 | 37 | |
| fc950d | 38 | The object passed to a view callable as ``request`` is an instance of |
| CM | 39 | :class:`pyramid.request.Request`. ``request.response`` is an instance of |
| 40 | the class :class:`pyramid.request.Response`. View callables that are | |
| 41 | configured with a :term:`renderer` will return this response object to the | |
| 42 | Pyramid router. Therefore, code in a renderer-using view callable can set | |
| 43 | response attributes such as ``request.response.content_type`` (before they | |
| 44 | return, e.g. a dictionary to the renderer) and this will influence the HTTP | |
| 45 | return value of the view callable. | |
| 46 | ||
| 47 | ``request.response`` can also be used in view callable code that is not | |
| 48 | configured to use a renderer. For example, a view callable might do | |
| 49 | ``request.response.body = '123'; return request.response``. However, the | |
| 50 | response object that is produced by ``request.response`` must be *returned* | |
| 51 | when a renderer is not in play in order to have any effect on the HTTP | |
| 52 | response (it is not a "global" response, and modifications to it are not | |
| 53 | somehow merged into a separately returned response object). | |
| 54 | ||
| 55 | The ``request.response`` object is lazily created, so its introduction does | |
| 56 | not negatively impact performance. | |
| 0ee9c2 | 57 | |
| CM | 58 | ``paster pviews`` |
| 59 | ~~~~~~~~~~~~~~~~~ | |
| 60 | ||
| 61 | - A new paster command named ``paster pviews`` was added. This command | |
| 62 | prints a summary of potentially matching views for a given path. See | |
| 837c25 | 63 | the section entitled :ref:`displaying_matching_views` for more |
| CDLG | 64 | information. |
| 0ee9c2 | 65 | |
| CM | 66 | Static Routes |
| 67 | ~~~~~~~~~~~~~ | |
| 68 | ||
| 69 | - The ``add_route`` method of the Configurator now accepts a ``static`` | |
| 70 | argument. If this argument is ``True``, the added route will never be | |
| 71 | considered for matching when a request is handled. Instead, it will only | |
| 72 | be useful for URL generation via ``route_url`` and ``route_path``. See the | |
| 73 | section entitled :ref:`static_route_narr` for more information. | |
| 74 | ||
| 1ffb8e | 75 | Default HTTP Exception View |
| CM | 76 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 77 | ||
| 8cbbd9 | 78 | - A default exception view for the interface |
| f8f08b | 79 | :class:`pyramid.interfaces.IExceptionResponse` is now registered by |
| 1ffb8e | 80 | default. This means that an instance of any exception class imported from |
| CM | 81 | :mod:`pyramid.httpexceptions` (such as ``HTTPFound``) can now be raised |
| 82 | from within view code; when raised, this exception view will render the | |
| 83 | exception to a response. | |
| 84 | ||
| 85 | To allow for configuration of this feature, the :term:`Configurator` now | |
| 8cbbd9 | 86 | accepts an additional keyword argument named ``exceptionresponse_view``. |
| CM | 87 | By default, this argument is populated with a default exception view |
| 88 | function that will be used when an HTTP exception is raised. When ``None`` | |
| 89 | is passed for this value, an exception view for HTTP exceptions will not be | |
| 1ffb8e | 90 | registered. Passing ``None`` returns the behavior of raising an HTTP |
| CM | 91 | exception to that of Pyramid 1.0 (the exception will propagate to |
| 92 | middleware and to the WSGI server). | |
| 0ee9c2 | 93 | |
| CM | 94 | Minor Feature Additions |
| 95 | ----------------------- | |
| 96 | ||
| 0ca4bb | 97 | - New authentication policy: |
| 54064a | 98 | :class:`pyramid.authentication.SessionAuthenticationPolicy`, which uses a |
| 0ca4bb | 99 | session to store credentials. |
| 31d78e | 100 | |
| f8f08b | 101 | - A function named :func:`pyramid.httpexceptions.exception_response` is a |
| CM | 102 | shortcut that can be used to create HTTP exception response objects using |
| 103 | an HTTP integer status code. | |
| 0ca4bb | 104 | |
| 0ee9c2 | 105 | - Integers and longs passed as ``elements`` to |
| CM | 106 | :func:`pyramid.url.resource_url` or |
| 107 | :meth:`pyramid.request.Request.resource_url` e.g. ``resource_url(context, | |
| 108 | request, 1, 2)`` (``1`` and ``2`` are the ``elements``) will now be | |
| 109 | converted implicitly to strings in the result. Previously passing integers | |
| 110 | or longs as elements would cause a TypeError. | |
| 111 | ||
| 0b02c4 | 112 | - ``pyramid_alchemy`` scaffold now uses ``query.get`` rather than |
| 0ee9c2 | 113 | ``query.filter_by`` to take better advantage of identity map caching. |
| CM | 114 | |
| 0b02c4 | 115 | - ``pyramid_alchemy`` scaffold now has unit tests. |
| 0ee9c2 | 116 | |
| CM | 117 | - Added a :func:`pyramid.i18n.make_localizer` API. |
| 118 | ||
| 119 | - An exception raised by a :class:`pyramid.events.NewRequest` event | |
| 120 | subscriber can now be caught by an exception view. | |
| 121 | ||
| 122 | - It is now possible to get information about why Pyramid raised a Forbidden | |
| 123 | exception from within an exception view. The ``ACLDenied`` object returned | |
| 124 | by the ``permits`` method of each stock authorization policy | |
| 125 | (:meth:`pyramid.interfaces.IAuthorizationPolicy.permits`) is now attached | |
| 126 | to the Forbidden exception as its ``result`` attribute. Therefore, if | |
| 127 | you've created a Forbidden exception view, you can see the ACE, ACL, | |
| 128 | permission, and principals involved in the request as | |
| 129 | eg. ``context.result.permission``, ``context.result.acl``, etc within the | |
| 130 | logic of the Forbidden exception view. | |
| 131 | ||
| 132 | - Don't explicitly prevent the ``timeout`` from being lower than the | |
| 133 | ``reissue_time`` when setting up an | |
| 134 | :class:`pyramid.authentication.AuthTktAuthenticationPolicy` (previously | |
| 135 | such a configuration would raise a ``ValueError``, now it's allowed, | |
| 136 | although typically nonsensical). Allowing the nonsensical configuration | |
| 137 | made the code more understandable and required fewer tests. | |
| 8cbbd9 | 138 | |
| CM | 139 | - The :class:`pyramid.request.Request` class now has a ``ResponseClass`` |
| 140 | attribute which points at :class:`pyramid.response.Response`. | |
| 141 | ||
| 142 | - The :class:`pyramid.response.Response` class now has a ``RequestClass`` | |
| 143 | interface which points at :class:`pyramid.request.Request`. | |
| 144 | ||
| 145 | - It is now possible to return an arbitrary object from a Pyramid view | |
| 146 | callable even if a renderer is not used, as long as a suitable adapter to | |
| 147 | :class:`pyramid.interfaces.IResponse` is registered for the type of the | |
| 148 | returned object by using the new | |
| 149 | :meth:`pyramid.config.Configurator.add_response_adapter` API. See the | |
| 150 | section in the Hooks chapter of the documentation entitled | |
| 151 | :ref:`using_iresponse`. | |
| 152 | ||
| 153 | - The Pyramid router will now, by default, call the ``__call__`` method of | |
| 154 | response objects when returning a WSGI response. This means that, among | |
| 155 | other things, the ``conditional_response`` feature response objects | |
| 156 | inherited from WebOb will now behave properly. | |
| 157 | ||
| 158 | - New method named :meth:`pyramid.request.Request.is_response`. This method | |
| 159 | should be used instead of the :func:`pyramid.view.is_response` function, | |
| 160 | which has been deprecated. | |
| 161 | ||
| 162 | - :class:`pyramid.exceptions.NotFound` is now just an alias for | |
| 163 | :class:`pyramid.httpexceptions.HTTPNotFound`. | |
| 164 | ||
| 032e77 | 165 | - :class:`pyramid.exceptions.Forbidden` is now just an alias for |
| CM | 166 | :class:`pyramid.httpexceptions.HTTPForbidden`. |
| 8cbbd9 | 167 | |
| CM | 168 | Backwards Incompatibilities |
| 169 | --------------------------- | |
| 170 | ||
| 171 | - Pyramid no longer supports Python 2.4. Python 2.5 or better is required to | |
| 172 | run Pyramid 1.1+. Pyramid, however, does not work under any version of | |
| 173 | Python 3 yet. | |
| 174 | ||
| 175 | - The Pyramid router now, by default, expects response objects returned from | |
| 176 | view callables to implement the :class:`pyramid.interfaces.IResponse` | |
| 177 | interface. Unlike the Pyramid 1.0 version of this interface, objects which | |
| 178 | implement IResponse now must define a ``__call__`` method that accepts | |
| 179 | ``environ`` and ``start_response``, and which returns an ``app_iter`` | |
| 180 | iterable, among other things. Previously, it was possible to return any | |
| 181 | object which had the three WebOb ``app_iter``, ``headerlist``, and | |
| 182 | ``status`` attributes as a response, so this is a backwards | |
| 183 | incompatibility. It is possible to get backwards compatibility back by | |
| 184 | registering an adapter to IResponse from the type of object you're now | |
| 185 | returning from view callables. See the section in the Hooks chapter of the | |
| 186 | documentation entitled :ref:`using_iresponse`. | |
| 187 | ||
| 188 | - The :class:`pyramid.interfaces.IResponse` interface is now much more | |
| 189 | extensive. Previously it defined only ``app_iter``, ``status`` and | |
| 190 | ``headerlist``; now it is basically intended to directly mirror the | |
| 191 | ``webob.Response`` API, which has many methods and attributes. | |
| 192 | ||
| 193 | - The :mod:`pyramid.httpexceptions` classes named ``HTTPFound``, | |
| 194 | ``HTTPMultipleChoices``, ``HTTPMovedPermanently``, ``HTTPSeeOther``, | |
| 195 | ``HTTPUseProxy``, and ``HTTPTemporaryRedirect`` now accept ``location`` as | |
| 196 | their first positional argument rather than ``detail``. This means that | |
| 197 | you can do, e.g. ``return pyramid.httpexceptions.HTTPFound('http://foo')`` | |
| 198 | rather than ``return | |
| 199 | pyramid.httpexceptions.HTTPFound(location='http//foo')`` (the latter will | |
| 200 | of course continue to work). | |
| 0ee9c2 | 201 | |
| cc85e7 | 202 | - The pyramid Router attempted to set a value into the key |
| CM | 203 | ``environ['repoze.bfg.message']`` when it caught a view-related exception |
| 204 | for backwards compatibility with applications written for :mod:`repoze.bfg` | |
| 205 | during error handling. It did this by using code that looked like so:: | |
| 206 | ||
| 207 | # "why" is an exception object | |
| 208 | try: | |
| 209 | msg = why[0] | |
| 210 | except: | |
| 211 | msg = '' | |
| 212 | ||
| 213 | environ['repoze.bfg.message'] = msg | |
| 214 | ||
| 215 | Use of the value ``environ['repoze.bfg.message']`` was docs-deprecated in | |
| 216 | Pyramid 1.0. Our standing policy is to not remove features after a | |
| 217 | deprecation for two full major releases, so this code was originally slated | |
| 218 | to be removed in Pyramid 1.2. However, computing the | |
| 219 | ``repoze.bfg.message`` value was the source of at least one bug found in | |
| 220 | the wild (https://github.com/Pylons/pyramid/issues/199), and there isn't a | |
| 221 | foolproof way to both preserve backwards compatibility and to fix the bug. | |
| 222 | Therefore, the code which sets the value has been removed in this release. | |
| 223 | Code in exception views which relies on this value's presence in the | |
| 224 | environment should now use the ``exception`` attribute of the request | |
| 225 | (e.g. ``request.exception[0]``) to retrieve the message instead of relying | |
| 226 | on ``request.environ['repoze.bfg.message']``. | |
| 227 | ||
| 0ee9c2 | 228 | Deprecations and Behavior Differences |
| CM | 229 | ------------------------------------- |
| 230 | ||
| 18b25a | 231 | - The default Mako renderer is now configured to escape all HTML in |
| MM | 232 | expression tags. This is intended to help prevent XSS attacks caused by |
| 233 | rendering unsanitized input from users. To revert this behavior in user's | |
| 234 | templates, they need to filter the expression through the 'n' filter:: | |
| 235 | ||
| 236 | ${ myhtml | n }. | |
| 237 | ||
| 238 | See https://github.com/Pylons/pyramid/issues/193. | |
| 239 | ||
| 0ee9c2 | 240 | - Deprecated all assignments to ``request.response_*`` attributes (for |
| CM | 241 | example ``request.response_content_type = 'foo'`` is now deprecated). |
| 242 | Assignments and mutations of assignable request attributes that were | |
| 243 | considered by the framework for response influence are now deprecated: | |
| 244 | ``response_content_type``, ``response_headerlist``, ``response_status``, | |
| 245 | ``response_charset``, and ``response_cache_for``. Instead of assigning | |
| 246 | these to the request object for later detection by the rendering machinery, | |
| 247 | users should use the appropriate API of the Response object created by | |
| 248 | accessing ``request.response`` (e.g. code which does | |
| 249 | ``request.response_content_type = 'abc'`` should be changed to | |
| 250 | ``request.response.content_type = 'abc'``). | |
| 251 | ||
| 252 | - Passing view-related parameters to | |
| 253 | :meth:`pyramid.config.Configurator.add_route` is now deprecated. | |
| 254 | Previously, a view was permitted to be connected to a route using a set of | |
| 255 | ``view*`` parameters passed to the ``add_route`` method of the | |
| 256 | Configurator. This was a shorthand which replaced the need to perform a | |
| 257 | subsequent call to ``add_view``. For example, it was valid (and often | |
| 258 | recommended) to do:: | |
| 259 | ||
| 260 | config.add_route('home', '/', view='mypackage.views.myview', | |
| 261 | view_renderer='some/renderer.pt') | |
| 262 | ||
| 263 | Passing ``view*`` arguments to ``add_route`` is now deprecated in favor of | |
| 264 | connecting a view to a predefined route via | |
| 265 | :meth:`pyramid.config.Configurator.add_view` using the route's | |
| 266 | ``route_name`` parameter. As a result, the above example should now be | |
| 267 | spelled:: | |
| 268 | ||
| 269 | config.add_route('home', '/') | |
| 40369d | 270 | config.add_view('mypackage.views.myview', route_name='home', |
| 0ee9c2 | 271 | renderer='some/renderer.pt') |
| CM | 272 | |
| 273 | This deprecation was done to reduce confusion observed in IRC, as well as | |
| 274 | to (eventually) reduce documentation burden (see also | |
| 275 | https://github.com/Pylons/pyramid/issues/164). A deprecation warning is | |
| 276 | now issued when any view-related parameter is passed to | |
| 277 | ``add_route``. | |
| 278 | ||
| 279 | - Passing an ``environ`` dictionary to the ``__call__`` method of a | |
| 280 | "traverser" (e.g. an object that implements | |
| 281 | :class:`pyramid.interfaces.ITraverser` such as an instance of | |
| 282 | :class:`pyramid.traversal.ResourceTreeTraverser`) as its ``request`` | |
| 283 | argument now causes a deprecation warning to be emitted. Consumer code | |
| 284 | should pass a ``request`` object instead. The fact that passing an environ | |
| 285 | dict is permitted has been documentation-deprecated since ``repoze.bfg`` | |
| 286 | 1.1, and this capability will be removed entirely in a future version. | |
| 287 | ||
| 288 | - The following (undocumented, dictionary-like) methods of the | |
| 289 | :class:`pyramid.request.Request` object have been deprecated: | |
| 290 | ``__contains__``, ``__delitem__``, ``__getitem__``, ``__iter__``, | |
| 291 | ``__setitem__``, ``get``, ``has_key``, ``items``, ``iteritems``, | |
| 292 | ``itervalues``, ``keys``, ``pop``, ``popitem``, ``setdefault``, ``update``, | |
| 293 | and ``values``. Usage of any of these methods will cause a deprecation | |
| 294 | warning to be emitted. These methods were added for internal compatibility | |
| 295 | in ``repoze.bfg`` 1.1 (code that currently expects a request object | |
| 296 | expected an environ object in BFG 1.0 and before). In a future version, | |
| 297 | these methods will be removed entirely. | |
| 298 | ||
| 99edc5 | 299 | - A custom request factory is now required to return a request object that |
| 0ee9c2 | 300 | has a ``response`` attribute (or "reified"/lazy property) if they the |
| CM | 301 | request is meant to be used in a view that uses a renderer. This |
| 302 | ``response`` attribute should be an instance of the class | |
| 303 | :class:`pyramid.response.Response`. | |
| 304 | ||
| 305 | - The JSON and string renderer factories now assign to | |
| 306 | ``request.response.content_type`` rather than | |
| bf7544 | 307 | ``request.response_content_type``. |
| CM | 308 | |
| 309 | - Each built-in renderer factory now determines whether it should change the | |
| 310 | content type of the response by comparing the response's content type | |
| 311 | against the response's default content type; if the content type is the | |
| 312 | default content type (usually ``text/html``), the renderer changes the | |
| 313 | content type (to ``application/json`` or ``text/plain`` for JSON and string | |
| 314 | renderers respectively). | |
| 0ee9c2 | 315 | |
| CM | 316 | - The :func:`pyramid.wsgi.wsgiapp2` now uses a slightly different method of |
| 317 | figuring out how to "fix" ``SCRIPT_NAME`` and ``PATH_INFO`` for the | |
| 318 | downstream application. As a result, those values may differ slightly from | |
| 319 | the perspective of the downstream application (for example, ``SCRIPT_NAME`` | |
| 320 | will now never possess a trailing slash). | |
| 321 | ||
| 322 | - Previously, :class:`pyramid.request.Request` inherited from | |
| 323 | :class:`webob.request.Request` and implemented ``__getattr__``, | |
| 92cf3d | 324 | ``__setattr__`` and ``__delattr__`` itself in order to override "adhoc |
| 0ee9c2 | 325 | attr" WebOb behavior where attributes of the request are stored in the |
| 654e3d | 326 | environ. Now, :class:`pyramid.request.Request` inherits from (the more |
| CDLG | 327 | recent) :class:`webob.request.BaseRequest` instead of |
| 0ee9c2 | 328 | :class:`webob.request.Request`, which provides the same behavior. |
| CM | 329 | :class:`pyramid.request.Request` no longer implements its own |
| 330 | ``__getattr__``, ``__setattr__`` or ``__delattr__`` as a result. | |
| 331 | ||
| 8cbbd9 | 332 | - Deprecated :func:`pyramid.view.is_response` function in favor of |
| CM | 333 | (newly-added) :meth:`pyramid.request.Request.is_response` method. |
| 334 | Determining if an object is truly a valid response object now requires | |
| 335 | access to the registry, which is only easily available as a request | |
| 336 | attribute. The :func:`pyramid.view.is_response` function will still work | |
| 337 | until it is removed, but now may return an incorrect answer under some | |
| 338 | (very uncommon) circumstances. | |
| 339 | ||
| 340 | - :class:`pyramid.response.Response` is now a *subclass* of | |
| 341 | ``webob.response.Response`` (in order to directly implement the | |
| 342 | :class:`pyramid.interfaces.IResponse` interface, to speed up response | |
| 343 | generation). | |
| 344 | ||
| 345 | - The "exception response" objects importable from ``pyramid.httpexceptions`` | |
| 346 | (e.g. ``HTTPNotFound``) are no longer just import aliases for classes that | |
| 347 | actually live in ``webob.exc``. Instead, we've defined our own exception | |
| 348 | classes within the module that mirror and emulate the ``webob.exc`` | |
| 349 | exception response objects almost entirely. See | |
| 350 | :ref:`http_exception_hierarchy` in the Design Defense chapter for more | |
| 351 | information. | |
| 352 | ||
| 353 | - When visiting a URL that represented a static view which resolved to a | |
| 354 | subdirectory, the ``index.html`` of that subdirectory would not be served | |
| 355 | properly. Instead, a redirect to ``/subdir`` would be issued. This has | |
| 356 | been fixed, and now visiting a subdirectory that contains an ``index.html`` | |
| 357 | within a static view returns the index.html properly. See also | |
| 358 | https://github.com/Pylons/pyramid/issues/67. | |
| 359 | ||
| 0ee9c2 | 360 | Dependency Changes |
| CM | 361 | ------------------ |
| 362 | ||
| 363 | - Pyramid now depends on :term:`WebOb` >= 1.0.2 as tests depend on the bugfix | |
| 364 | in that release: "Fix handling of WSGI environs with missing | |
| 365 | ``SCRIPT_NAME``". (Note that in reality, everyone should probably be using | |
| 366 | 1.0.4 or better though, as WebOb 1.0.2 and 1.0.3 were effectively brownbag | |
| 367 | releases.) | |
| 368 | ||
| 369 | Documentation Enhancements | |
| 370 | -------------------------- | |
| 371 | ||
| 372 | - The :ref:`bfg_wiki_tutorial` was updated slightly. | |
| 373 | ||
| 374 | - The :ref:`bfg_sql_wiki_tutorial` was updated slightly. | |
| 375 | ||
| 376 | - Made :class:`pyramid.interfaces.IAuthenticationPolicy` and | |
| 377 | :class:`pyramid.interfaces.IAuthorizationPolicy` public interfaces, and | |
| 378 | they are now referred to within the :mod:`pyramid.authentication` and | |
| 379 | :mod:`pyramid.authorization` API docs. | |
| 380 | ||
| 381 | - Render the function definitions for each exposed interface in | |
| 382 | :mod:`pyramid.interfaces`. | |
| 383 | ||
| 384 | - Add missing docs reference to | |
| 385 | :meth:`pyramid.config.Configurator.set_view_mapper` and refer to it within | |
| 386 | the documentation section entitled :ref:`using_a_view_mapper`. | |
| 387 | ||
| 388 | - Added section to the "Environment Variables and ``.ini`` File Settings" | |
| 389 | chapter in the narrative documentation section entitled | |
| 390 | :ref:`adding_a_custom_setting`. | |
| 391 | ||
| 392 | - Added documentation for a :term:`multidict` as | |
| 393 | :class:`pyramid.interfaces.IMultiDict`. | |
| 394 | ||
| 395 | - Added a section to the "URL Dispatch" narrative chapter regarding the new | |
| 396 | "static" route feature entitled :ref:`static_route_narr`. | |
| 1ffb8e | 397 | |
| 8cbbd9 | 398 | - Added API docs for :func:`pyramid.httpexceptions.exception_response`. |
| 1ffb8e | 399 | |
| CM | 400 | - Added :ref:`http_exceptions` section to Views narrative chapter including a |
| 8cbbd9 | 401 | description of :func:`pyramid.httpexceptions.exception_response`. |
| CM | 402 | |
| 403 | - Added API docs for | |
| 404 | :class:`pyramid.authentication.SessionAuthenticationPolicy`. | |
