Merge remote branch 'remotes/upstream/master'

16 files changed, 267 insertions, 173 deletions

diff --git a/docs/narr/MyProject/development.ini b/docs/narr/MyProject/development.ini
index 9c51cfe6e..80d89e46a 100644
--- a/docs/narr/MyProject/development.ini
+++ b/docs/narr/MyProject/development.ini
@@ -15,3 +15,29 @@ pipeline =
 use = egg:Paste#http
 host = 0.0.0.0
 port = 6543
+
+# Begin logging configuration
+
+[loggers]
+keys = root
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
+
+# End logging configuration
diff --git a/docs/narr/MyProject/myproject/__init__.py b/docs/narr/MyProject/myproject/__init__.py
index bfbbfd4df..580dfe546 100644
--- a/docs/narr/MyProject/myproject/__init__.py
+++ b/docs/narr/MyProject/myproject/__init__.py
@@ -5,11 +5,8 @@ def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
     config = Configurator(root_factory=get_root, settings=settings)
-    config.begin()
     config.add_view('myproject.views.my_view',
                     context='myproject.models.MyModel',
                     renderer='myproject:templates/mytemplate.pt')
     config.add_static_view('static', 'myproject:static')
-    config.end()
     return config.make_wsgi_app()
-
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 6a91cbf75..ae02a5a6c 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -47,20 +47,16 @@ imperatively:
 
    if __name__ == '__main__':
        config = Configurator()
-       config.begin()
        config.add_view(hello_world)
-       config.end()
        app = config.make_wsgi_app()
        serve(app, host='0.0.0.0')
 
-We won't talk much about what this application does yet.  Just note
-that the "configuration' statements take place underneath the ``if
-__name__ == '__main__':`` stanza in the form of method calls on a
-:term:`Configurator` object (e.g. ``config.begin()``,
-``config.add_view(...)``, and ``config.end()``.  These statements take
-place one after the other, and are executed in order, so the full
-power of Python, including conditionals, can be employed in this mode
-of configuration.
+We won't talk much about what this application does yet.  Just note that the
+"configuration' statements take place underneath the ``if __name__ ==
+'__main__':`` stanza in the form of method calls on a :term:`Configurator`
+object (e.g. ``config.add_view(...)``).  These statements take place one
+after the other, and are executed in order, so the full power of Python,
+including conditionals, can be employed in this mode of configuration.
 
 .. index::
    single: view_config
@@ -123,9 +119,7 @@ and its subpackages.  For example:
       if __name__ == '__main__':
           from pyramid.configuration import Configurator
           config = Configurator()
-          config.begin()
           config.scan()
-          config.end()
           app = config.make_wsgi_app()
           serve(app, host='0.0.0.0')
 
diff --git a/docs/narr/contextfinding.rst b/docs/narr/contextfinding.rst
index c3fbe7f5a..770f97d15 100644
--- a/docs/narr/contextfinding.rst
+++ b/docs/narr/contextfinding.rst
@@ -75,7 +75,7 @@ URL dispatch can easily handle URLs such as
 ``http://example.com/members/Chris``, where it's assumed that each
 item "below" ``members`` in the URL represents a single member in some
 system.  You just match everything "below" ``members`` to a particular
-:term:`view callable`, e.g. ``/members/:memberid``.
+:term:`view callable`, e.g. ``/members/{memberid}``.
 
 However, URL dispatch is not very convenient if you'd like your URLs
 to represent an arbitrary hierarchy.  For example, if you need to
diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst
index 48a3ea134..b9dbcab7d 100644
--- a/docs/narr/declarative.rst
+++ b/docs/narr/declarative.rst
@@ -655,7 +655,7 @@ declaration` causes a route to be added to the application.
 
    <route
        name="myroute"
-       pattern="/prefix/:one/:two"
+       pattern="/prefix/{one}/{two}"
        view=".views.myview"
     />
 
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 2aa4064cd..c3fe401ec 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -201,6 +201,72 @@ should be changed accordingly.
 |                             |
 +-----------------------------+
 
+Mako Error Handler
+++++++++++++++++++
+
+Python callable which is called whenever Mako compile or runtime exceptions
+occur. The callable is passed the current context as well as the exception. If
+the callable returns True, the exception is considered to be handled, else it
+is re-raised after the function completes. Is used to provide custom
+error-rendering functions.
+
++-----------------------------+
+| Config File Setting Name    |
++=============================+
+|  ``mako.error_handler``     |
+|                             |
+|                             |
+|                             |
++-----------------------------+
+
+Mako Default Filters
+++++++++++++++++++++
+
+List of string filter names that will be applied to all Mako expressions.
+
++-----------------------------+
+| Config File Setting Name    |
++=============================+
+|  ``mako.default_filters``   |
+|                             |
+|                             |
+|                             |
++-----------------------------+
+
+Mako Import
++++++++++++
+
+String list of Python statements, typically individual “import” lines, which
+will be placed into the module level preamble of all generated Python modules.
+
+
++-----------------------------+
+| Config File Setting Name    |
++=============================+
+|  ``mako.imports``           |
+|                             |
+|                             |
+|                             |
++-----------------------------+
+
+
+Mako Strict Undefined
++++++++++++++++++++++
+
+``true`` or ``false``, representing the "strict undefined" behavior of Mako
+(see `Mako Context Variables
+<http://www.makotemplates.org/docs/runtime.html#context-variables>`_).  By
+default, this is ``false``.
+
++-----------------------------+
+| Config File Setting Name    |
++=============================+
+|  ``mako.strict_undefined``  |
+|                             |
+|                             |
+|                             |
++-----------------------------+
+
 Examples
 --------
 
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index bc21bf29f..9d3cad13c 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -38,10 +38,8 @@ configured imperatively:
 
    if __name__ == '__main__':
        config = Configurator()
-       config.begin()
        config.add_view(hello_world)
        config.add_view(goodbye_world, name='goodbye')
-       config.end()
        app = config.make_wsgi_app()
        serve(app, host='0.0.0.0')
 
@@ -149,10 +147,8 @@ imports and function definitions is placed within the confines of an
 
    if __name__ == '__main__':
        config = Configurator()
-       config.begin()
        config.add_view(hello_world)
        config.add_view(goodbye_world, name='goodbye')
-       config.end()
        app = config.make_wsgi_app()
        serve(app, host='0.0.0.0')
 
@@ -190,29 +186,6 @@ this particular :app:`Pyramid` application.  Methods called on the
 Configurator will cause registrations to be made in a
 :term:`application registry` associated with the application.
 
-Beginning Configuration
-~~~~~~~~~~~~~~~~~~~~~~~
-
-.. ignore-next-block
-.. code-block:: python
-
-   config.begin()
-
-The :meth:`pyramid.configuration.Configurator.begin` method tells
-the system that application configuration has begun.  In particular,
-this causes the :term:`application registry` associated with this
-configurator to become the "current" application registry, meaning
-that code which attempts to use the application registry :term:`thread
-local` will obtain the registry associated with the configurator.
-This is an explicit step because it's sometimes convenient to use a
-configurator without causing the registry associated with the
-configurator to become "current".
-
-.. note::
-
-   See :ref:`threadlocals_chapter` for a discussion about what it
-   means for an application registry to be "current".
-
 .. _adding_configuration:
 
 Adding Configuration
@@ -281,28 +254,6 @@ important.  We can register ``goodbye_world`` first and
 ``hello_world`` second; :app:`Pyramid` will still give us the most
 specific callable when a request is dispatched to it.
 
-Ending Configuration
-~~~~~~~~~~~~~~~~~~~~
-
-.. ignore-next-block
-.. code-block:: python
-
-   config.end()
-
-The :meth:`pyramid.configuration.Configurator.end` method tells the
-system that application configuration has ended.  It is the inverse of
-:meth:`pyramid.configuration.Configurator.begin`.  In particular,
-this causes the :term:`application registry` associated with this
-configurator to no longer be the "current" application registry,
-meaning that code which attempts to use the application registry
-:term:`thread local` will no longer obtain the registry associated
-with the configurator.
-
-.. note::
-
-   See :ref:`threadlocals_chapter` for a discussion about what it
-   means for an application registry to be "current".
-
 .. index::
    single: make_wsgi_app
    single: WSGI application
diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst
index b8e7b5d9b..d82f42bdb 100644
--- a/docs/narr/handlers.rst
+++ b/docs/narr/handlers.rst
@@ -59,11 +59,11 @@ be performed in order to register it with the system:
 
 .. code-block:: python
 
-    config.add_handler('hello', '/hello/:action', handler=Hello)
+    config.add_handler('hello', '/hello/{action}', handler=Hello)
 
 This example will result in a route being added for the pattern
-``/hello/:action``, each method of the ``Hello`` class will then be examined
-to register the views. The value of ``:action`` in the route pattern will be
+``/hello/{action}``, each method of the ``Hello`` class will then be examined
+to register the views. The value of ``{action}`` in the route pattern will be
 used to determine which view should be called, and each view in the class will
 be setup with a view predicate that requires a specific ``action`` name.
 
@@ -98,7 +98,7 @@ For example:
 
 .. code-block:: python
     
-    config.add_handler('hello', '/hello/:action',
+    config.add_handler('hello', '/hello/{action}',
                        handler='mypackage.handlers:MyHandler')
 
 In larger applications, it is advised to use a :term:`resource specification`
@@ -168,8 +168,8 @@ information on the handler method which is used by
 configuration.
 
 All keyword arguments are recorded, and passed to
-:meth:`!pyramid.configuration.Configurator.add_view`. Any valid keyword
-arguments for :meth:`!pyramid.configuration.Configurator.add_view` can thus be
+:meth:`~pyramid.configuration.Configurator.add_view`. Any valid keyword
+arguments for :meth:`~pyramid.configuration.Configurator.add_view` can thus be
 used with the :class:`~pyramid.view.action` decorator to further restrict when
 the view will be called.
 
@@ -219,7 +219,7 @@ Example:
             return {}
 
     # in the config
-    config.add_handler('hello', '/hello/:action', handler=Hello)
+    config.add_handler('hello', '/hello/{action}', handler=Hello)
 
 With this configuration, the url ``/hello/home`` will find a view configuration
 that results in calling the ``show_template`` method, then rendering the
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index 61ac68d5d..e704463c7 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -42,8 +42,8 @@ configuration:
 
    # config is an instance of pyramid.configuration.Configurator
 
-   config.add_route('foobar', ':foo/:bar', view='myproject.views.foobar')
-   config.add_route('bazbuz', ':baz/:buz', view='myproject.views.bazbuz')
+   config.add_route('foobar', '{foo}/{bar}', view='myproject.views.foobar')
+   config.add_route('bazbuz', '{baz}/{buz}', view='myproject.views.bazbuz')
 
 Each :term:`route` typically corresponds to a single view callable,
 and when that route is matched during a request, the view callable
@@ -185,7 +185,7 @@ of a route's pattern:
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', ':foo/:bar/*traverse')
+   config.add_route('home', '{foo}/{bar}/*traverse')
 
 A ``*traverse`` token at the end of the pattern in a route's
 configuration implies a "remainder" *capture* value.  When it is used,
@@ -243,7 +243,7 @@ route configuration statement:
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', ':foo/:bar/*traverse', 
+   config.add_route('home', '{foo}/{bar}/*traverse', 
                     factory='mypackage.routes.root_factory')
 
 The ``factory`` above points at the function we've defined.  It
@@ -267,14 +267,14 @@ to do.
 
 When the route configuration named ``home`` above is matched during a
 request, the matchdict generated will be based on its pattern:
-``:foo/:bar/*traverse``.  The "capture value" implied by the
+``{foo}/{bar}/*traverse``.  The "capture value" implied by the
 ``*traverse`` element in the pattern will be used to traverse the
 graph in order to find a context, starting from the root object
 returned from the root factory.  In the above example, the
 :term:`root` object found will be the instance named ``root`` in
 ``routes.py``.
 
-If the URL that matched a route with the pattern ``:foo/:bar/*traverse``,
+If the URL that matched a route with the pattern ``{foo}/{bar}/*traverse``,
 is ``http://example.com/one/two/a/b/c``, the traversal path used
 against the root object will be ``a/b/c``.  As a result,
 :app:`Pyramid` will attempt to traverse through the edges ``a``,
@@ -296,7 +296,7 @@ invoked after a route matches:
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', ':foo/:bar/*traverse', 
+   config.add_route('home', '{foo}/{bar}/*traverse', 
                     factory='mypackage.routes.root_factory')
    config.add_view('mypackage.views.myview', route_name='home')
 
@@ -326,7 +326,7 @@ when a hybrid route is matched:
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', ':foo/:bar/*traverse', 
+   config.add_route('home', '{foo}/{bar}/*traverse', 
                     factory='mypackage.routes.root_factory')
    config.add_view('mypackage.views.myview', name='home')
    config.add_view('mypackage.views.another_view', name='another', 
@@ -358,7 +358,7 @@ Using the ``traverse`` Argument In a Route Definition
 
 Rather than using the ``*traverse`` remainder marker in a pattern, you
 can use the ``traverse`` argument to the
-:meth:`pyramid.configuration.Configurator.add_route`` method.
+:meth:`pyramid.configuration.Configurator.add_route` method.
 
 When you use the ``*traverse`` remainder marker, the traversal path is
 limited to being the remainder segments of a request URL when a route
@@ -371,14 +371,14 @@ Here's a use of the ``traverse`` pattern in a call to
 .. code-block:: python
    :linenos:
 
-   config.add_route('abc', '/articles/:article/edit',
-                    traverse='/articles/:article')
+   config.add_route('abc', '/articles/{article}/edit',
+                    traverse='/articles/{article}')
 
 The syntax of the ``traverse`` argument is the same as it is for
 ``pattern``.
 
-If, as above, the ``pattern`` provided is ``articles/:article/edit``,
-and the ``traverse`` argument provided is ``/:article``, when a
+If, as above, the ``pattern`` provided is ``articles/{article}/edit``,
+and the ``traverse`` argument provided is ``/{article}``, when a
 request comes in that causes the route to match in such a way that the
 ``article`` match value is ``1`` (when the request URI is
 ``/articles/1/edit``), the traversal path will be generated as ``/1``.
@@ -467,7 +467,7 @@ startup time.
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', ':foo/:bar/*traverse',
+   config.add_route('home', '{foo}/{bar}/*traverse',
                     view='myproject.views.home')
    config.add_view('myproject.views.another', route_name='home')
 
@@ -479,7 +479,7 @@ supply a view attribute.  For example, this ``add_route`` call:
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', ':foo/:bar/*traverse',
+   config.add_route('home', '{foo}/{bar}/*traverse',
                     view='myproject.views.home')
 
 Can also be spelled like so:
@@ -487,7 +487,7 @@ Can also be spelled like so:
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', ':foo/:bar/*traverse')
+   config.add_route('home', '{foo}/{bar}/*traverse')
    config.add_view('myproject.views.home', route_name='home')
 
 The two spellings are logically equivalent.  In fact, the former is
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 703883fb2..9e2071872 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -773,8 +773,8 @@ If this setting is supplied within the :app:`Pyramid` application
 .. code-block:: python
    :linenos:
 
-   from pyramid.setttings import get_settings
-   settings = get_settings()
+   from pyramid.threadlocal import get_current_registry
+   settings = get_current_registry().settings
    default_locale_name = settings['default_locale_name']
 
 "Detecting" Available Languages
@@ -822,8 +822,9 @@ Then as a part of the code of a custom :term:`locale negotiator`:
 
 .. code-block:: py
 
-  from pyramid.settings import get_settings
-  languages = get_settings()['available_languages'].split()
+   from pyramid.threadlocal import get_current_registry
+   settings = get_current_registry().settings
+   languages = settings['available_languages'].split()
 
 This is only a suggestion.  You can create your own "available
 languages" configuration scheme as necessary.
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 725d32725..7c725690d 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -103,7 +103,7 @@ What Is The Pylons Project?
 ---------------------------
 
 :app:`Pyramid` is a member of the collection of software published under the
-Pylons Project.  :Pylons software is written by a loose-knit community of
+Pylons Project.  Pylons software is written by a loose-knit community of
 contributors.  The `Pylons Project website <http://docs.pylonshq.com>`_
 includes details about how :app:`Pyramid` relates to the Pylons Project.
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index f47e9f293..aef134ff7 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -316,12 +316,13 @@ Python interpreter shell unconditionally.
 
       [pipeline:main]
       pipeline = egg:WebError#evalerror
-                 myapp
+                 MyProject
 
-   If you use ``main`` as the section name argument instead of ``myapp``
-   against the above ``.ini`` file, an error will occur.  Use the most
-   specific reference to your application within the ``.ini`` file possible
-   as the section name argument.
+   Use ``MyProject`` instead of ``main`` as the section name argument to
+   ``pshell`` against the above ``.ini`` file (e.g. ``paster pshell
+   development.ini MyProject``).  If you use ``main`` instead, an error will
+   occur.  Use the most specific reference to your application within the
+   ``.ini`` file possible as the section name argument.
 
 Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
 
@@ -740,14 +741,14 @@ also informs Python that the directory which contains it is a *package*.
 #. Line 2 imports the ``get_root`` function from
    :mod:`myproject.models` that we use later.
 
-#. Lines 4-14 define a function that returns a :app:`Pyramid`
+#. Lines 4-12 define a function that returns a :app:`Pyramid`
    WSGI application.  This function is meant to be called
    by the :term:`PasteDeploy` framework as a result of running
    ``paster serve``.
 
    Within this function, configuration is performed.
 
-   Lines 9-11 register a "default view" (a view that has no ``name``
+   Lines 8-10 register a "default view" (a view that has no ``name``
    attribute).  It is registered so that it will be found when the
    :term:`context` of the request is an instance of the
    :class:`myproject.models.MyModel` class.  The first argument to
@@ -761,11 +762,11 @@ also informs Python that the directory which contains it is a *package*.
    ``templates`` directory of the ``myproject`` package.  The template file
    it actually points to is a :term:`Chameleon` ZPT template file.
 
-   Line 12 registers a static view, which will serve up the files from the
+   Line 11 registers a static view, which will serve up the files from the
    ``mypackage:static`` :term:`resource specification` (the ``static``
    directory of the ``mypackage`` package).
 
-   Line 14 returns a :term:`WSGI` application to the caller of the function
+   Line 12 returns a :term:`WSGI` application to the caller of the function
    (Paste).
 
 ``views.py``
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index c57525f4c..427acc319 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -86,9 +86,9 @@ press ``return`` after running ``paster serve development.ini``.
       :linenos:
 
    In this case, the ``myproject.run:app`` function referred to by the entry
-   point URI ``egg:MyProject#app`` (see :ref:`MyProject_ini` for more
-   information about entry point URIs, and how they relate to callables),
-   will receive the key/value pairs ``{'reload_templates':'true',
+   point URI ``egg:MyProject`` (see :ref:`MyProject_ini` for more information
+   about entry point URIs, and how they relate to callables), will receive
+   the key/value pairs ``{'reload_templates':'true',
    'debug_authorization':'false', 'debug_notfound':'false',
    'debug_templates':'true', 'default_locale_name':'en'}``.
 
diff --git a/docs/narr/static.rst b/docs/narr/static.rst
index efeabd012..a01cbbabf 100644
--- a/docs/narr/static.rst
+++ b/docs/narr/static.rst
@@ -69,22 +69,21 @@ when generating a URL using :func:`pyramid.url.static_url`.
 .. note::
 
    Using :func:`pyramid.url.static_url` in conjunction with a
-   :meth:`pyramid.configuration.Configurator.add_static_view` makes
-   it possible to put static media on a separate webserver during
-   production (if the ``name`` argument to
-   :meth:`pyramid.configuration.Configurator.add_static_view` is a
-   URL), while keeping static media package-internal and served by the
-   development webserver during development (if the ``name`` argument
-   to :meth:`pyramid.configuration.Configurator.add_static_view` is
-   a view name).  To create such a circumstance, we suggest using the
-   :func:`pyramid.settings.get_settings` API in conjunction with a
-   setting in the application ``.ini`` file named ``media_location``.
-   Then set the value of ``media_location`` to either a view name or a
-   URL depending on whether the application is being run in
-   development or in production (use a different `.ini`` file for
-   production than you do for development).  This is just a suggestion
-   for a pattern; any setting name other than ``media_location`` could
-   be used.
+   :meth:`pyramid.configuration.Configurator.add_static_view` makes it
+   possible to put static media on a separate webserver during production (if
+   the ``name`` argument to
+   :meth:`pyramid.configuration.Configurator.add_static_view` is a URL),
+   while keeping static media package-internal and served by the development
+   webserver during development (if the ``name`` argument to
+   :meth:`pyramid.configuration.Configurator.add_static_view` is a view
+   name).  To create such a circumstance, we suggest using the
+   :attr:`pyramid.registry.Registry.settings` API in conjunction with a
+   setting in the application ``.ini`` file named ``media_location``.  Then
+   set the value of ``media_location`` to either a view name or a URL
+   depending on whether the application is being run in development or in
+   production (use a different `.ini`` file for production than you do for
+   development).  This is just a suggestion for a pattern; any setting name
+   other than ``media_location`` could be used.
 
 For example, :meth:`pyramid.configuration.Configurator.add_static_view` may
 be fed a ``name`` argument which is ``http://example.com/images``:
diff --git a/docs/narr/unittesting.rst b/docs/narr/unittesting.rst
index 5cd8a0683..26035726b 100644
--- a/docs/narr/unittesting.rst
+++ b/docs/narr/unittesting.rst
@@ -1,4 +1,4 @@
-.. index::
+\.. index::
    single: unit testing
    single: integration testing
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 4442be355..df7d592f9 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -92,7 +92,12 @@ registry`.  Here's an example:
    # pyramid.configuration.Configurator class; "myview" is assumed
    # to be a "view callable" function
    from views import myview
-   config.add_route('myroute', '/prefix/:one/:two', view=myview)
+   config.add_route('myroute', '/prefix/{one}/{two}', view=myview)
+
+.. versionchanged:: 1.0a4
+    Prior to 1.0a4, routes allow for a marker starting with a ``:``, for
+    example ``/prefix/{one}``. Starting in 1.0a4, this style is deprecated
+    in favor or ``{}`` usage which allows for additional functionality.
 
 .. index::
    single: route configuration; view callable
@@ -116,7 +121,7 @@ Here's an example route configuration that references a view callable:
    # pyramid.configuration.Configurator class; "myview" is assumed
    # to be a "view callable" function
    from myproject.views import myview
-   config.add_route('myroute', '/prefix/:one/:two', view=myview)
+   config.add_route('myroute', '/prefix/{one}/{two}', view=myview)
 
 You can also pass a :term:`dotted Python name` as the ``view`` argument
 rather than an actual callable:
@@ -128,7 +133,7 @@ rather than an actual callable:
    # pyramid.configuration.Configurator class; "myview" is assumed
    # to be a "view callable" function
    from myproject.views import myview
-   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,28 +205,28 @@ the following patterns are equivalent:
 
 .. code-block:: text
 
-   :foo/bar/baz
+   {foo}/bar/baz
 
 and:
 
 .. code-block:: text
 
-   /:foo/bar/baz
+   /{foo}/bar/baz
 
-A patttern segment (an individual item between ``/`` characters in the
-pattern) may either be a literal string (e.g. ``foo``) *or* it may be
-a segment replacement marker (e.g. ``:foo``) or a certain combination
-of both.
+A pattern segment (an individual item between ``/`` characters in the pattern)
+may either be a literal string (e.g. ``foo``) *or* it may be a replacement
+marker (e.g. ``{foo}``) or a certain combination of both. A replacement marker
+does not need to be preceded by a ``/`` character.
 
-A segment replacement marker is in the format ``:name``, where this
-means "accept any characters up to the next nonalphaunumeric character
+A replacement marker is in the format ``{name}``, where this
+means "accept any characters up to the next non-alphanumeric character
 and use this as the ``name`` matchdict value."  For example, the
 following pattern defines one literal segment ("foo") and two dynamic
-segments ("baz", and "bar"):
+replacement markers ("baz", and "bar"):
 
 .. code-block:: text
 
-   foo/:baz/:bar
+   foo/{baz}/{bar}
 
 The above pattern will match these URLs, generating the following
 matchdicts:
@@ -244,24 +249,36 @@ pattern.  So, for instance, if this route pattern was used:
 
 .. code-block:: text
 
-   foo/:name.html
+   foo/{name}.html
 
 The literal path ``/foo/biz.html`` will match the above route pattern,
 and the match result will be ``{'name':u'biz'}``.  However, the
 literal path ``/foo/biz`` will not match, because it does not contain
 a literal ``.html`` at the end of the segment represented by
-``:name.html`` (it only contains ``biz``, not ``biz.html``).
+``{name}.html`` (it only contains ``biz``, not ``biz.html``).
+
+To capture both segments, two replacement markers can be used:
+
+.. code-block:: text
+    
+    foo/{name}.{ext}
 
-This does not mean, however, that you can use two segment replacement
-markers in the same segment.  For instance, ``/:foo:bar`` is a
-nonsensical route pattern.  It will never match anything.
+The literal path ``/foo/biz.html`` will match the above route pattern, and the
+match result will be ``{'name': 'biz', 'ext': 'html'}``. This occurs because
+the replacement marker ``{name}`` has a literal part of ``.`` between the other
+replacement marker ``:ext``.
+
+It is possible to use two replacement markers without any literal characters
+between them, for instance ``/{foo}{bar}``. This would be a nonsensical pattern
+without specifying a custom regular expression to restrict what a marker
+captures.
 
 Segments must contain at least one character in order to match a
 segment replacement marker.  For example, for the URL ``/abc/``:
 
-- ``/abc/:foo`` will not match.
+- ``/abc/{foo}`` will not match.
 
-- ``/:foo/`` will match.
+- ``/{foo}/`` will match.
 
 Note that values representing path segments matched with a
 ``:segment`` match will be url-unquoted and decoded from UTF-8 into
@@ -270,7 +287,7 @@ pattern:
 
 .. code-block:: text
 
-   foo/:bar
+   foo/{bar}
 
 When matching the following URL:
 
@@ -292,7 +309,7 @@ need to be preceded by a slash.  For example:
 
 .. code-block:: text
 
-   foo/:baz/:bar*fizzle
+   foo/{baz}/{bar}*fizzle
 
 The above pattern will match these URLs, generating the following
 matchdicts:
@@ -324,6 +341,25 @@ Will generate the following matchdict:
 
    {'fizzle':(u'La Pe\xf1a', u'a', u'b', u'c')}
 
+By default, the ``*stararg`` will parse the remainder sections into a tuple
+split by segment. Changing the regular expression used to match a marker can
+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::
+
+   foo/1/2/           -> {'baz':'1', 'bar':'2', 'fizzle':()}
+   foo/abc/def/a/b/c  -> {'baz':'abc', 'bar':'def', 'fizzle': 'a/b/c')}
+
+This occurs because the default regular expression for a marker is ``[^/]+``
+which will match everything up to the first ``/``, while ``{filzzle:.*}`` will
+result in a regular expression match of ``.*`` capturing the remainder into
+a single value.
+
 .. index::
    single: route ordering
 
@@ -348,12 +384,12 @@ be added in the following order:
 
 .. code-block:: text
 
-   members/:def
+   members/{def}
    members/abc
 
 In such a configuration, the ``members/abc`` pattern would *never* be
 matched; this is because the match ordering will always match
-``members/:def`` first; the route configuration with ``members/abc``
+``members/{def}`` first; the route configuration with ``members/abc``
 will never be evaluated.
 
 .. index::
@@ -434,8 +470,8 @@ represent neither predicates nor view configuration information.
 
   The syntax of the ``traverse`` argument is the same as it is for
   ``pattern``. For example, if the ``pattern`` provided is
-  ``articles/:article/edit``, and the ``traverse`` argument provided
-  is ``/:article``, when a request comes in that causes the route to
+  ``articles/{article}/edit``, and the ``traverse`` argument provided
+  is ``/{article}``, when a request comes in that causes the route to
   match in such a way that the ``article`` match value is '1' (when
   the request URI is ``/articles/1/edit``), the traversal path will be
   generated as ``/1``.  This means that the root object's
@@ -462,7 +498,7 @@ represent neither predicates nor view configuration information.
 **Predicate Arguments**
 
 ``pattern``
-  The path of the route e.g. ``ideas/:idea``.  This argument is
+  The path of the route e.g. ``ideas/{idea}``.  This argument is
   required.  See :ref:`route_path_pattern_syntax` for information
   about the syntax of route paths.  If the path doesn't match the
   current URL, route matching continues.  
@@ -470,7 +506,7 @@ represent neither predicates nor view configuration information.
   .. note:: In earlier releases of this framework, this argument existed
      as ``path``.  ``path`` continues to work as an alias for
      ``pattern``.
-
+  
 ``xhr``
   This value should be either ``True`` or ``False``.  If this value is
   specified and is ``True``, the :term:`request` must possess an
@@ -644,7 +680,7 @@ match.  For example:
 
    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
@@ -675,7 +711,7 @@ For instance, a predicate might do some type conversion of values:
 
     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
@@ -683,6 +719,29 @@ return ``True`` or ``False``; a predicate that does *only* conversion,
 such as the one we demonstrate above should unconditionally return
 ``True``.
 
+To avoid the try/except uncertainty, the route pattern can contain regular
+expressions specifying requirements for that marker. For instance:
+
+.. code-block:: python
+   :linenos:
+
+    def integers(*segment_names):
+        def predicate(info, request):
+            match = info['match']
+            for segment_name in segment_names:
+                match[segment_name] = int(match[segment_name])
+            return True
+        return predicate
+
+    ymd_to_int = integers('year', 'month', 'day')
+
+    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
+all unless these markers match ``\d+`` which requires them to be valid digits
+for an ``int`` type conversion.
+
 The ``match`` dictionary passed within ``info`` to each predicate
 attached to a route will be the same dictionary.  Therefore, when
 registering a custom predicate which modifies the ``match`` dict, the
@@ -713,9 +772,9 @@ An example of using the route in a set of route predicates:
         if info['route'].name in ('ymd', 'ym', 'y'):
             return info['match']['year'] == '2010'
 
-    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('y', '/{year}', custom_predicates=(twenty_ten,))
+    config.add_route('ym', '/{year}/{month}', custom_predicates=(twenty_ten,))
+    config.add_route('ymd', '/{year}/{month}/{day}', 
                      custom_predicates=(twenty_ten,))
 
 The above predicate, when added to a number of route configurations
@@ -814,7 +873,7 @@ The simplest route declaration which configures a route match to
 .. code-block:: python
    :linenos:
 
-    config.add_route('idea', 'site/:id', view='mypackage.views.site_view')
+    config.add_route('idea', 'site/{id}', view='mypackage.views.site_view')
 
 When a route configuration with a ``view`` attribute is added to the
 system, and an incoming request matches the *pattern* of the route
@@ -822,12 +881,12 @@ configuration, the :term:`view callable` named as the ``view``
 attribute of the route configuration will be invoked.
 
 In the case of the above example, when the URL of a request matches
-``/site/:id``, the view callable at the Python dotted path name
+``/site/{id}``, the view callable at the Python dotted path name
 ``mypackage.views.site_view`` will be called with the request.  In
 other words, we've associated a view callable directly with a route
 pattern.
 
-When the ``/site/:id`` route pattern matches during a request, the
+When the ``/site/{id}`` route pattern matches during a request, the
 ``site_view`` view callable is invoked with that request as its sole
 argument.  When this route matches, a ``matchdict`` will be generated
 and attached to the request as ``request.matchdict``.  If the specific
@@ -860,30 +919,30 @@ might add to your application:
 .. code-block:: python
    :linenos:
 
-   config.add_route('idea', 'ideas/:idea', view='mypackage.views.idea_view')
-   config.add_route('user', 'users/:user', view='mypackage.views.user_view')
-   config.add_route('tag', 'tags/:tags', view='mypackage.views.tag_view')
+   config.add_route('idea', 'ideas/{idea}', view='mypackage.views.idea_view')
+   config.add_route('user', 'users/{user}', view='mypackage.views.user_view')
+   config.add_route('tag', 'tags/{tags}', view='mypackage.views.tag_view')
 
 The above configuration will allow :app:`Pyramid` to service URLs
 in these forms:
 
 .. code-block:: text
 
-   /ideas/:idea
-   /users/:user
-   /tags/:tag
+   /ideas/{idea}
+   /users/{user}
+   /tags/{tag}
 
-- When a URL matches the pattern ``/ideas/:idea``, the view callable
+- When a URL matches the pattern ``/ideas/{idea}``, the view callable
   available at the dotted Python pathname ``mypackage.views.idea_view`` will
   be called.  For the specific URL ``/ideas/1``, the ``matchdict`` generated
   and attached to the :term:`request` will consist of ``{'idea':'1'}``.
 
-- When a URL matches the pattern ``/users/:user``, the view callable
+- When a URL matches the pattern ``/users/{user}``, the view callable
   available at the dotted Python pathname ``mypackage.views.user_view`` will
   be called.  For the specific URL ``/users/1``, the ``matchdict`` generated
   and attached to the :term:`request` will consist of ``{'user':'1'}``.
 
-- When a URL matches the pattern ``/tags/:tag``, the view callable available
+- When a URL matches the pattern ``/tags/{tag}``, the view callable available
   at the dotted Python pathname ``mypackage.views.tag_view`` will be called.
   For the specific URL ``/tags/1``, the ``matchdict`` generated and attached
   to the :term:`request` will consist of ``{'tag':'1'}``.
@@ -911,7 +970,7 @@ An example of using a route with a factory:
 .. code-block:: python
    :linenos:
 
-   config.add_route('idea', 'ideas/:idea', 
+   config.add_route('idea', 'ideas/{idea}', 
                     view='myproject.views.idea_view',
                     factory='myproject.models.Idea')
 
@@ -939,7 +998,7 @@ a ``view`` declaration.
 .. code-block:: python
    :linenos:
 
-   config.add_route('idea', 'site/:id')
+   config.add_route('idea', 'site/{id}')
    config.add_view(route_name='idea', view='mypackage.views.site_view')
 
 This set of configuration parameters creates a configuration
@@ -949,7 +1008,7 @@ completely equivalent to this example provided in
 .. code-block:: python
    :linenos:
 
-   config.add_route('idea', 'site/:id', view='mypackage.views.site_view')
+   config.add_route('idea', 'site/{id}', view='mypackage.views.site_view')
 
 In fact, the spelling which names a ``view`` attribute is just
 syntactic sugar for the more verbose spelling which contains separate
@@ -990,7 +1049,7 @@ Generating Route URLs
 
 Use the :func:`pyramid.url.route_url` function to generate URLs based on
 route patterns.  For example, if you've configured a route with the ``name``
-"foo" and the ``pattern`` ":a/:b/:c", you might do this.
+"foo" and the ``pattern`` "{a}/{b}/{c}", you might do this.
 
 .. ignore-next-block
 .. code-block:: python
@@ -1184,7 +1243,7 @@ Such a ``factory`` might look like so:
           if article == '1':
               self.__acl__ = [ (Allow, 'editor', 'view') ]
 
-If the route ``archives/:article`` is matched, and the article number
+If the route ``archives/{article}`` is matched, and the article number
 is ``1``, :app:`Pyramid` will generate an ``Article``
 :term:`context` with an ACL on it that allows the ``editor`` principal
 the ``view`` permission.  Obviously you can do more generic things