diff options
Diffstat (limited to 'docs/whatsnew-1.2.rst')
| -rw-r--r-- | docs/whatsnew-1.2.rst | 310 |
1 files changed, 310 insertions, 0 deletions
diff --git a/docs/whatsnew-1.2.rst b/docs/whatsnew-1.2.rst new file mode 100644 index 000000000..9ff933ace --- /dev/null +++ b/docs/whatsnew-1.2.rst @@ -0,0 +1,310 @@ +What's New in Pyramid 1.2 +========================= + +This article explains the new features in :app:`Pyramid` version 1.2 as +compared to its predecessor, :app:`Pyramid` 1.1. It also documents backwards +incompatibilities between the two versions and deprecations added to Pyramid +1.2, as well as software dependency changes and notable documentation +additions. + +Major Feature Additions +----------------------- + +The major feature additions in Pyramid 1.2 follow. + +Debug Toolbar +~~~~~~~~~~~~~ + +The scaffolding packages that come with Pyramid now include a debug toolbar +component which can be used to interactively debug an application. See +:ref:`debug_toolbar` for more information. + +``route_prefix`` Argument to include +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :meth:`pyramid.config.Configurator.include` method now accepts a +``route_prefix`` argument. This argument allows you to compose URL dispatch +applications together from disparate packages. See :ref:`route_prefix` for +more information. + +Tweens +~~~~~~ + +A :term:`tween` is used to wrap the Pyramid router's primary request handling +function. This is a feature that can be used by Pyramid framework extensions, +to provide, for example, view timing support and can provide a convenient +place to hang bookkeeping code. Tweens are a little like :term:`WSGI` +:term:`middleware`, but have access to Pyramid functionality such as renderers +and a full-featured request object. + +To support this feature, a new configurator directive exists named +:meth:`pyramid.config.Configurator.add_tween`. This directive adds a +"tween". + +Tweens are further described in :ref:`registering_tweens`. + +A new paster command now exists: ``paster ptweens``. This command prints the +current tween configuration for an application. See the section entitled +:ref:`displaying_tweens` for more info. + +Scaffolding Changes +~~~~~~~~~~~~~~~~~~~ + +- All scaffolds now use the ``pyramid_tm`` package rather than the + ``repoze.tm2`` :term:`middleware` to manage transaction management. + +- The ZODB scaffold now uses the ``pyramid_zodbconn`` package rather than the + ``repoze.zodbconn`` package to provide ZODB integration. + +- All scaffolds now use the ``pyramid_debugtoolbar`` package rather than the + ``WebError`` package to provide interactive debugging features. + +- Projects created via a scaffold no longer depend on the ``WebError`` package + at all; configuration in the ``production.ini`` file which used to require + its ``error_catcher`` :term:`middleware` has been removed. Configuring + error catching / email sending is now the domain of the ``pyramid_exclog`` + package (see http://docs.pylonsproject.org/projects/pyramid_exclog/dev/). + +- All scaffolds now send the ``cache_max_age`` parameter to the + ``add_static_view`` method. + +Minor Feature Additions +----------------------- + +- The ``[pshell]`` section in an ini configuration file now treats a + ``setup`` key as a dotted name that points to a callable that is passed the + bootstrap environment. It can mutate the environment as necessary during a + ``paster pshell`` session. This feature is described in + :ref:`writing_a_script`. + +- A new configuration setting named ``pyramid.includes`` is now available. + It is described in :ref:`including_packages`. + +- Added a :data:`pyramid.security.NO_PERMISSION_REQUIRED` constant for use in + ``permission=`` statements to view configuration. This constant has a + value of the string ``__no_permission_required__``. This string value was + previously referred to in documentation; now the documentation uses the + constant. + +- Added a decorator-based way to configure a response adapter: + :class:`pyramid.response.response_adapter`. This decorator has the same + use as :meth:`pyramid.config.Configurator.add_response_adapter` but it's + declarative. + +- The :class:`pyramid.events.BeforeRender` event now has an attribute named + ``rendering_val``. This can be used to introspect the value returned by a + view in a BeforeRender subscriber. + +- The Pyramid debug logger now uses the standard logging configuration + (usually set up by Paste as part of startup). This means that output from + e.g. ``debug_notfound``, ``debug_authorization``, etc. will go to the + normal logging channels. The logger name of the debug logger will be the + package name of the *caller* of the Configurator's constructor. + +- A new attribute is available on request objects: ``exc_info``. Its value + will be ``None`` until an exception is caught by the Pyramid router, after + which it will be the result of ``sys.exc_info()``. + +- :class:`pyramid.testing.DummyRequest` now implements the + ``add_finished_callback`` and ``add_response_callback`` methods implemented + by :class:`pyramid.request.Request`. + +- New methods of the :class:`pyramid.config.Configurator` class: + :meth:`~pyramid.config.Configurator.set_authentication_policy` and + :meth:`~pyramid.config.Configurator.set_authorization_policy`. These are + meant to be consumed mostly by add-on authors who wish to offer packages + which register security policies. + +- New Configurator method: + :meth:`pyramid.config.Configurator.set_root_factory`, which can set the + root factory after the Configurator has been constructed. + +- Pyramid no longer eagerly commits some default configuration statements at + :term:`Configurator` construction time, which permits values passed in as + constructor arguments (e.g. ``authentication_policy`` and + ``authorization_policy``) to override the same settings obtained via the + :meth:`pyramid.config.Configurator.include` method. + +- Better Mako rendering exceptions; the template line which caused the error + is now shown when a Mako rendering raises an exception. + +- New request methods: :meth:`~pyramid.request.Request.current_route_url`, + :meth:`~pyramid.request.Request.current_route_path`, and + :meth:`~pyramid.request.Request.static_path`. + +- New functions in the :mod:`pyramid.url` module: + :func:`~pyramid.url.current_route_path` and + :func:`~pyramid.url.static_path`. + +- The :meth:`pyramid.request.Request.static_url` API (and its brethren + :meth:`pyramid.request.Request.static_path`, + :func:`pyramid.url.static_url`, and :func:`pyramid.url.static_path`) now + accept an absolute filename as a "path" argument. This will generate a URL + to an asset as long as the filename is in a directory which was previously + registered as a static view. Previously, trying to generate a URL to an + asset using an absolute file path would raise a ValueError. + +- The :class:`~pyramid.authentication.RemoteUserAuthenticationPolicy`, + :class:`~pyramid.authentication.AuthTktAuthenticationPolicy`, and + :class:`~pyramid.authentication.SessionAuthenticationPolicy` constructors + now accept an additional keyword argument named ``debug``. By default, + this keyword argument is ``False``. When it is ``True``, debug information + will be sent to the Pyramid debug logger (usually on stderr) when the + ``authenticated_userid`` or ``effective_principals`` method is called on + any of these policies. The output produced can be useful when trying to + diagnose authentication-related problems. + +- New view predicate: ``match_param``. Example: a view added via + ``config.add_view(aview, match_param='action=edit')`` will be called only + when the ``request.matchdict`` has a value inside it named ``action`` with + a value of ``edit``. + +- Support an ``onerror`` keyword argument to + :meth:`pyramid.config.Configurator.scan`. This argument is passed to + :meth:`venusian.Scanner.scan` to influence error behavior when an exception + is raised during scanning. + +- The ``request_method`` predicate argument to + :meth:`pyramid.config.Configurator.add_view` and + :meth:`pyramid.config.Configurator.add_route` is now permitted to be a + tuple of HTTP method names. Previously it was restricted to being a string + representing a single HTTP method name. + +- Undeprecated ``pyramid.traversal.find_model``, + ``pyramid.traversal.model_path``, ``pyramid.traversal.model_path_tuple``, + and ``pyramid.url.model_url``, which were all deprecated in Pyramid 1.0. + There's just not much cost to keeping them around forever as aliases to + their renamed ``resource_*`` prefixed functions. + +- Undeprecated ``pyramid.view.bfg_view``, which was deprecated in Pyramid + 1.0. This is a low-cost alias to ``pyramid.view.view_config`` which we'll + just keep around forever. + +- Route pattern replacement marker names can now begin with an underscore. + See https://github.com/Pylons/pyramid/issues/276. + +Deprecations +------------ + +- All Pyramid-related :term:`deployment settings` (e.g. ``debug_all``, + ``debug_notfound``) are now meant to be prefixed with the prefix + ``pyramid.``. For example: ``debug_all`` -> ``pyramid.debug_all``. The + old non-prefixed settings will continue to work indefinitely but supplying + them may print a deprecation warning. All scaffolds and tutorials have + been changed to use prefixed settings. + +- The :term:`deployment settings` dictionary now raises a deprecation warning + when you attempt to access its values via ``__getattr__`` instead of via + ``__getitem__``. + +Backwards Incompatibilities +--------------------------- + +- If a string is passed as the ``debug_logger`` parameter to a + :term:`Configurator`, that string is considered to be the name of a global + Python logger rather than a dotted name to an instance of a logger. + +- The :meth:`pyramid.config.Configurator.include` method now accepts only a + single ``callable`` argument. A *sequence* of callables used to be + permitted. If you are passing more than one ``callable`` to + :meth:`pyramid.config.Configurator.include`, it will break. You now must + now instead make a separate call to the method for each callable. + +- It may be necessary to more strictly order configuration route and view + statements when using an "autocommitting" :term:`Configurator`. In the + past, it was possible to add a view which named a route name before adding + a route with that name when you used an autocommitting configurator. For + example: + + .. code-block:: python + + config = Configurator(autocommit=True) + config.add_view('my.pkg.someview', route_name='foo') + config.add_route('foo', '/foo') + + The above will raise an exception when the view attempts to add itself. + Now you must add the route before adding the view: + + .. code-block:: python + + config = Configurator(autocommit=True) + config.add_route('foo', '/foo') + config.add_view('my.pkg.someview', route_name='foo') + + This won't effect "normal" users, only people who have legacy BFG codebases + that used an autommitting configurator and possibly tests that use the + configurator API (the configurator returned by + :func:`pyramid.testing.setUp` is an autocommitting configurator). The + right way to get around this is to use a default non-autocommitting + configurator, which does not have these directive ordering requirements: + + .. code-block:: python + + config = Configurator() + config.add_view('my.pkg.someview', route_name='foo') + config.add_route('foo', '/foo') + + The above will work fine. + +- The :meth:`pyramid.config.Configurator.add_route` directive no longer + returns a route object. This change was required to make route vs. view + configuration processing work properly. + +Behavior Differences +-------------------- + +- An ETag header is no longer set when serving a static file. A + Last-Modified header is set instead. + +- Static file serving no longer supports the ``wsgi.file_wrapper`` extension. + +- Instead of returning a ``403 Forbidden`` error when a static file is served + that cannot be accessed by the Pyramid process' user due to file + permissions, an IOError (or similar) will be raised. + +Documentation Enhancements +-------------------------- + +- Narrative and API documentation which used the ``route_url``, + ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` + functions in the :mod:`pyramid.url` package have now been changed to use + eponymous methods of the request instead. + +- Added a section entitled :ref:`route_prefix` to the "URL Dispatch" + narrative documentation chapter. + +- Added a new module to the API docs: :mod:`pyramid.tweens`. + +- Added a :ref:`registering_tweens` section to the "Hooks" narrative chapter. + +- Added a :ref:`displaying_tweens` section to the "Command-Line Pyramid" + narrative chapter. + +- Added documentation for :ref:`explicit_tween_config` and + :ref:`including_packages` to the "Environment Variables and ``.ini`` Files + Settings" chapter. + +- Added a :ref:`logging_chapter` chapter to the narrative docs. + +- All tutorials now use - The ``route_url``, ``route_path``, + ``resource_url``, ``static_url``, and ``current_route_url`` methods of the + :class:`pyramid.request.Request` rather than the function variants imported + from ``pyramid.url``. + +- The ZODB wiki tutorial now uses the ``pyramid_zodbconn`` package rather + than the ``repoze.zodbconn`` package to provide ZODB integration. + +- Added :ref:`what_makes_pyramid_unique` to the Introduction narrative + chapter. + + +Dependency Changes +------------------ + +- Pyramid now relies on PasteScript >= 1.7.4. This version contains a + feature important for allowing flexible logging configuration. + +- Pyramid now requires Venusian 1.0a1 or better to support the ``onerror`` + keyword argument to :meth:`pyramid.config.Configurator.scan`. + +- The ``zope.configuration`` package is no longer a dependency. |