clean up ".. warning" and ".. note" broken by docutils 0.8 upgrade ignore _...

Michael

2011-09-29 f361e493da2d0b5166bcd8f1507123dd9ca06e65

clean up ".. warning" and ".. note" broken by docutils 0.8 upgrade
ignore _themes/README.rst during docs compilation

 docs/conf.py

@@ -106,6 +106,10 @@
# List of documents that shouldn't be included in the build.
#unused_docs = []

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_themes/README.rst',]

# List of directories, relative to source directories, that shouldn't be searched
# for source files.
#exclude_dirs = []
@@ -381,7 +385,7 @@
% reset page counter
\setcounter{page}{1}
% suppress first toc pagenum
\addtocontents{toc}{\protect\thispagestyle{empty}} 
\addtocontents{toc}{\protect\thispagestyle{empty}}
""",
        format='latex')]

@@ -394,7 +398,7 @@
% allow part/chapter/section numbering
\setcounter{secnumdepth}{2}
% get headers back
\pagestyle{fancy} 
\pagestyle{fancy}
\fancyhf{}
\renewcommand{\headrulewidth}{0.5pt}
\renewcommand{\footrulewidth}{0pt}

 docs/designdefense.rst

@@ -245,14 +245,14 @@
abandoned and it is not used in :app:`Pyramid`.  We continued to use a ZCA
registry within :app:`Pyramid` because it ultimately proved a better fit.

.. note:: We continued using ZCA registry rather than disusing it in
   favor of using the registry implementation in
   :mod:`repoze.component` largely because the ZCA concept of
   interfaces provides for use of an interface hierarchy, which is
   useful in a lot of scenarios (such as context type inheritance).
   Coming up with a marker type that was something like an interface
   that allowed for this functionality seemed like it was just
   reinventing the wheel.
.. note::

   We continued using ZCA registry rather than disusing it in favor of using the
   registry implementation in :mod:`repoze.component` largely because the ZCA
   concept of interfaces provides for use of an interface hierarchy, which is
   useful in a lot of scenarios (such as context type inheritance).  Coming up
   with a marker type that was something like an interface that allowed for this
   functionality seemed like it was just reinventing the wheel.

Making framework developers and extenders understand the ZCA registry API is
a trade-off.  We (the :app:`Pyramid` developers) like the features that the
@@ -406,7 +406,7 @@
   :linenos:

   from pyramid.view import view_config
   @view_config(name='post_view', request_method='POST', 
   @view_config(name='post_view', request_method='POST',
                accept='application/json', renderer='json')
   def post_view(request):
       return 'POSTed'
@@ -791,12 +791,12 @@
    often via a registered handler or callback and converts the event
    into appropriate user action, understandable for the model.

    The controller notifies the model of the user action, possibly  
    The controller notifies the model of the user action, possibly
    resulting in a change in the model's state. (For example, the
    controller updates the user's shopping cart.)[5]

    A view queries the model in order to generate an appropriate
    user interface (for example, the view lists the shopping cart's     
    user interface (for example, the view lists the shopping cart's
    contents). Note that the view gets its own data from the model.

    The controller may (in some implementations) issue a general
@@ -1101,7 +1101,7 @@

.. code-block:: text

    [chrism@thinko]$ python app.py 
    [chrism@thinko]$ python app.py
    [<function foo at 0x7f4ea41ab1b8>,
     <function foo at 0x7f4ea41ab230>,
     <function bar at 0x7f4ea41ab2a8>]
@@ -1402,7 +1402,7 @@
            else:
                error = 'Invalid username/password'
        # this is executed if the request method was GET or the
        # credentials were invalid    
        # credentials were invalid

The `Pylons 1.X <http://pylonsproject.org>`_ web framework uses a similar
strategy.  It calls these things "Stacked Object Proxies", so, for purposes
@@ -1502,7 +1502,7 @@

   def hello_world(request):  # accepts a request; no request thread local reqd
       # explicit response object means no response threadlocal
       return Response('Hello world!') 
       return Response('Hello world!')

   if __name__ == '__main__':
       from pyramid.config import Configurator

 docs/narr/assets.rst

@@ -98,10 +98,12 @@
mechanism makes a directory of static files available at a name relative to
the application root URL, e.g. ``/static`` or as an external URL.

.. note:: :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a
   single file, nor can it serve a directory of static files directly
   relative to the root URL of a :app:`Pyramid` application.  For these
   features, see :ref:`advanced_static`.
.. note::

   :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a single
   file, nor can it serve a directory of static files directly relative to the
   root URL of a :app:`Pyramid` application.  For these features, see
   :ref:`advanced_static`.

Here's an example of a use of
:meth:`~pyramid.config.Configurator.add_static_view` that will serve files up
@@ -170,7 +172,7 @@
   :linenos:

   # config is an instance of pyramid.config.Configurator
   config.add_static_view(name='http://example.com/images', 
   config.add_static_view(name='http://example.com/images',
                          path='mypackage:images')

Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with
@@ -250,7 +252,7 @@
.. code-block:: python
   :linenos:

   config.add_static_view(name='http://example.com/images', 
   config.add_static_view(name='http://example.com/images',
                          path='mypackage:images')

Under such a configuration, the URL generated by ``static_url`` for
@@ -305,7 +307,9 @@
:meth:`~pyramid.config.Configurator.add_static_view` configuration method, so
its behavior is almost exactly the same once it's configured.

.. warning:: The following example *will not work* for applications that use
.. warning::

   The following example *will not work* for applications that use
   :term:`traversal`, it will only work if you use :term:`URL dispatch`
   exclusively.  The root-relative route we'll be registering will always be
   matched before traversal takes place, subverting any views registered via
@@ -384,7 +388,7 @@
.. code-block:: python
   :linenos:

   config.add_route('favicon', '/favicon.ico', 
   config.add_route('favicon', '/favicon.ico',
                    view='myapp.views.favicon_view')

Because this is a simple view callable, it can be protected with a

 docs/narr/firstapp.rst

@@ -120,11 +120,13 @@
passed to the ``Response`` constructor as the *body* of the response.  In the
``goodbye_world`` function, the string ``'Goodbye world!'`` is passed.

.. note:: As we'll see in later chapters, returning a literal
   :term:`response` object from a view callable is not always required; we
   can instead use a :term:`renderer` in our view configurations.  If we use
   a renderer, our view callable is allowed to return a value that the
   renderer understands, and the renderer generates a response on our behalf.
.. note::

   As we'll see in later chapters, returning a literal :term:`response` object
   from a view callable is not always required; we can instead use a
   :term:`renderer` in our view configurations.  If we use a renderer, our view
   callable is allowed to return a value that the renderer understands, and the
   renderer generates a response on our behalf.

.. index::
   single: imperative configuration

 docs/narr/hooks.rst

@@ -55,18 +55,21 @@
   def notfound_view(request):
       return HTTPNotFound()

.. note:: When a NotFound view callable is invoked, it is passed a
   :term:`request`.  The ``exception`` attribute of the request will
   be an instance of the :exc:`~pyramid.exceptions.NotFound`
   exception that caused the not found view to be called.  The value
   of ``request.exception.args[0]`` will be a value explaining why the
   not found error was raised.  This message will be different when
   the ``debug_notfound`` environment setting is true than it is when
   it is false.
.. note::

.. warning:: When a NotFound view callable accepts an argument list as
   described in :ref:`request_and_context_view_definitions`, the ``context``
   passed as the first argument to the view callable will be the
   When a NotFound view callable is invoked, it is passed a :term:`request`.
   The ``exception`` attribute of the request will be an instance of the
   :exc:`~pyramid.exceptions.NotFound` exception that caused the not found view
   to be called.  The value of ``request.exception.args[0]`` will be a value
   explaining why the not found error was raised.  This message will be
   different when the ``debug_notfound`` environment setting is true than it is
   when it is false.

.. warning::

   When a NotFound view callable accepts an argument list as described in
   :ref:`request_and_context_view_definitions`, the ``context`` passed as the
   first argument to the view callable will be the
   :exc:`~pyramid.exceptions.NotFound` exception instance.  If available, the
   resource context will still be available as ``request.context``.

@@ -120,14 +123,15 @@
   def forbidden_view(request):
       return Response('forbidden')

.. note:: When a forbidden view callable is invoked, it is passed a
   :term:`request`.  The ``exception`` attribute of the request will
   be an instance of the :exc:`~pyramid.exceptions.Forbidden`
   exception that caused the forbidden view to be called.  The value
   of ``request.exception.args[0]`` will be a value explaining why the
   forbidden was raised.  This message will be different when the
   ``debug_authorization`` environment setting is true than it is when
   it is false.
.. note::

   When a forbidden view callable is invoked, it is passed a :term:`request`.
   The ``exception`` attribute of the request will be an instance of the
   :exc:`~pyramid.exceptions.Forbidden` exception that caused the forbidden view
   to be called.  The value of ``request.exception.args[0]`` will be a value
   explaining why the forbidden was raised.  This message will be different when
   the ``debug_authorization`` environment setting is true than it is when it is
   false.

.. index::
   single: request factory
@@ -484,7 +488,7 @@
   from myapp.traversal import URLGenerator
   from myapp.resources import MyRoot

   config.registry.registerAdapter(URLGenerator, (MyRoot, Interface), 
   config.registry.registerAdapter(URLGenerator, (MyRoot, Interface),
                                   IContextURL)

In the above example, the ``myapp.traversal.URLGenerator`` class will be used
@@ -647,9 +651,9 @@
   import venusian
   from pyramid.threadlocal import get_current_registry
   from mypackage.interfaces import IMyUtility
    

   class registerFunction(object):
        

       def __init__(self, path):
           self.path = path

@@ -658,11 +662,11 @@
           registry.getUtility(IMyUtility).register(
               self.path, wrapped
               )
        

       def __call__(self, wrapped):
           venusian.attach(wrapped, self.register)
           return wrapped
    

This decorator could then be used to register functions throughout
your code:


 docs/narr/i18n.rst

@@ -95,7 +95,7 @@
   :linenos:

   from pyramid.i18n import TranslationString
   ts = TranslationString('Add ${number}', mapping={'number':1}, 
   ts = TranslationString('Add ${number}', mapping={'number':1},
                          domain='form')

The above translation string named a domain of ``form``.  A
@@ -170,7 +170,7 @@
   :linenos:

   from pyramid.i18n import TranslationString as _
   ts = _('Add ${number}', msgid='add-number', mapping={'number':1}, 
   ts = _('Add ${number}', msgid='add-number', mapping={'number':1},
          domain='pyramid')

You can set up your own translation string factory much like the one
@@ -527,7 +527,7 @@
   from pyramid.i18n import get_localizer
   from pyramid.i18n import TranslationString

   ts = TranslationString('Add ${number}', mapping={'number':1}, 
   ts = TranslationString('Add ${number}', mapping={'number':1},
                          domain='pyramid')

   def aview(request):
@@ -542,9 +542,10 @@
``domain`` attribute of the provided translation string as well as the
locale of the localizer.

.. note:: If you're using :term:`Chameleon` templates, you don't need
   to pre-translate translation strings this way.  See
   :ref:`chameleon_translation_strings`.
.. note::

   If you're using :term:`Chameleon` templates, you don't need to pre-translate
   translation strings this way.  See :ref:`chameleon_translation_strings`.

.. index::
   single: pluralizing (i18n)
@@ -836,7 +837,7 @@

.. code-block:: python
   :linenos:
    

   from pyramid.threadlocal import get_current_registry
   settings = get_current_registry().settings
   languages = settings['available_languages'].split()
@@ -889,7 +890,7 @@
   :linenos:

   from pyramid.config import Configurator
   config.add_translation_dirs('my.application:locale/', 
   config.add_translation_dirs('my.application:locale/',
                               'another.application:locale/')

A message catalog in a translation directory added via

 docs/narr/install.rst

@@ -10,7 +10,7 @@
------------------

You will need `Python <http://python.org>`_ version 2.4 or better to
run :app:`Pyramid`.  
run :app:`Pyramid`.

.. sidebar:: Python Versions

@@ -143,7 +143,7 @@
.. code-block:: text

   [chrism@vitaminf pyramid]$ python
   Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
   Python 2.4.5 (#1, Aug 29 2008, 12:27:37)
   [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import setuptools
@@ -221,14 +221,15 @@
   New python executable in env/bin/python
   Installing setuptools.............done.

.. warning:: Using ``--no-site-packages`` when generating your
   virtualenv is *very important*. This flag provides the necessary
   isolation for running the set of packages required by
   :app:`Pyramid`.  If you do not specify ``--no-site-packages``,
   it's possible that :app:`Pyramid` will not install properly into
   the virtualenv, or, even if it does, may not run properly,
   depending on the packages you've already got installed into your
   Python's "main" site-packages dir.
.. warning::

   Using ``--no-site-packages`` when generating your virtualenv is *very
   important*. This flag provides the necessary isolation for running the set of
   packages required by :app:`Pyramid`.  If you do not specify
   ``--no-site-packages``, it's possible that :app:`Pyramid` will not install
   properly into the virtualenv, or, even if it does, may not run properly,
   depending on the packages you've already got installed into your Python's
   "main" site-packages dir.

.. warning:: If you're on UNIX, *do not* use ``sudo`` to run the
   ``virtualenv`` script.  It's perfectly acceptable (and desirable)

 docs/narr/muchadoabouttraversal.rst

@@ -12,7 +12,7 @@
:app:`Pyramid` applications to map URLs to code.

.. note::
   

   Ex-Zope users whom are already familiar with traversal and view lookup
   conceptually may want to skip directly to the :ref:`traversal_chapter`
   chapter, which discusses technical details.  This chapter is mostly aimed
@@ -161,7 +161,7 @@
.. code-block:: text
   :linenos:

   Python 2.4.6 (#2, Apr 29 2010, 00:31:48) 
   Python 2.4.6 (#2, Apr 29 2010, 00:31:48)
   [GCC 4.4.3] on linux2
   Type "help", "copyright", "credits" or "license" for more information.
   >>> adict = {}
@@ -304,6 +304,8 @@
using :app:`Pyramid` and you ever find that you *do* need to support one of
these use cases, you'll be glad you have traversal in your toolkit.

.. note:: It is even possible to mix and match :term:`traversal` with
   :term:`URL dispatch` in the same :app:`Pyramid` application. See the
.. note::

   It is even possible to mix and match :term:`traversal` with :term:`URL
   dispatch` in the same :app:`Pyramid` application. See the
   :ref:`hybrid_chapter` chapter for details.

 docs/narr/resources.rst

@@ -160,14 +160,14 @@
just like if you keep executing the ``cd ..`` filesystem command, eventually
you will reach the filesystem root directory.

.. warning:: If your root resource has a ``__name__`` argument
   that is not ``None`` or the empty string, URLs returned by the
   :func:`~pyramid.url.resource_url` function and paths generated by
   the :func:`~pyramid.traversal.resource_path` and
   :func:`~pyramid.traversal.resource_path_tuple` APIs will be
   generated improperly.  The value of ``__name__`` will be prepended
   to every path and URL generated (as opposed to a single leading
   slash or empty tuple element).
.. warning::

   If your root resource has a ``__name__`` argument that is not ``None`` or the
   empty string, URLs returned by the :func:`~pyramid.url.resource_url` function
   and paths generated by the :func:`~pyramid.traversal.resource_path` and
   :func:`~pyramid.traversal.resource_path_tuple` APIs will be generated
   improperly.  The value of ``__name__`` will be prepended to every path and
   URL generated (as opposed to a single leading slash or empty tuple element).

.. sidebar::  Using :mod:`pyramid_traversalwrapper`

@@ -428,7 +428,7 @@

.. code-block:: python
   :linenos:
    

   list(lineage(thing2))
   [ <Thing object at thing2>, <Thing object at thing1> ]


 docs/narr/templates.rst

@@ -42,21 +42,22 @@
   from pyramid.renderers import render_to_response

   def sample_view(request):
       return render_to_response('templates/foo.pt', 
                                 {'foo':1, 'bar':2}, 
       return render_to_response('templates/foo.pt',
                                 {'foo':1, 'bar':2},
                                 request=request)

.. warning:: Earlier iterations of this documentation
   (pre-version-1.3) encouraged the application developer to use
   ZPT-specific APIs such as
.. warning::

   Earlier iterations of this documentation (pre-version-1.3) encouraged the
   application developer to use ZPT-specific APIs such as
   :func:`pyramid.chameleon_zpt.render_template_to_response` and
   :func:`pyramid.chameleon_zpt.render_template` to render templates
   directly.  This style of rendering still works, but at least for
   purposes of this documentation, those functions are deprecated.
   Application developers are encouraged instead to use the functions
   available in the :mod:`pyramid.renderers` module to perform
   rendering tasks.  This set of functions works to render templates
   for all renderer extensions registered with :app:`Pyramid`.
   :func:`pyramid.chameleon_zpt.render_template` to render templates directly.
   This style of rendering still works, but at least for purposes of this
   documentation, those functions are deprecated.  Application developers are
   encouraged instead to use the functions available in the
   :mod:`pyramid.renderers` module to perform rendering tasks.  This set of
   functions works to render templates for all renderer extensions registered
   with :app:`Pyramid`.

The ``sample_view`` :term:`view callable` function above returns a
:term:`response` object which contains the body of the
@@ -128,8 +129,8 @@
which use a :term:`renderer` named via view configuration (which we'll
see shortly).  The :func:`pyramid.renderers.render_to_response`
function is a shortcut function that actually returns a response
object. This allows the example view above to simply return the result 
of its call to ``render_to_response()`` directly. 
object. This allows the example view above to simply return the result
of its call to ``render_to_response()`` directly.

Obviously not all APIs you might call to get response data will return a
response object. For example, you might render one or more templates to
@@ -145,8 +146,8 @@
   from pyramid.response import Response

   def sample_view(request):
       result = render('mypackage:templates/foo.pt', 
                       {'foo':1, 'bar':2}, 
       result = render('mypackage:templates/foo.pt',
                       {'foo':1, 'bar':2},
                       request=request)
       response = Response(result)
       return response
@@ -229,7 +230,7 @@

   def sample_view(request):
       result = render('mypackage:templates/foo.pt',
                       {'foo':1, 'bar':2}, 
                       {'foo':1, 'bar':2},
                       request=request)
       response = Response(result)
       response.content_type = 'text/plain'
@@ -263,7 +264,7 @@
  The renderer name used to perform the rendering,
  e.g. ``mypackage:templates/foo.pt``.

``renderer_info`` 
``renderer_info``
  An object implementing the :class:`pyramid.interfaces.IRendererInfo`
  interface.  Basically, an object with the following attributes:
  ``name``, ``package`` and ``type``.
@@ -285,7 +286,7 @@
An alternative to using :func:`~pyramid.renderers.render_to_response`
to render templates manually in your view callable code, is
to specify the template as a :term:`renderer` in your
*view configuration*. This can be done with any of the 
*view configuration*. This can be done with any of the
templating languages supported by :app:`Pyramid`.

To use a renderer via view configuration, specify a template
@@ -401,7 +402,7 @@
templates is available from `the Chameleon website
<http://chameleon.repoze.org/>`_.

.. warning:: 
.. warning::

   :term:`Chameleon` only works on :term:`CPython` platforms and
   :term:`Google App Engine`.  On :term:`Jython` and other non-CPython
@@ -437,7 +438,7 @@
.. code-block:: xml
   :linenos:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
    <!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">
@@ -500,7 +501,7 @@
.. code-block:: xml
   :linenos:

    <html xmlns="http://www.w3.org/1999/xhtml" 
    <html xmlns="http://www.w3.org/1999/xhtml"
          xmlns:tal="http://xml.zope.org/namespaces/tal"
          xmlns:metal="http://xml.zope.org/namespaces/metal">
      <span metal:define-macro="hello">
@@ -515,7 +516,7 @@
.. code-block:: xml
   :linenos:

    <html xmlns="http://www.w3.org/1999/xhtml" 
    <html xmlns="http://www.w3.org/1999/xhtml"
          xmlns:tal="http://xml.zope.org/namespaces/tal"
          xmlns:metal="http://xml.zope.org/namespaces/metal">
      <span metal:use-macro="main.macros['hello']">
@@ -734,7 +735,7 @@
.. code-block:: xml
   :linenos:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
    <!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">
@@ -807,7 +808,7 @@

Jinja2 template bindings are available for :app:`Pyramid` in the
``pyramid_jinja2`` package. You can get the latest release of
this package from the 
this package from the
`Python package index <http://pypi.python.org/pypi/pyramid_jinja2>`_
(pypi).


 docs/narr/urldispatch.rst

@@ -10,7 +10,7 @@
code using a simple pattern matching language.  An ordered set of
patterns is checked one-by-one.  If one of the patterns matches the path
information associated with a request, a particular :term:`view
callable` is invoked.  
callable` is invoked.

:term:`URL dispatch` is one of two ways to perform :term:`resource
location` in :app:`Pyramid`; the other way is using :term:`traversal`.
@@ -118,7 +118,7 @@
   # "config" below is presumed to be an instance of the
   # pyramid.config.Configurator class; "myview" is assumed
   # to be a "view callable" function
   config.add_route('myroute', '/prefix/{one}/{two}', 
   config.add_route('myroute', '/prefix/{one}/{two}',
                    view='myproject.views.myview')

When a route configuration names a ``view`` attribute, the :term:`view
@@ -200,7 +200,7 @@
To capture both segments, two replacement markers can be used:

.. code-block:: text
    

    foo/{name}.{ext}

The literal path ``/foo/biz.html`` will match the above route pattern, and
@@ -266,10 +266,10 @@

.. code-block:: text

   foo/1/2/           -> 
   foo/1/2/           ->
            {'baz':u'1', 'bar':u'2', 'fizzle':()}

   foo/abc/def/a/b/c  -> 
   foo/abc/def/a/b/c  ->
            {'baz':u'abc', 'bar':u'def', 'fizzle':(u'a', u'b', u'c')}

Note that when a ``*stararg`` remainder match is matched, the value put into
@@ -298,7 +298,7 @@
also capture the remainder of the URL, for example:

.. code-block:: text
    

    foo/{baz}/{bar}{fizzle:.*}

The above pattern will match these URLs, generating the following matchdicts:
@@ -363,7 +363,7 @@
.. code-block:: python
   :linenos:

   config.add_route('abc', '/abc', view='myproject.views.theview', 
   config.add_route('abc', '/abc', view='myproject.views.theview',
                    factory='myproject.resources.root_factory')

The factory can either be a Python object or a :term:`dotted Python name` (a
@@ -430,7 +430,7 @@

   num_one_two_or_three = any_of('num', 'one', 'two', 'three')

   config.add_route('num', '/{num}', 
   config.add_route('num', '/{num}',
                    custom_predicates=(num_one_two_or_three,))

The above ``any_of`` function generates a predicate which ensures that the
@@ -461,7 +461,7 @@

    ymd_to_int = integers('year', 'month', 'day')

    config.add_route('num', '/{year}/{month}/{day}', 
    config.add_route('num', '/{year}/{month}/{day}',
                     custom_predicates=(ymd_to_int,))

Note that a conversion predicate is still a predicate so it must return
@@ -484,7 +484,7 @@

    ymd_to_int = integers('year', 'month', 'day')

    config.add_route('num', '/{year:\d+}/{month:\d+}/{day:\d+}', 
    config.add_route('num', '/{year:\d+}/{month:\d+}/{day:\d+}',
                     custom_predicates=(ymd_to_int,))

Now the try/except is no longer needed because the route will not match at
@@ -522,7 +522,7 @@

    config.add_route('y', '/{year}', custom_predicates=(twenty_ten,))
    config.add_route('ym', '/{year}/{month}', custom_predicates=(twenty_ten,))
    config.add_route('ymd', '/{year}/{month}/{day}', 
    config.add_route('ymd', '/{year}/{month}/{day}',
                     custom_predicates=(twenty_ten,))

The above predicate, when added to a number of route configurations ensures
@@ -717,7 +717,7 @@
.. code-block:: python
   :linenos:

   config.add_route('idea', 'ideas/{idea}', 
   config.add_route('idea', 'ideas/{idea}',
                    view='myproject.views.idea_view',
                    factory='myproject.resources.Idea')

@@ -835,7 +835,7 @@

   config.add_route('noslash', 'no_slash',
                    view='myproject.views.no_slash')
   config.add_route('hasslash', 'has_slash/', 
   config.add_route('hasslash', 'has_slash/',
                    view='myproject.views.has_slash')

If a request enters the application with the ``PATH_INFO`` value of
@@ -911,7 +911,7 @@
---------------------------

Sometimes it's required that some cleanup be performed at the end of a
request when a database connection is involved.  
request when a database connection is involved.

For example, let's say you have a ``mypackage`` :app:`Pyramid` application
package that uses SQLAlchemy, and you'd like the current SQLAlchemy database
@@ -985,8 +985,10 @@
match dict to see if the ``article`` argument matches a particular string;
our sample ``Article`` factory class is not very ambitious.

.. note:: See :ref:`security_chapter` for more information about
   :app:`Pyramid` security and ACLs.
.. note::

   See :ref:`security_chapter` for more information about :app:`Pyramid`
   security and ACLs.

.. _debug_routematch_section:

@@ -1005,7 +1007,7 @@
   :linenos:

    [chrism@thinko pylonsbasic]$ PYRAMID_DEBUG_ROUTEMATCH=true \
                                 bin/paster serve development.ini 
                                 bin/paster serve development.ini
    Starting server in PID 13586.
    serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
    2010-12-16 14:45:19,956 no route matched for url \
@@ -1042,10 +1044,10 @@

   [chrism@thinko MyProject]$ ../bin/paster proutes development.ini MyProject
   Name            Pattern                        View
   ----            -------                        ----                     
   ----            -------                        ----
   home            /                              <function my_view>
   home2           /                              <function my_view>
   another         /another                       None                     
   another         /another                       None
   static/         static/*subpath                <static_view object>
   catchall        /*subpath                      <function static_view>


 docs/tutorials/wiki/definingviews.rst

@@ -232,15 +232,16 @@
.. literalinclude:: src/views/tutorial/templates/view.pt
   :language: xml

.. note:: The names available for our use in a template are always those that
   are present in the dictionary returned by the view callable.  But our
   templates make use of a ``request`` object that none of our tutorial views
   return in their dictionary.  This value appears as if "by magic".
   However, ``request`` is one of several names that are available "by
   default" in a template when a template renderer is used.  See
   :ref:`chameleon_template_renderers` for more information about other names
   that are available by default in a template when a template is used as a
   renderer.
.. note::

   The names available for our use in a template are always those that are
   present in the dictionary returned by the view callable.  But our templates
   make use of a ``request`` object that none of our tutorial views return in
   their dictionary.  This value appears as if "by magic".  However, ``request``
   is one of several names that are available "by default" in a template when a
   template renderer is used.  See :ref:`chameleon_template_renderers` for more
   information about other names that are available by default in a template
   when a template is used as a renderer.

The ``edit.pt`` Template
------------------------
@@ -317,7 +318,7 @@
   .........
   ----------------------------------------------------------------------
   Ran 9 tests in 0.203s
   

   OK

Viewing the Application in a Browser

 docs/tutorials/wiki2/definingviews.rst

@@ -7,18 +7,18 @@
accepts a single parameter named :term:`request`.  A view callable is
assumed to return a :term:`response` object.

.. note:: A :app:`Pyramid` view can also be defined as callable
   which accepts *two* arguments: a :term:`context` and a
   :term:`request`.  You'll see this two-argument pattern used in
   other :app:`Pyramid` tutorials and applications.  Either calling
   convention will work in any :app:`Pyramid` application; the
   calling conventions can be used interchangeably as necessary.  In
   :term:`url dispatch` based applications, however, the context
   object is rarely used in the view body itself, so within this
   tutorial we define views as callables that accept only a request to
   avoid the visual "noise".  If you do need the ``context`` within a
   view function that only takes the request as a single argument, you
   can obtain it via ``request.context``.
.. note::

   A :app:`Pyramid` view can also be defined as callable which accepts *two*
   arguments: a :term:`context` and a :term:`request`.  You'll see this
   two-argument pattern used in other :app:`Pyramid` tutorials and applications.
   Either calling convention will work in any :app:`Pyramid` application; the
   calling conventions can be used interchangeably as necessary.  In :term:`url
   dispatch` based applications, however, the context object is rarely used in
   the view body itself, so within this tutorial we define views as callables
   that accept only a request to avoid the visual "noise".  If you do need the
   ``context`` within a view function that only takes the request as a single
   argument, you can obtain it via ``request.context``.

The request passed to every view that is called as the result of a route
match has an attribute named ``matchdict`` that contains the elements placed
@@ -350,7 +350,7 @@
   writing top-level names to tutorial.egg-info/top_level.txt
   writing dependency_links to tutorial.egg-info/dependency_links.txt
   writing entry points to tutorial.egg-info/entry_points.txt
   unrecognized .svn/entries format in 
   unrecognized .svn/entries format in
   reading manifest file 'tutorial.egg-info/SOURCES.txt'
   writing manifest file 'tutorial.egg-info/SOURCES.txt'
   running build_ext
@@ -362,4 +362,4 @@



   


 pyramid/chameleon_text.py

@@ -6,7 +6,7 @@
try:
    from chameleon.zpt.template import PageTextTemplateFile
    # prevent pyflakes complaining about a redefinition below
    PageTextTemplateFile 
    PageTextTemplateFile
except ImportError: # pragma: no cover
    exc_class, exc, tb = sys.exc_info()
    # Chameleon doesn't work on non-CPython platforms
@@ -41,7 +41,7 @@

    def implementation(self):
        return self.template
    

    def __call__(self, value, system):
        try:
            system.update(value)
@@ -56,7 +56,7 @@
    ``path`` argument.  The ``path`` argument may be a
    package-relative path, an absolute path, or a :term:`asset
    specification`.
    

    .. warning:: This API is deprecated in :app:`Pyramid` 1.0.  Use
       :func:`pyramid.renderers.get_renderer` instead.
    """
@@ -75,8 +75,10 @@
    The ``path`` argument may be a package-relative path, an absolute
    path, or a :term:`asset specification`.

    .. warning:: This API is deprecated in :app:`Pyramid` 1.0.  Use
       the ``implementation()`` method of a template renderer retrieved via
    .. warning::

       This API is deprecated in :app:`Pyramid` 1.0.  Use the
       ``implementation()`` method of a template renderer retrieved via
       :func:`pyramid.renderers.get_renderer` instead.
    """
    package = caller_package()
@@ -97,7 +99,9 @@
    names to the template, and so may be used within the template
    itself.  Returns a string.

    .. warning:: This API is deprecated in :app:`Pyramid` 1.0.  Use
    .. warning::

       This API is deprecated in :app:`Pyramid` 1.0.  Use
       :func:`pyramid.renderers.render` instead.
    """
    package = caller_package()
@@ -119,7 +123,9 @@
    itself.  Returns a :term:`Response` object with the body as the
    template result.

    .. warning:: This API is deprecated in :app:`Pyramid` 1.0.  Use
    .. warning::

       This API is deprecated in :app:`Pyramid` 1.0.  Use
       :func:`pyramid.renderers.render_to_response` instead.
    """
    package = caller_package()

 pyramid/chameleon_zpt.py

@@ -21,7 +21,7 @@
from pyramid import renderers

registry_lock = threading.Lock()
    

def renderer_factory(info, lock=registry_lock):
    return renderers.template_renderer_factory(info, ZPTTemplateRenderer)

@@ -43,7 +43,7 @@

    def implementation(self):
        return self.template
    

    def __call__(self, value, system):
        try:
            system.update(value)
@@ -58,7 +58,7 @@
    ``path`` argument.  The ``path`` argument may be a
    package-relative path, an absolute path, or a :term:`asset
    specification`.
    

    .. warning:: This API is deprecated in :app:`Pyramid` 1.0.  Use
       :func:`pyramid.renderers.get_renderer` instead.
    """
@@ -77,8 +77,10 @@
    The ``path`` argument may be a package-relative path, an absolute
    path, or a :term:`asset specification`.

    .. warning:: This API is deprecated in :app:`Pyramid` 1.0.  Use
       the ``implementation()`` method of a template renderer retrieved via
    .. warning::

       This API is deprecated in :app:`Pyramid` 1.0.  Use the
       ``implementation()`` method of a template renderer retrieved via
       :func:`pyramid.renderers.get_renderer` instead.
    """
    package = caller_package()
@@ -99,7 +101,9 @@
    names to the template, and so may be used within the template
    itself.  Returns a string.

    .. warning:: This API is deprecated in :app:`Pyramid` 1.0.  Use
    .. warning::

       This API is deprecated in :app:`Pyramid` 1.0.  Use
       :func:`pyramid.renderers.render` instead.
    """
    package = caller_package()
@@ -121,7 +125,9 @@
    itself.  Returns a :term:`Response` object with the body as the
    template result.

    .. warning:: This API is deprecated in :app:`Pyramid` 1.0.  Use
    .. warning::

       This API is deprecated in :app:`Pyramid` 1.0.  Use
       :func:`pyramid.renderers.render_to_response` instead.
    """
    package = caller_package()

 pyramid/config.py

@@ -50,7 +50,7 @@
    from pyramid import chameleon_text
except TypeError:  # pragma: no cover
    chameleon_text = None # pypy
try: 
try:
    from pyramid import chameleon_zpt
except TypeError: # pragma: no cover
    chameleon_zpt = None # pypy
@@ -336,7 +336,7 @@
        policy = self.maybe_dotted(policy)
        self.registry.registerUtility(policy, IAuthorizationPolicy)
        self.action(IAuthorizationPolicy, None)
            

    def _make_spec(self, path_or_spec):
        package, filename = resolve_asset_spec(path_or_spec,
                                               self.package_name)
@@ -378,7 +378,7 @@
                              package=self.package,
                              mapper=mapper,
                              decorator=decorator)
        

        return deriver(view)

    def _override(self, package, path, override_package, override_prefix,
@@ -510,7 +510,7 @@
        Python :term:`module`, in which case, the module will be searched for
        a callable named ``includeme``, which will be treated as the
        configuration callable.
        

        For example, if the ``includeme`` function below lives in a module
        named ``myapp.myconfig``:

@@ -592,7 +592,7 @@
        discriminators.  ``action_wrap`` will cause the directive to be
        wrapped in a decorator which provides more accurate conflict
        cause information.
        

        ``add_directive`` does not participate in conflict detection, and
        later calls to ``add_directive`` will override earlier calls.
        """
@@ -719,7 +719,7 @@
        if default_view_mapper is not None:
            self.set_view_mapper(default_view_mapper)
            self.commit()
        

    # getSiteManager is a unit testing dep injection
    def hook_zca(self, getSiteManager=None):
        """ Call :func:`zope.component.getSiteManager.sethook` with
@@ -1050,7 +1050,7 @@
          accept ``(context, request)``.  The decorator must return a
          replacement view callable which also accepts ``(context,
          request)``.
          

        mapper

          A Python object or :term:`dotted Python name` which refers to a
@@ -1059,7 +1059,7 @@
          plug-point is useful for Pyramid extension developers, but it's not
          very useful for 'civilians' who are just developing stock Pyramid
          applications. Pay no attention to the man behind the curtain.
          

        Predicate Arguments

        name
@@ -1091,11 +1091,12 @@
          by :term:`traversal` against the result of the route's
          :term:`root factory`.

          .. warning:: Using this argument services an advanced
             feature that isn't often used unless you want to perform
             traversal *after* a route has matched. See
             :ref:`hybrid_chapter` for more information on using this
             advanced feature.
          .. warning::

             Using this argument services an advanced feature that isn't often
             used unless you want to perform traversal *after* a route has
             matched. See :ref:`hybrid_chapter` for more information on using
             this advanced feature.

        request_type

@@ -1510,12 +1511,14 @@
          pattern doesn't match the current URL, route matching
          continues.

          .. note:: For backwards compatibility purposes (as of
             :app:`Pyramid` 1.0), a ``path`` keyword argument passed
             to this function will be used to represent the pattern
             value if the ``pattern`` argument is ``None``.  If both
             ``path`` and ``pattern`` are passed, ``pattern`` wins.
        
          .. note::

             For backwards compatibility purposes (as of :app:`Pyramid` 1.0), a
             ``path`` keyword argument passed to this function will be used to
             represent the pattern value if the ``pattern`` argument is
             ``None``.  If both ``path`` and ``pattern`` are passed, ``pattern``
             wins.

        xhr

          This value should be either ``True`` or ``False``.  If this
@@ -1829,7 +1832,7 @@
        # if name is None or the empty string, we're trying to register
        # a default renderer, but registerUtility is too dumb to accept None
        # as a name
        if not name: 
        if not name:
            name = ''
        # we need to register renderers eagerly because they are used during
        # view configuration
@@ -1892,11 +1895,12 @@
        """ Add a default forbidden view to the current configuration
        state.

        .. warning:: This method has been deprecated in :app:`Pyramid`
           1.0.  *Do not use it for new development; it should only be
           used to support older code bases which depend upon it.* See
           :ref:`changing_the_forbidden_view` to see how a forbidden
           view should be registered in new projects.
        .. warning::

           This method has been deprecated in :app:`Pyramid` 1.0.  *Do not use
           it for new development; it should only be used to support older code
           bases which depend upon it.* See :ref:`changing_the_forbidden_view`
           to see how a forbidden view should be registered in new projects.

        The ``view`` argument should be a :term:`view callable` or a
        :term:`dotted Python name` which refers to a view callable.
@@ -1930,12 +1934,12 @@
        """ Add a default not found view to the current configuration
        state.

        .. warning:: This method has been deprecated in
           :app:`Pyramid` 1.0.  *Do not use it for new development;
           it should only be used to support older code bases which
           depend upon it.* See :ref:`changing_the_notfound_view` to
           see how a not found view should be registered in new
           projects.
        .. warning::

           This method has been deprecated in :app:`Pyramid` 1.0.  *Do not use
           it for new development; it should only be used to support older code
           bases which depend upon it.* See :ref:`changing_the_notfound_view` to
           see how a not found view should be registered in new projects.

        The ``view`` argument should be a :term:`view callable` or a
        :term:`dotted Python name` which refers to a view callable.
@@ -1974,9 +1978,11 @@
        :class:`pyramid.request.Request` class (particularly
        ``__call__``, and ``blank``).

        .. note:: Using the :meth:``request_factory`` argument to the
           :class:`pyramid.config.Configurator` constructor
           can be used to achieve the same purpose.
        .. note::

           Using the :meth:``request_factory`` argument to the
           :class:`pyramid.config.Configurator` constructor can be used to
           achieve the same purpose.
        """
        factory = self.maybe_dotted(factory)
        def register():
@@ -1997,10 +2003,11 @@
        dictionary, and therefore will be made available to the code
        which uses the renderer.

        .. note:: Using the :meth:`renderer_globals_factory`
           argument to the
           :class:`pyramid.config.Configurator` constructor
           can be used to achieve the same purpose.
        .. note::

           Using the :meth:`renderer_globals_factory` argument to the
           :class:`pyramid.config.Configurator` constructor can be used to
           achieve the same purpose.
        """
        factory = self.maybe_dotted(factory)
        def register():
@@ -2022,9 +2029,11 @@
        application.  See :ref:`activating_translation` for more
        information.

        .. note:: Using the ``locale_negotiator`` argument to the
           :class:`pyramid.config.Configurator` constructor
           can be used to achieve the same purpose.
        .. note::

           Using the ``locale_negotiator`` argument to the
           :class:`pyramid.config.Configurator` constructor can be used to
           achieve the same purpose.
        """
        negotiator = self.maybe_dotted(negotiator)
        def register():
@@ -2064,9 +2073,11 @@

        See also :ref:`setting_a_default_permission`.

        .. note:: Using the ``default_permission`` argument to the
           :class:`pyramid.config.Configurator` constructor
           can be used to achieve the same purpose.
        .. note::

           Using the ``default_permission`` argument to the
           :class:`pyramid.config.Configurator` constructor can be used to
           achieve the same purpose.
        """
        # default permission used during view registration
        self.registry.registerUtility(permission, IDefaultPermission)
@@ -2088,7 +2099,7 @@
        used by all subsequent :term:`view configuration` registrations, as
        if you had passed a ``default_view_mapper`` argument to the
        :class:`pyramid.config.Configurator` constructor.
        

        See also :ref:`using_an_alternate_view_mapper`.
        """
        mapper = self.maybe_dotted(mapper)
@@ -2879,7 +2890,7 @@
        elif self.attr:
            mapped_view = self.map_nonclass_attr(view)
        return mapped_view
        

    def map_class_requestonly(self, view):
        # its a class that has an __init__ which only accepts request
        attr = self.attr

 pyramid/events.py

@@ -16,7 +16,7 @@
    For example:

    .. code-block:: python
    

       from pyramid.events import NewRequest
       from pyramid.events import subscriber

@@ -25,9 +25,9 @@
           event.request.foo = 1

    More than one event type can be passed as a construtor argument:
        

    .. code-block:: python
    

       from pyramid.events import NewRequest, NewResponse
       from pyramid.events import subscriber

@@ -39,7 +39,7 @@
    the function it decorates is called for every event sent:

    .. code-block:: python
    

       from pyramid.events import subscriber

       @subscriber()
@@ -50,7 +50,7 @@
    against the package or module which contains it, ala:

    .. code-block:: python
    

       from pyramid.config import Configurator
       config = Configurator()
       config.scan('somepackage_containing_subscribers')
@@ -130,17 +130,18 @@
    This class implements the
    :class:`pyramid.interfaces.IContextFound` interface.

    .. note:: As of :app:`Pyramid` 1.0, for backwards compatibility
       purposes, this event may also be imported as
       :class:`pyramid.events.AfterTraversal`.
    .. note::

       As of :app:`Pyramid` 1.0, for backwards compatibility purposes, this
       event may also be imported as :class:`pyramid.events.AfterTraversal`.
    """
    implements(IContextFound)
    def __init__(self, request):
        self.request = request

AfterTraversal = ContextFound # b/c as of 1.0
    
class ApplicationCreated(object):    

class ApplicationCreated(object):
    """ An instance of this class is emitted as an :term:`event` when
    the :meth:`pyramid.config.Configurator.make_wsgi_app` is
    called.  The instance has an attribute, ``app``, which is an
@@ -148,11 +149,11 @@
    This class implements the
    :class:`pyramid.interfaces.IApplicationCreated` interface.

    .. note:: For backwards compatibility purposes, this class can
       also be imported as
       :class:`pyramid.events.WSGIApplicationCreatedEvent`.  This
       was the name of the event class before :app:`Pyramid` 1.0.
    .. note::

       For backwards compatibility purposes, this class can also be imported as
       :class:`pyramid.events.WSGIApplicationCreatedEvent`.  This was the name
       of the event class before :app:`Pyramid` 1.0.
    """
    implements(IApplicationCreated)
    def __init__(self, app):
@@ -221,4 +222,4 @@
        """ Return the value for key ``k`` from the renderer globals
        dictionary, or the default if no such value exists."""
        return self._system.get(k)
            


 pyramid/interfaces.py

@@ -9,9 +9,11 @@
    documentation attached to :class:`pyramid.events.ContextFound`
    for more information.

    .. note:: For backwards compatibility with versions of
       :app:`Pyramid` before 1.0, this event interface can also be
       imported as :class:`pyramid.interfaces.IAfterTraversal`.
    .. note::

       For backwards compatibility with versions of :app:`Pyramid` before 1.0,
       this event interface can also be imported as
       :class:`pyramid.interfaces.IAfterTraversal`.
    """
    request = Attribute('The request object')

@@ -22,7 +24,7 @@
    begins to process a new request.  See the documentation attached
    to :class:`pyramid.events.NewRequest` for more information."""
    request = Attribute('The request object')
    

class INewResponse(Interface):
    """ An event type that is emitted whenever any :app:`Pyramid`
    view returns a response. See the
@@ -38,8 +40,10 @@
    :class:`pyramid.events.ApplicationCreated` for more
    information.

    .. note:: For backwards compatibility with :app:`Pyramid`
       versions before 1.0, this interface can also be imported as
    .. note::

       For backwards compatibility with :app:`Pyramid` versions before 1.0, this
       interface can also be imported as
       :class:`pyramid.interfaces.IWSGIApplicationCreatedEvent`.
    """
    app = Attribute(u"Created application")
@@ -146,7 +150,7 @@
class IRequest(Interface):
    """ Request type interface attached to all request objects """

IRequest.combined = IRequest # for exception view lookups 
IRequest.combined = IRequest # for exception view lookups

class IRouteRequest(Interface):
    """ *internal only* interface used as in a utility lookup to find
@@ -180,7 +184,7 @@
        principal named ``principal`` when set in a response.  An
        individual authentication policy and its consumers can decide
        on the composition and meaning of **kw. """
    

    def forget(request):
        """ Return a set of headers suitable for 'forgetting' the
        current user on subsequent requests. """
@@ -191,7 +195,7 @@
        """ Return ``True`` if any of the ``principals`` is allowed the
        ``permission`` in the current ``context``, else return ``False``
        """
        

    def principals_allowed_by_permission(context, permission):
        """ Return a set of principal identifiers allowed by the
        ``permission`` in ``context``.  This behavior is optional; if you
@@ -314,12 +318,12 @@
    a view registry."""
    registry = Attribute(
        """Component architecture registry local to this application.""")
    

class ISettings(Interface):
    """ Runtime settings utility for pyramid; represents the
    deployment settings for the application.  Implements a mapping
    interface."""
    

# this interface, even if it becomes unused within Pyramid, is
# imported by other packages (such as traversalwrapper)
class ILocation(Interface):
@@ -446,7 +450,7 @@

class ILocalizer(Interface):
    """ Localizer for a specific language """
        

class ILocaleNegotiator(Interface):
    def __call__(request):
        """ Return a locale name """
@@ -533,7 +537,7 @@
        """

    # mapping methods
    

    def __getitem__(key):
        """Get a value for a key

@@ -578,19 +582,19 @@

    def clear():
        "delete all items"
    

    def update(d):
        " Update D from E: for k in E.keys(): D[k] = E[k]"
    

    def setdefault(key, default=None):
        " D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D "
    

    def pop(k, *args):
        """remove specified key and return the corresponding value
        ``*args`` may contain a single default value, or may not be supplied.
        If key is not found, default is returned if given, otherwise 
        If key is not found, default is returned if given, otherwise
        ``KeyError`` is raised"""
    

    def popitem():
        """remove and return some (key, value) pair as a
        2-tuple; but raise ``KeyError`` if mapping is empty"""
@@ -620,5 +624,5 @@
                         'renderer was created')
    settings = Attribute('The deployment settings dictionary related '
                         'to the current application')
    



 pyramid/security.py

@@ -107,7 +107,9 @@
    :mod:`pyramid.security.Everyone` (the special principal
    identifier representing all principals).

    .. note:: even if an :term:`authorization policy` is in effect,
    .. note::

       even if an :term:`authorization policy` is in effect,
       some (exotic) authorization policies may not implement the
       required machinery for this function; those will cause a
       :exc:`NotImplementedError` exception to be raised when this
@@ -190,14 +192,14 @@
        return []
    else:
        return policy.forget(request)
    

class PermitsResult(int):
    def __new__(cls, s, *args):
        inst = int.__new__(cls, cls.boolval)
        inst.s = s
        inst.args = args
        return inst
        

    @property
    def msg(self):
        return self.s % self.args

 pyramid/static.py

@@ -52,7 +52,7 @@
                cache_max_age=self.cache_max_age)(environ, start_response)
        if (environ.get('PATH_INFO')
            and environ.get('PATH_INFO') != '/'): # pragma: no cover
            return self.error_extra_path(environ, start_response) 
            return self.error_extra_path(environ, start_response)
        full = pkg_resources.resource_filename(self.package_name, resource)
        if_none_match = environ.get('HTTP_IF_NONE_MATCH')
        if if_none_match:
@@ -178,14 +178,16 @@
    response headers returned by the view (default is 3600 seconds or
    five minutes).

    .. note:: If the ``root_dir`` is relative to a :term:`package`, or
    .. note::

         If the ``root_dir`` is relative to a :term:`package`, or
         is a :term:`asset specification` the :app:`Pyramid`
         :class:`pyramid.config.Configurator` method can be
         used to override assets within the named ``root_dir``
         package-relative directory.  However, if the ``root_dir`` is
         absolute, configuration will not be able to
         override the assets it contains.  """
    

    def __init__(self, root_dir, cache_max_age=3600, package_name=None):
        # package_name is for bw compat; it is preferred to pass in a
        # package-relative path as root_dir

 pyramid/traversal.py

@@ -131,17 +131,17 @@

    The ``resource`` passed in *must* be :term:`location`-aware.

    .. note:: Each segment in the path string returned will use the
              ``__name__`` attribute of the resource it represents within
              the resource tree.  Each of these segments *should* be a unicode
              or string object (as per the contract of
              :term:`location`-awareness).  However, no conversion or
              safety checking of resource names is performed.  For
              instance, if one of the resources in your tree has a
              ``__name__`` which (by error) is a dictionary, the
              :func:`pyramid.traversal.resource_path` function will
              attempt to append it to a string and it will cause a
              :exc:`pyramid.exceptions.URLDecodeError`.
    .. note::

       Each segment in the path string returned will use the ``__name__``
       attribute of the resource it represents within the resource tree.  Each
       of these segments *should* be a unicode or string object (as per the
       contract of :term:`location`-awareness).  However, no conversion or
       safety checking of resource names is performed.  For instance, if one of
       the resources in your tree has a ``__name__`` which (by error) is a
       dictionary, the :func:`pyramid.traversal.resource_path` function will
       attempt to append it to a string and it will cause a
       :exc:`pyramid.exceptions.URLDecodeError`.

    .. note:: The :term:`root` resource *must* have a ``__name__``
              attribute with a value of either ``None`` or the empty
@@ -310,7 +310,7 @@
        resource = find_root(resource)

    reg = get_current_registry()
    

    request_factory = reg.queryUtility(IRequestFactory)
    if request_factory is None:
        from pyramid.request import Request # avoid circdep
@@ -343,16 +343,16 @@

    The ``resource`` passed in *must* be :term:`location`-aware.

    .. note:: Each segment in the path tuple returned will equal the
              ``__name__`` attribute of the resource it represents within
              the resource tree.  Each of these segments *should* be a unicode
              or string object (as per the contract of
              :term:`location`-awareness).  However, no conversion or
              safety checking of resource names is performed.  For
              instance, if one of the resources in your tree has a
              ``__name__`` which (by error) is a dictionary, that
              dictionary will be placed in the path tuple; no warning
              or error will be given.
    .. note::

       Each segment in the path tuple returned will equal the ``__name__``
       attribute of the resource it represents within the resource tree.  Each
       of these segments *should* be a unicode or string object (as per the
       contract of :term:`location`-awareness).  However, no conversion or
       safety checking of resource names is performed.  For instance, if one of
       the resources in your tree has a ``__name__`` which (by error) is a
       dictionary, that dictionary will be placed in the path tuple; no warning
       or error will be given.

    .. note:: The :term:`root` resource *must* have a ``__name__``
              attribute with a value of either ``None`` or the empty
@@ -475,18 +475,17 @@

        (u'archives', u'<unprintable unicode>')

    .. note:: This function does not generate the same type of tuples
              that :func:`pyramid.traversal.resource_path_tuple` does.
              In particular, the leading empty string is not present
              in the tuple it returns, unlike tuples returned by
              :func:`pyramid.traversal.resource_path_tuple`.  As a
              result, tuples generated by ``traversal_path`` are not
              resolveable by the
              :func:`pyramid.traversal.find_resource` API.
              ``traversal_path`` is a function mostly used by the
              internals of :app:`Pyramid` and by people writing
              their own traversal machinery, as opposed to users
              writing applications in :app:`Pyramid`.
    .. note::

       This function does not generate the same type of tuples that
       :func:`pyramid.traversal.resource_path_tuple` does.  In particular, the
       leading empty string is not present in the tuple it returns, unlike
       tuples returned by :func:`pyramid.traversal.resource_path_tuple`.  As a
       result, tuples generated by ``traversal_path`` are not resolveable by the
       :func:`pyramid.traversal.find_resource` API.  ``traversal_path`` is a
       function mostly used by the internals of :app:`Pyramid` and by people
       writing their own traversal machinery, as opposed to users writing
       applications in :app:`Pyramid`.
    """
    if isinstance(path, unicode):
        path = path.encode('ascii')

 pyramid/url.py

@@ -65,13 +65,13 @@
    data is turned into a query string, a leading ``?`` is prepended,
    and the resulting string is appended to the generated URL.

    .. note:: Python data structures that are passed as ``_query``
              which are sequences or dictionaries are turned into a
              string under the same rules as when run through
              :func:`urllib.urlencode` with the ``doseq`` argument
              equal to ``True``.  This means that sequences can be
              passed as values, and a k=v pair will be placed into the
              query string for each value.
    .. note::

       Python data structures that are passed as ``_query`` which are sequences
       or dictionaries are turned into a string under the same rules as when run
       through :func:`urllib.urlencode` with the ``doseq`` argument equal to
       ``True``.  This means that sequences can be passed as values, and a k=v
       pair will be placed into the query string for each value.

    If a keyword argument ``_anchor`` is present, its string
    representation will be used as a named anchor in the generated URL
@@ -233,13 +233,13 @@
    turned into a query string, a leading ``?`` is prepended, and the
    resulting string is appended to the generated URL.

    .. note:: Python data structures that are passed as ``query``
              which are sequences or dictionaries are turned into a
              string under the same rules as when run through
              :func:`urllib.urlencode` with the ``doseq`` argument
              equal to ``True``.  This means that sequences can be
              passed as values, and a k=v pair will be placed into the
              query string for each value.
    .. note::

       Python data structures that are passed as ``query`` which are sequences
       or dictionaries are turned into a string under the same rules as when run
       through :func:`urllib.urlencode` with the ``doseq`` argument equal to
       ``True``.  This means that sequences can be passed as values, and a k=v
       pair will be placed into the query string for each value.

    If a keyword argument ``anchor`` is present, its string
    representation will be used as a named anchor in the generated URL
@@ -262,18 +262,20 @@
    resource which is operated upon by this function.  See also
    :ref:`overriding_resource_url_generation`.

    .. note:: If the :term:`resource` used is the result of a
             :term:`traversal`, it must be :term:`location`-aware.
             The resource can also be the context of a :term:`URL
             dispatch`; contexts found this way do not need to be
             location-aware.
    .. note::

    .. note:: If a 'virtual root path' is present in the request
              environment (the value of the WSGI environ key
              ``HTTP_X_VHM_ROOT``), and the resource was obtained via
              :term:`traversal`, the URL path will not include the
              virtual root prefix (it will be stripped off the
              left hand side of the generated URL).
       If the :term:`resource` used is the result of a :term:`traversal`, it
       must be :term:`location`-aware.  The resource can also be the context of
       a :term:`URL dispatch`; contexts found this way do not need to be
       location-aware.

    .. note::

       If a 'virtual root path' is present in the request environment (the value
       of the WSGI environ key ``HTTP_X_VHM_ROOT``), and the resource was
       obtained via :term:`traversal`, the URL path will not include the virtual
       root prefix (it will be stripped off the left hand side of the generated
       URL).

    .. note:: For backwards compatibility purposes, this function can also be
       imported as ``model_url``, although doing so will emit a deprecation
@@ -283,7 +285,7 @@
        reg = request.registry
    except AttributeError:
        reg = get_current_registry() # b/c
    

    context_url = reg.queryMultiAdapter((resource, request), IContextURL)
    if context_url is None:
        context_url = TraversalContextURL(resource, request)
@@ -367,17 +369,17 @@
        reg = request.registry
    except AttributeError:
        reg = get_current_registry() # b/c
    

    info = reg.queryUtility(IStaticURLInfo)
    if info is None:
        raise ValueError('No static URL definition matching %s' % path)
        

    return info.generate(path, request, **kw)

def current_route_url(request, *elements, **kw):
    """Generates a fully qualified URL for a named :app:`Pyramid`
    :term:`route configuration` based on the 'current route'.
    

    This function supplements :func:`pyramid.url.route_url`. It presents an
    easy way to generate a URL for the 'current route' (defined as the route
    which matched when the request was generated).
@@ -405,7 +407,7 @@
    current current url path is ``/foo/1``, the matchdict will be
    ``{'page':'1'}``.  The result of ``current_route_url(request, page='2')``
    in this situation will be ``/foo/2``.
        

    Usage of the ``_route_name`` keyword argument: if our routing table
    defines routes ``/foo/{action}`` named 'foo' and ``/foo/{action}/{page}``
    named ``fooaction``, and the current url pattern is ``/foo/view`` (which

 pyramid/view.py

@@ -327,5 +327,3 @@
See also :ref:`changing_the_notfound_view`.

"""