| commit | author | age | ||
| 41aeac | 1 | What's New in Pyramid 1.4 |
| fcd704 | 2 | ========================= |
| CM | 3 | |
| 4 | This article explains the new features in :app:`Pyramid` version 1.4 as | |
| 5 | compared to its predecessor, :app:`Pyramid` 1.3. It also documents backwards | |
| 6 | incompatibilities between the two versions and deprecations added to | |
| 7 | :app:`Pyramid` 1.4, as well as software dependency changes and notable | |
| 8 | documentation additions. | |
| 9 | ||
| 10 | Major Feature Additions | |
| 11 | ----------------------- | |
| 12 | ||
| 13 | The major feature additions in Pyramid 1.4 follow. | |
| 14 | ||
| 15 | Third-Party Predicates | |
| 16 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
| 17 | ||
| 18 | - Third-party custom view, route, and subscriber predicates can now be added | |
| 19 | for use by view authors via | |
| 20 | :meth:`pyramid.config.Configurator.add_view_predicate`, | |
| 21 | :meth:`pyramid.config.Configurator.add_route_predicate` and | |
| 22 | :meth:`pyramid.config.Configurator.add_subscriber_predicate`. So, for | |
| 23 | example, doing this:: | |
| 24 | ||
| 25 | config.add_view_predicate('abc', my.package.ABCPredicate) | |
| 26 | ||
| 27 | Might allow a view author to do this in an application that configured that | |
| 28 | predicate:: | |
| 29 | ||
| 30 | @view_config(abc=1) | |
| 31 | ||
| 32 | Similar features exist for :meth:`pyramid.config.Configurator.add_route`, | |
| 33 | and :meth:`pyramid.config.Configurator.add_subscriber`. See | |
| 34 | :ref:`registering_thirdparty_predicates` for more information. | |
| 35 | ||
| 36 | Easy Custom JSON Serialization | |
| 37 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 38 | ||
| 39 | - Views can now return custom objects which will be serialized to JSON by a | |
| 40 | JSON renderer by defining a ``__json__`` method on the object's class. This | |
| 41 | method should return values natively serializable by ``json.dumps`` (such | |
| 42 | as ints, lists, dictionaries, strings, and so forth). See | |
| 43 | :ref:`json_serializing_custom_objects` for more information. The JSON | |
| 44 | renderer now also allows for the definition of custom type adapters to | |
| 45 | convert unknown objects to JSON serializations, in case you can't add a | |
| 46 | ``__json__`` method to returned objects. | |
| 47 | ||
| 48 | Partial Mako and Chameleon Template Renderings | |
| 49 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 50 | ||
| 51 | - The Mako renderer now supports using a def name in an asset spec. When the | |
| 52 | def name is present in the asset spec, the system will render the template | |
| 53 | named def within the template instead of rendering the entire template. An | |
| 54 | example asset spec which names a def is | |
| 55 | ``package:path/to/template#defname.mako``. This will render the def named | |
| 56 | ``defname`` inside the ``template.mako`` template instead of rendering the | |
| 57 | entire template. The old way of returning a tuple in the form | |
| 58 | ``('defname', {})`` from the view is supported for backward compatibility. | |
| 59 | ||
| 60 | - The Chameleon ZPT renderer now supports using a macro name in an asset | |
| 61 | spec. When the macro name is present in the asset spec, the system will | |
| 62 | render the macro listed as a ``define-macro`` and return the result instead | |
| 63 | of rendering the entire template. An example asset spec: | |
| 64 | ``package:path/to/template#macroname.pt``. This will render the macro | |
| 65 | defined as ``macroname`` within the ``template.pt`` template instead of the | |
| 1affe4 | 66 | entire template. |
| fcd704 | 67 | |
| 37d2c2 | 68 | Subrequest Support |
| CM | 69 | ~~~~~~~~~~~~~~~~~~ |
| 70 | ||
| 71 | - Developers may invoke a subrequest by using the | |
| 64452e | 72 | :meth:`pyramid.request.Request.invoke_subrequest` API. This allows a |
| CM | 73 | developer to obtain a response from one view callable by issuing a subrequest |
| 355ed0 | 74 | from within a different view callable. See :ref:`subrequest_chapter` for |
| CM | 75 | more information. |
| 37d2c2 | 76 | |
| fcd704 | 77 | Minor Feature Additions |
| CM | 78 | ----------------------- |
| 79 | ||
| 2063ed | 80 | - :class:`pyramid.authentication.AuthTktAuthenticationPolicy` has been updated |
| CM | 81 | to support newer hashing algorithms such as ``sha512``. Existing applications |
| 82 | should consider updating if possible for improved security over the default | |
| 83 | md5 hashing. | |
| 84 | ||
| fcd704 | 85 | - :meth:`pyramid.config.Configurator.add_directive` now accepts arbitrary |
| 1affe4 | 86 | callables like partials or objects implementing ``__call__`` which don't |
| fcd704 | 87 | have ``__name__`` and ``__doc__`` attributes. See |
| CM | 88 | https://github.com/Pylons/pyramid/issues/621 and |
| 89 | https://github.com/Pylons/pyramid/pull/647. | |
| 90 | ||
| 91 | - As of this release, the ``request_method`` view/route predicate, when used, | |
| 92 | will also imply that ``HEAD`` is implied when you use ``GET``. For | |
| 93 | example, using ``@view_config(request_method='GET')`` is equivalent to | |
| 94 | using ``@view_config(request_method=('GET', 'HEAD'))``. Using | |
| 95 | ``@view_config(request_method=('GET', 'POST')`` is equivalent to using | |
| 96 | ``@view_config(request_method=('GET', 'HEAD', 'POST')``. This is because | |
| 97 | HEAD is a variant of GET that omits the body, and WebOb has special support | |
| 98 | to return an empty body when a HEAD is used. | |
| 99 | ||
| 100 | - :meth:`pyramid.config.Configurator.add_request_method` has been introduced | |
| 101 | to support extending request objects with arbitrary callables. This method | |
| 043656 | 102 | expands on the now documentation-deprecated |
| fcd704 | 103 | :meth:`pyramid.config.Configurator.set_request_property` by supporting |
| 043656 | 104 | methods as well as properties. This method also causes less code to be |
| PJ | 105 | executed at request construction time than |
| fcd704 | 106 | :meth:`~pyramid.config.Configurator.set_request_property`. |
| CM | 107 | |
| 108 | - The static view machinery now raises rather than returns | |
| 109 | :class:`pyramid.httpexceptions.HTTPNotFound` and | |
| 110 | :class:`pyramid.httpexceptions.HTTPMovedPermanently` exceptions, so these can | |
| cec2b0 | 111 | be caught by the Not Found View (and other exception views). |
| fcd704 | 112 | |
| CM | 113 | - When there is a predicate mismatch exception (seen when no view matches for |
| 114 | a given request due to predicates not working), the exception now contains | |
| 115 | a textual description of the predicate which didn't match. | |
| 116 | ||
| 117 | - An :meth:`pyramid.config.Configurator.add_permission` directive method was | |
| 118 | added to the Configurator. This directive registers a free-standing | |
| 119 | permission introspectable into the Pyramid introspection system. | |
| 1affe4 | 120 | Frameworks built atop Pyramid can thus use the ``permissions`` |
| fcd704 | 121 | introspectable category data to build a comprehensive list of permissions |
| CM | 122 | supported by a running system. Before this method was added, permissions |
| 123 | were already registered in this introspectable category as a side effect of | |
| 124 | naming them in an :meth:`pyramid.config.Configurator.add_view` call, this | |
| 125 | method just makes it possible to arrange for a permission to be put into | |
| 126 | the ``permissions`` introspectable category without naming it along with an | |
| 127 | associated view. Here's an example of usage of ``add_permission``:: | |
| 128 | ||
| 129 | config = Configurator() | |
| 130 | config.add_permission('view') | |
| 131 | ||
| 132 | - The :func:`pyramid.session.UnencryptedCookieSessionFactoryConfig` function | |
| 133 | now accepts ``signed_serialize`` and ``signed_deserialize`` hooks which may | |
| 134 | be used to influence how the sessions are marshalled (by default this is | |
| 135 | done with HMAC+pickle). | |
| 136 | ||
| 137 | - :class:`pyramid.testing.DummyRequest` now supports methods supplied by the | |
| 138 | ``pyramid.util.InstancePropertyMixin`` class such as ``set_property``. | |
| 139 | ||
| 140 | - Request properties and methods added via | |
| 043656 | 141 | :meth:`pyramid.config.Configurator.add_request_method` or |
| PJ | 142 | :meth:`pyramid.config.Configurator.set_request_property` are now available to |
| fcd704 | 143 | tweens. |
| CM | 144 | |
| 145 | - Request properties and methods added via | |
| 043656 | 146 | :meth:`pyramid.config.Configurator.add_request_method` or |
| PJ | 147 | :meth:`pyramid.config.Configurator.set_request_property` are now available |
| fcd704 | 148 | in the request object returned from :func:`pyramid.paster.bootstrap`. |
| CM | 149 | |
| 150 | - ``request.context`` of environment request during | |
| 151 | :func:`pyramid.paster.bootstrap` is now the root object if a context isn't | |
| 152 | already set on a provided request. | |
| 153 | ||
| 154 | - :class:`pyramid.decorator.reify` is now an API, and was added to | |
| 155 | the API documentation. | |
| 156 | ||
| 157 | - Added the :func:`pyramid.testing.testConfig` context manager, which can be | |
| 158 | used to generate a configurator in a test, e.g. ``with | |
| 159 | testing.testConfig(...):``. | |
| 160 | ||
| 68c00d | 161 | - A new :func:`pyramid.session.check_csrf_token` convenience API function was |
| CM | 162 | added. |
| 163 | ||
| 643a83 | 164 | - A ``check_csrf`` view predicate was added. For example, you can now do |
| CM | 165 | ``config.add_view(someview, check_csrf=True)``. When the predicate is |
| 166 | checked, if the ``csrf_token`` value in ``request.params`` matches the csrf | |
| 167 | token in the request's session, the view will be permitted to execute. | |
| 168 | Otherwise, it will not be permitted to execute. | |
| 169 | ||
| 072cbf | 170 | - Add ``Base.metadata.bind = engine`` to ``alchemy`` scaffold, so that tables |
| CM | 171 | defined imperatively will work. |
| 172 | ||
| 4a6cca | 173 | - Comments with references to documentation sections placed in scaffold |
| CM | 174 | ``.ini`` files. |
| 175 | ||
| 176 | - Allow multiple values to be specified to the ``request_param`` view/route | |
| 177 | predicate as a sequence. Previously only a single string value was allowed. | |
| 178 | See https://github.com/Pylons/pyramid/pull/705 | |
| 179 | ||
| 180 | - Added an HTTP Basic authentication policy | |
| 181 | at :class:`pyramid.authentication.BasicAuthAuthenticationPolicy`. | |
| 182 | ||
| 183 | - The :meth:`pyramid.config.Configurator.testing_securitypolicy` method now | |
| 184 | returns the policy object it creates. | |
| 185 | ||
| 186 | - The DummySecurityPolicy created by | |
| 50218d | 187 | :meth:`pyramid.config.Configurator.testing_securitypolicy` now sets a |
| TL | 188 | ``forgotten`` value on the policy (the value ``True``) when its ``forget`` |
| 189 | method is called. | |
| 4a6cca | 190 | |
| CM | 191 | - The DummySecurityPolicy created by |
| 50218d | 192 | :meth:`pyramid.config.Configurator.testing_securitypolicy` now sets a |
| 4a6cca | 193 | ``remembered`` value on the policy, which is the value of the ``principal`` |
| CM | 194 | argument it's called with when its ``remember`` method is called. |
| 195 | ||
| 196 | - New ``physical_path`` view predicate. If specified, this value should be a | |
| 197 | string or a tuple representing the physical traversal path of the context | |
| 198 | found via traversal for this predicate to match as true. For example: | |
| 199 | ``physical_path='/'`` or ``physical_path='/a/b/c'`` or ``physical_path=('', | |
| 200 | 'a', 'b', 'c')``. It's useful when you want to always potentially show a | |
| 201 | view when some object is traversed to, but you can't be sure about what kind | |
| 202 | of object it will be, so you can't use the ``context`` predicate. | |
| 2063ed | 203 | |
| CM | 204 | - Added an ``effective_principals`` route and view predicate. |
| 205 | ||
| 206 | - Do not allow the userid returned from the | |
| 207 | :func:`pyramid.security.authenticated_userid` or the userid that is one of the | |
| 208 | list of principals returned by :func:`pyramid.security.effective_principals` | |
| 209 | to be either of the strings ``system.Everyone`` or ``system.Authenticated`` | |
| 210 | when any of the built-in authorization policies that live in | |
| 211 | :mod:`pyramid.authentication` are in use. These two strings are reserved for | |
| 212 | internal usage by Pyramid and they will no longer be accepted as valid | |
| 213 | userids. | |
| 214 | ||
| 215 | - Allow a ``_depth`` argument to :class:`pyramid.view.view_config`, which will | |
| 216 | permit limited composition reuse of the decorator by other software that | |
| 217 | wants to provide custom decorators that are much like view_config. | |
| 218 | ||
| 219 | - Allow an iterable of decorators to be passed to | |
| 220 | :meth:`pyramid.config.Configurator.add_view`. This allows views to be wrapped | |
| 221 | by more than one decorator without requiring combining the decorators | |
| 222 | yourself. | |
| 223 | ||
| 224 | - :func:`pyramid.security.view_execution_permitted` used to return `True` if no | |
| 225 | view could be found. It now raises a :exc:`TypeError` exception in that case, | |
| 226 | as it doesn't make sense to assert that a nonexistent view is | |
| 227 | execution-permitted. See https://github.com/Pylons/pyramid/issues/299. | |
| 4a6cca | 228 | |
| 50fdf8 | 229 | - Small microspeed enhancement which anticipates that a |
| CM | 230 | :class:`pyramid.response.Response` object is likely to be returned from a |
| 231 | view. Some code is shortcut if the class of the object returned by a view is | |
| 232 | this class. A similar microoptimization was done to | |
| 233 | :func:`pyramid.request.Request.is_response`. | |
| 234 | ||
| 235 | - Make it possible to use variable arguments on all ``p*`` commands | |
| 236 | (``pserve``, ``pshell``, ``pviews``, etc) in the form ``a=1 b=2`` so you can | |
| 237 | fill in values in parameterized ``.ini`` file, e.g. ``pshell | |
| 238 | etc/development.ini http_port=8080``. | |
| 239 | ||
| 240 | - In order to allow people to ignore unused arguments to subscriber callables | |
| 241 | and to normalize the relationship between event subscribers and subscriber | |
| 242 | predicates, we now allow both subscribers and subscriber predicates to accept | |
| 243 | only a single ``event`` argument even if they've been subscribed for | |
| 244 | notifications that involve multiple interfaces. | |
| 245 | ||
| fcd704 | 246 | Backwards Incompatibilities |
| CM | 247 | --------------------------- |
| 248 | ||
| 249 | - The Pyramid router no longer adds the values ``bfg.routes.route`` or | |
| 250 | ``bfg.routes.matchdict`` to the request's WSGI environment dictionary. | |
| 251 | These values were docs-deprecated in ``repoze.bfg`` 1.0 (effectively seven | |
| 252 | minor releases ago). If your code depended on these values, use | |
| 1affe4 | 253 | ``request.matched_route`` and ``request.matchdict`` instead. |
| fcd704 | 254 | |
| CM | 255 | - It is no longer possible to pass an environ dictionary directly to |
| 256 | ``pyramid.traversal.ResourceTreeTraverser.__call__`` (aka | |
| 257 | ``ModelGraphTraverser.__call__``). Instead, you must pass a request | |
| 258 | object. Passing an environment instead of a request has generated a | |
| 259 | deprecation warning since Pyramid 1.1. | |
| 260 | ||
| 261 | - Pyramid will no longer work properly if you use the | |
| 262 | ``webob.request.LegacyRequest`` as a request factory. Instances of the | |
| 263 | LegacyRequest class have a ``request.path_info`` which return a string. | |
| 264 | This Pyramid release assumes that ``request.path_info`` will | |
| 265 | unconditionally be Unicode. | |
| 266 | ||
| 267 | - The functions from ``pyramid.chameleon_zpt`` and ``pyramid.chameleon_text`` | |
| 268 | named ``get_renderer``, ``get_template``, ``render_template``, and | |
| 269 | ``render_template_to_response`` have been removed. These have issued a | |
| 270 | deprecation warning upon import since Pyramid 1.0. Use | |
| 271 | :func:`pyramid.renderers.get_renderer`, | |
| 272 | ``pyramid.renderers.get_renderer().implementation()``, | |
| 273 | :func:`pyramid.renderers.render` or | |
| 274 | :func:`pyramid.renderers.render_to_response` respectively instead of these | |
| 275 | functions. | |
| 276 | ||
| 277 | - The ``pyramid.configuration`` module was removed. It had been deprecated | |
| 278 | since Pyramid 1.0 and printed a deprecation warning upon its use. Use | |
| 279 | :mod:`pyramid.config` instead. | |
| 280 | ||
| 281 | - The ``pyramid.paster.PyramidTemplate`` API was removed. It had been | |
| 282 | deprecated since Pyramid 1.1 and issued a warning on import. If your code | |
| 283 | depended on this, adjust your code to import | |
| 284 | :class:`pyramid.scaffolds.PyramidTemplate` instead. | |
| 285 | ||
| 286 | - The ``pyramid.settings.get_settings()`` API was removed. It had been | |
| 287 | printing a deprecation warning since Pyramid 1.0. If your code depended on | |
| 288 | this API, use ``pyramid.threadlocal.get_current_registry().settings`` | |
| 289 | instead or use the ``settings`` attribute of the registry available from | |
| 290 | the request (``request.registry.settings``). | |
| 291 | ||
| 292 | - These APIs from the ``pyramid.testing`` module were removed. They have | |
| 293 | been printing deprecation warnings since Pyramid 1.0: | |
| 294 | ||
| 295 | * ``registerDummySecurityPolicy``, use | |
| 296 | :meth:`pyramid.config.Configurator.testing_securitypolicy` instead. | |
| 297 | ||
| 298 | * ``registerResources`` (aka ``registerModels``), use | |
| 299 | :meth:`pyramid.config.Configurator.testing_resources` instead. | |
| 300 | ||
| 301 | * ``registerEventListener``, use | |
| 302 | :meth:`pyramid.config.Configurator.testing_add_subscriber` instead. | |
| 303 | ||
| 1affe4 | 304 | * ``registerTemplateRenderer`` (aka ``registerDummyRenderer``), use |
| 50218d | 305 | :meth:`pyramid.config.Configurator.testing_add_renderer` instead. |
| fcd704 | 306 | |
| CM | 307 | * ``registerView``, use :meth:`pyramid.config.Configurator.add_view` instead. |
| 308 | ||
| 309 | * ``registerUtility``, use | |
| 310 | :meth:`pyramid.config.Configurator.registry.registerUtility` instead. | |
| 311 | ||
| 312 | * ``registerAdapter``, use | |
| 313 | :meth:`pyramid.config.Configurator.registry.registerAdapter` instead. | |
| 314 | ||
| 315 | * ``registerSubscriber``, use | |
| 316 | :meth:`pyramid.config.Configurator.add_subscriber` instead. | |
| 317 | ||
| 318 | * ``registerRoute``, use | |
| 319 | :meth:`pyramid.config.Configurator.add_route` instead. | |
| 320 | ||
| 321 | * ``registerSettings``, use | |
| 322 | :meth:`pyramid.config.Configurator.add_settings` instead. | |
| 323 | ||
| 64452e | 324 | - In Pyramid 1.3 and previous, the ``__call__`` method of a Response object |
| CM | 325 | returned by a view was invoked before any finished callbacks were executed. |
| 326 | As of this release, the ``__call__`` method of a Response object is invoked | |
| 327 | *after* finished callbacks are executed. This is in support of the | |
| 328 | :meth:`pyramid.request.Request.invoke_subrequest` feature. | |
| 329 | ||
| fcd704 | 330 | Deprecations |
| CM | 331 | ------------ |
| 332 | ||
| 333 | - The :meth:`pyramid.config.Configurator.set_request_property` directive has | |
| 334 | been documentation-deprecated. The method remains usable but the more | |
| 335 | featureful :meth:`pyramid.config.Configurator.add_request_method` should be | |
| 336 | used in its place (it has all of the same capabilities but can also extend | |
| 337 | the request object with methods). | |
| 338 | ||
| 2063ed | 339 | - :class:`pyramid.authentication.AuthTktAuthenticationPolicy` will emit a |
| CM | 340 | deprecation warning if an application is using the policy without explicitly |
| 341 | passing a ``hashalg`` argument. This is because the default is "md5" which is | |
| 342 | considered theoretically subject to collision attacks. If you really want | |
| 343 | "md5" then you must specify it explicitly to get rid of the warning. | |
| 344 | ||
| fcd704 | 345 | Documentation Enhancements |
| CM | 346 | -------------------------- |
| 347 | ||
| 348 | - Added an :ref:`upgrading_chapter` chapter to the narrative documentation. | |
| 349 | It describes how to cope with deprecations and removals of Pyramid APIs and | |
| 350 | how to show Pyramid-generated deprecation warnings while running tests and | |
| 351 | while running a server. | |
| 352 | ||
| 37d2c2 | 353 | - Added a :ref:`subrequest_chapter` chapter to the narrative documentation. |
| CM | 354 | |
| 2063ed | 355 | - All of the tutorials that use |
| CM | 356 | :class:`pyramid.authentication.AuthTktAuthenticationPolicy` now explicitly |
| 357 | pass ``sha512`` as a ``hashalg`` argument. | |
| 358 | ||
| fcd704 | 359 | - Many cleanups and improvements to narrative and API docs. |
| CM | 360 | |
| 361 | Dependency Changes | |
| 362 | ------------------ | |
| 363 | ||
| 364 | - Pyramid now requires WebOb 1.2b3+ (the prior Pyramid release only relied on | |
| 365 | 1.2dev+). This is to ensure that we obtain a version of WebOb that returns | |
| 366 | ``request.path_info`` as text. | |
| 367 | ||
