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`` and ``paster create`` instead if they like. However, using ``pserve`` and ``pcreate`` will work under both Python 2 and Python 3. Analogues of ``paster pshell``, ``paster pviews`` and ``paster ptweens`` also exist under the respective console script names ``pshell``, ``pviews``, 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. 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: .. code-block:: python :linenos: 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: .. code-block:: python :linenos: 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 ----------------------- - New APIs: :class:`pyramid.path.AssetResolver` and :class:`pyramid.path.DottedNameResolver`. The former can be used to resolve an :term:`asset specification` to an API that can be used to read the asset's data, the latter can be used to resolve a :term:`dotted Python name` to a module or a package. - A ``mako.directories`` setting is no longer required to use Mako templates Rationale: Mako template renderers can be specified using an absolute asset spec. An entire application can be written with such asset specs, requiring no ordered lookup path. - ``bpython`` interpreter compatibility in ``pshell``. See :ref:`ipython_or_bpython` for more information. - Added :func:`pyramid.paster.get_appsettings` API function. This function returns the settings defined within an ``[app:...]`` section in a PasteDeploy ``ini`` file. - Added :func:`pyramid.paster.setup_logging` API function. This function sets up Python logging according to the logging configuration in a PasteDeploy ``ini`` file. - Configuration conflict reporting is reported in a more understandable way ("Line 11 in file..." vs. a repr of a tuple of similar info). - We allow extra keyword arguments to be passed to the :meth:`pyramid.config.Configurator.action` method. 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 `` 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 -------------------------- - The :ref:`bfg_sql_wiki_tutorial` has been updated. It now uses ``@view_config`` decorators and an explicit database population script. - Minor updates to the :ref:`bfg_wiki_tutorial`. - A narrative documentation chapter named :ref:`extconfig_narr` was added; it describes how to add a custom :term:`configuration directive`, and how use the :meth:`pyramid.config.Configurator.action` method within custom directives. It also describes how to add :term:`introspectable` objects. - A narrative documentation chapter named :ref:`using_introspection` was added. It describes how to query the introspection system. 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.