Merge remote-tracking branch 'origin/master' into docs.gettingstarted

Conflicts:
	docs/index.rst
	docs/latexindex.rst
	setup.py

11 files changed, 173 insertions, 28 deletions

diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index e1347f3ca..17e5227fa 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -474,6 +474,30 @@ input of the ``prequest`` process is used as the ``POST`` body::
 
    $ $VENV/bin/prequest -mPOST development.ini / < somefile
 
+Showing All Installed Distributions and their Versions
+------------------------------------------------------
+
+.. versionadded:: 1.5
+
+You can use the ``pdistreport`` command to show the Pyramid version in use, the
+Python version in use, and all installed versions of Python distributions in
+your Python environment::
+
+   $ $VENV/bin/pdistreport
+   Pyramid version: 1.5dev 
+   Platform Linux-3.2.0-51-generic-x86_64-with-debian-wheezy-sid 
+   Packages: 
+     authapp 0.0 
+       /home/chrism/projects/foo/src/authapp 
+     beautifulsoup4 4.1.3 
+       /home/chrism/projects/foo/lib/python2.7/site-packages/beautifulsoup4-4.1.3-py2.7.egg
+   ... more output ...
+
+``pdistreport`` takes no options.  Its output is useful to paste into a
+pastebin when you are having problems and need someone with more familiarity
+with Python packaging and distribution than you have to look at your
+environment.
+
 .. _writing_a_script:
 
 Writing a Script
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index 929208083..11af89ca6 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -53,7 +53,7 @@ method (see also :term:`Configurator`):
 
   from subscribers import mysubscriber
 
-  # "config" below is assumed to be an instance of a 
+  # "config" below is assumed to be an instance of a
   # pyramid.config.Configurator object
 
   config.add_subscriber(mysubscriber, NewRequest)
@@ -77,7 +77,7 @@ type via the :func:`pyramid.events.subscriber` function.
 
   @subscriber(NewRequest)
   def mysubscriber(event):
-	  event.request.foo = 1
+      event.request.foo = 1
 
 When the :func:`~pyramid.events.subscriber` decorator is used a
 :term:`scan` must be performed against the package containing the
@@ -113,7 +113,7 @@ your application like so:
    :linenos:
 
    def handle_new_request(event):
-       print 'request', event.request   
+       print 'request', event.request
 
    def handle_new_response(event):
        print 'response', event.response
@@ -150,3 +150,86 @@ application, because the interface defined at
 :class:`pyramid.interfaces.INewResponse` says it must
 (:class:`pyramid.events.NewResponse` objects also have a ``request``).
 
+.. _custom_events:
+
+Creating Your Own Events
+------------------------
+
+In addition to using the events that the Pyramid framework creates,
+you can create your own events for use in your application. This can
+be useful to decouple parts of your application.
+
+For example, suppose your application has to do many things when a new
+document is created. Rather than putting all this logic in the view
+that creates the document, you can create the document in your view
+and then fire a custom event. Subscribers to the custom event can take
+other actions, such as indexing the document, sending email, or
+sending a message to a remote system.
+
+An event is simply an object. There are no required attributes or
+method for your custom events. In general, your events should keep
+track of the information that subscribers will need. Here are some
+example custom event classes:
+
+.. code-block:: python
+   :linenos:
+
+    class DocCreated(object):
+        def __init__(self, doc, request):
+            self.doc = doc
+            self.request = request
+
+    class UserEvent(object):
+        def __init__(self, user):
+            self.user = user
+
+    class UserLoggedIn(UserEvent):
+        pass
+
+Some Pyramid applications choose to define custom events classes in an
+``events`` module.
+
+You can subscribe to custom events in the same way that you subscribe
+to Pyramid events -- either imperatively or with a decorator. You can
+also use custom events with :ref:`subscriber predicates
+<subscriber_predicates>`. Here's an example of subscribing to a custom
+event with a decorator:
+
+.. code-block:: python
+   :linenos:
+
+    from pyramid.events import subscriber
+    from .events import DocCreated
+    from .index import index_doc
+
+    @subscriber(DocCreated)
+    def index_doc(event):
+        # index the document using our application's index_doc function
+        index_doc(event.doc, event.request)
+
+The above example assumes that the application defines a
+``DocCreated`` event class and an ``index_doc`` function.
+
+To fire your custom events use the
+:meth:`pyramid.registry.Registry.notify` method, which is most often
+accessed as ``request.registry.notify``. For example:
+
+.. code-block:: python
+   :linenos:
+
+    from .events import DocCreated
+
+    def new_doc_view(request):
+        doc = MyDoc()
+        event = DocCreated(doc, request)
+        request.registry.notify(event)
+        return {'document': doc}
+
+This example view will notify all subscribers to the custom
+``DocCreated`` event.
+
+Note that when you fire an event, all subscribers are run
+synchronously so it's generally not a good idea
+to create event handlers that may take a long time to run. Although
+event handlers could be used as a central place to spawn tasks on your
+own message queues.
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 74765f8e2..2964686d3 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -808,7 +808,7 @@ If this setting is supplied within the :app:`Pyramid` application
    default_locale_name = settings['pyramid.default_locale_name']
 
 .. index::
-   single: detecting langauges
+   single: detecting languages
 
 "Detecting" Available Languages
 -------------------------------
@@ -984,7 +984,7 @@ requires no additional coding or configuration.
 
 The default locale negotiator implementation named
 :class:`~pyramid.i18n.default_locale_negotiator` uses the following
-set of steps to dermine the locale name.
+set of steps to determine the locale name.
 
 - First, the negotiator looks for the ``_LOCALE_`` attribute of the
   request object (possibly set directly by view code or by a listener
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 48164d323..032f4be6b 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -217,6 +217,8 @@ that the Pyramid core doesn't.  Add-on packages already exist which let you
 easily send email, let you use the Jinja2 templating system, let you use
 XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc.
 
+Examples: http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-on-documentation
+
 
 Class-based and function-based views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -857,7 +859,7 @@ It's our goal that no Pyramid question go unanswered.  Whether you ask a
 question on IRC, on the Pylons-discuss maillist, or on StackOverflow, you're
 likely to get a reasonably prompt response.  We don't tolerate "support
 trolls" or other people who seem to get their rocks off by berating fellow
-users in our various offical support channels.  We try to keep it well-lit
+users in our various official support channels.  We try to keep it well-lit
 and new-user-friendly.
 
 Example: Visit irc\://freenode.net#pyramid (the ``#pyramid`` channel on
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 8cf67e104..ec5d706aa 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -1007,12 +1007,12 @@ Pyramid application based on the data in the file.
 application.  As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be
 invoked at all to run a :app:`Pyramid` application.  The use of ``pserve`` to
 run a :app:`Pyramid` application is purely conventional based on the output
-of its scaffolding.  But we strongly recommend using while developing your
-application, because many other convenience introspection commands (such as
-``pviews``, ``prequest``, ``proutes`` and others) are also implemented in
-terms of configuration availability of this ``.ini`` file format.  It also
-configures Pyramid logging and provides the ``--reload`` switch for
-convenient restarting of the server when code changes.
+of its scaffolding.  But we strongly recommend using ``pserve`` while
+developing your application, because many other convenience introspection
+commands (such as ``pviews``, ``prequest``, ``proutes`` and others) are also
+implemented in terms of configuration availability of this ``.ini`` file
+format.  It also configures Pyramid logging and provides the ``--reload``
+switch for convenient restarting of the server when code changes.
 
 .. _alternate_wsgi_server:
 
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 20a9eda31..a2811dbae 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -198,7 +198,7 @@ representing the JSON serialization of the return value:
 
 .. code-block:: python
 
-   '{"content": "Hello!"}'
+   {"content": "Hello!"}
 
 The return value needn't be a dictionary, but the return value must contain
 values serializable by the configured serializer (by default ``json.dumps``).
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 7ba46c92c..358977089 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -148,6 +148,7 @@ Some gotchas:
 .. index::
    single: pyramid_beaker
    single: Beaker
+   single: pyramid_redis_sessions
    single: session factory (alternates)
 
 .. _using_alternate_session_factories:
@@ -155,11 +156,17 @@ Some gotchas:
 Using Alternate Session Factories
 ---------------------------------
 
-At the time of this writing, exactly one alternate session factory
-implementation exists, named ``pyramid_beaker``. This is a session factory
-that uses the `Beaker <http://beaker.groovie.org/>`_ library as a backend.
-Beaker has support for file-based sessions, database based sessions, and
-encrypted cookie-based sessions.  See `the pyramid_beaker documentation
+At the time of this writing, exactly two alternate session factories
+exist.
+
+The first is named ``pyramid_redis_sessions``.  It can be downloaded from PyPI.
+It uses Redis as a backend.  It is the recommended persistent session solution
+at the time of this writing.
+
+The second is named ``pyramid_beaker``. This is a session factory that uses the
+`Beaker <http://beaker.groovie.org/>`_ library as a backend.  Beaker has
+support for file-based sessions, database based sessions, and encrypted
+cookie-based sessions.  See `the pyramid_beaker documentation
 <http://docs.pylonsproject.org/projects/pyramid_beaker/en/latest/>`_ for more
 information about ``pyramid_beaker``.
 
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index a70398c80..26bb6b6cd 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -725,7 +725,7 @@ This template doesn't use any advanced features of Mako, only the
 Using A Mako def name Within a Renderer Name
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sommetime you'd like to render a ``def`` inside of a Mako template instead of
+Sometimes you'd like to render a ``def`` inside of a Mako template instead of
 the full Mako template. To render a def inside a Mako template, given a
 :term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can
 configure the template as a :term:`renderer` like so:
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 2eb6ece13..a60c5ba56 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -289,7 +289,7 @@ system uses this algorithm to find a :term:`context` resource and a
     return resource "C".
 
 #.  Traversal ends when a) the entire path is exhausted or b) when any
-    resouce raises a :exc:`KeyError` from its ``__getitem__`` or c) when any
+    resource raises a :exc:`KeyError` from its ``__getitem__`` or c) when any
     non-final path element traversal does not have a ``__getitem__`` method
     (resulting in a :exc:`AttributeError`) or d) when any path element is
     prefixed with the set of characters ``@@`` (indicating that the characters
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 18cb3e4db..310c160c0 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -865,7 +865,7 @@ Debugging Route Matching
 ------------------------
 
 It's useful to be able to take a peek under the hood when requests that enter
-your application arent matching your routes as you expect them to.  To debug
+your application aren't matching your routes as you expect them to.  To debug
 route matching, use the ``PYRAMID_DEBUG_ROUTEMATCH`` environment variable or the
 ``pyramid.debug_routematch`` configuration file setting (set either to ``true``).
 Details of the route matching decision for a particular request to the
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 047898cfe..e09fd83ab 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -290,9 +290,9 @@ configured view.
   of the ``REQUEST_METHOD`` of the :term:`WSGI` environment.
 
 ``request_param``
-  This value can be any string or a sequence of strings.  A view declaration 
-  with this argument ensures that the view will only be called when the 
-  :term:`request` has a key in the ``request.params`` dictionary (an HTTP 
+  This value can be any string or a sequence of strings.  A view declaration
+  with this argument ensures that the view will only be called when the
+  :term:`request` has a key in the ``request.params`` dictionary (an HTTP
   ``GET`` or ``POST`` variable) that has a name which matches the
   supplied value.
 
@@ -306,8 +306,6 @@ configured view.
   consideration of keys and values in the ``request.params`` dictionary.
 
 ``match_param``
-  .. versionadded:: 1.2
-
   This param may be either a single string of the format "key=value" or a
   dict of key/value pairs.
 
@@ -324,6 +322,8 @@ configured view.
   If ``match_param`` is not supplied, the view will be invoked without
   consideration of the keys and values in ``request.matchdict``.
 
+  .. versionadded:: 1.2
+
 ``containment``
   This value should be a reference to a Python class or :term:`interface`
   that a parent object in the context resource's :term:`lineage` must provide
@@ -505,7 +505,7 @@ configuration stanza:
 .. code-block:: python
    :linenos:
 
-   config.add_view('mypackage.views.my_view', route_name='ok', 
+   config.add_view('mypackage.views.my_view', route_name='ok',
                    request_method='POST', permission='read')
 
 All arguments to ``view_config`` may be omitted.  For example:
@@ -557,6 +557,35 @@ form of :term:`declarative configuration`, while
 :meth:`pyramid.config.Configurator.add_view` is a form of :term:`imperative
 configuration`.  However, they both do the same thing.
 
+Inverting Predicate Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can invert the meaning of any predicate value by wrapping it in a call to
+:class:`pyramid.config.not_`.
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import not_
+
+   config.add_view(
+       'mypackage.views.my_view',
+       route_name='ok',
+       request_method=not_('POST')
+       )
+
+The above example will ensure that the view is called if the request method
+is *not* ``POST``, at least if no other view is more specific.
+
+This technique of wrapping a predicate value in ``not_`` can be used anywhere
+predicate values are accepted:
+
+- :meth:`pyramid.config.Configurator.add_view`
+
+- :meth:`pyramid.view.view_config`
+
+.. versionadded:: 1.5
+
 .. index::
    single: view_config placement
 
@@ -802,7 +831,7 @@ of this:
        config.add_view(
            RESTView, route_name='rest', attr='delete', request_method='DELETE')
 
-To reduce the amount of repetion in the ``config.add_view`` statements, we
+To reduce the amount of repetition in the ``config.add_view`` statements, we
 can move the ``route_name='rest'`` argument to a ``@view_default`` class
 decorator on the RESTView class: