Merge remote-tracking branch 'refs/remotes/Pylons/master'

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.