| commit | author | age | ||
| 41aeac | 1 | What's New in Pyramid 1.2 |
| a8c81d | 2 | ========================= |
| CM | 3 | |
| 4 | This article explains the new features in :app:`Pyramid` version 1.2 as | |
| 5 | compared to its predecessor, :app:`Pyramid` 1.1. It also documents backwards | |
| 6 | incompatibilities between the two versions and deprecations added to Pyramid | |
| 7 | 1.2, as well as software dependency changes and notable documentation | |
| 8 | additions. | |
| 9 | ||
| 10 | Major Feature Additions | |
| 11 | ----------------------- | |
| 12 | ||
| 13 | The major feature additions in Pyramid 1.2 follow. | |
| 14 | ||
| 6a7931 | 15 | Debug Toolbar |
| CM | 16 | ~~~~~~~~~~~~~ |
| 17 | ||
| 18 | The scaffolding packages that come with Pyramid now include a debug toolbar | |
| 19 | component which can be used to interactively debug an application. See | |
| 20 | :ref:`debug_toolbar` for more information. | |
| 21 | ||
| a8c81d | 22 | ``route_prefix`` Argument to include |
| CM | 23 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 24 | ||
| 25 | The :meth:`pyramid.config.Configurator.include` method now accepts a | |
| 26 | ``route_prefix`` argument. This argument allows you to compose URL dispatch | |
| 27 | applications together from disparate packages. See :ref:`route_prefix` for | |
| 28 | more information. | |
| 29 | ||
| 30 | Tweens | |
| 31 | ~~~~~~ | |
| 32 | ||
| 33 | A :term:`tween` is used to wrap the Pyramid router's primary request handling | |
| 37607c | 34 | function. This is a feature that can be used by Pyramid framework extensions, |
| CI | 35 | to provide, for example, view timing support and can provide a convenient |
| a9cdf8 | 36 | place to hang bookkeeping code. Tweens are a little like :term:`WSGI` |
| 37607c | 37 | :term:`middleware`, but have access to Pyramid functionality such as renderers |
| CI | 38 | and a full-featured request object. |
| a8c81d | 39 | |
| CM | 40 | To support this feature, a new configurator directive exists named |
| 41 | :meth:`pyramid.config.Configurator.add_tween`. This directive adds a | |
| 42 | "tween". | |
| 43 | ||
| 44 | Tweens are further described in :ref:`registering_tweens`. | |
| 45 | ||
| 46 | A new paster command now exists: ``paster ptweens``. This command prints the | |
| 47 | current tween configuration for an application. See the section entitled | |
| 48 | :ref:`displaying_tweens` for more info. | |
| 49 | ||
| 50 | Scaffolding Changes | |
| 51 | ~~~~~~~~~~~~~~~~~~~ | |
| 52 | ||
| 53 | - All scaffolds now use the ``pyramid_tm`` package rather than the | |
| 37607c | 54 | ``repoze.tm2`` :term:`middleware` to manage transaction management. |
| a8c81d | 55 | |
| CM | 56 | - The ZODB scaffold now uses the ``pyramid_zodbconn`` package rather than the |
| 57 | ``repoze.zodbconn`` package to provide ZODB integration. | |
| 58 | ||
| 59 | - All scaffolds now use the ``pyramid_debugtoolbar`` package rather than the | |
| 60 | ``WebError`` package to provide interactive debugging features. | |
| 61 | ||
| 37607c | 62 | - Projects created via a scaffold no longer depend on the ``WebError`` package |
| CI | 63 | at all; configuration in the ``production.ini`` file which used to require |
| 64 | its ``error_catcher`` :term:`middleware` has been removed. Configuring | |
| a8c81d | 65 | error catching / email sending is now the domain of the ``pyramid_exclog`` |
| f75a3f | 66 | package (see http://docs.pylonsproject.org/projects/pyramid_exclog/dev/). |
| a8c81d | 67 | |
| d00fa0 | 68 | - All scaffolds now send the ``cache_max_age`` parameter to the |
| CM | 69 | ``add_static_view`` method. |
| 70 | ||
| a8c81d | 71 | Minor Feature Additions |
| CM | 72 | ----------------------- |
| 73 | ||
| 74 | - The ``[pshell]`` section in an ini configuration file now treats a | |
| 75 | ``setup`` key as a dotted name that points to a callable that is passed the | |
| 76 | bootstrap environment. It can mutate the environment as necessary during a | |
| 77 | ``paster pshell`` session. This feature is described in | |
| 78 | :ref:`writing_a_script`. | |
| 79 | ||
| 80 | - A new configuration setting named ``pyramid.includes`` is now available. | |
| 81 | It is described in :ref:`including_packages`. | |
| 82 | ||
| 83 | - Added a :data:`pyramid.security.NO_PERMISSION_REQUIRED` constant for use in | |
| 84 | ``permission=`` statements to view configuration. This constant has a | |
| 85 | value of the string ``__no_permission_required__``. This string value was | |
| 86 | previously referred to in documentation; now the documentation uses the | |
| 87 | constant. | |
| 88 | ||
| 89 | - Added a decorator-based way to configure a response adapter: | |
| 90 | :class:`pyramid.response.response_adapter`. This decorator has the same | |
| 91 | use as :meth:`pyramid.config.Configurator.add_response_adapter` but it's | |
| 92 | declarative. | |
| 93 | ||
| 94 | - The :class:`pyramid.events.BeforeRender` event now has an attribute named | |
| 95 | ``rendering_val``. This can be used to introspect the value returned by a | |
| 96 | view in a BeforeRender subscriber. | |
| 97 | ||
| 98 | - The Pyramid debug logger now uses the standard logging configuration | |
| 99 | (usually set up by Paste as part of startup). This means that output from | |
| 100 | e.g. ``debug_notfound``, ``debug_authorization``, etc. will go to the | |
| 101 | normal logging channels. The logger name of the debug logger will be the | |
| 102 | package name of the *caller* of the Configurator's constructor. | |
| 103 | ||
| 104 | - A new attribute is available on request objects: ``exc_info``. Its value | |
| 105 | will be ``None`` until an exception is caught by the Pyramid router, after | |
| 106 | which it will be the result of ``sys.exc_info()``. | |
| 107 | ||
| 108 | - :class:`pyramid.testing.DummyRequest` now implements the | |
| 109 | ``add_finished_callback`` and ``add_response_callback`` methods implemented | |
| 110 | by :class:`pyramid.request.Request`. | |
| 111 | ||
| 112 | - New methods of the :class:`pyramid.config.Configurator` class: | |
| 113 | :meth:`~pyramid.config.Configurator.set_authentication_policy` and | |
| 114 | :meth:`~pyramid.config.Configurator.set_authorization_policy`. These are | |
| 115 | meant to be consumed mostly by add-on authors who wish to offer packages | |
| 116 | which register security policies. | |
| 117 | ||
| 118 | - New Configurator method: | |
| 119 | :meth:`pyramid.config.Configurator.set_root_factory`, which can set the | |
| 120 | root factory after the Configurator has been constructed. | |
| 121 | ||
| 122 | - Pyramid no longer eagerly commits some default configuration statements at | |
| 123 | :term:`Configurator` construction time, which permits values passed in as | |
| 124 | constructor arguments (e.g. ``authentication_policy`` and | |
| 125 | ``authorization_policy``) to override the same settings obtained via the | |
| 126 | :meth:`pyramid.config.Configurator.include` method. | |
| 127 | ||
| 128 | - Better Mako rendering exceptions; the template line which caused the error | |
| 129 | is now shown when a Mako rendering raises an exception. | |
| 130 | ||
| 131 | - New request methods: :meth:`~pyramid.request.Request.current_route_url`, | |
| 132 | :meth:`~pyramid.request.Request.current_route_path`, and | |
| 133 | :meth:`~pyramid.request.Request.static_path`. | |
| 134 | ||
| 135 | - New functions in the :mod:`pyramid.url` module: | |
| 136 | :func:`~pyramid.url.current_route_path` and | |
| 137 | :func:`~pyramid.url.static_path`. | |
| 138 | ||
| 139 | - The :meth:`pyramid.request.Request.static_url` API (and its brethren | |
| 140 | :meth:`pyramid.request.Request.static_path`, | |
| 141 | :func:`pyramid.url.static_url`, and :func:`pyramid.url.static_path`) now | |
| f4b088 | 142 | accept an absolute filename as a "path" argument. This will generate a URL |
| a8c81d | 143 | to an asset as long as the filename is in a directory which was previously |
| CM | 144 | registered as a static view. Previously, trying to generate a URL to an |
| 145 | asset using an absolute file path would raise a ValueError. | |
| 146 | ||
| 147 | - The :class:`~pyramid.authentication.RemoteUserAuthenticationPolicy`, | |
| 148 | :class:`~pyramid.authentication.AuthTktAuthenticationPolicy`, and | |
| 149 | :class:`~pyramid.authentication.SessionAuthenticationPolicy` constructors | |
| 150 | now accept an additional keyword argument named ``debug``. By default, | |
| 151 | this keyword argument is ``False``. When it is ``True``, debug information | |
| 152 | will be sent to the Pyramid debug logger (usually on stderr) when the | |
| 153 | ``authenticated_userid`` or ``effective_principals`` method is called on | |
| 154 | any of these policies. The output produced can be useful when trying to | |
| 155 | diagnose authentication-related problems. | |
| 156 | ||
| 141f90 | 157 | - New view predicate: ``match_param``. Example: a view added via |
| CM | 158 | ``config.add_view(aview, match_param='action=edit')`` will be called only |
| 159 | when the ``request.matchdict`` has a value inside it named ``action`` with | |
| 160 | a value of ``edit``. | |
| 161 | ||
| 1aeae3 | 162 | - Support an ``onerror`` keyword argument to |
| 50218d | 163 | :meth:`pyramid.config.Configurator.scan`. This argument is passed to |
| 1aeae3 | 164 | :meth:`venusian.Scanner.scan` to influence error behavior when an exception |
| CM | 165 | is raised during scanning. |
| 166 | ||
| 49f082 | 167 | - The ``request_method`` predicate argument to |
| CM | 168 | :meth:`pyramid.config.Configurator.add_view` and |
| 169 | :meth:`pyramid.config.Configurator.add_route` is now permitted to be a | |
| 170 | tuple of HTTP method names. Previously it was restricted to being a string | |
| 171 | representing a single HTTP method name. | |
| 172 | ||
| 33516a | 173 | - Undeprecated ``pyramid.traversal.find_model``, |
| CM | 174 | ``pyramid.traversal.model_path``, ``pyramid.traversal.model_path_tuple``, |
| 175 | and ``pyramid.url.model_url``, which were all deprecated in Pyramid 1.0. | |
| 176 | There's just not much cost to keeping them around forever as aliases to | |
| 177 | their renamed ``resource_*`` prefixed functions. | |
| 178 | ||
| 179 | - Undeprecated ``pyramid.view.bfg_view``, which was deprecated in Pyramid | |
| 180 | 1.0. This is a low-cost alias to ``pyramid.view.view_config`` which we'll | |
| 181 | just keep around forever. | |
| 182 | ||
| acec46 | 183 | - Route pattern replacement marker names can now begin with an underscore. |
| CM | 184 | See https://github.com/Pylons/pyramid/issues/276. |
| 185 | ||
| a8c81d | 186 | Deprecations |
| CM | 187 | ------------ |
| 188 | ||
| 189 | - All Pyramid-related :term:`deployment settings` (e.g. ``debug_all``, | |
| 190 | ``debug_notfound``) are now meant to be prefixed with the prefix | |
| 191 | ``pyramid.``. For example: ``debug_all`` -> ``pyramid.debug_all``. The | |
| 192 | old non-prefixed settings will continue to work indefinitely but supplying | |
| 193 | them may print a deprecation warning. All scaffolds and tutorials have | |
| 194 | been changed to use prefixed settings. | |
| 195 | ||
| 196 | - The :term:`deployment settings` dictionary now raises a deprecation warning | |
| 197 | when you attempt to access its values via ``__getattr__`` instead of via | |
| 198 | ``__getitem__``. | |
| 199 | ||
| 200 | Backwards Incompatibilities | |
| 201 | --------------------------- | |
| 202 | ||
| 203 | - If a string is passed as the ``debug_logger`` parameter to a | |
| 204 | :term:`Configurator`, that string is considered to be the name of a global | |
| 205 | Python logger rather than a dotted name to an instance of a logger. | |
| 206 | ||
| 207 | - The :meth:`pyramid.config.Configurator.include` method now accepts only a | |
| 208 | single ``callable`` argument. A *sequence* of callables used to be | |
| 209 | permitted. If you are passing more than one ``callable`` to | |
| 210 | :meth:`pyramid.config.Configurator.include`, it will break. You now must | |
| 211 | now instead make a separate call to the method for each callable. | |
| 212 | ||
| 04b7ea | 213 | - It may be necessary to more strictly order configuration route and view |
| CM | 214 | statements when using an "autocommitting" :term:`Configurator`. In the |
| 215 | past, it was possible to add a view which named a route name before adding | |
| 216 | a route with that name when you used an autocommitting configurator. For | |
| 217 | example: | |
| 218 | ||
| 219 | .. code-block:: python | |
| 220 | ||
| 221 | config = Configurator(autocommit=True) | |
| 222 | config.add_view('my.pkg.someview', route_name='foo') | |
| 223 | config.add_route('foo', '/foo') | |
| 224 | ||
| 225 | The above will raise an exception when the view attempts to add itself. | |
| 226 | Now you must add the route before adding the view: | |
| 227 | ||
| 228 | .. code-block:: python | |
| 229 | ||
| 230 | config = Configurator(autocommit=True) | |
| 231 | config.add_route('foo', '/foo') | |
| 232 | config.add_view('my.pkg.someview', route_name='foo') | |
| 233 | ||
| 234 | This won't effect "normal" users, only people who have legacy BFG codebases | |
| 235 | that used an autommitting configurator and possibly tests that use the | |
| 236 | configurator API (the configurator returned by | |
| 237 | :func:`pyramid.testing.setUp` is an autocommitting configurator). The | |
| 238 | right way to get around this is to use a default non-autocommitting | |
| 239 | configurator, which does not have these directive ordering requirements: | |
| 240 | ||
| 241 | .. code-block:: python | |
| 242 | ||
| 243 | config = Configurator() | |
| 244 | config.add_view('my.pkg.someview', route_name='foo') | |
| 245 | config.add_route('foo', '/foo') | |
| 246 | ||
| 247 | The above will work fine. | |
| 248 | ||
| 249 | - The :meth:`pyramid.config.Configurator.add_route` directive no longer | |
| 250 | returns a route object. This change was required to make route vs. view | |
| 251 | configuration processing work properly. | |
| 252 | ||
| d00fa0 | 253 | Behavior Differences |
| CM | 254 | -------------------- |
| 255 | ||
| 256 | - An ETag header is no longer set when serving a static file. A | |
| 257 | Last-Modified header is set instead. | |
| 258 | ||
| 259 | - Static file serving no longer supports the ``wsgi.file_wrapper`` extension. | |
| 260 | ||
| 261 | - Instead of returning a ``403 Forbidden`` error when a static file is served | |
| 262 | that cannot be accessed by the Pyramid process' user due to file | |
| 263 | permissions, an IOError (or similar) will be raised. | |
| 264 | ||
| a8c81d | 265 | Documentation Enhancements |
| CM | 266 | -------------------------- |
| 267 | ||
| 268 | - Narrative and API documentation which used the ``route_url``, | |
| 269 | ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` | |
| 270 | functions in the :mod:`pyramid.url` package have now been changed to use | |
| 271 | eponymous methods of the request instead. | |
| 272 | ||
| 273 | - Added a section entitled :ref:`route_prefix` to the "URL Dispatch" | |
| 274 | narrative documentation chapter. | |
| 275 | ||
| 276 | - Added a new module to the API docs: :mod:`pyramid.tweens`. | |
| 277 | ||
| 278 | - Added a :ref:`registering_tweens` section to the "Hooks" narrative chapter. | |
| 279 | ||
| 280 | - Added a :ref:`displaying_tweens` section to the "Command-Line Pyramid" | |
| 281 | narrative chapter. | |
| 282 | ||
| 283 | - Added documentation for :ref:`explicit_tween_config` and | |
| 284 | :ref:`including_packages` to the "Environment Variables and ``.ini`` Files | |
| 285 | Settings" chapter. | |
| 286 | ||
| 287 | - Added a :ref:`logging_chapter` chapter to the narrative docs. | |
| 288 | ||
| 289 | - All tutorials now use - The ``route_url``, ``route_path``, | |
| 290 | ``resource_url``, ``static_url``, and ``current_route_url`` methods of the | |
| 291 | :class:`pyramid.request.Request` rather than the function variants imported | |
| 292 | from ``pyramid.url``. | |
| 293 | ||
| 294 | - The ZODB wiki tutorial now uses the ``pyramid_zodbconn`` package rather | |
| 295 | than the ``repoze.zodbconn`` package to provide ZODB integration. | |
| 296 | ||
| d8fc16 | 297 | - Added :ref:`what_makes_pyramid_unique` to the Introduction narrative |
| CM | 298 | chapter. |
| 299 | ||
| 300 | ||
| a8c81d | 301 | Dependency Changes |
| CM | 302 | ------------------ |
| 303 | ||
| 304 | - Pyramid now relies on PasteScript >= 1.7.4. This version contains a | |
| 305 | feature important for allowing flexible logging configuration. | |
| 306 | ||
| 1aeae3 | 307 | - Pyramid now requires Venusian 1.0a1 or better to support the ``onerror`` |
| CM | 308 | keyword argument to :meth:`pyramid.config.Configurator.scan`. |
| 061154 | 309 | |
| CM | 310 | - The ``zope.configuration`` package is no longer a dependency. |
