| commit | author | age | ||
| 41aeac | 1 | What's New in Pyramid 1.0 |
| a9688f | 2 | ========================= |
| CM | 3 | |
| 4 | This article explains the new features in Pyramid version 1.0 as compared to | |
| 5 | its predecessor, :mod:`repoze.bfg` 1.3. It also documents backwards | |
| 6 | incompatibilities between the two versions and deprecations added to Pyramid | |
| 7 | 1.0, 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.0 are: | |
| 14 | ||
| 15 | - New name and branding association with the Pylons Project. | |
| 16 | ||
| c88d44 | 17 | - BFG conversion script |
| CM | 18 | |
| 758464 | 19 | - Scaffold improvements |
| a9688f | 20 | |
| CM | 21 | - Terminology changes |
| 22 | ||
| 23 | - Better platform compatibility and support | |
| 24 | ||
| 25 | - Direct built-in support for the Mako templating language. | |
| 26 | ||
| 27 | - Built-in support for sessions. | |
| 28 | ||
| 29 | - Updated URL dispatch features | |
| 30 | ||
| 31 | - Better imperative extensibility | |
| 32 | ||
| 33 | - ZCML externalized | |
| 34 | ||
| 35 | - Better support for global template variables during rendering | |
| 36 | ||
| 37 | - View mappers | |
| 38 | ||
| 39 | - Testing system improvements | |
| 40 | ||
| 41 | - Authentication support improvements | |
| 42 | ||
| 43 | - Documentation improvements | |
| 44 | ||
| 45 | New Name and Branding | |
| 46 | ~~~~~~~~~~~~~~~~~~~~~ | |
| 47 | ||
| c88d44 | 48 | The name of ``repoze.bfg`` has been changed to Pyramid. The project is also |
| CM | 49 | now a subproject of a new entity, "The Pylons Project". The Pylons Project |
| a9688f | 50 | is the project name for a collection of web-framework-related technologies. |
| CM | 51 | Pyramid was the first package in the Pylons Project. Other packages to the |
| 52 | collection have been added over time, such as support packages useful for | |
| 53 | Pylons 1 users as well as ex-Zope users. Pyramid is the successor to both | |
| 54 | :mod:`repoze.bfg` and :term:`Pylons` version 1. | |
| 55 | ||
| 56 | The Pyramid codebase is derived almost entirely from :mod:`repoze.bfg` | |
| 57 | with some changes made for the sake of Pylons 1 compatibility. | |
| 58 | ||
| 59 | Pyramid is technically backwards incompatible with :mod:`repoze.bfg`, as it | |
| 60 | has a new package name, so older imports from the ``repoze.bfg`` module will | |
| 61 | fail if you do nothing to your existing :mod:`repoze.bfg` application. | |
| 62 | However, you won't have to do much to use your existing BFG applications on | |
| 63 | Pyramid. There's automation which will change most of your import statements | |
| 64 | and ZCML declarations. See | |
| 39e88a | 65 | http://docs.pylonsproject.org/projects/pyramid/current/tutorials/bfg/index.html |
| CM | 66 | for upgrade instructions. |
| a9688f | 67 | |
| CM | 68 | Pylons 1 users will need to do more work to use Pyramid, as Pyramid shares no |
| 69 | "DNA" with Pylons. It is hoped that over time documentation and upgrade code | |
| 70 | will be developed to help Pylons 1 users transition to Pyramid more easily. | |
| 71 | ||
| 72 | :mod:`repoze.bfg` version 1.3 will be its last major release. Minor updates | |
| 73 | will be made for critical bug fixes. Pylons version 1 will continue to see | |
| 74 | maintenance releases, as well. | |
| 75 | ||
| 76 | The Repoze project will continue to exist. Repoze will be able to regain its | |
| 77 | original focus: bringing Zope technologies to WSGI. The popularity of | |
| 78 | :mod:`repoze.bfg` as its own web framework hindered this goal. | |
| 79 | ||
| 80 | We hope that people are attracted at first by the spirit of cooperation | |
| 81 | demonstrated by the Pylons Project and the merging of development | |
| 82 | communities. It takes humility to sacrifice a little sovereignty and work | |
| 83 | together. The opposite, forking or splintering of projects, is much more | |
| 84 | common in the open source world. We feel there is a limited amount of oxygen | |
| 85 | in the space of "top-tier" Python web frameworks and we don’t do the Python | |
| 86 | community a service by over-crowding. By merging the :mod:`repoze.bfg` and | |
| 87 | the philosophically-similar Pylons communities, both gain an expanded | |
| 88 | audience and a stronger chance of future success. | |
| 89 | ||
| c88d44 | 90 | BFG Conversion Script |
| CM | 91 | ~~~~~~~~~~~~~~~~~~~~~ |
| 92 | ||
| 93 | The ``bfg2pyramid`` conversion script performs a mostly automated conversion | |
| 94 | of an existing :mod:`repoze.bfg` application to Pyramid. The process is | |
| e75754 | 95 | described in "Converting a BFG Application to Pyramid". |
| c88d44 | 96 | |
| 758464 | 97 | Scaffold Improvements |
| a9688f | 98 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| CM | 99 | |
| 758464 | 100 | - The scaffolds now have much nicer CSS and graphics. |
| c88d44 | 101 | |
| 391402 | 102 | - The ``development.ini``, generated by all scaffolds, is now configured to |
| CM | 103 | use the WebError interactive exception debugger by default. |
| c88d44 | 104 | |
| 758464 | 105 | - All scaffolds have been normalized: each now uses the name ``main`` |
| c88d44 | 106 | to represent the function that returns a WSGI application, and each now has |
| CM | 107 | roughly the same shape of development.ini style. |
| a9688f | 108 | |
| 758464 | 109 | - All preexisting scaffolds now use "imperative" configuration |
| c88d44 | 110 | (``starter``, ``routesalchemy``, ``alchemy``, ``zodb``) instead of ZCML |
| CM | 111 | configuration. |
| a9688f | 112 | |
| 8092b6 | 113 | - The ``pyramid_zodb``, ``routesalchemy`` and ``pyramid_alchemy`` |
| 758464 | 114 | scaffolds now use a default "commit veto" hook when configuring the |
| a9688f | 115 | ``repoze.tm2`` transaction manager in ``development.ini``. This prevents a |
| CM | 116 | transaction from being committed when the response status code is within |
| 2033ee | 117 | the 400 or 500 ranges. |
| SP | 118 | |
| 119 | .. seealso:: | |
| 120 | ||
| 121 | See also http://docs.repoze.org/tm2/#using-a-commit-veto. | |
| a9688f | 122 | |
| CM | 123 | Terminology Changes |
| 124 | ~~~~~~~~~~~~~~~~~~~ | |
| 125 | ||
| 126 | - The Pyramid concept previously known as "model" is now known as "resource". | |
| c88d44 | 127 | As a result, the following API renames have been made. Backwards |
| CM | 128 | compatibility shims for the old names have been left in place in all cases:: |
| a9688f | 129 | |
| CM | 130 | pyramid.url.model_url -> |
| 131 | pyramid.url.resource_url | |
| 132 | ||
| 133 | pyramid.traversal.find_model -> | |
| 134 | pyramid.url.find_resource | |
| 135 | ||
| 136 | pyramid.traversal.model_path -> | |
| 137 | pyramid.traversal.resource_path | |
| 138 | ||
| 139 | pyramid.traversal.model_path_tuple -> | |
| 140 | pyramid.traversal.resource_path_tuple | |
| 141 | ||
| 142 | pyramid.traversal.ModelGraphTraverser -> | |
| 143 | pyramid.traversal.ResourceTreeTraverser | |
| 144 | ||
| 145 | pyramid.config.Configurator.testing_models -> | |
| 146 | pyramid.config.Configurator.testing_resources | |
| 147 | ||
| 148 | pyramid.testing.registerModels -> | |
| 149 | pyramid.testing.registerResources | |
| 150 | ||
| 151 | pyramid.testing.DummyModel -> | |
| 152 | pyramid.testing.DummyResource | |
| 153 | ||
| c88d44 | 154 | - All documentation which previously referred to "model" now refers to |
| CM | 155 | "resource". |
| a9688f | 156 | |
| 758464 | 157 | - The ``starter`` scaffold now has a ``resources.py`` module instead |
| c88d44 | 158 | of a ``models.py`` module. |
| a9688f | 159 | |
| c88d44 | 160 | - Positional argument names of various APIs have been changed from |
| CM | 161 | ``model`` to ``resource``. |
| a9688f | 162 | |
| CM | 163 | - The Pyramid concept previously known as "resource" is now known as "asset". |
| c88d44 | 164 | As a result, the following API changes were made. Backwards compatibility |
| CM | 165 | shims have been left in place as necessary:: |
| a9688f | 166 | |
| CM | 167 | pyramid.config.Configurator.absolute_resource_spec -> |
| 168 | pyramid.config.Configurator.absolute_asset_spec | |
| 169 | ||
| 170 | pyramid.config.Configurator.override_resource -> | |
| 171 | pyramid.config.Configurator.override_asset | |
| 172 | ||
| 173 | ||
| c88d44 | 174 | - The (non-API) module previously known as ``pyramid.resource`` is now |
| CM | 175 | known as ``pyramid.asset``. |
| a9688f | 176 | |
| c88d44 | 177 | - All docs that previously referred to "resource specification" now refer |
| CM | 178 | to "asset specification". |
| 179 | ||
| 180 | - The setting previously known as ``BFG_RELOAD_RESOURCES`` (envvar) or | |
| 181 | ``reload_resources`` (config file) is now known, respectively, as | |
| 182 | ``PYRAMID_RELOAD_ASSETS`` and ``reload_assets``. | |
| 758464 | 183 | |
| a9688f | 184 | Better Platform Compatibility and Support |
| CM | 185 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 186 | ||
| c88d44 | 187 | We've made Pyramid's test suite pass on both Jython and PyPy. However, |
| CM | 188 | Chameleon doesn't work on either, so you'll need to use Mako or Jinja2 |
| 189 | templates on these platforms. | |
| a9688f | 190 | |
| CM | 191 | Sessions |
| 192 | ~~~~~~~~ | |
| 193 | ||
| c88d44 | 194 | Pyramid now has built-in sessioning support, documented in |
| CM | 195 | :ref:`sessions_chapter`. The sessioning implementation is pluggable. It |
| 196 | also provides flash messaging and cross-site-scripting prevention features. | |
| a9688f | 197 | |
| c88d44 | 198 | Using ``request.session`` now returns a (dictionary-like) session object if |
| CM | 199 | a :term:`session factory` has been configured. |
| a9688f | 200 | |
| c88d44 | 201 | A new argument to the Configurator constructor exists: ``session_factory`` |
| CM | 202 | and a new method on the configurator exists: |
| 203 | :meth:`pyramid.config.Configurator.set_session_factory`. | |
| a9688f | 204 | |
| CM | 205 | Mako |
| 206 | ~~~~ | |
| 207 | ||
| c88d44 | 208 | In addition to Chameleon templating, Pyramid now also provides built-in |
| 70784a | 209 | support for :term:`Mako` templating. See |
| MM | 210 | :ref:`available_template_system_bindings` for more information. |
| a9688f | 211 | |
| CM | 212 | URL Dispatch |
| 213 | ~~~~~~~~~~~~ | |
| 214 | ||
| 215 | - URL Dispatch now allows for replacement markers to be located anywhere | |
| 216 | in the pattern, instead of immediately following a ``/``. | |
| 217 | ||
| 218 | - URL Dispatch now uses the form ``{marker}`` to denote a replace marker in | |
| 219 | the route pattern instead of ``:marker``. The old colon-style marker syntax | |
| 220 | is still accepted for backwards compatibility. The new format allows a | |
| 221 | regular expression for that marker location to be used instead of the | |
| 222 | default ``[^/]+``, for example ``{marker:\d+}`` is now valid to require the | |
| 223 | marker to be digits. | |
| 224 | ||
| c88d44 | 225 | - Addded a new API :func:`pyramid.url.current_route_url`, which computes a |
| CM | 226 | URL based on the "current" route (if any) and its matchdict values. |
| a9688f | 227 | |
| c88d44 | 228 | - Added a ``paster proute`` command which displays a summary of the routing |
| CM | 229 | table. See the narrative documentation section entitled |
| 230 | :ref:`displaying_application_routes`. | |
| a9688f | 231 | |
| c88d44 | 232 | - Added ``debug_routematch`` configuration setting (settable in your ``.ini`` |
| CM | 233 | file) that logs matched routes including the matchdict and predicates. |
| a9688f | 234 | |
| c88d44 | 235 | - Add a :func:`pyramid.url.route_path` API, allowing folks to generate |
| CM | 236 | relative URLs. Calling ``route_path`` is the same as calling |
| 237 | :func:`pyramid.url.route_url` with the argument ``_app_url`` equal to the | |
| 238 | empty string. | |
| a9688f | 239 | |
| c88d44 | 240 | - Add a :meth:`pyramid.request.Request.route_path` API. This is a |
| CM | 241 | convenience method of the request which calls |
| 242 | :func:`pyramid.url.route_url`. | |
| a9688f | 243 | |
| CM | 244 | - Added class vars ``matchdict`` and ``matched_route`` to |
| c88d44 | 245 | :class:`pyramid.request.Request`. Each is set to ``None`` when a route |
| CM | 246 | isn't matched during a request. |
| a9688f | 247 | |
| CM | 248 | ZCML Externalized |
| 249 | ~~~~~~~~~~~~~~~~~ | |
| 250 | ||
| 251 | - The ``load_zcml`` method of a Configurator has been removed from the | |
| c88d44 | 252 | Pyramid core. Loading ZCML is now a feature of the :term:`pyramid_zcml` |
| a9688f | 253 | package, which can be downloaded from PyPI. Documentation for the package |
| CM | 254 | should be available via |
| 8087fb | 255 | http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest/, which describes how to |
| c88d44 | 256 | add a configuration statement to your ``main`` block to reobtain this |
| a9688f | 257 | method. You will also need to add an ``install_requires`` dependency upon |
| c88d44 | 258 | the ``pyramid_zcml`` distribution to your ``setup.py`` file. |
| a9688f | 259 | |
| CM | 260 | - The "Declarative Configuration" narrative chapter has been removed (it was |
| 261 | moved to the ``pyramid_zcml`` package). | |
| 262 | ||
| 263 | - Most references to ZCML in narrative chapters have been removed or | |
| 264 | redirected to ``pyramid_zcml`` locations. | |
| 265 | ||
| 758464 | 266 | - The ``starter_zcml`` paster scaffold has been moved to the ``pyramid_zcml`` |
| a9688f | 267 | package. |
| CM | 268 | |
| 269 | Imperative Two-Phase Configuration | |
| 270 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 271 | ||
| c88d44 | 272 | To support application extensibility, the :app:`Pyramid` |
| CM | 273 | :term:`Configurator`, by default, now detects configuration conflicts and |
| 274 | allows you to include configuration imperatively from other packages or | |
| 275 | modules. It also, by default, performs configuration in two separate phases. | |
| 276 | This allows you to ignore relative configuration statement ordering in some | |
| 277 | circumstances. See :ref:`advconfig_narr` for more information. | |
| a9688f | 278 | |
| c88d44 | 279 | The :meth:`pyramid.config.Configurator.add_directive` allows framework |
| CM | 280 | extenders to add methods to the configurator, which allows extenders to avoid |
| 281 | subclassing a Configurator just to add methods. See :ref:`add_directive` for | |
| 282 | more info. | |
| a9688f | 283 | |
| c88d44 | 284 | Surrounding application configuration with ``config.begin()`` and |
| 758464 | 285 | ``config.end()`` is no longer necessary. All scaffolds have been |
| c88d44 | 286 | changed to no longer call these functions. |
| a9688f | 287 | |
| CM | 288 | Better Support for Global Template Variables During Rendering |
| 289 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 290 | ||
| c88d44 | 291 | A new event type named :class:`pyramid.interfaces.IBeforeRender` is now sent |
| CM | 292 | as an event before a renderer is invoked. Applications may now subscribe to |
| 293 | the ``IBeforeRender`` event type in order to introspect the and modify the | |
| 294 | set of renderer globals before they are passed to a renderer. The event | |
| 295 | object iself has a dictionary-like interface that can be used for this | |
| 296 | purpose. For example:: | |
| a9688f | 297 | |
| CM | 298 | from repoze.events import subscriber |
| 299 | from pyramid.interfaces import IRendererGlobalsEvent | |
| 300 | ||
| 301 | @subscriber(IRendererGlobalsEvent) | |
| 302 | def add_global(event): | |
| 303 | event['mykey'] = 'foo' | |
| 304 | ||
| 305 | View Mappers | |
| 306 | ~~~~~~~~~~~~ | |
| 307 | ||
| c88d44 | 308 | A "view mapper" subsystem has been extracted, which allows framework |
| CM | 309 | extenders to control how view callables are constructed and called. This |
| 310 | feature is not useful for "civilians", only for extension writers. See | |
| 311 | :ref:`using_a_view_mapper` for more information. | |
| a9688f | 312 | |
| CM | 313 | Testing Support Improvements |
| 314 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 315 | ||
| 6482f7 | 316 | The :func:`pyramid.testing.setUp` and :func:`pyramid.testing.tearDown` APIs |
| c88d44 | 317 | have been undeprecated. They are now the canonical setup and teardown APIs |
| CM | 318 | for test configuration, replacing "direct" creation of a Configurator. This |
| 319 | is a change designed to provide a facade that will protect against any future | |
| 320 | Configurator deprecations. | |
| a9688f | 321 | |
| CM | 322 | Authentication Support Improvements |
| 323 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 324 | ||
| c88d44 | 325 | - The :class:`pyramid.interfaces.IAuthenticationPolicy` interface now |
| CM | 326 | specifies an ``unauthenticated_userid`` method. This method supports an |
| 327 | important optimization required by people who are using persistent storages | |
| 328 | which do not support object caching and whom want to create a "user object" | |
| 329 | as a request attribute. | |
| a9688f | 330 | |
| c88d44 | 331 | - A new API has been added to the :mod:`pyramid.security` module named |
| a9688f | 332 | ``unauthenticated_userid``. This API function calls the |
| CM | 333 | ``unauthenticated_userid`` method of the effective security policy. |
| 334 | ||
| c88d44 | 335 | - The class :class:`pyramid.authentication.AuthTktCookieHelper` is now an |
| CM | 336 | API. This class can be used by third-party authentication policy |
| 337 | developers to help in the mechanics of authentication cookie-setting. | |
| a9688f | 338 | |
| c88d44 | 339 | - The :class:`pyramid.authentication.AuthTktAuthenticationPolicy` now accepts |
| CM | 340 | a ``tokens`` parameter via :func:`pyramid.security.remember`. The value |
| 341 | must be a sequence of strings. Tokens are placed into the auth_tkt | |
| 342 | "tokens" field and returned in the auth_tkt cookie. | |
| a9688f | 343 | |
| c88d44 | 344 | - Added a ``wild_domain`` argument to |
| CM | 345 | :class:`pyramid.authentication.AuthTktAuthenticationPolicy`, which defaults |
| ef2ce5 | 346 | to ``True``. If it is set to ``False``, the feature of the policy which |
| CM | 347 | sets a cookie with a wilcard domain will be turned off. |
| 348 | ||
| a9688f | 349 | Documentation Improvements |
| CM | 350 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 351 | ||
| 352 | - Casey Duncan, a good friend, and an excellent technical writer has given us | |
| 353 | the gift of professionally editing the entire Pyramid documentation set. | |
| 354 | Any faults in the documentation are the development team's, and all | |
| 355 | improvements are his. | |
| 356 | ||
| 357 | - The "Resource Location and View Lookup" chapter has been replaced with a | |
| 358 | variant of Rob Miller's "Much Ado About Traversal" (originally published at | |
| 359 | http://blog.nonsequitarian.org/2010/much-ado-about-traversal/). | |
| 360 | ||
| 361 | - Many users have contributed documentation fixes and improvements including | |
| 362 | Ben Bangert, Blaise Laflamme, Rob Miller, Mike Orr, Carlos de la Guardia, | |
| 363 | Paul Everitt, Tres Seaver, John Shipman, Marius Gedminas, Chris Rossi, | |
| 364 | Joachim Krebs, Xavier Spriet, Reed O'Brien, William Chambers, Charlie | |
| 365 | Choiniere, and Jamaludin Ahmad. | |
| 366 | ||
| 367 | Minor Feature Additions | |
| 368 | ----------------------- | |
| 369 | ||
| c88d44 | 370 | - The ``settings`` dictionary passed to the Configurator is now available as |
| CM | 371 | ``config.registry.settings`` in configuration code and |
| 372 | ``request.registry.settings`` in view code). | |
| a9688f | 373 | |
| c88d44 | 374 | - :meth:`pyramid.config.Configurator.add_view` now accepts a ``decorator`` |
| CM | 375 | keyword argument, a callable which will decorate the view callable before |
| 376 | it is added to the registry. | |
| a9688f | 377 | |
| CM | 378 | - Allow static renderer provided during view registration to be overridden at |
| 379 | request time via a request attribute named ``override_renderer``, which | |
| 380 | should be the name of a previously registered renderer. Useful to provide | |
| 381 | "omnipresent" RPC using existing rendered views. | |
| 382 | ||
| 383 | - If a resource implements a ``__resource_url__`` method, it will be called | |
| c88d44 | 384 | as the result of invoking the :func:`pyramid.url.resource_url` function to |
| CM | 385 | generate a URL, overriding the default logic. See |
| 386 | :ref:`generating_the_url_of_a_resource` for more information. | |
| a9688f | 387 | |
| CM | 388 | - The name ``registry`` is now available in a ``pshell`` environment by |
| 389 | default. It is the application registry object. | |
| 390 | ||
| c88d44 | 391 | - Added support for json on Google App Engine by catching |
| CM | 392 | :exc:`NotImplementedError` and importing ``simplejson`` from |
| 393 | ``django.utils``. | |
| a9688f | 394 | |
| c88d44 | 395 | - Added the :mod:`pyramid.httpexceptions` module, which is a facade for the |
| a9688f | 396 | ``webob.exc`` module. |
| CM | 397 | |
| c88d44 | 398 | - New class: :class:`pyramid.response.Response`. This is a pure facade for |
| a9688f | 399 | ``webob.Response`` (old code need not change to use this facade, it's |
| CM | 400 | existence is mostly for vanity and documentation-generation purposes). |
| 401 | ||
| 402 | - The request now has a new attribute: ``tmpl_context`` for benefit of | |
| 403 | Pylons users. | |
| 404 | ||
| c88d44 | 405 | - New API methods for :class:`pyramid.request.Request`: ``model_url``, |
| a9688f | 406 | ``route_url``, and ``static_url``. These are simple passthroughs for their |
| c88d44 | 407 | respective functions in :mod:`pyramid.url`. |
| a9688f | 408 | |
| CM | 409 | Backwards Incompatibilities |
| 410 | --------------------------- | |
| 411 | ||
| c88d44 | 412 | - When a :class:`pyramid.exceptions.Forbidden` error is raised, its status |
| CM | 413 | code now ``403 Forbidden``. It was previously ``401 Unauthorized``, for |
| 414 | backwards compatibility purposes with :mod:`repoze.bfg`. This change will | |
| 415 | cause problems for users of Pyramid with :mod:`repoze.who`, which | |
| 416 | intercepts ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to | |
| 417 | pass through. Those deployments will need to configure :mod:`repoze.who` | |
| d3a028 | 418 | to also react to ``403 Forbidden``. To do so, use a repoze.who |
| CM | 419 | ``challenge_decider`` that looks like this:: |
| 420 | ||
| 421 | import zope.interface | |
| 422 | from repoze.who.interfaces import IChallengeDecider | |
| 423 | ||
| 424 | def challenge_decider(environ, status, headers): | |
| 425 | return status.startswith('403') or status.startswith('401') | |
| 426 | zope.interface.directlyProvides(challenge_decider, IChallengeDecider) | |
| a9688f | 427 | |
| c88d44 | 428 | - The ``paster bfgshell`` command is now known as ``paster pshell``. |
| a9688f | 429 | |
| c88d44 | 430 | - There is no longer an ``IDebugLogger`` object registered as a named utility |
| a9688f | 431 | with the name ``repoze.bfg.debug``. |
| CM | 432 | |
| c88d44 | 433 | - These deprecated APIs have been removed: |
| CM | 434 | ``pyramid.testing.registerViewPermission``, |
| 435 | ``pyramid.testing.registerRoutesMapper``, ``pyramid.request.get_request``, | |
| 436 | ``pyramid.security.Unauthorized``, | |
| 437 | ``pyramid.view.view_execution_permitted``, ``pyramid.view.NotFound`` | |
| a9688f | 438 | |
| CM | 439 | - The Venusian "category" for all built-in Venusian decorators |
| 440 | (e.g. ``subscriber`` and ``view_config``/``bfg_view``) is now | |
| 441 | ``pyramid`` instead of ``bfg``. | |
| 442 | ||
| c88d44 | 443 | - The ``pyramid.renderers.rendered_response`` function removed; use |
| CM | 444 | :func:`pyramid.renderers.render_to_response` instead. |
| a9688f | 445 | |
| CM | 446 | - Renderer factories now accept a *renderer info object* rather than an |
| 447 | absolute resource specification or an absolute path. The object has the | |
| 448 | following attributes: ``name`` (the ``renderer=`` value), ``package`` (the | |
| 449 | 'current package' when the renderer configuration statement was found), | |
| 450 | ``type``: the renderer type, ``registry``: the current registry, and | |
| c88d44 | 451 | ``settings``: the deployment settings dictionary. Third-party |
| CM | 452 | ``repoze.bfg`` renderer implementations that must be ported to Pyramid will |
| 453 | need to account for this. This change was made primarily to support more | |
| 454 | flexible Mako template rendering. | |
| a9688f | 455 | |
| CM | 456 | - The presence of the key ``repoze.bfg.message`` in the WSGI environment when |
| 457 | an exception occurs is now deprecated. Instead, code which relies on this | |
| 458 | environ value should use the ``exception`` attribute of the request | |
| 459 | (e.g. ``request.exception[0]``) to retrieve the message. | |
| 460 | ||
| 461 | - The values ``bfg_localizer`` and ``bfg_locale_name`` kept on the request | |
| 462 | during internationalization for caching purposes were never APIs. These | |
| 463 | however have changed to ``localizer`` and ``locale_name``, respectively. | |
| 464 | ||
| 465 | - The default ``cookie_name`` value of the | |
| c88d44 | 466 | :class:`pyramid.authentication.AuthTktAuthenticationPolicy` now defaults to |
| CM | 467 | ``auth_tkt`` (it used to default to ``repoze.bfg.auth_tkt``). |
| a9688f | 468 | |
| c88d44 | 469 | - The :func:`pyramid.testing.zcml_configure` API has been removed. It had |
| CM | 470 | been advertised as removed since :mod:`repoze.bfg` 1.2a1, but hadn't |
| 471 | actually been. | |
| a9688f | 472 | |
| CM | 473 | - All environment variables which used to be prefixed with ``BFG_`` are now |
| 474 | prefixed with ``PYRAMID_`` (e.g. ``BFG_DEBUG_NOTFOUND`` is now | |
| 475 | ``PYRAMID_DEBUG_NOTFOUND``) | |
| 476 | ||
| c88d44 | 477 | - Since the :class:`pyramid.interfaces.IAuthenticationPolicy` interface now |
| a9688f | 478 | specifies that a policy implementation must implement an |
| CM | 479 | ``unauthenticated_userid`` method, all third-party custom authentication |
| 480 | policies now must implement this method. It, however, will only be called | |
| c88d44 | 481 | when the global function named |
| CM | 482 | :func:`pyramid.security.unauthenticated_userid` is invoked, so if you're |
| 483 | not invoking that, you will not notice any issues. | |
| a9688f | 484 | |
| CM | 485 | - The ``configure_zcml`` setting within the deployment settings (within |
| 486 | ``**settings`` passed to a Pyramid ``main`` function) has ceased to have any | |
| 487 | meaning. | |
| 488 | ||
| c88d44 | 489 | - The ``make_app`` function has been removed from the :mod:`pyramid.router` |
| CM | 490 | module. It continues life within the ``pyramid_zcml`` package. This |
| 491 | leaves the :mod:`pyramid.router` module without any API functions. | |
| 492 | ||
| a9688f | 493 | Deprecations and Behavior Differences |
| CM | 494 | ------------------------------------- |
| 495 | ||
| c88d44 | 496 | - :class:`pyramid.configuration.Configurator` is now deprecated. Use |
| CM | 497 | :class:`pyramid.config.Configurator`, passing its constructor |
| 498 | ``autocommit=True`` instead. The | |
| 499 | :class:`pyramid.configuration.Configurator` alias will live for a long | |
| 500 | time, as every application uses it, but its import now issues a deprecation | |
| 501 | warning. The :class:`pyramid.config.Configurator` class has the same API | |
| 502 | as the :class:`pyramid.configuration.Configurator` class, which it means to | |
| 503 | replace, except by default it is a *non-autocommitting* configurator. The | |
| 504 | now-deprecated ``pyramid.configuration.Configurator`` will autocommit every | |
| 505 | time a configuration method is called. The :mod:`pyramid.configuration` | |
| 506 | module remains, but it is deprecated. Use :mod:`pyramid.config` instead. | |
| 507 | ||
| 508 | - The :func:`pyramid.settings.get_settings` API is now deprecated. Use | |
| a9688f | 509 | ``pyramid.threadlocals.get_current_registry().settings`` instead or use the |
| CM | 510 | ``settings`` attribute of the registry available from the request |
| 511 | (``request.registry.settings``). | |
| 512 | ||
| c88d44 | 513 | - The decorator previously known as ``pyramid.view.bfg_view`` is now known |
| 758464 | 514 | most formally as :class:`pyramid.view.view_config` in docs and scaffolds. |
| a9688f | 515 | |
| CM | 516 | - Obtaining the ``settings`` object via |
| 517 | ``registry.{get|query}Utility(ISettings)`` is now deprecated. Instead, | |
| 518 | obtain the ``settings`` object via the ``registry.settings`` attribute. A | |
| 519 | backwards compatibility shim was added to the registry object to register | |
| 520 | the settings object as an ISettings utility when ``setattr(registry, | |
| 521 | 'settings', foo)`` is called, but it will be removed in a later release. | |
| 522 | ||
| c88d44 | 523 | - Obtaining the ``settings`` object via :func:`pyramid.settings.get_settings` |
| CM | 524 | is now deprecated. Obtain it instead as the ``settings`` attribute of the |
| 525 | registry now (obtain the registry via | |
| 526 | :func:`pyramid.threadlocal.get_registry` or as ``request.registry``). | |
| a9688f | 527 | |
| CM | 528 | Dependency Changes |
| 529 | ------------------ | |
| 530 | ||
| 531 | - Depend on Venusian >= 0.5 (for scanning conflict exception decoration). | |
| 532 | ||
| 533 | Documentation Enhancements | |
| 534 | -------------------------- | |
| 535 | ||
| c88d44 | 536 | - Added a :mod:`pyramid.httpexceptions` API documentation chapter. |
| a9688f | 537 | |
| c88d44 | 538 | - Added a :mod:`pyramid.session` API documentation chapter. |
| a9688f | 539 | |
| c88d44 | 540 | - Added an API chapter for the :mod:`pyramid.response` module. |
| a9688f | 541 | |
| c88d44 | 542 | - Added a :ref:`sessions_chapter` narrative documentation chapter. |
| a9688f | 543 | |
| CM | 544 | - All documentation which previously referred to ``webob.Response`` now uses |
| c88d44 | 545 | :class:`pyramid.response.Response` instead. |
| a9688f | 546 | |
| CM | 547 | - The documentation has been overhauled to use imperative configuration, |
| c88d44 | 548 | moving declarative configuration (ZCML) explanations to an external |
| CM | 549 | package, :term:`pyramid_zcml`. |
| a9688f | 550 | |
| CM | 551 | - Removed ``zodbsessions`` tutorial chapter. It's still useful, but we now |
| 552 | have a SessionFactory abstraction which competes with it, and maintaining | |
| 553 | documentation on both ways to do it is a distraction. | |
| 554 | ||
| 555 | - Added an example of ``WebTest`` functional testing to the testing narrative | |
| c88d44 | 556 | chapter at :ref:`functional_tests`. |
| a9688f | 557 | |
| c88d44 | 558 | - Extended the Resources chapter with examples of calls to resource-related |
| CM | 559 | APIs. |
| a9688f | 560 | |
| CM | 561 | - Add "Pyramid Provides More Than One Way to Do It" to Design Defense |
| 562 | documentation. | |
| 563 | ||
| 564 | - The (weak) "Converting a CMF Application to Pyramid" tutorial has been | |
| 565 | removed from the tutorials section. It was moved to the | |
| a2b9b6 | 566 | ``pyramid_tutorials`` Github repository at |
| CM | 567 | http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/. |
| 568 | ||
| 569 | - Moved "Using ZODB With ZEO" and "Using repoze.catalog Within Pyramid" | |
| 570 | tutorials out of core documentation and into the Pyramid Tutorials site | |
| 571 | (http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/). | |
| 572 | ||
| 573 | - Removed API documentation for deprecated ``pyramid.testing`` APIs named | |
| 574 | ``registerDummySecurityPolicy``, ``registerResources``, ``registerModels``, | |
| 575 | ``registerEventListener``, ``registerTemplateRenderer``, | |
| 576 | ``registerDummyRenderer``, ``registerView``, ``registerUtility``, | |
| 577 | ``registerAdapter``, ``registerSubscriber``, ``registerRoute``, and | |
| 578 | ``registerSettings``. | |
| a9688f | 579 | |
