Skip to content

Latest commit

 

History

History
331 lines (244 loc) · 13.2 KB

whatsnew-1.3.rst

File metadata and controls

331 lines (244 loc) · 13.2 KB
Raw

What's New In Pyramid 1.3

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

Major Feature Additions

The major feature additions in Pyramid 1.3 follow.

Python 3 Compatibility

Pyramid is now Python 3 compatible. Python 3.2 or better is required.

Warning

As of this writing (the release of Pyramid 1.3a1), if you attempt to install a Pyramid project that used alchemy scaffold via setup.py develop on Python 3.2, it may quit with an installation error while trying to install Pygments. If this happens, please rerun the setup.py develop command again and it will complete. We're just as clueless as you are as to why this happens at this point, but hopefully we'll figure it out before Pyramid 1.3 leaves the alpha/beta phase.

This feature required us to make some compromises.

Pyramid no longer runs on Python 2.5. This includes the most recent release of Jython and the Python 2.5 version of Google App Engine. We could not easily "straddle" Python 2 and 3 versions and support Python 2 versions older than Python 2.6. You will need Python 2.6 or better to run this version of Pyramid. If you need to use Python 2.5, you should use the most recent 1.2.X release of Pyramid.

Though many Pyramid add-ons have releases which are already Python 3 compatible (in particular pyramid_debugtoolbar, pyramid_jinja2, pyramid_exclog, and pyramid_tm), some are still known to work only under Python 2. Likewise, some scaffolding dependencies (particularly ZODB) do not yet work under Python 3. Please be patient as we gain full ecosystem support for Python 3. You can see more details about ongoing porting efforts at https://github.com/Pylons/pyramid/wiki/Python-3-Porting .

The libraries named Paste and PasteScript which have been dependencies of Pyramid since 1.0+ have not been ported to Python 3, and we were unwilling to port and maintain them ourselves. As a result, we've had to make some changes:

  • We've replaced the paster command with Pyramid-specific analogues.
  • We've made the default WSGI server the wsgiref server.

Previously (in Pyramid 1.0, 1.1 and 1.2), you created a Pyramid application using paster create, like so:

$ myvenv/bin/paster create -t pyramid_starter foo

You're now instead required to create an application using pcreate like so:

$ myvenv/bin/pcreate -s starter foo

Note that the names of available scaffolds have changed and the flags supported by pcreate are different than those that were supported by paster create.

Instead of running a Pyramid project created via a scaffold using paster serve, as was done in Pyramid <= 1.2.X, you now must use the pserve command:

$myvenv/bin/pserve development.ini

The ini configuration file format supported by Pyramid has not changed. As a result, Python 2-only users can install PasteScript manually and use paster serve instead if they like. However, using pserve will work under both Python 2 and Python 3. pcreate is required to be used for internal Pyramid scaffolding; externally distributed scaffolding may allow for both pcreate and/or paster create.

Analogues of paster pshell, paster pviews, paster request and paster ptweens also exist under the respective console script names pshell, pviews, prequest and ptweens.

We've replaced use of the Paste httpserver with the wsgiref server in the scaffolds, so once you create a project from a scaffold, its development.ini and production.ini will have the following line:

use = egg:pyramid#wsgiref

Instead of this (which was the default in older versions):

use = egg:Paste#http

Using wsgiref as the default WSGI server is purely a default to make it possible to use the same scaffolding under Python 2 and Python 3; people running Pyramid under Python 2 can still manually install Paste and use the Paste httpserver by replacing the former line with the latter. This is actually recommended if you rely on proxying from Apache or Nginx to a pserve -invoked application. The wsgiref server is not a production quality server. See :ref:`alternate_wsgi_server` for more information.

New releases in every older major Pyramid series (1.0.2, 1.1.3, 1.2.5) also have the egg:pyramid#wsgiref entry point, so scaffold-writers can depend on it being there even in older major Pyramid versions.

Warning

Previously, paste.httpserver "helped" by converting header values that weren't strings to strings. The wsgiref server, on the other hand implements the spec more fully. This specifically may affect you if you are modifying headers on your response. The following error might be an indicator of this problem: AssertionError: Header values must be strings, please check the type of the header being returned. A common case would be returning unicode headers instead of string headers.

A new :mod:`pyramid.compat` module was added which provides Python 2/3 straddling support for Pyramid add-ons and development environments.

Python 3 compatibility required dropping some package dependencies and support for older Python versions and platforms. See the "Backwards Incompatibilities" section below for more information.

Introspection

A configuration introspection system was added; see :ref:`using_introspection` and :ref:`introspection` for more information on using the introspection system as a developer.

The latest release of the pyramid debug toolbar (0.9.7+) provides an "Introspection" panel that exposes introspection information to a Pyramid application developer.

New APIs were added to support introspection :attr:`pyramid.registry.Introspectable`, :attr:`pyramid.registry.noop_introspector`, :attr:`pyramid.config.Configurator.introspector`, :attr:`pyramid.config.Configurator.introspectable`, :attr:`pyramid.registry.Registry.introspector`.

@view_defaults Decorator

If you use a class as a view, you can use the new :class:`pyramid.view.view_defaults` class decorator on the class to provide defaults to the view configuration information used by every @view_config decorator that decorates a method of that class.

For instance, if you've got a class that has methods that represent "REST actions", all which are mapped to the same route, but different request methods, instead of this:

from pyramid.view import view_config
from pyramid.response import Response

class RESTView(object):
    def __init__(self, request):
        self.request = request

    @view_config(route_name='rest', request_method='GET')
    def get(self):
        return Response('get')

    @view_config(route_name='rest', request_method='POST')
    def post(self):
        return Response('post')

    @view_config(route_name='rest', request_method='DELETE')
    def delete(self):
        return Response('delete')

You can do this:

from pyramid.view import view_defaults
from pyramid.view import view_config
from pyramid.response import Response

@view_defaults(route_name='rest')
class RESTView(object):
    def __init__(self, request):
        self.request = request

    @view_config(request_method='GET')
    def get(self):
        return Response('get')

    @view_config(request_method='POST')
    def post(self):
        return Response('post')

    @view_config(request_method='DELETE')
    def delete(self):
        return Response('delete')

This also works for imperative view configurations that involve a class.

See :ref:`view_defaults` for more information.

Minor Feature Additions

Backwards Incompatibilities

  • Pyramid no longer runs on Python 2.5 (which includes the most recent release of Jython and the Python 2.5 version of GAE as of this writing).
  • The paster command is no longer the documented way to create projects, start the server, or run debugging commands. To create projects from scaffolds, paster create is replaced by the pcreate console script. To serve up a project, paster serve is replaced by the pserve console script. New console scripts named pshell, pviews, proutes, and ptweens do what their paster <commandname> equivalents used to do. All relevant narrative documentation has been updated. Rationale: the Paste and PasteScript packages do not run under Python 3.
  • The default WSGI server run as the result of pserve from newly rendered scaffolding is now the wsgiref WSGI server instead of the paste.httpserver server. wsgiref, unlike the server it replaced (paste.httpserver) is not a production quality server. See :ref:`alternate_wsgi_server` for information about how to use another WSGI server in production. Rationale: the Paste and PasteScript packages do not run under Python 3.
  • The pshell command (see "paster pshell") no longer accepts a --disable-ipython command-line argument. Instead, it accepts a -p or --python-shell argument, which can be any of the values python, ipython or bpython.
  • Removed the pyramid.renderers.renderer_from_name function. It has been deprecated since Pyramid 1.0, and was never an API.
  • To use ZCML with versions of Pyramid >= 1.3, you will need pyramid_zcml version >= 0.8 and zope.configuration version >= 3.8.0. The pyramid_zcml package version 0.8 is backwards compatible all the way to Pyramid 1.0, so you won't be warned if you have older versions installed and upgrade Pyramid itself "in-place"; it may simply break instead (particularly if you use ZCML's includeOverrides directive).

Documentation Enhancements

Dependency Changes

  • Pyramid no longer depends on the zope.component package, except as a testing dependency.
  • Pyramid now depends on the following package versions: zope.interface>=3.8.0, WebOb>=1.2dev, repoze.lru>=0.4, zope.deprecation>=3.5.0, translationstring>=0.4 for Python 3 compatibility purposes. It also, as a testing dependency, depends on WebTest>=1.3.1 for the same reason.
  • Pyramid no longer depends on the Paste or PasteScript packages. These packages are not Python 3 compatible.

Scaffolding Changes

  • Rendered scaffolds have now been changed to be more relocatable (fewer mentions of the package name within files in the package).
  • The routesalchemy scaffold has been renamed alchemy, replacing the older (traversal-based) alchemy scaffold (which has been retired).
  • The alchemy and starter scaffolds are Python 3 compatible.
  • The starter scaffold now uses URL dispatch by default.