Merge remote branch 'source/master'

Conflicts:
	docs/narr/hooks.rst

1 files changed, 546 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 8532ebec8..9ce6184a3 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -4,6 +4,522 @@ Next release
 Features
 --------
 
+- Integers and longs passed as ``elements`` to ``pyramid.url.resource_url``
+  or ``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 ``pyramid.i18n.make_localizer`` API (broken out from
+  ``get_localizer`` guts).
+
+Bug Fixes
+---------
+
+- Don't send port numbers along with domain information in cookies set by
+  AuthTktCookieHelper (see https://github.com/Pylons/pyramid/issues/131).
+
+- ``pyramid.url.route_path`` (and the shortcut
+  ``pyramid.request.Request.route_url`` method) now include the WSGI
+  SCRIPT_NAME at the front of the path if it is not empty (see
+  https://github.com/Pylons/pyramid/issues/135).
+
+- ``pyramid.testing.DummyRequest`` now has a ``script_name`` attribute (the
+  empty string).
+
+- Don't quote ``:@&+$,`` symbols in ``*elements`` passed to
+  ``pyramid.url.route_url`` or ``pyramid.url.resource_url`` (see
+  https://github.com/Pylons/pyramid/issues#issue/141).
+
+- Include SCRIPT_NAME in redirects issued by
+  ``pyramid.view.append_slash_notfound_view`` (see
+  https://github.com/Pylons/pyramid/issues#issue/149).
+
+1.0 (2011-01-30)
+================
+
+Documentation
+-------------
+
+- Fixed bug in ZODB Wiki tutorial (missing dependency on ``docutils`` in
+  "models" step within ``setup.py``).
+
+- Removed API documentation for ``pyramid.testing`` APIs named
+  ``registerDummySecurityPolicy``, ``registerResources``, ``registerModels``,
+  ``registerEventListener``, ``registerTemplateRenderer``,
+  ``registerDummyRenderer``, ``registerView``, ``registerUtility``,
+  ``registerAdapter``, ``registerSubscriber``, ``registerRoute``,
+  and ``registerSettings``.
+
+- Moved "Using ZODB With ZEO" and "Using repoze.catalog Within Pyramid"
+  tutorials out of core documentation and into the Pyramid Tutorials site
+  (http://docs.pylonsproject.org/projects/pyramid_tutorials/dev/).
+
+- Changed "Cleaning up After a Request" section in the URL Dispatch chapter
+  to use ``request.add_finished_callback`` instead of jamming an object with
+  a ``__del__`` into the WSGI environment.
+
+- Remove duplication of ``add_route`` API documentation from URL Dispatch
+  narrative chapter.
+
+- Remove duplication of API and narrative documentation in
+  ``pyramid.view.view_config`` API docs by pointing to
+  ``pyramid.config.add_view`` documentation and narrative chapter
+  documentation.
+
+- Removed some API documentation duplicated in narrative portions of
+  documentation 
+
+- Removed "Overall Flow of Authentication" from SQLAlchemy + URL Dispatch
+  wiki tutorial due to print space concerns (moved to Pyramid Tutorials
+  site).
+
+Bug Fixes
+---------
+
+- Deprecated-since-BFG-1.2 APIs from ``pyramid.testing`` now properly emit
+  deprecation warnings.
+
+- Added ``egg:repoze.retry#retry`` middleware to the WSGI pipeline in ZODB
+  templates (retry ZODB conflict errors which occur in normal operations).
+
+- Removed duplicate implementations of ``is_response``.  Two competing
+  implementations existed: one in ``pyramid.config`` and one in
+  ``pyramid.view``.  Now the one defined in ``pyramid.view`` is used
+  internally by ``pyramid.config`` and continues to be advertised as an API.
+
+1.0b3 (2011-01-28)
+==================
+
+Bug Fixes
+---------
+
+- Use © instead of copyright symbol in paster templates / tutorial
+  templates for the benefit of folks who cutnpaste and save to a non-UTF8
+  format.
+
+- ``pyramid.view.append_slash_notfound_view`` now preserves GET query
+  parameters across redirects.
+
+Documentation
+-------------
+
+- Beef up documentation related to ``set_default_permission``: explicitly
+  mention that default permissions also protect exception views.
+
+- Paster templates and tutorials now use spaces instead of tabs in their HTML
+  templates.
+
+1.0b2 (2011-01-24)
+==================
+
+Bug Fixes
+---------
+
+- The ``production.ini`` generated by all paster templates now have an
+  effective logging level of WARN, which prevents e.g. SQLAlchemy statement
+  logging and other inappropriate output.
+
+- The ``production.ini`` of the ``pyramid_routesalchemy`` and
+  ``pyramid_alchemy`` paster templates did not have a ``sqlalchemy`` logger
+  section, preventing ``paster serve production.ini`` from working.
+
+- The ``pyramid_routesalchemy`` and ``pyramid_alchemy`` paster templates used
+  the ``{{package}}`` variable in a place where it should have used the
+  ``{{project}}`` variable, causing applications created with uppercase
+  letters e.g. ``paster create -t pyramid_routesalchemy Dibbus`` to fail to
+  start when ``paster serve development.ini`` was used against the result.
+  See https://github.com/Pylons/pyramid/issues/#issue/107
+
+- The ``render_view`` method of ``pyramid.renderers.RendererHelper`` passed
+  an incorrect value into the renderer for ``renderer_info``.  It now passes
+  an instance of ``RendererHelper`` instead of a dictionary, which is
+  consistent with other usages.  See
+  https://github.com/Pylons/pyramid/issues#issue/106
+
+- A bug existed in the ``pyramid.authentication.AuthTktCookieHelper`` which
+  would break any usage of an AuthTktAuthenticationPolicy when one was
+  configured to reissue its tokens (``reissue_time`` < ``timeout`` /
+  ``max_age``). Symptom: ``ValueError: ('Invalid token %r', '')``.  See
+  https://github.com/Pylons/pyramid/issues#issue/108.
+
+1.0b1 (2011-01-21)
+==================
+
+Features
+--------
+
+- The AuthTktAuthenticationPolicy now accepts a ``tokens`` parameter via
+  ``pyramid.security.remember``.  The value must be a sequence of strings.
+  Tokens are placed into the auth_tkt "tokens" field and returned in the
+  auth_tkt cookie.
+
+- Add ``wild_domain`` argument to AuthTktAuthenticationPolicy, which defaults
+  to ``True``.  If it is set to ``False``, the feature of the policy which
+  sets a cookie with a wilcard domain will be turned off.
+
+- Add a ``MANIFEST.in`` file to each paster template. See
+  https://github.com/Pylons/pyramid/issues#issue/95
+
+Bug Fixes
+---------
+
+- ``testing.setUp`` now adds a ``settings`` attribute to the registry (both
+  when it's passed a registry without any settings and when it creates one).
+
+- The ``testing.setUp`` function now takes a ``settings`` argument, which
+  should be a dictionary.  Its values will subsequently be available on the
+  returned ``config`` object as ``config.registry.settings``.
+
+Documentation
+-------------
+
+- Added "What's New in Pyramid 1.0" chapter to HTML rendering of
+  documentation.
+
+- Merged caseman-master narrative editing branch, many wording fixes and
+  extensions.
+
+- Fix deprecated example showing ``chameleon_zpt`` API call in testing
+  narrative chapter.
+
+- Added "Adding Methods to the Configurator via ``add_directive``" section to
+  Advanced Configuration narrative chapter.
+
+- Add docs for ``add_finished_callback``, ``add_response_callback``,
+  ``route_path``, ``route_url``, and ``static_url`` methods to
+  ``pyramid.request.Request`` API docs.
+
+- Add (minimal) documentation about using I18N within Mako templates to
+  "Internationalization and Localization" narrative chapter.
+
+- Move content of "Forms" chapter back to "Views" chapter; I can't think of a
+  better place to put it.
+
+- Slightly improved interface docs for ``IAuthorizationPolicy``.
+
+- Minimally explain usage of custom regular expressions in URL dispatch
+  replacement markers within URL Dispatch chapter.
+
+Deprecations
+-------------
+
+- Using the ``pyramid.view.bfg_view`` alias for ``pyramid.view.view_config``
+  (a backwards compatibility shim) now issues a deprecation warning.
+
+Backwards Incompatibilities
+---------------------------
+
+- When a ``pyramid.exceptions.Forbidden`` error is raised, its status code
+  now ``403 Forbidden``.  It was previously ``401 Unauthorized``, for
+  backwards compatibility purposes with ``repoze.bfg``.  This change will
+  cause problems for users of Pyramid with ``repoze.who``, which intercepts
+  ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to pass
+  through.  Those deployments will need to configure ``repoze.who`` to also
+  react to ``403 Forbidden``.
+
+- The default value for the ``cookie_on_exception`` parameter to
+  ``pyramid.session.UnencyrptedCookieSessionFactory`` is now ``True``.  This
+  means that when view code causes an exception to be raised, and the session
+  has been mutated, a cookie will be sent back in the response.  Previously
+  its default value was ``False``.
+
+Paster Templates
+----------------
+
+- The ``pyramid_zodb``, ``pyramid_routesalchemy`` and ``pyramid_alchemy``
+  paster templates now use a default "commit veto" hook when configuring the
+  ``repoze.tm2`` transaction manager in ``development.ini``.  This prevents a
+  transaction from being committed when the response status code is within
+  the 400 or 500 ranges.  See also
+  http://docs.repoze.org/tm2/#using-a-commit-veto.
+
+1.0a10 (2011-01-18)
+===================
+
+Bug Fixes
+---------
+
+- URL dispatch now properly handles a ``.*`` or ``*`` appearing in a regex
+  match when used inside brackets.  Resolves issue #90.
+
+Backwards Incompatibilities
+---------------------------
+
+- The ``add_handler`` method of a Configurator has been removed from the
+  Pyramid core.  Handlers are now a feature of the ``pyramid_handlers``
+  package, which can be downloaded from PyPI.  Documentation for the package
+  should be available via
+  http://pylonsproject.org/projects/pyramid_handlers/dev/, which describes how
+  to add a configuration statement to your ``main`` block to reobtain this
+  method.  You will also need to add an ``install_requires`` dependency upon
+  ``pyramid_handlers`` to your ``setup.py`` file.
+
+- The ``load_zcml`` method of a Configurator has been removed from the
+  Pyramid core.  Loading ZCML is now a feature of the ``pyramid_zcml``
+  package, which can be downloaded from PyPI.  Documentation for the package
+  should be available via
+  http://pylonsproject.org/projects/pyramid_zcml/dev/, which describes how
+  to add a configuration statement to your ``main`` block to reobtain this
+  method.  You will also need to add an ``install_requires`` dependency upon
+  ``pyramid_zcml`` to your ``setup.py`` file.
+
+- The ``pyramid.includes`` subpackage has been removed.  ZCML files which use
+  include the package ``pyramid.includes`` (e.g. ``<include
+  package="pyramid.includes"/>``) now must include the ``pyramid_zcml``
+  package instead (e.g. ``<include package="pyramid_zcml"/>``).
+
+- The ``pyramid.view.action`` decorator has been removed from the Pyramid
+  core.  Handlers are now a feature of the ``pyramid_handlers`` package.  It
+  should now be imported from ``pyramid_handlers`` e.g. ``from
+  pyramid_handlers import action``.
+
+- The ``handler`` ZCML directive has been removed.  It is now a feature of
+  the ``pyramid_handlers`` package.
+
+- The ``pylons_minimal``, ``pylons_basic`` and ``pylons_sqla`` paster
+  templates were removed.  Use ``pyramid_sqla`` (available from PyPI) as a
+  generic replacement for Pylons-esque development.
+
+- The ``make_app`` function has been removed from the ``pyramid.router``
+  module.  It continues life within the ``pyramid_zcml`` package.  This
+  leaves the ``pyramid.router`` module without any API functions.
+
+- The ``configure_zcml`` setting within the deployment settings (within
+  ``**settings`` passed to a Pyramid ``main`` function) has ceased to have any
+  meaning.
+
+Features
+--------
+
+- ``pyramid.testing.setUp`` and ``pyramid.testing.tearDown`` have been
+  undeprecated.  They are now the canonical setup and teardown APIs for test
+  configuration, replacing "direct" creation of a Configurator.  This is a
+  change designed to provide a facade that will protect against any future
+  Configurator deprecations.
+
+- Add ``charset`` attribute to ``pyramid.testing.DummyRequest``
+  (unconditionally ``UTF-8``).
+
+- Add ``add_directive`` method to configurator, which allows framework
+  extenders to add methods to the configurator (ala ZCML directives).
+
+- When ``Configurator.include`` is passed a *module* as an argument, it
+  defaults to attempting to find and use a callable named ``includeme``
+  within that module.  This makes it possible to use
+  ``config.include('some.module')`` rather than
+  ``config.include('some.module.somefunc')`` as long as the include function
+  within ``some.module`` is named ``includeme``.
+
+- The ``bfg2pyramid`` script now converts ZCML include tags that have
+  ``repoze.bfg.includes`` as a package attribute to the value
+  ``pyramid_zcml``.  For example, ``<include package="repoze.bfg.includes">``
+  will be converted to ``<include package="pyramid_zcml">``.
+
+Paster Templates
+----------------
+
+- All paster templates now use ``pyramid.testing.setUp`` and
+  ``pyramid.testing.tearDown`` rather than creating a Configurator "by hand"
+  within their ``tests.py`` module, as per decision in features above.
+
+- The ``starter_zcml`` paster template has been moved to the ``pyramid_zcml``
+  package.
+
+Documentation
+-------------
+
+- The wiki and wiki2 tutorials now use ``pyramid.testing.setUp`` and
+  ``pyramid.testing.tearDown`` rather than creating a Configurator "by hand",
+  as per decision in features above.
+
+- The "Testing" narrative chapter now explains ``pyramid.testing.setUp`` and
+  ``pyramid.testing.tearDown`` instead of Configurator creation and
+  ``Configurator.begin()`` and ``Configurator.end()``.
+
+- Document the ``request.override_renderer`` attribute within the narrative
+  "Renderers" chapter in a section named "Overriding A Renderer at Runtime".
+
+- The "Declarative Configuration" narrative chapter has been removed (it was
+  moved to the ``pyramid_zcml`` package).
+
+- Most references to ZCML in narrative chapters have been removed or
+  redirected to ``pyramid_zcml`` locations.
+
+Deprecations
+------------
+
+- Deprecation warnings related to import of the following API functions were
+  added: ``pyramid.traversal.find_model``, ``pyramid.traversal.model_path``,
+  ``pyramid.traversal.model_path_tuple``, ``pyramid.url.model_url``.  The
+  instructions emitted by the deprecation warnings instruct the developer to
+  change these method spellings to their ``resource`` equivalents.  This is a
+  consequence of the mass concept rename of "model" to "resource" performed
+  in 1.0a7.
+
+1.0a9 (2011-01-08)
+==================
+
+Bug Fixes
+---------
+
+- The ``proutes`` command tried too hard to resolve the view for printing,
+  resulting in exceptions when an exceptional root factory was encountered.
+  Instead of trying to resolve the view, if it cannot, it will now just print
+  ``<unknown>``.
+
+- The `self` argument was included in new methods of the ``ISession`` interface
+  signature, causing ``pyramid_beaker`` tests to fail.
+
+- Readd ``pyramid.traversal.model_path_tuple`` as an alias for
+  ``pyramid.traversal.resource_path_tuple`` for backwards compatibility.
+
+Features
+--------
+
+- Add a new API ``pyramid.url.current_route_url``, which computes a URL based
+  on the "current" route (if any) and its matchdict values.
+
+- ``config.add_view`` now accepts a ``decorator`` keyword argument, a callable
+  which will decorate the view callable before it is added to the registry.
+
+- If a handler class provides an ``__action_decorator__`` attribute (usually
+  a classmethod or staticmethod), use that as the decorator for each view
+  registration for that handler.
+
+- The ``pyramid.interfaces.IAuthenticationPolicy`` interface now specifies an
+  ``unauthenticated_userid`` method.  This method supports an important
+  optimization required by people who are using persistent storages which do
+  not support object caching and whom want to create a "user object" as a
+  request attribute.
+
+- A new API has been added to the ``pyramid.security`` module named
+  ``unauthenticated_userid``.  This API function calls the
+  ``unauthenticated_userid`` method of the effective security policy.
+
+- An ``unauthenticated_userid`` method has been added to the dummy
+  authentication policy returned by
+  ``pyramid.config.Configurator.testing_securitypolicy``.  It returns the
+  same thing as that the dummy authentication policy's
+  ``authenticated_userid`` method.
+
+- The class ``pyramid.authentication.AuthTktCookieHelper`` is now an API.
+  This class can be used by third-party authentication policy developers to
+  help in the mechanics of authentication cookie-setting.
+
+- New constructor argument to Configurator: ``default_view_mapper``.  Useful
+  to create systems that have alternate view calling conventions.  A view
+  mapper allows objects that are meant to be used as view callables to have
+  an arbitrary argument list and an arbitrary result.  The object passed as
+  ``default_view_mapper`` should implement the
+  ``pyramid.interfaces.IViewMapperFactory`` interface.
+
+- add a ``set_view_mapper`` API to Configurator.  Has
+  the same result as passing ``default_view_mapper`` to the Configurator
+  constructor.
+
+- ``config.add_view`` now accepts a ``mapper`` keyword argument, which should
+  either be ``None``, a string representing a Python dotted name, or an
+  object which is an ``IViewMapperFactory``.  This feature is not useful for
+  "civilians", only for extension writers.
+
+- Allow static renderer provided during view registration to be overridden at
+  request time via a request attribute named ``override_renderer``, which
+  should be the name of a previously registered renderer.  Useful to provide
+  "omnipresent" RPC using existing rendered views.
+
+- Instances of ``pyramid.testing.DummyRequest`` now have a ``session``
+  object, which is mostly a dictionary, but also implements the other session
+  API methods for flash and CSRF.
+
+Backwards Incompatibilities
+---------------------------
+
+- Since the ``pyramid.interfaces.IAuthenticationPolicy`` interface now
+  specifies that a policy implementation must implement an
+  ``unauthenticated_userid`` method, all third-party custom authentication
+  policies now must implement this method.  It, however, will only be called
+  when the global function named ``pyramid.security.unauthenticated_userid``
+  is invoked, so if you're not invoking that, you will not notice any issues.
+
+- ``pyramid.interfaces.ISession.get_csrf_token`` now mandates that an
+  implementation should return a *new* token if one doesn't already exist in
+  the session (previously it would return None).  The internal sessioning
+  implementation has been changed.
+
+Documentation
+-------------
+
+- The (weak) "Converting a CMF Application to Pyramid" tutorial has been
+  removed from the tutorials section.  It was moved to the
+  ``pyramid_tutorials`` Github repository.
+
+- The "Resource Location and View Lookup" chapter has been replaced with a
+  variant of Rob Miller's "Much Ado About Traversal" (originally published at
+  http://blog.nonsequitarian.org/2010/much-ado-about-traversal/).
+
+- Many minor wording tweaks and refactorings (merged Casey Duncan's docs
+  fork, in which he is working on general editing).
+
+- Added (weak) description of new view mapper feature to Hooks narrative
+  chapter.
+
+- Split views chapter into 2: View Callables and View Configuration.
+
+- Reorder Renderers and Templates chapters after View Callables but before
+  View Configuration.
+
+- Merge Session Objects, Cross-Site Request Forgery, and Flash Messaging
+  chapter into a single Sessions chapter.
+
+- The Wiki and Wiki2 tutorials now have much nicer CSS and graphics.
+
+Internals
+---------
+
+- The "view derivation" code is now factored into a set of classes rather
+  than a large number of standalone functions (a side effect of the
+  view mapper refactoring).
+
+- The ``pyramid.renderer.RendererHelper`` class has grown a ``render_view``
+  method, which is used by the default view mapper (a side effect of the
+  view mapper refactoring).
+
+- The object passed as ``renderer`` to the "view deriver" is now an instance
+  of ``pyramid.renderers.RendererHelper`` rather than a dictionary (a side
+  effect of view mapper refactoring).
+
+- The class used as the "page template" in ``pyramid.chameleon_text`` was
+  removed, in preference to using a Chameleon-inbuilt version.
+
+- A view callable wrapper registered in the registry now contains an
+  ``__original_view__`` attribute which references the original view callable
+  (or class).
+
+- The (non-API) method of all internal authentication policy implementations
+  previously named ``_get_userid`` is now named ``unauthenticated_userid``,
+  promoted to an API method.  If you were overriding this method, you'll now
+  need to override it as ``unauthenticated_userid`` instead.
+
+- Remove (non-API) function of config.py named _map_view.
+
+1.0a8 (2010-12-27)
+==================
+
+Bug Fixes
+---------
+
+- The name ``registry`` was not available in the ``paster pshell``
+  environment under IPython.
+
+Features
+--------
+
 - If a resource implements a ``__resource_url__`` method, it will be called
   as the result of invoking the ``pyramid.url.resource_url`` function to
   generate a URL, overriding the default logic.  See the new "Generating The
@@ -15,6 +531,14 @@ Features
 - Added CSRF token generation, as described in the narrative chapter entitled
   "Preventing Cross-Site Request Forgery Attacks".
 
+- Prevent misunderstanding of how the ``view`` and ``view_permission``
+  arguments to add_route work by raising an exception during configuration if
+  view-related arguments exist but no ``view`` argument is passed.
+
+- Add ``paster proute`` command which displays a summary of the routing
+  table.  See the narrative documentation section within the "URL Dispatch"
+  chapter entitled "Displaying All Application Routes".
+
 Paster Templates
 ----------------
 
@@ -53,6 +577,28 @@ Documentation
 - Changed the "ZODB + Traversal Wiki Tutorial" based on changes to
   ``pyramid_zodb`` Paster template.
 
+- Added "Advanced Configuration" narrative chapter which documents how to
+  deal with configuration conflicts, two-phase configuration, ``include`` and
+  ``commit``.
+
+- Fix API documentation rendering for ``pyramid.view.static``
+
+- Add "Pyramid Provides More Than One Way to Do It" to Design Defense
+  documentation.
+
+- Changed "Static Assets" narrative chapter: clarify that ``name`` represents
+  a prefix unless it's a URL, added an example of a root-relative static view
+  fallback for URL dispatch, added an example of creating a simple view that
+  returns the body of a file.
+
+- Move ZCML usage in Hooks chapter to Declarative Configuration chapter.
+
+- Merge "Static Assets" chapter into the "Assets" chapter.
+
+- Added narrative documentation section within the "URL Dispatch" chapter
+  entitled "Displaying All Application Routes" (for ``paster proutes``
+  command).
+
 1.0a7 (2010-12-20)
 ==================