Skip to content

Latest commit

 

History

History
579 lines (427 loc) · 24.3 KB

whatsnew-1.0.rst

File metadata and controls

579 lines (427 loc) · 24.3 KB

What's New In Pyramid 1.0

This article explains the new features in Pyramid version 1.0 as compared to its predecessor, :mod:`repoze.bfg` 1.3. It also documents backwards incompatibilities between the two versions and deprecations added to Pyramid 1.0, as well as software dependency changes and notable documentation additions.

Major Feature Additions

The major feature additions in Pyramid 1.0 are:

  • New name and branding association with the Pylons Project.
  • BFG conversion script
  • Scaffold improvements
  • Terminology changes
  • Better platform compatibility and support
  • Direct built-in support for the Mako templating language.
  • Built-in support for sessions.
  • Updated URL dispatch features
  • Better imperative extensibility
  • ZCML externalized
  • Better support for global template variables during rendering
  • View mappers
  • Testing system improvements
  • Authentication support improvements
  • Documentation improvements

New Name and Branding

The name of repoze.bfg has been changed to Pyramid. The project is also now a subproject of a new entity, "The Pylons Project". The Pylons Project is the project name for a collection of web-framework-related technologies. Pyramid was the first package in the Pylons Project. Other packages to the collection have been added over time, such as support packages useful for Pylons 1 users as well as ex-Zope users. Pyramid is the successor to both :mod:`repoze.bfg` and :term:`Pylons` version 1.

The Pyramid codebase is derived almost entirely from :mod:`repoze.bfg` with some changes made for the sake of Pylons 1 compatibility.

Pyramid is technically backwards incompatible with :mod:`repoze.bfg`, as it has a new package name, so older imports from the repoze.bfg module will fail if you do nothing to your existing :mod:`repoze.bfg` application. However, you won't have to do much to use your existing BFG applications on Pyramid. There's automation which will change most of your import statements and ZCML declarations. See http://docs.pylonsproject.org/projects/pyramid/current/tutorials/bfg/index.html for upgrade instructions.

Pylons 1 users will need to do more work to use Pyramid, as Pyramid shares no "DNA" with Pylons. It is hoped that over time documentation and upgrade code will be developed to help Pylons 1 users transition to Pyramid more easily.

:mod:`repoze.bfg` version 1.3 will be its last major release. Minor updates will be made for critical bug fixes. Pylons version 1 will continue to see maintenance releases, as well.

The Repoze project will continue to exist. Repoze will be able to regain its original focus: bringing Zope technologies to WSGI. The popularity of :mod:`repoze.bfg` as its own web framework hindered this goal.

We hope that people are attracted at first by the spirit of cooperation demonstrated by the Pylons Project and the merging of development communities. It takes humility to sacrifice a little sovereignty and work together. The opposite, forking or splintering of projects, is much more common in the open source world. We feel there is a limited amount of oxygen in the space of "top-tier" Python web frameworks and we don’t do the Python community a service by over-crowding. By merging the :mod:`repoze.bfg` and the philosophically-similar Pylons communities, both gain an expanded audience and a stronger chance of future success.

BFG Conversion Script

The bfg2pyramid conversion script performs a mostly automated conversion of an existing :mod:`repoze.bfg` application to Pyramid. The process is described in "Converting a BFG Application to Pyramid".

Scaffold Improvements

  • The scaffolds now have much nicer CSS and graphics.

  • The development.ini, generated by all scaffolds, is now configured to use the WebError interactive exception debugger by default.

  • All scaffolds have been normalized: each now uses the name main to represent the function that returns a WSGI application, and each now has roughly the same shape of development.ini style.

  • All preexisting scaffolds now use "imperative" configuration (starter, routesalchemy, alchemy, zodb) instead of ZCML configuration.

  • The pyramid_zodb, routesalchemy and pyramid_alchemy scaffolds now use a default "commit veto" hook when configuring the repoze.tm2 transaction manager in development.ini. This prevents a transaction from being committed when the response status code is within the 400 or 500 ranges.

    .. seealso::

   See also http://docs.repoze.org/tm2/#using-a-commit-veto.

Terminology Changes

  • The Pyramid concept previously known as "model" is now known as "resource". As a result, the following API renames have been made. Backwards compatibility shims for the old names have been left in place in all cases:

    pyramid.url.model_url ->
                  pyramid.url.resource_url

pyramid.traversal.find_model ->
                  pyramid.url.find_resource

pyramid.traversal.model_path ->
                  pyramid.traversal.resource_path

pyramid.traversal.model_path_tuple ->
                  pyramid.traversal.resource_path_tuple

pyramid.traversal.ModelGraphTraverser ->
                  pyramid.traversal.ResourceTreeTraverser

pyramid.config.Configurator.testing_models ->
                  pyramid.config.Configurator.testing_resources

pyramid.testing.registerModels ->
                  pyramid.testing.registerResources

pyramid.testing.DummyModel ->
                  pyramid.testing.DummyResource

  • All documentation which previously referred to "model" now refers to "resource".

  • The starter scaffold now has a resources.py module instead of a models.py module.

  • Positional argument names of various APIs have been changed from model to resource.

  • The Pyramid concept previously known as "resource" is now known as "asset". As a result, the following API changes were made. Backwards compatibility shims have been left in place as necessary:

    pyramid.config.Configurator.absolute_resource_spec ->
                  pyramid.config.Configurator.absolute_asset_spec

pyramid.config.Configurator.override_resource ->
                  pyramid.config.Configurator.override_asset

  • The (non-API) module previously known as pyramid.resource is now known as pyramid.asset.

  • All docs that previously referred to "resource specification" now refer to "asset specification".

  • The setting previously known as BFG_RELOAD_RESOURCES (envvar) or reload_resources (config file) is now known, respectively, as PYRAMID_RELOAD_ASSETS and reload_assets.

Better Platform Compatibility and Support

We've made Pyramid's test suite pass on both Jython and PyPy. However, Chameleon doesn't work on either, so you'll need to use Mako or Jinja2 templates on these platforms.

Sessions

Pyramid now has built-in sessioning support, documented in :ref:`sessions_chapter`. The sessioning implementation is pluggable. It also provides flash messaging and cross-site-scripting prevention features.

Using request.session now returns a (dictionary-like) session object if a :term:`session factory` has been configured.

A new argument to the Configurator constructor exists: session_factory and a new method on the configurator exists: :meth:`pyramid.config.Configurator.set_session_factory`.

Mako

In addition to Chameleon templating, Pyramid now also provides built-in support for :term:`Mako` templating. See :ref:`available_template_system_bindings` for more information.

URL Dispatch

  • URL Dispatch now allows for replacement markers to be located anywhere in the pattern, instead of immediately following a /.
  • URL Dispatch now uses the form {marker} to denote a replace marker in the route pattern instead of :marker. The old colon-style marker syntax is still accepted for backwards compatibility. The new format allows a regular expression for that marker location to be used instead of the default [^/]+, for example {marker:\d+} is now valid to require the marker to be digits.
  • Addded a new API :func:`pyramid.url.current_route_url`, which computes a URL based on the "current" route (if any) and its matchdict values.
  • Added a paster proute command which displays a summary of the routing table. See the narrative documentation section entitled :ref:`displaying_application_routes`.
  • Added debug_routematch configuration setting (settable in your .ini file) that logs matched routes including the matchdict and predicates.
  • Add a :func:`pyramid.url.route_path` API, allowing folks to generate relative URLs. Calling route_path is the same as calling :func:`pyramid.url.route_url` with the argument _app_url equal to the empty string.
  • Add a :meth:`pyramid.request.Request.route_path` API. This is a convenience method of the request which calls :func:`pyramid.url.route_url`.
  • Added class vars matchdict and matched_route to :class:`pyramid.request.Request`. Each is set to None when a route isn't matched during a request.

ZCML Externalized

  • The load_zcml method of a Configurator has been removed from the Pyramid core. Loading ZCML is now a feature of the :term:`pyramid_zcml` package, which can be downloaded from PyPI. Documentation for the package should be available via http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest/, which describes how to add a configuration statement to your main block to reobtain this method. You will also need to add an install_requires dependency upon the pyramid_zcml distribution to your setup.py file.
  • The "Declarative Configuration" narrative chapter has been removed (it was moved to the pyramid_zcml package).
  • Most references to ZCML in narrative chapters have been removed or redirected to pyramid_zcml locations.
  • The starter_zcml paster scaffold has been moved to the pyramid_zcml package.

Imperative Two-Phase Configuration

To support application extensibility, the :app:`Pyramid` :term:`Configurator`, by default, now detects configuration conflicts and allows you to include configuration imperatively from other packages or modules. It also, by default, performs configuration in two separate phases. This allows you to ignore relative configuration statement ordering in some circumstances. See :ref:`advconfig_narr` for more information.

The :meth:`pyramid.config.Configurator.add_directive` allows framework extenders to add methods to the configurator, which allows extenders to avoid subclassing a Configurator just to add methods. See :ref:`add_directive` for more info.

Surrounding application configuration with config.begin() and config.end() is no longer necessary. All scaffolds have been changed to no longer call these functions.

Better Support for Global Template Variables During Rendering

A new event type named :class:`pyramid.interfaces.IBeforeRender` is now sent as an event before a renderer is invoked. Applications may now subscribe to the IBeforeRender event type in order to introspect the and modify the set of renderer globals before they are passed to a renderer. The event object iself has a dictionary-like interface that can be used for this purpose. For example:

from repoze.events import subscriber
from pyramid.interfaces import IRendererGlobalsEvent

@subscriber(IRendererGlobalsEvent)
def add_global(event):
    event['mykey'] = 'foo'

View Mappers

A "view mapper" subsystem has been extracted, which allows framework extenders to control how view callables are constructed and called. This feature is not useful for "civilians", only for extension writers. See :ref:`using_a_view_mapper` for more information.

Testing Support Improvements

The :func:`pyramid.testing.setUp` and :func:`pyramid.testing.tearDown` APIs have been undeprecated. They are now the canonical setup and teardown APIs for test configuration, replacing "direct" creation of a Configurator. This is a change designed to provide a facade that will protect against any future Configurator deprecations.

Authentication Support Improvements

Documentation Improvements

  • Casey Duncan, a good friend, and an excellent technical writer has given us the gift of professionally editing the entire Pyramid documentation set. Any faults in the documentation are the development team's, and all improvements are his.
  • The "Resource Location and View Lookup" chapter has been replaced with a variant of Rob Miller's "Much Ado About Traversal" (originally published at http://blog.nonsequitarian.org/2010/much-ado-about-traversal/).
  • Many users have contributed documentation fixes and improvements including Ben Bangert, Blaise Laflamme, Rob Miller, Mike Orr, Carlos de la Guardia, Paul Everitt, Tres Seaver, John Shipman, Marius Gedminas, Chris Rossi, Joachim Krebs, Xavier Spriet, Reed O'Brien, William Chambers, Charlie Choiniere, and Jamaludin Ahmad.

Minor Feature Additions

  • The settings dictionary passed to the Configurator is now available as config.registry.settings in configuration code and request.registry.settings in view code).
  • :meth:`pyramid.config.Configurator.add_view` now accepts a decorator keyword argument, a callable which will decorate the view callable before it is added to the registry.
  • Allow static renderer provided during view registration to be overridden at request time via a request attribute named override_renderer, which should be the name of a previously registered renderer. Useful to provide "omnipresent" RPC using existing rendered views.
  • If a resource implements a __resource_url__ method, it will be called as the result of invoking the :func:`pyramid.url.resource_url` function to generate a URL, overriding the default logic. See :ref:`generating_the_url_of_a_resource` for more information.
  • The name registry is now available in a pshell environment by default. It is the application registry object.
  • Added support for json on Google App Engine by catching :exc:`NotImplementedError` and importing simplejson from django.utils.
  • Added the :mod:`pyramid.httpexceptions` module, which is a facade for the webob.exc module.
  • New class: :class:`pyramid.response.Response`. This is a pure facade for webob.Response (old code need not change to use this facade, it's existence is mostly for vanity and documentation-generation purposes).
  • The request now has a new attribute: tmpl_context for benefit of Pylons users.
  • New API methods for :class:`pyramid.request.Request`: model_url, route_url, and static_url. These are simple passthroughs for their respective functions in :mod:`pyramid.url`.

Backwards Incompatibilities

  • When a :class:`pyramid.exceptions.Forbidden` error is raised, its status code now 403 Forbidden. It was previously 401 Unauthorized, for backwards compatibility purposes with :mod:`repoze.bfg`. This change will cause problems for users of Pyramid with :mod:`repoze.who`, which intercepts 401 Unauthorized by default, but allows 403 Forbidden to pass through. Those deployments will need to configure :mod:`repoze.who` to also react to 403 Forbidden. To do so, use a repoze.who challenge_decider that looks like this:

    import zope.interface
from repoze.who.interfaces import IChallengeDecider

def challenge_decider(environ, status, headers):
    return status.startswith('403') or status.startswith('401')
zope.interface.directlyProvides(challenge_decider, IChallengeDecider)

  • The paster bfgshell command is now known as paster pshell.

  • There is no longer an IDebugLogger object registered as a named utility with the name repoze.bfg.debug.

  • These deprecated APIs have been removed: pyramid.testing.registerViewPermission, pyramid.testing.registerRoutesMapper, pyramid.request.get_request, pyramid.security.Unauthorized, pyramid.view.view_execution_permitted, pyramid.view.NotFound

  • The Venusian "category" for all built-in Venusian decorators (e.g. subscriber and view_config/bfg_view) is now pyramid instead of bfg.

  • The pyramid.renderers.rendered_response function removed; use :func:`pyramid.renderers.render_to_response` instead.

  • Renderer factories now accept a renderer info object rather than an absolute resource specification or an absolute path. The object has the following attributes: name (the renderer= value), package (the 'current package' when the renderer configuration statement was found), type: the renderer type, registry: the current registry, and settings: the deployment settings dictionary. Third-party repoze.bfg renderer implementations that must be ported to Pyramid will need to account for this. This change was made primarily to support more flexible Mako template rendering.

  • The presence of the key repoze.bfg.message in the WSGI environment when an exception occurs is now deprecated. Instead, code which relies on this environ value should use the exception attribute of the request (e.g. request.exception[0]) to retrieve the message.

  • The values bfg_localizer and bfg_locale_name kept on the request during internationalization for caching purposes were never APIs. These however have changed to localizer and locale_name, respectively.

  • The default cookie_name value of the :class:`pyramid.authentication.AuthTktAuthenticationPolicy` now defaults to auth_tkt (it used to default to repoze.bfg.auth_tkt).

  • The :func:`pyramid.testing.zcml_configure` API has been removed. It had been advertised as removed since :mod:`repoze.bfg` 1.2a1, but hadn't actually been.

  • All environment variables which used to be prefixed with BFG_ are now prefixed with PYRAMID_ (e.g. BFG_DEBUG_NOTFOUND is now PYRAMID_DEBUG_NOTFOUND)

  • Since the :class:`pyramid.interfaces.IAuthenticationPolicy` interface now specifies that a policy implementation must implement an unauthenticated_userid method, all third-party custom authentication policies now must implement this method. It, however, will only be called when the global function named :func:`pyramid.security.unauthenticated_userid` is invoked, so if you're not invoking that, you will not notice any issues.

  • The configure_zcml setting within the deployment settings (within **settings passed to a Pyramid main function) has ceased to have any meaning.

  • The make_app function has been removed from the :mod:`pyramid.router` module. It continues life within the pyramid_zcml package. This leaves the :mod:`pyramid.router` module without any API functions.

Deprecations and Behavior Differences

Dependency Changes

  • Depend on Venusian >= 0.5 (for scanning conflict exception decoration).

Documentation Enhancements

  • Added a :mod:`pyramid.httpexceptions` API documentation chapter.
  • Added a :mod:`pyramid.session` API documentation chapter.
  • Added an API chapter for the :mod:`pyramid.response` module.
  • Added a :ref:`sessions_chapter` narrative documentation chapter.
  • All documentation which previously referred to webob.Response now uses :class:`pyramid.response.Response` instead.
  • The documentation has been overhauled to use imperative configuration, moving declarative configuration (ZCML) explanations to an external package, :term:`pyramid_zcml`.
  • Removed zodbsessions tutorial chapter. It's still useful, but we now have a SessionFactory abstraction which competes with it, and maintaining documentation on both ways to do it is a distraction.
  • Added an example of WebTest functional testing to the testing narrative chapter at :ref:`functional_tests`.
  • Extended the Resources chapter with examples of calls to resource-related APIs.
  • Add "Pyramid Provides More Than One Way to Do It" to Design Defense documentation.
  • The (weak) "Converting a CMF Application to Pyramid" tutorial has been removed from the tutorials section. It was moved to the pyramid_tutorials Github repository at http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/.
  • Moved "Using ZODB With ZEO" and "Using repoze.catalog Within Pyramid" tutorials out of core documentation and into the Pyramid Tutorials site (http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/).
  • Removed API documentation for deprecated pyramid.testing APIs named registerDummySecurityPolicy, registerResources, registerModels, registerEventListener, registerTemplateRenderer, registerDummyRenderer, registerView, registerUtility, registerAdapter, registerSubscriber, registerRoute, and registerSettings.