Merge branch 'cmbeelby-master'

Chris McDonough

2011-02-05 62af268dba6c0f1abbe7abf07fd2ee31d2e51ce1

Merge branch 'cmbeelby-master'

 docs/authorintro.rst

@@ -163,6 +163,7 @@
   single: Duncan, Casey
   single: Orr, Mike
   single: Shipman, John
   single: Beelby, Chris

Thanks
======
@@ -176,9 +177,9 @@
software which it details would exist: Paul Everitt, Tres Seaver, Andrew
Sawyers, Malthe Borch, Carlos de la Guardia, Chris Rossi, Shane Hathaway,
Daniel Holth, Wichert Akkerman, Georg Brandl, Blaise Laflamme, Ben Bangert,
Casey Duncan, Hugues Laflamme, Mike Orr, John Shipman, Simon Oram, Nat
Hardwick, Ian Bicking, Jim Fulton, Tom Moroz of the Open Society Institute,
and Todd Koym of Environmental Health Sciences.
Casey Duncan, Hugues Laflamme, Mike Orr, John Shipman, Chris Beelby, Simon
Oram, Nat Hardwick, Ian Bicking, Jim Fulton, Tom Moroz of the Open Society
Institute, and Todd Koym of Environmental Health Sciences.

Thanks to Guido van Rossum and Tim Peters for Python.


 docs/narr/muchadoabouttraversal.rst

@@ -107,7 +107,7 @@
   single: traversal overview

Believe it or not, if you understand how serving files from a file system
works,you understand traversal.  And if you understand that a server might do
works, you understand traversal.  And if you understand that a server might do
something different based on what type of file a given request specifies,
then you understand view lookup.


 docs/narr/renderers.rst

@@ -79,7 +79,7 @@
returns a Response object directly (an object with the attributes ``status``,
``headerlist`` and ``app_iter``), any renderer associated with the view
configuration is ignored, and the response is passed back to :app:`Pyramid`
unmolested.  For example, if your view callable returns an instance of the
unchanged.  For example, if your view callable returns an instance of the
:class:`pyramid.httpexceptions.HTTPFound` class as a response, no renderer
will be employed.

@@ -351,7 +351,7 @@
  e.g. ``text/xml``.

``response_headerlist``
  A sequence of tuples describing cookie values that should be set in the
  A sequence of tuples describing header values that should be set in the
  response, e.g. ``[('Set-Cookie', 'abc=123'), ('X-My-Header', 'foo')]``.

``response_status``
@@ -499,8 +499,8 @@
has a ``name`` attribute that does not contain a dot, the full ``name``
value is used to construct a renderer from the associated renderer
factory.  In this case, the view configuration will create an instance
of an ``AMFRenderer`` for each view configuration which includes ``amf``
as its renderer value.  The ``name`` passed to the ``AMFRenderer``
of an ``MyAMFRenderer`` for each view configuration which includes ``amf``
as its renderer value.  The ``name`` passed to the ``MyAMFRenderer``
constructor will always be ``amf``.

Here's an example of the registration of a more complicated renderer
@@ -533,9 +533,9 @@
renderer factory for the configured view.  Then the value of
``renderer`` is passed to the factory to create a renderer for the view.
In this case, the view configuration will create an instance of a
``Jinja2Renderer`` for each view configuration which includes anything
``MyJinja2Renderer`` for each view configuration which includes anything
ending with ``.jinja2`` in its ``renderer`` value.  The ``name`` passed
to the ``Jinja2Renderer`` constructor will be the full value that was
to the ``MyJinja2Renderer`` constructor will be the full value that was
set as ``renderer=`` in the view configuration.

Changing an Existing Renderer

 docs/narr/security.rst

@@ -193,11 +193,11 @@

When a default permission is registered:

- if a view configuration names an explicit ``permission``, the default
- If a view configuration names an explicit ``permission``, the default
  permission is ignored for that view registration, and the
  view-configuration-named permission is used.

- if a view configuration names an explicit permission as the string
- If a view configuration names an explicit permission as the string
  ``__no_permission_required__``, the default permission is ignored,
  and the view is registered *without* a permission (making it
  available to all callers regardless of their credentials).
@@ -460,7 +460,7 @@
In order to allow the security machinery to perform ACL inheritance, resource
objects must provide *location-awareness*.  Providing *location-awareness*
means two things: the root object in the resource tree must have a
``_name__`` attribute and a ``__parent__`` attribute.
``__name__`` attribute and a ``__parent__`` attribute.

.. code-block:: python
   :linenos:

 docs/narr/templates.rst

@@ -734,12 +734,8 @@
.. code-block:: xml
   :linenos:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml"
          xmlns:tal="http://xml.zope.org/namespaces/tal">
    <html>
    <head>
        <meta http-equiv="content-type" content="text/html; charset=utf-8" />
        <title>${project} Application</title>
    </head>
      <body>
@@ -751,7 +747,7 @@
    </html>

This template doesn't use any advanced features of Mako, only the
``${squiggly}`` replacement syntax for names that are passed in as
``${}`` replacement syntax for names that are passed in as
:term:`renderer globals`.  See the `the Mako documentation
<http://www.makotemplates.org/>`_ to use more advanced features.


 docs/narr/traversal.rst

@@ -355,7 +355,7 @@
- :mod:`traversal` traverses "foo", and attempts to find "bar", which it
  finds.

- :mod:`traversal` traverses bar, and attempts to find "baz", which it does
- :mod:`traversal` traverses "bar", and attempts to find "baz", which it does
  not find (the "bar" resource raises a :exc:`KeyError` when asked for
  "baz").


 docs/narr/urldispatch.rst

@@ -373,7 +373,7 @@
supply a different :term:`context` resource object to the view related to
each particular route.

Supplying a different resource factory each route is useful when you're
Supplying a different resource factory for each route is useful when you're
trying to use a :app:`Pyramid` :term:`authorization policy` to provide
declarative, "context sensitive" security checks; each resource can maintain
a separate :term:`ACL`, as documented in
@@ -805,8 +805,9 @@
   url = route_url('foo', request, a='1', b='2', c='3')

This would return something like the string ``http://example.com/1/2/3`` (at
least if the current protocol and hostname implied ``http:/example.com``).
See the :func:`~pyramid.url.route_url` API documentation for more information.
least if the current protocol and hostname implied ``http://example.com``).
See the :func:`~pyramid.url.route_url` API documentation for more
information.

.. index::
   single: redirecting to slash-appended routes

 docs/narr/viewconfig.rst

@@ -155,7 +155,7 @@

  The ``renderer`` attribute is optional.  If it is not defined, the "null"
  renderer is assumed (no rendering is performed and the value is passed back
  to the upstream :app:`Pyramid` machinery unmolested).  Note that if the
  to the upstream :app:`Pyramid` machinery unchanged).  Note that if the
  view callable itself returns a :term:`response` (see :ref:`the_response`),
  the specified renderer implementation is never called.

@@ -176,7 +176,7 @@
  If ``wrapper`` is not supplied, no wrapper view is used.

``decorator``
  A :term:`dotted Python name` to function (or the function itself) which
  A :term:`dotted Python name` to a function (or the function itself) which
  will be used to decorate the registered :term:`view callable`.  The
  decorator function will be called with the view callable as a single
  argument.  The view callable it is passed will accept ``(context,
@@ -242,7 +242,7 @@
  *This is an advanced feature, not often used by "civilians"*.

``request_method``
  This value can either be one of the strings ``GET``, ``POST``, ``PUT``,
  This value can be one of the strings ``GET``, ``POST``, ``PUT``,
  ``DELETE``, or ``HEAD`` representing an HTTP ``REQUEST_METHOD``.  A view
  declaration with this argument ensures that the view will only be called
  when the request's ``method`` attribute (aka the ``REQUEST_METHOD`` of the
@@ -399,7 +399,7 @@
.. code-block:: python
   :linenos:

   config.add_view('.views.my_view', name='my_view', request_method='POST', 
   config.add_view('mypackage.views.my_view', name='my_view', request_method='POST', 
                   context=MyResource, permission='read')

All arguments to ``view_config`` may be omitted.  For example:
@@ -423,9 +423,9 @@
The mere existence of a ``@view_config`` decorator doesn't suffice to perform
view configuration.  All that the decorator does is "annotate" the function
with your configuration declarations, it doesn't process them. To make
:app:`Pyramid` process your :class:`~pyramid.view.view_config` declarations,
you *must* do use the ``scan`` method of a
:class:`~pyramid.config.Configurator`:
:app:`Pyramid` process your :class:`pyramid.view.view_config` declarations,
you *must* use the ``scan`` method of a
:class:`pyramid.config.Configurator`:

.. code-block:: python
   :linenos:

 docs/narr/views.rst

@@ -94,7 +94,7 @@
A view callable may also be represented by a Python class instead of a
function.  When a view callable is a class, the calling semantics are
slightly different than when it is a function or another non-class callable.
When a view callable is a class, the class' ``__init__`` is called with a
When a view callable is a class, the class' ``__init__`` method is called with a
``request`` parameter.  As a result, an instance of the class is created.
Subsequently, that instance's ``__call__`` method is invoked with no
parameters.  Views defined as classes must have the following traits:
@@ -122,13 +122,12 @@
described in :ref:`function_as_view`.

If you'd like to use a different attribute than ``__call__`` to represent the
method expected to return a response, you can either:

- use an ``attr`` value as part of the configuration for the view.  See
  :ref:`view_configuration_parameters`.  The same view callable class can be
  used in different view configuration statements with different ``attr``
  values, each pointing at a different method of the class if you'd like the
  class to represent a collection of related view callables.
method expected to return a response, you can use an ``attr`` value as part 
of the configuration for the view.  See :ref:`view_configuration_parameters`.
The same view callable class can be used in different view configuration 
statements with different ``attr`` values, each pointing at a different 
method of the class if you'd like the class to represent a collection of 
related view callables.

.. note:: A package named :term:`pyramid_handlers` (available from PyPI)
   provides an analogue of :term:`Pylons` -style "controllers", which are a
@@ -174,7 +173,7 @@
          return Response('OK')

#. Classes that have an ``__init__`` method that accepts ``context,
   request`` and a ``__call__`` which accepts no arguments, e.g.:
   request`` and a ``__call__`` method which accepts no arguments, e.g.:

   .. code-block:: python
      :linenos:
@@ -218,7 +217,7 @@
View Callable Responses
-----------------------

A view callable may always return an object that implements the :app:`Pyramid`
A view callable may return an object that implements the :app:`Pyramid`
:term:`Response` interface.  The easiest way to return something that
implements the :term:`Response` interface is to return a
:class:`pyramid.response.Response` object instance directly.  For example:
@@ -253,7 +252,7 @@
  world!</body></html>']`` or it can be a file-like object, or any
  other sort of iterable.

These attributes form the notional "Pyramid Response interface".
These attributes form the structure of the "Pyramid Response interface".

.. index::
   single: view http redirect
@@ -370,7 +369,7 @@

Assuming that a :term:`scan` was run to pick up this view registration, this
view callable will be invoked whenever a
``helloworld.exceptions.ValidationError`` is raised by your application's
``helloworld.exceptions.ValidationFailure`` is raised by your application's
view code.  The same exception raised by a custom root factory or a custom
traverser is also caught and hooked.


 docs/tutorials/wiki/basiclayout.rst

@@ -20,7 +20,7 @@

When you run the application using the ``paster`` command using the
``development.ini`` generated config file, the application configuration
points at an Setuptools *entry point* described as ``egg:tutorial``.  In our
points at a Setuptools *entry point* described as ``egg:tutorial``.  In our
application, because the application's ``setup.py`` file says so, this entry
point happens to be the ``main`` function within the file named
``__init__.py``:
@@ -181,7 +181,7 @@

The ``egg:WebError#evalerror`` middleware is at the "top" of the pipeline.
This is middleware which displays debuggable errors in the browser while
you're developing (not recommended for deployment).
you're developing (not recommended for a production system).

The ``egg:repoze.zodbconn#closer`` middleware is in the middle of the
pipeline.  This is a piece of middleware which closes the ZODB connection