Merge https://github.com/Pylons/pyramid

12 files changed, 84 insertions, 218 deletions

diff --git a/docs/Makefile b/docs/Makefile
index 768efb9df..b74c55bd5 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -25,7 +25,7 @@ help:
 clean:
 	-rm -rf _build/*
 
-html:
+html: _themes/
 	mkdir -p _build/html _build/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
 	@echo
@@ -47,7 +47,7 @@ pickle:
 
 web: pickle
 
-htmlhelp:
+htmlhelp: _themes
 	mkdir -p _build/htmlhelp _build/doctrees
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
 	@echo
@@ -83,3 +83,6 @@ epub:
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) _build/epub
 	@echo
 	@echo "Build finished. The epub file is in _build/epub."
+
+_themes:
+	git clone git://github.com/Pylons/pylons_sphinx_theme.git _themes
diff --git a/docs/api/url.rst b/docs/api/url.rst
index 71987498a..8c702a3fb 100644
--- a/docs/api/url.rst
+++ b/docs/api/url.rst
@@ -9,6 +9,8 @@
 
   .. autofunction:: route_url
 
+  .. autofunction:: route_path
+
   .. autofunction:: static_url
 
   .. autofunction:: urlencode
diff --git a/docs/conf.py b/docs/conf.py
index c2ecb1e8d..81096da3b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,6 +13,9 @@
 
 import sys, os
 import datetime
+import warnings
+
+warnings.simplefilter('ignore', DeprecationWarning)
 
 # skip raw nodes
 from sphinx.writers.text import TextTranslator
@@ -73,7 +76,7 @@ copyright = '%s, Agendaless Consulting' % datetime.datetime.now().year
 # other places throughout the built documents.
 #
 # The short X.Y version.
-version = '1.0a2'
+version = '1.0a3'
 # The full version, including alpha/beta/rc tags.
 release = version
 
diff --git a/docs/copyright.rst b/docs/copyright.rst
index 64a0f819b..fa564a785 100644
--- a/docs/copyright.rst
+++ b/docs/copyright.rst
@@ -49,7 +49,8 @@ Attributions
 ------------
 
 Contributors:
-  Ben Bangert, Blaise Laflamme, Carlos de la Guardia, Paul Everitt
+  Ben Bangert, Blaise Laflamme, Carlos de la Guardia, Paul Everitt, 
+  Marius Gedminas
 
 .. Cover Designer:
 ..   Nat Hardwick of `Electrosoup <http://www.electrosoup.co.uk>`_.
diff --git a/docs/index.rst b/docs/index.rst
index 4efb25dde..bfe956af2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -80,7 +80,6 @@ applications to various platforms.
    tutorials/gae/index.rst
    tutorials/modwsgi/index.rst
    tutorials/zeo/index.rst
-   tutorials/zodbsessions/index.rst
    tutorials/catalog/index.rst
 
 Reference Material
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 4efb193bd..388297de7 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -71,7 +71,6 @@ Tutorials
    tutorials/gae/index.rst
    tutorials/modwsgi/index.rst
    tutorials/zeo/index.rst
-   tutorials/zodbsessions/index.rst
    tutorials/catalog/index.rst
 
 .. _api_reference:
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 2aa4064cd..ecf85e464 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -201,6 +201,54 @@ 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``           |
+|                             |
+|                             |
+|                             |
++-----------------------------+
+
 Examples
 --------
 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index 61ac68d5d..b89d10c9f 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -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
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/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/tutorials/gae/index.rst b/docs/tutorials/gae/index.rst
index a2b190a31..9c8e8c07e 100644
--- a/docs/tutorials/gae/index.rst
+++ b/docs/tutorials/gae/index.rst
@@ -72,13 +72,13 @@ system.
 #. Edit ``config.py``
 
    Edit the ``APP_NAME`` and ``APP_ARGS`` settings within
-   ``config.py``.  The ``APP_NAME`` must be ``pyramidapp:app``, and
+   ``config.py``.  The ``APP_NAME`` must be ``pyramidapp:main``, and
    the APP_ARGS must be ``({},)``.  Any other settings in
    ``config.py`` should remain the same.
 
    .. code-block:: python
 
-      APP_NAME = 'pyramidapp:app'
+      APP_NAME = 'pyramidapp:main'
       APP_ARGS = ({},)
 
 #. Edit ``runner.py``
diff --git a/docs/tutorials/zodbsessions/index.rst b/docs/tutorials/zodbsessions/index.rst
deleted file mode 100644
index 9582e5de4..000000000
--- a/docs/tutorials/zodbsessions/index.rst
+++ /dev/null
@@ -1,189 +0,0 @@
-.. _zodb_sessions:
-
-Using ZODB-Based Sessions
-=========================
-
-Sessions are server-side namespaces which are associated with a site
-user that expire automatically after some period of disuse.
-
-If your application is ZODB-based (e.g. you've created an application
-from the ``bfg_zodb`` paster template, or you've followed the
-instructions in :ref:`zodb_with_zeo`), you can make use of the
-``repoze.session`` and ``repoze.browserid`` packages to add
-sessioning to your application.
-
-.. note:: You can use the ``repoze.session`` package even if your
-   application is not ZODB-based, but its backing store requires ZODB,
-   so it makes the most sense to use this package if your application
-   already uses ZODB.  This tutorial does not cover usage of
-   ``repoze.session``-based sessions in applications that don't
-   already use ZODB.  For this, see `the standalone repoze.session
-   usage documentation <http://docs.repoze.org/session/usage.html>`_.
-   If you don't want to use ZODB to do sessioning, you might choose to
-   use a relational/filestorage sessioning system such as `Beaker
-   <http://pypi.python.org/pypi/Beaker>`_.  :app:`Pyramid` is fully
-   compatible with this system too.
-
-Installing Dependencies
------------------------
-
-#. Edit your :app:`Pyramid` application's ``setup.py`` file, adding
-   the following packages to the ``install_requires`` of the
-   application:
-
-   - ``repoze.session``
-
-   - ``repoze.browserid``
-
-   For example, the relevant portion of your application's
-   ``setup.py`` file might look like so when you're finished adding
-   the dependencies.
-
-   .. code-block:: python
-      :linenos:
-
-      setup(
-          # ... other elements left out for brevity
-          install_requires=[
-                'pyramid',
-                'repoze.folder',
-                'repoze.retry',
-                'repoze.tm2',
-                'repoze.zodbconn',
-                'repoze.session'
-                'repoze.browserid',
-                ],
-          # ... other elements left out for brevity
-           )
-
-#. Rerun your application's ``setup.py`` file (e.g. using ``python
-   setup.py develop``) to get these packages installed.
-
-Configuration
--------------
-
-#. Edit your application's Paste ``.ini`` file.
-
-   If you already have an ``app`` section in the ``.ini`` file named
-   ``main``, rename this section to ``myapp`` (e.g. ``app:main`` ->
-   ``app:myapp``).  Add a key to it named ``zodb_uri``, e.g.
-
-   .. code-block:: python
-      :linenos:
-
-      [app:myapp]
-      use = egg:myapp#app
-      zodb_uri = zeo://%(here)s/zeo.sock
-      reload_templates = true
-      debug_authorization = false
-      debug_notfound = false
-
-   Add a ``filter`` section to the ``.ini`` file named "browserid":
-
-   .. code-block:: python
-      :linenos:
-
-      [filter:browserid]
-      use = egg:repoze.browserid#browserid
-      secret_key = my-secret-key
-
-   Replace ``my-secret-key`` with any random string.  This string
-   represents the value which the client-side "browser id" cookie is
-   encrypted with, to prevent tampering.
-
-   If a ``pipeline`` named ``main`` does not already exist in the
-   paste ``.ini`` file , add a ``pipeline`` section named ``main``.
-   Put the names ``connector``, ``egg:repoze.retry#retry``, and
-   ``egg:repoze.tm2#tm`` to the top of the pipeline.
-
-   .. code-block:: python
-      :linenos:
-
-      [pipeline:main]
-      pipeline = 
-             browserid
-             egg:repoze.retry#retry
-             egg:repoze.tm2#tm
-             myapp
-
-   When you're finished, your ``.ini`` file might look like so:
-
-   .. code-block:: ini
-      :linenos:
-
-      [DEFAULT]
-      debug = true
-
-      [app:myapp]
-      use = egg:myapp#app
-      zodb_uri = zeo://%(here)s/zeo.sock
-      reload_templates = true
-      debug_authorization = false
-      debug_notfound = false
-
-      [filter:browserid]
-      use = egg:repoze.browserid#browserid
-      secret_key = my-secret-key
-
-      [pipeline:main]
-      pipeline = 
-             browserid
-             egg:repoze.retry#retry
-             egg:repoze.tm2#tm
-             myapp
-
-      [server:main]
-      use = egg:Paste#http
-      host = 0.0.0.0
-      port = 6543
-
-   See :ref:`MyProject_ini` for more information about project Paste
-   ``.ini`` files.
-
-#.  Add a ``get_session`` API to your application.  I've chosen to add
-    it directly to my ``views.py`` file, although it can live anywhere.
-
-    .. code-block:: python
-       :linenos:
-
-       from repoze.session.manager import SessionDataManager
-       from pyramid.traversal import find_root
-
-       def get_session(context, request):
-           root = find_root(context)
-           if not hasattr(root, '_sessions'):
-               root._sessions = SessionDataManager(3600, 5)
-           session = root._sessions.get(request.environ['repoze.browserid'])
-           return session
-
-    Note in the call to ``SessionDataManager`` that '3600' represents
-    the disuse timeout (60 minutes == 3600 seconds), and '5' represents
-    a write granularity time (the session will be marked as active at
-    most every five seconds).  Vary these values as necessary.
-
-#.  Whenever you want to use a session in your application, call this API:
-
-    .. code-block:: python
-       :linenos:
-
-       from repoze.session.manager import SessionDataManager
-       from pyramid.traversal import find_root
-       from pyramid.chameleon_zpt import render_template_to_response
-
-       def my_view(context, request):
-           session = get_session(context, request)
-           session['abc'] = '123'
-           return render_template_to_response('templates/mytemplate.pt',
-                                              request = request,
-                                              project = 'sess')
-
-       def get_session(context, request):
-           root = find_root(context)
-           if not hasattr(root, '_sessions'):
-               root._sessions = SessionDataManager(3600, 5)
-           session = root._sessions.get(request.environ['repoze.browserid'])
-           return session
-
-For more information, see the `repoze.session documentation
-<http://docs.repoze.org/session/>`_ and the `repoze.browserid
-documentation <http://pypi.python.org/pypi/repoze.browserid>`_.