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