Merge branch 'master' of github.com:Pylons/pyramid

author: Chris McDonough <chrism@plope.com> 2013-08-15 18:40:27 +0200
committer: Chris McDonough <chrism@plope.com> 2013-08-15 18:40:27 +0200
commit: 5aab1e9c2aebbbb0e955a34067db9a196d430a0c (patch)
tree: 727028ad4eeb596c291d0f96fbc9bb520ec971fd /docs/narr
parent: b210ce350a3856166376f63a32725cc1516ba294 (diff)
parent: 7319ab677216063581e47a231fd70b8b55a19466 (diff)
download: pyramid-5aab1e9c2aebbbb0e955a34067db9a196d430a0c.tar.gz
pyramid-5aab1e9c2aebbbb0e955a34067db9a196d430a0c.tar.bz2
pyramid-5aab1e9c2aebbbb0e955a34067db9a196d430a0c.zip
11 files changed, 155 insertions, 135 deletions
diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt
index 0bfac946e..0fccba624 100644
--- a/docs/narr/MyProject/myproject/templates/mytemplate.pt
+++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt
@@ -1,7 +1,7 @@
 <!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" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
 <head>
-  <title>The Pyramid Web Application Development Framework</title>
+  <title>The Pyramid Web Framework</title>
   <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
   <meta name="keywords" content="python web application" />
   <meta name="description" content="pyramid web application" />
@@ -24,7 +24,7 @@
       <div class="middle align-center">
         <p class="app-welcome">
           Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
+          the Pyramid Web Framework.
         </p>
       </div>
     </div>
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/install.rst b/docs/narr/install.rst
index 8fc63f3a4..d05c8abeb 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -162,19 +162,19 @@ also prevent :app:`Pyramid` from globally installing versions of
 packages that are not compatible with your system Python.
 
 To set up a virtualenv in which to install :app:`Pyramid`, first ensure that
-:term:`setuptools` or :term:`distribute` is installed.  To do so, invoke
+:term:`setuptools` is installed.  To do so, invoke
 ``import setuptools`` within the Python interpreter you'd like to run
 :app:`Pyramid` under.
 
-The following command will not display anything if setuptools or distribute is
+The following command will not display anything if setuptools is
 already installed:
 
 .. code-block:: text
 
    $ python2.7 -c 'import setuptools'
 
-Running the same command will yield the following output if setuptools or
-distribute is not yet installed:
+Running the same command will yield the following output if setuptools is not
+yet installed:
 
 .. code-block:: text
 
@@ -183,27 +183,23 @@ distribute is not yet installed:
    ImportError: No module named setuptools
 
 If ``import setuptools`` raises an :exc:`ImportError` as it does above, you
-will need to install setuptools or distribute manually.
+will need to install setuptools manually.
 
 If you are using a "system" Python (one installed by your OS distributor or a
 3rd-party packager such as Fink or MacPorts), you can usually install the
-setuptools or distribute package by using your system's package manager.  If
+setuptools package by using your system's package manager.  If
 you cannot do this, or if you're using a self-installed version of Python,
-you will need to install setuptools or distribute "by hand".  Installing
-setuptools or distribute "by hand" is always a reasonable thing to do, even
+you will need to install setuptools "by hand".  Installing
+setuptools "by hand" is always a reasonable thing to do, even
 if your package manager already has a pre-chewed version of setuptools for
 installation.
 
-If you're using Python 2, you'll want to install ``setuptools``.  If you're
-using Python 3, you'll want to install ``distribute``.  Below we tell you how
-to do both.
-
-Installing Setuptools On Python 2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Installing Setuptools
+~~~~~~~~~~~~~~~~~~~~~
 
 To install setuptools by hand under Python 2, first download `ez_setup.py
-<http://peak.telecommunity.com/dist/ez_setup.py>`_ then invoke it using the
-Python interpreter into which you want to install setuptools.
+<https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ then
+invoke it using the Python interpreter into which you want to install setuptools.
 
 .. code-block:: text
 
@@ -218,35 +214,13 @@ the script.  To remediate this, you may need to do:
 
    $ sudo python ez_setup.py
 
-Installing Distribute On Python 3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``setuptools`` doesn't work under Python 3.  Instead, you can use
-``distribute``, which is a fork of setuptools.  To
-install it, first download `distribute_setup.py
-<http://python-distribute.org/distribute_setup.py>`_ then invoke it using the
-Python interpreter into which you want to install setuptools.
-
-.. code-block:: text
-
-   $ python3 distribute_setup.py
-
-Once this command is invoked, distribute should be installed on your system.
-If the command fails due to permission errors, you may need to be the
-administrative user on your system to successfully invoke the script.  To
-remediate this, you may need to do:
-
-.. code-block:: text
-
-   $ sudo python3 distribute_setup.py
-
 .. index::
    pair: install; virtualenv
 
 Installing the ``virtualenv`` Package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Once you've got setuptools or distribute installed, you should install the
+Once you've got setuptools installed, you should install the
 :term:`virtualenv` package.  To install the :term:`virtualenv` package into
 your setuptools-enabled Python interpreter, use the ``easy_install`` command.
 
@@ -261,7 +235,7 @@ your setuptools-enabled Python interpreter, use the ``easy_install`` command.
    Turing-complete.
 
    If you insist on using ``pyvenv``, you'll need to understand how to install
-   software such as ``distribute`` into the virtual environment manually,
+   software such as ``setuptools`` into the virtual environment manually,
    which this guide does not cover.
 
 .. code-block:: text
@@ -335,91 +309,37 @@ complete, as it downloads and installs a number of dependencies.
 Installing :app:`Pyramid` on a Windows System
 -------------------------------------------------
 
-You can use Pyramid on Windows under Python 2 or under Python 3.  Directions
-for both versions are included below.
+You can use Pyramid on Windows under Python 2 or under Python 3.
 
-Windows Using Python 2
-~~~~~~~~~~~~~~~~~~~~~~
-
-#. Install the most recent `Python 2.7.x version
+#. Install the most recent `Python 2.7.x or 3.3.x version
    <http://www.python.org/download/>`_ for your system.
 
 #. Install the `Python for Windows extensions
    <http://sourceforge.net/projects/pywin32/files/>`_.  Make sure to
-   pick the right download for Python 2.7 and install it using the
-   same Python installation from the previous step.
+   pick the right download for Python 2.7 or Python 3.3 and install it
+   using the same Python installation from the previous step.
 
 #. Install latest :term:`setuptools` distribution into the Python you
    obtained/installed/found in the step above: download `ez_setup.py
-   <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.7 installation using a
-   command prompt:
+   <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_
+   and run it using the ``python`` interpreter of your Python 2.7 or 3.3
+   installation using a command prompt:
 
    .. code-block:: text
 
+      # modify the command according to the python version, e.g.:
+      # for Python 2.7:
       c:\> c:\Python27\python ez_setup.py
+      # for Python 3.3:
+      c:\> c:\Python33\python ez_setup.py
 
 #. Install `virtualenv`:
 
    .. code-block:: text
-
-      c:\> c:\Python27\Scripts\easy_install virtualenv
-
-#. Make a :term:`virtualenv` workspace:
-
-   .. code-block:: text
-
-      c:\> set VENV=c:\env
-      c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV%
-
-   You can either follow the use of the environment variable, ``%VENV%``,
-   or replace it with the root directory of the :term:`virtualenv`.
-   In that case, the `set` command can be skipped.
-   If you choose the former approach, ensure that it's an absolute path.
-
-#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell
-   environment wired to use the virtualenv.
-
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
-   installed:
-
-   .. code-block:: text
-
-      c:\env> %VENV%\Scripts\easy_install pyramid
-
-Windows Using Python 3
-~~~~~~~~~~~~~~~~~~~~~~
-
-#. Install, or find the latest version of `Python 3.x
-   <http://www.python.org/download/>`_ for your system and which is
-   supported by Pyramid.
-
-#. Install the `Python for Windows extensions
-   <http://sourceforge.net/projects/pywin32/files/>`_.  Make sure to
-   pick the right download for Python 3.x and install it using the
-   same Python installation from the previous step.
-
-#. Install latest :term:`distribute` distribution into the Python you
-   obtained/installed/found in the step above: download `distribute_setup.py
-   <http://python-distribute.org/distribute_setup.py>`_ and run it using the
-   ``python`` interpreter of your Python 3.x installation using a command
-   prompt:
-
-   .. code-block:: text
-
       # modify the command according to the python version, e.g.:
-      # for Python 3.2.x:
-      c:\> c:\Python32\python distribute_setup.py
-      # for Python 3.3.x:
-      c:\> c:\Python33\python distribute_setup.py
-
-#. Install :term:`virtualenv`:
-
-   .. code-block:: text
-
-      # for Python 3.2.x:
-      c:\> c:\Python32\Scripts\easy_install virtualenv
-      # for Python 3.3.x:
+      # for Python 2.7:
+      c:\> c:\Python27\Scripts\easy_install virtualenv
+      # for Python 3.3:
       c:\> c:\Python33\Scripts\easy_install virtualenv
 
 #. Make a :term:`virtualenv` workspace:
@@ -427,9 +347,11 @@ Windows Using Python 3
    .. code-block:: text
 
       c:\> set VENV=c:\env
-      # for Python 3.2.x:
-      c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV%
-      # for Python 3.3.x:
+      
+      # modify the command according to the python version, e.g.:
+      # for Python 2.7:
+      c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV%
+      # for Python 3.3:
       c:\> c:\Python33\Scripts\virtualenv --no-site-packages %VENV%
 
    You can either follow the use of the environment variable, ``%VENV%``,
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index fa2646134..032f4be6b 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -859,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 9d69a65a5..ec5d706aa 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -992,6 +992,8 @@ prompt with a similar configuration as would be loaded if you were running
 your Pyramid application via ``pserve``.  This can be a useful debugging tool.
 See :ref:`interactive_shell` for more details.
 
+.. _what_is_this_pserve_thing:
+
 What Is This ``pserve`` Thing
 -----------------------------
 
@@ -1005,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/sessions.rst b/docs/narr/sessions.rst
index 7ec280c8a..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``.
 
@@ -181,6 +188,8 @@ implementation in the :mod:`pyramid.session` module as inspiration.
 .. index::
    single: flash messages
 
+.. _flash_messages:
+
 Flash Messages
 --------------
 
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index d4cf20b93..26bb6b6cd 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -616,6 +616,8 @@ extension so that these ``svn:ignore`` patterns work.
 .. index::
    pair: debugging; templates
 
+.. _debugging_templates:
+
 Debugging Templates
 -------------------
 
@@ -711,7 +713,7 @@ look like:
          <h1 class="title">Welcome to <code>${project}</code>, an
 	  application generated by the <a
 	  href="http://docs.pylonsproject.org/projects/pyramid/current/"
-         >pyramid</a> web application framework.</h1>
+         >pyramid</a> web framework.</h1>
       </body>
     </html>
 
@@ -723,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 fd3229339..e09fd83ab 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -831,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:
 
@@ -1005,6 +1005,8 @@ invoked as the result of the ``http_cache`` argument to view configuration.
 .. index::
    pair: view configuration; debugging
 
+.. _debugging_view_configuration:
+
 Debugging View Configuration
 ----------------------------
author	Chris McDonough <chrism@plope.com>	2013-08-15 18:40:27 +0200
committer	Chris McDonough <chrism@plope.com>	2013-08-15 18:40:27 +0200
commit	5aab1e9c2aebbbb0e955a34067db9a196d430a0c (patch)
tree	727028ad4eeb596c291d0f96fbc9bb520ec971fd /docs/narr
parent	b210ce350a3856166376f63a32725cc1516ba294 (diff)
parent	7319ab677216063581e47a231fd70b8b55a19466 (diff)
download	pyramid-5aab1e9c2aebbbb0e955a34067db9a196d430a0c.tar.gz pyramid-5aab1e9c2aebbbb0e955a34067db9a196d430a0c.tar.bz2 pyramid-5aab1e9c2aebbbb0e955a34067db9a196d430a0c.zip