add 'What's new In Pyramid 1.1' document

1 files changed, 224 insertions, 0 deletions

diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
new file mode 100644
index 000000000..4be323a1c
--- /dev/null
+++ b/docs/whatsnew-1.1.rst
@@ -0,0 +1,224 @@
+What's New In Pyramid 1.1
+=========================
+
+This article explains the new features in Pyramid version 1.1 as compared to
+its predecessor, :app:`Pyramid` 1.0.  It also documents backwards
+incompatibilities between the two versions and deprecations added to Pyramid
+1.1, as well as software dependency changes and notable documentation
+additions.
+
+Major Feature Additions
+-----------------------
+
+The major feature additions in Pyramid 1.1 are:
+
+- Support for the ``request.response`` attribute.
+
+- New views introspection feature: ``paster pviews``.
+
+- Support for "static" routes.
+
+``request.response``
+~~~~~~~~~~~~~~~~~~~~
+
+- Accessing the ``response`` attribute of a :class:`pyramid.request.Request`
+  object (e.g. ``request.response`` within a view) now produces a new
+  :class:`pyramid.response.Response` object.  This feature is meant to be
+  used mainly when a view configured with a renderer needs to set response
+  attributes: all renderers will use the Response object implied by
+  ``request.response`` as the response object returned to the router.
+
+  ``request.response`` can also be used by code in a view that does not use a
+  renderer, however the response object that is produced by
+  ``request.response`` must be returned when a renderer is not in play (it is
+  not a "global" response).
+
+``paster pviews``
+~~~~~~~~~~~~~~~~~
+
+- A new paster command named ``paster pviews`` was added.  This command
+  prints a summary of potentially matching views for a given path.  See
+  documentation the section entitled :ref:`displaying_matching_views` for
+  more information.
+
+Static Routes
+~~~~~~~~~~~~~
+
+- The ``add_route`` method of the Configurator now accepts a ``static``
+  argument.  If this argument is ``True``, the added route will never be
+  considered for matching when a request is handled.  Instead, it will only
+  be useful for URL generation via ``route_url`` and ``route_path``.  See the
+  section entitled :ref:`static_route_narr` for more information.
+
+Minor Feature Additions
+-----------------------
+
+- Integers and longs passed as ``elements`` to
+  :func:`pyramid.url.resource_url` or
+  :meth:`pyramid.request.Request.resource_url` e.g. ``resource_url(context,
+  request, 1, 2)`` (``1`` and ``2`` are the ``elements``) will now be
+  converted implicitly to strings in the result.  Previously passing integers
+  or longs as elements would cause a TypeError.
+
+- ``pyramid_alchemy`` paster template now uses ``query.get`` rather than
+  ``query.filter_by`` to take better advantage of identity map caching.
+
+- ``pyramid_alchemy`` paster template now has unit tests.
+
+- Added a :func:`pyramid.i18n.make_localizer` API.
+
+- An exception raised by a :class:`pyramid.events.NewRequest` event
+  subscriber can now be caught by an exception view.
+
+- It is now possible to get information about why Pyramid raised a Forbidden
+  exception from within an exception view.  The ``ACLDenied`` object returned
+  by the ``permits`` method of each stock authorization policy
+  (:meth:`pyramid.interfaces.IAuthorizationPolicy.permits`) is now attached
+  to the Forbidden exception as its ``result`` attribute.  Therefore, if
+  you've created a Forbidden exception view, you can see the ACE, ACL,
+  permission, and principals involved in the request as
+  eg. ``context.result.permission``, ``context.result.acl``, etc within the
+  logic of the Forbidden exception view.
+
+- Don't explicitly prevent the ``timeout`` from being lower than the
+  ``reissue_time`` when setting up an
+  :class:`pyramid.authentication.AuthTktAuthenticationPolicy` (previously
+  such a configuration would raise a ``ValueError``, now it's allowed,
+  although typically nonsensical).  Allowing the nonsensical configuration
+  made the code more understandable and required fewer tests.
+
+Deprecations and Behavior Differences
+-------------------------------------
+
+- Deprecated all assignments to ``request.response_*`` attributes (for
+  example ``request.response_content_type = 'foo'`` is now deprecated).
+  Assignments and mutations of assignable request attributes that were
+  considered by the framework for response influence are now deprecated:
+  ``response_content_type``, ``response_headerlist``, ``response_status``,
+  ``response_charset``, and ``response_cache_for``.  Instead of assigning
+  these to the request object for later detection by the rendering machinery,
+  users should use the appropriate API of the Response object created by
+  accessing ``request.response`` (e.g. code which does
+  ``request.response_content_type = 'abc'`` should be changed to
+  ``request.response.content_type = 'abc'``).
+
+- Passing view-related parameters to
+  :meth:`pyramid.config.Configurator.add_route` is now deprecated.
+  Previously, a view was permitted to be connected to a route using a set of
+  ``view*`` parameters passed to the ``add_route`` method of the
+  Configurator.  This was a shorthand which replaced the need to perform a
+  subsequent call to ``add_view``. For example, it was valid (and often
+  recommended) to do::
+
+     config.add_route('home', '/', view='mypackage.views.myview',
+                       view_renderer='some/renderer.pt')
+
+  Passing ``view*`` arguments to ``add_route`` is now deprecated in favor of
+  connecting a view to a predefined route via
+  :meth:`pyramid.config.Configurator.add_view` using the route's
+  ``route_name`` parameter.  As a result, the above example should now be
+  spelled::
+
+     config.add_route('home', '/')
+     config.add_view('mypackage.views.myview', route_name='home')
+                     renderer='some/renderer.pt')
+
+  This deprecation was done to reduce confusion observed in IRC, as well as
+  to (eventually) reduce documentation burden (see also
+  https://github.com/Pylons/pyramid/issues/164).  A deprecation warning is
+  now issued when any view-related parameter is passed to
+  ``add_route``.
+
+- Passing an ``environ`` dictionary to the ``__call__`` method of a
+  "traverser" (e.g. an object that implements
+  :class:`pyramid.interfaces.ITraverser` such as an instance of
+  :class:`pyramid.traversal.ResourceTreeTraverser`) as its ``request``
+  argument now causes a deprecation warning to be emitted.  Consumer code
+  should pass a ``request`` object instead.  The fact that passing an environ
+  dict is permitted has been documentation-deprecated since ``repoze.bfg``
+  1.1, and this capability will be removed entirely in a future version.
+
+- The following (undocumented, dictionary-like) methods of the
+  :class:`pyramid.request.Request` object have been deprecated:
+  ``__contains__``, ``__delitem__``, ``__getitem__``, ``__iter__``,
+  ``__setitem__``, ``get``, ``has_key``, ``items``, ``iteritems``,
+  ``itervalues``, ``keys``, ``pop``, ``popitem``, ``setdefault``, ``update``,
+  and ``values``.  Usage of any of these methods will cause a deprecation
+  warning to be emitted.  These methods were added for internal compatibility
+  in ``repoze.bfg`` 1.1 (code that currently expects a request object
+  expected an environ object in BFG 1.0 and before).  In a future version,
+  these methods will be removed entirely.
+
+- A custom request factory is now required to return a response object that
+  has a ``response`` attribute (or "reified"/lazy property) if they the
+  request is meant to be used in a view that uses a renderer.  This
+  ``response`` attribute should be an instance of the class
+  :class:`pyramid.response.Response`.
+
+- The JSON and string renderer factories now assign to
+  ``request.response.content_type`` rather than
+  ``request.response_content_type``.  Each renderer factory determines
+  whether it should change the content type of the response by comparing the
+  response's content type against the response's default content type; if the
+  content type is not the default content type (usually ``text/html``), the
+  renderer changes the content type (to ``application/json`` or
+  ``text/plain`` for JSON and string renderers respectively).
+
+- The :func:`pyramid.wsgi.wsgiapp2` now uses a slightly different method of
+  figuring out how to "fix" ``SCRIPT_NAME`` and ``PATH_INFO`` for the
+  downstream application.  As a result, those values may differ slightly from
+  the perspective of the downstream application (for example, ``SCRIPT_NAME``
+  will now never possess a trailing slash).
+
+- Previously, :class:`pyramid.request.Request` inherited from
+  :class:`webob.request.Request` and implemented ``__getattr__``,
+  ``__setattr__`` and ``__delattr__`` itself in order to overidde "adhoc
+  attr" WebOb behavior where attributes of the request are stored in the
+  environ.  Now, :class:`pyramid.request.Request inherits from (the more
+  recent) :class:`webob.request.BaseRequest`` instead of
+  :class:`webob.request.Request`, which provides the same behavior.
+  :class:`pyramid.request.Request` no longer implements its own
+  ``__getattr__``, ``__setattr__`` or ``__delattr__`` as a result.
+
+Dependency Changes
+------------------
+
+- Pyramid now depends on :term:`WebOb` >= 1.0.2 as tests depend on the bugfix
+  in that release: "Fix handling of WSGI environs with missing
+  ``SCRIPT_NAME``".  (Note that in reality, everyone should probably be using
+  1.0.4 or better though, as WebOb 1.0.2 and 1.0.3 were effectively brownbag
+  releases.)
+
+Documentation Enhancements
+--------------------------
+
+- The term "template" used to refer to both "paster templates" and "rendered
+  templates" (templates created by a rendering engine.  i.e. Mako, Chameleon,
+  Jinja, etc.).  "Paster templates" will now be refered to as "scaffolds",
+  whereas the name for "rendered templates" will remain as "templates."
+
+- The :ref:`bfg_wiki_tutorial` was updated slightly.
+
+- The :ref:`bfg_sql_wiki_tutorial` was updated slightly.
+
+- Made :class:`pyramid.interfaces.IAuthenticationPolicy` and
+  :class:`pyramid.interfaces.IAuthorizationPolicy` public interfaces, and
+  they are now referred to within the :mod:`pyramid.authentication` and
+  :mod:`pyramid.authorization` API docs.
+
+- Render the function definitions for each exposed interface in
+  :mod:`pyramid.interfaces`.
+
+- Add missing docs reference to
+  :meth:`pyramid.config.Configurator.set_view_mapper` and refer to it within
+  the documentation section entitled :ref:`using_a_view_mapper`.
+
+- Added section to the "Environment Variables and ``.ini`` File Settings"
+  chapter in the narrative documentation section entitled
+  :ref:`adding_a_custom_setting`.
+
+- Added documentation for a :term:`multidict` as
+  :class:`pyramid.interfaces.IMultiDict`.
+
+- Added a section to the "URL Dispatch" narrative chapter regarding the new
+  "static" route feature entitled :ref:`static_route_narr`.