Roles and refresh.

5 files changed, 145 insertions, 128 deletions

diff --git a/docs/tutorials/bfgwiki2/authorization.rst b/docs/tutorials/bfgwiki2/authorization.rst
index 5257bbe5f..9aeb98505 100644
--- a/docs/tutorials/bfgwiki2/authorization.rst
+++ b/docs/tutorials/bfgwiki2/authorization.rst
@@ -6,9 +6,9 @@ Adding Authorization
 
 Our application currently allows anyone with access to the server to
 view, edit, and add pages to our wiki.  For purposes of demonstration
-we'll change our application to allow people whom possess a specific
-username (`editor`) to add and edit wiki pages but we'll continue
-allowing anyone with access to the server to view pages.
+we'll change our application to allow only people whom possess a
+specific username (`editor`) to add and edit wiki pages but we'll
+continue allowing anyone with access to the server to view pages.
 :mod:`repoze.bfg` provides facilities for *authorization* and
 *authentication*.  We'll make use of both features to provide security
 to our application.
@@ -42,15 +42,16 @@ your ``models.py`` file:
 
 The ``RootFactory`` class we've just added will be used by
 :mod:`repoze.bfg` to construct a ``context`` object.  The context is
-attached to our request as the ``context`` attribute.
+attached to the request object passed to our view callables as the
+``context`` attribute.
 
 All of our context objects will possess an ``__acl__`` attribute that
-allows "Everyone" (a special principal) to view all pages, while
-allowing only a user named ``editor`` to edit and add pages.  The
-``__acl__`` attribute attached to a context is interpreted specially
-by :mod:`repoze.bfg` as an access control list during view execution.
-See :ref:`assigning_acls` for more information about what an
-:term:`ACL` represents.
+allows :data:`repoze.bfg.security.Everyone` (a special principal) to
+view all pages, while allowing only a user named ``editor`` to edit
+and add pages.  The ``__acl__`` attribute attached to a context is
+interpreted specially by :mod:`repoze.bfg` as an access control list
+during view callable execution.  See :ref:`assigning_acls` for more
+information about what an :term:`ACL` represents.
 
 .. note: Although we don't use the functionality here, the ``factory``
    used to create route contexts may differ per-route as opposed to
@@ -65,29 +66,31 @@ your application's ``run.py`` will look like this.
    :linenos:
    :language: python
 
-Configuring a ``repoze.bfg`` Authentication Policy
---------------------------------------------------
+Configuring a ``repoze.bfg`` Authorization Policy
+-------------------------------------------------
 
 For any :mod:`repoze.bfg` application to perform authorization, we
 need to add a ``security.py`` module and we'll need to change our
-:term:`application registry` to add an :term:`authentication policy`
-and an :term:`authorization policy`.
+``configure.zcml`` file to add an :term:`authentication policy` and an
+:term:`authorization policy`.
 
 Changing ``configure.zcml``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We'll change our ``configure.zcml`` file to enable an
-``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to
-enable declarative security checking.  We'll also change
-``configure.zcml`` to add a ``forbidden`` stanza which points at our
-login view.  This configures our newly created login view to show up when
-:mod:`repoze.bfg` detects that a view invocation can not be authorized. 
-Also, we'll add ``view_permission`` attributes with the value ``edit`` to
-the ``edit_page`` and ``add_page`` routes.  This indicates that the views
-which these routes reference cannot be invoked without the
-authenticated user possessing the ``edit`` permission with respect to
-the current context.  When you're done, your ``configure.zcml`` will
-look like so
+:class:`repoze.bfg.authentication.AuthTktAuthenticationPolicy` and an
+:class:`repoze.bfg.authorization.ACLAuthorizationPolicy` to enable
+declarative security checking.  We'll also change ``configure.zcml``
+to add a ``forbidden`` stanza which points at our ``login``
+:term:`view callable`, also known as a :term:`forbidden view`.  This
+configures our newly created login view to show up when
+:mod:`repoze.bfg` detects that a view invocation can not be
+authorized.  Also, we'll add ``view_permission`` attributes with the
+value ``edit`` to the ``edit_page`` and ``add_page`` route
+declarations.  This indicates that the view callables which these
+routes reference cannot be invoked without the authenticated user
+possessing the ``edit`` permission with respect to the current
+context.  When you're done, your ``configure.zcml`` will look like so
 
 .. literalinclude:: src/authorization/tutorial/configure.zcml
    :linenos:
@@ -98,14 +101,14 @@ Adding ``security.py``
 
 Add a ``security.py`` module within your package (in the same
 directory as "run.py", "views.py", etc) with the following content:
-The groupfinder defined here is an authorization policy "callback"; it
-is a a callable that accepts a userid and a request.  If the userid
-exists in the system, the callback will return a sequence of group
-identifiers (or an empty sequence if the user isn't a member of any
-groups).  If the userid *does not* exist in the system, the callback
-will return ``None``.  We'll use "dummy" data to represent user and
-groups sources.  When we're done, your application's ``security.py``
-will look like this.
+The groupfinder defined here is an :term:`authentication policy`
+"callback"; it is a a callable that accepts a userid and a request.
+If the userid exists in the system, the callback will return a
+sequence of group identifiers (or an empty sequence if the user isn't
+a member of any groups).  If the userid *does not* exist in the
+system, the callback will return ``None``.  We'll use "dummy" data to
+represent user and groups sources.  When we're done, your
+application's ``security.py`` will look like this.
 
 .. literalinclude:: src/authorization/tutorial/security.py
    :linenos:
@@ -114,16 +117,17 @@ will look like this.
 Adding Login and Logout Views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-We'll add a ``login`` view which renders a login form and processes
-the post from the login form, checking credentials.
+We'll add a ``login`` view callable which renders a login form and
+processes the post from the login form, checking credentials.
 
-We'll also add a ``logout`` view to our application and provide a link
-to it.  This view will clear the credentials of the logged in user and
-redirect back to the front page.
+We'll also add a ``logout`` view callable to our application and
+provide a link to it.  This view will clear the credentials of the
+logged in user and redirect back to the front page.
 
 We'll add a different file (for presentation convenience) to add login
-and logout views.  Add a file named ``login.py`` to your application
-(in the same directory as ``views.py``) with the following content:
+and logout view callables.  Add a file named ``login.py`` to your
+application (in the same directory as ``views.py``) with the following
+content:
 
 .. literalinclude:: src/authorization/tutorial/login.py
    :linenos:
@@ -133,8 +137,8 @@ Changing Existing Views
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Then we need to change each of our ``view_page``, ``edit_page`` and
-``add_page`` views in ``views.py`` to pass a "logged in" parameter
-into its template.  We'll add something like this to each view body:
+``add_page`` views in ``views.py`` to pass a "logged in" parameter to
+its template.  We'll add something like this to each view body:
 
 .. code-block:: python
    :linenos:
@@ -180,8 +184,8 @@ class="main_content">`` div:
 Viewing the Application in a Browser
 ------------------------------------
 
-Once we've set up the WSGI pipeline properly, we can finally examine
-our application in a browser.  The views we'll try are as follows:
+We can finally examine our application in a browser.  The views we'll
+try are as follows:
 
 - Visiting `http://localhost:6543/ <http://localhost:6543/>`_ in a
   browser invokes the ``view_wiki`` view.  This always redirects to
diff --git a/docs/tutorials/bfgwiki2/background.rst b/docs/tutorials/bfgwiki2/background.rst
index 31cecdf96..09dc8de64 100644
--- a/docs/tutorials/bfgwiki2/background.rst
+++ b/docs/tutorials/bfgwiki2/background.rst
@@ -12,6 +12,6 @@ To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
 variant, etc) *or* he will need a Windows system of any kind.
 
-This tutorial is known to work under :mod:`repoze.bfg` version 1.1a5.
+This tutorial is targeted at :mod:`repoze.bfg` version 1.2.
 
 Have fun!
diff --git a/docs/tutorials/bfgwiki2/basiclayout.rst b/docs/tutorials/bfgwiki2/basiclayout.rst
index b8d0ddcc2..b7c6b795d 100644
--- a/docs/tutorials/bfgwiki2/basiclayout.rst
+++ b/docs/tutorials/bfgwiki2/basiclayout.rst
@@ -25,29 +25,30 @@ following:
       :linenos:
       :language: xml
 
-#. *Line 1*.  The root ``<configure>`` element, in a ``bfg``
-   namespace.
+#. *Line 1*.  The root ``<configure>`` element, using the
+   ``http://namespaces.repoze.org/bfg`` namespace.
 
 #. *Line 4*. Boilerplate, the comment explains.
 
 #. *Lines 6-7*.  Register a :term:`subscriber` that tears down the
    SQLAlchemy connection after a request is finished.
 
-#. *Lines 9-13*.  Register a ``<route>`` that will be used when the
-   URL is ``/``.  Since this ``<route>`` has an empty ``path``
-   attribute, it is the "default" route. The attribute named ``view``
-   with the value ``.views.my_view`` is the dotted name to a
-   *function* we write (generated by the ``bfg_routesalchemy``
-   template) that is given a ``request`` object and which returns a
-   response or a dictionary.  You will use mostly ``<route>``
-   statements in a :term:`URL dispatch` based application to map URLs
-   to code.  This ``route`` also names a ``view_renderer``, which is a
-   template which lives in the ``templates`` subdirectory of the
-   package.  When the ``.views.my_view`` view returns a dictionary, a
-   "renderer" will use this template to create a response.
+#. *Lines 9-13*.  Register a ``<route>`` :term:`route configuration`
+   that will be used when the URL is ``/``.  Since this ``<route>``
+   has an empty ``path`` attribute, it is the "default" route. The
+   attribute named ``view`` with the value ``.views.my_view`` is the
+   dotted name to a *function* we write (generated by the
+   ``bfg_routesalchemy`` template) that is given a ``request`` object
+   and which returns a response or a dictionary.  You will use mostly
+   ``<route>`` statements in a :term:`URL dispatch` based application
+   to map URLs to code.  This ``route`` also names a
+   ``view_renderer``, which is a template which lives in the
+   ``templates`` subdirectory of the package.  When the
+   ``.views.my_view`` view returns a dictionary, a :term:`renderer`
+   will use this template to create a response.
 
 #. *Lines 15-18*.  Register a ``<static>`` directive that will match
-   any URL hat starts with ``/static/``.  This will serve up static
+   any URL that starts with ``/static/``.  This will serve up static
    resources for us, in this case, at
    ``http://localhost:6543/static/`` and below.  With this
    declaration, we're saying that any URL that starts with ``/static``
@@ -104,40 +105,46 @@ Here is the source for ``models.py``:
 App Startup with ``run.py``
 ---------------------------
 
-How does a :mod:`repoze.bfg` application start up?  When you run under
-``paster`` using the ``tutorial.ini`` generated config file, the
-application area points at an entry point.  Our entry point happens to
-be in ``run.py`` and its ``app`` function:
+When you run the application using the ``paster`` command using the
+``tutorial.ini`` generated config file, the application configuration
+points at an Setuptools *entry point* described as
+``egg:tutorial#app``.  In our application, because the application's
+``setup.py`` file says so, this entry point happens to be the ``app``
+function within the file named ``run.py``:
 
    .. literalinclude:: src/basiclayout/tutorial/run.py
       :linenos:
       :language: py
 
-#. *Lines 1-5*. Imports to support later code.
+#. *Lines 1-4*. Imports to support later code.
 
-#. *Lines 7-11*.  We define a ``Cleanup`` class which has a
+#. *Lines 6-10*.  We define a ``Cleanup`` class which has a
    ``__del__`` method (the method called at Python object
    destruction), which calls a function.
 
-#. *Lines 13-15*.  An event :term:`subscriber` which adds a
+#. *Lines 12-14*.  An event :term:`subscriber` which adds a
    ``Cleanup`` instance to the WSGI environment as
    ``tutorial.sasession``.  As a result of registering this event
    subscriber, when the WSGI environment is cleaned up, our database
    connection will be removed.
 
-#. *Lines 17-24*. Get the database configuration string from the
+#. *Lines 21-23*. Get the database configuration string from the
    ``tutorial.ini`` file's ``[app:sql]`` section.  This will be a URI
    (something like ``sqlite://``).
 
-#. Line *25*. We initialize our SQL database using SQLAlchemy, passing
+#. Line *24*. We initialize our SQL database using SQLAlchemy, passing
    it the db string.
 
-#. Line *26*.  We construct a :term:`Configurator`.  The first
+#. *Line 25*.  We construct a :term:`Configurator`.  The first
    argument provided to the configurator is the :term:`root factory`,
    which is used by the :mod:`repoze.bfg` :term:`traversal` mechanism.
    Since this is a URL dispatch application, the root factory is
    ``None``.  The second argument ``settings`` is passed as a keyword
    argument.  It contains a dictionary of settings parsed by
-   PasteDeploy.  We then use the ``make_wsgi_app`` method of the
-   :term:`Configurator` to return a :term:`WSGI` application.
+   PasteDeploy.
+
+# *Lines 26-29*.  We then load a ZCML file to do application
+   configuration, and use the
+   :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` method
+   to return a :term:`WSGI` application.
 
diff --git a/docs/tutorials/bfgwiki2/definingmodels.rst b/docs/tutorials/bfgwiki2/definingmodels.rst
index 982865a80..0cae00ede 100644
--- a/docs/tutorials/bfgwiki2/definingmodels.rst
+++ b/docs/tutorials/bfgwiki2/definingmodels.rst
@@ -24,19 +24,19 @@ sample and we're not going to use it.
 
 Then, we'll add a ``Page`` class.  Because this is a SQLAlchemy
 application, this class should inherit from an instance of
-``sqlalchemy.ext.declarative.declarative_base``.  Declarative
+:class:`sqlalchemy.ext.declarative.declarative_base`.  Declarative
 SQLAlchemy models are easier to use than directly-mapped ones.  The
 code generated by our ``routesalchemy`` paster template does not use
-declarative SQLAlchemy syntax, so we'll need to change various things to
-begin to use declarative syntax.
+declarative SQLAlchemy syntax, so we'll need to change various things
+to begin to use declarative syntax.
 
 Our ``Page`` class will have a class level attribute ``__tablename__``
 which equals the string ``pages``.  This means that SQLAlchemy will
 store our wiki data in a SQL table named ``pages``.  Our Page class
 will also have class-level attributes named ``id``, ``pagename`` and
-``data`` (all instances of ``sqlalchemy.Column``).  These will map to
-columns in the ``pages`` table.  The ``id`` attribute will be the
-primary key in the table.  The ``name`` attribute will be a text
+``data`` (all instances of :class:`sqlalchemy.Column`).  These will
+map to columns in the ``pages`` table.  The ``id`` attribute will be
+the primary key in the table.  The ``name`` attribute will be a text
 attribute, each value of which needs to be unique within the column.
 The ``data`` attribute is a text attribute that will hold the body of
 each page.
diff --git a/docs/tutorials/bfgwiki2/definingviews.rst b/docs/tutorials/bfgwiki2/definingviews.rst
index c4c609ff2..416b431be 100644
--- a/docs/tutorials/bfgwiki2/definingviews.rst
+++ b/docs/tutorials/bfgwiki2/definingviews.rst
@@ -2,16 +2,17 @@
 Defining Views
 ==============
 
-A :term:`view` in a :term:`url dispatch` -based :mod:`repoze.bfg`
-application is typically a simple Python function that accepts a
-single parameter named :term:`request`.  A view is assumed to return a
-:term:`response` object.
+A :term:`view callable` in a :term:`url dispatch` -based
+:mod:`repoze.bfg` application is typically a simple Python function
+that accepts a single parameter named :term:`request`.  A view
+callable is assumed to return a :term:`response` object.
 
 .. note:: A :mod:`repoze.bfg` view can also be defined as callable
    which accepts *two* arguments: a :term:`context` and a
    :term:`request`.  You'll see this two-argument pattern used in
    other :mod:`repoze.bfg` tutorials and applications.  Either calling
-   convention will work in any :mod:`repoze.bfg` application.  In
+   convention will work in any :mod:`repoze.bfg` application; the
+   calling conventions can be used interchangeably as necessary.  In
    :term:`url dispatch` based applications, however, the context
    object is rarely used in the view body itself, so within this
    tutorial we define views as callables that accept only a request to
@@ -56,31 +57,32 @@ Adding View Functions
 We'll get rid of our ``my_view`` view function in our ``views.py``
 file.  It's only an example and isn't relevant to our application.
 
-Then we're going to add four :term:`view` functions to our
-``views.py`` module.  One view (named ``view_wiki``) will display the
-wiki itself (it will answer on the root URL), another named
-``view_page`` will display an individual page, another named
-``add_page`` will allow a page to be added, and a final view named
-``edit_page`` will allow a page to be edited.  We'll describe each one
-briefly and show the resulting ``views.py`` file afterwards.
+Then we're going to add four :term:`view callable` functions to our
+``views.py`` module.  One view callable (named ``view_wiki``) will
+display the wiki itself (it will answer on the root URL), another
+named ``view_page`` will display an individual page, another named
+``add_page`` will allow a page to be added, and a final view callable
+named ``edit_page`` will allow a page to be edited.  We'll describe
+each one briefly and show the resulting ``views.py`` file afterwards.
 
 .. note::
 
   There is nothing special about the filename ``views.py``.  A project
-  may have many views throughout its codebase in arbitrarily-named
-  files.  Files implementing views often have ``view`` in their
-  filenames (or may live in a Python subpackage of your application
-  package named ``views``), but this is only by convention.
+  may have many view callables throughout its codebase in
+  arbitrarily-named files.  Files implementing view callables often
+  have ``view`` in their filenames (or may live in a Python subpackage
+  of your application package named ``views``), but this is only by
+  convention.
 
 The ``view_wiki`` view function
 -------------------------------
 
-The ``view_wiki`` function will respond as the default view of a
-``Wiki`` model object.  It always redirects to a URL which represents
-the path to our "FrontPage".  It returns an instance of the
-``webob.exc.HTTPFound`` class (instances of which implement the WebOb
-:term:`response` interface), It will use the
-``repoze.bfg.url.route_url`` API to construct a URL to the
+The ``view_wiki`` function will respond as the :term:`default view` of
+a ``Wiki`` model object.  It always redirects to a URL which
+represents the path to our "FrontPage".  It returns an instance of the
+:class:`webob.exc.HTTPFound` class (instances of which implement the
+WebOb :term:`response` interface), It will use the
+:func:`repoze.bfg.url.route_url` API to construct a URL to the
 ``FrontPage`` page (e.g. ``http://localhost:6543/FrontPage``), and
 will use it as the "location" of the HTTPFound response, forming an
 HTTP redirect.
@@ -88,8 +90,8 @@ HTTP redirect.
 The ``view_page`` view function
 -------------------------------
 
-The ``view_page`` function will respond as the default view of a
-``Page`` object.  The ``view_page`` function renders the
+The ``view_page`` function will respond as the :term:`default view` of
+a ``Page`` object.  The ``view_page`` function renders the
 :term:`ReStructuredText` body of a page (stored as the ``data``
 attribute of a Page object) as HTML.  Then it substitutes an HTML
 anchor for each *WikiWord* reference in the rendered HTML using a
@@ -134,22 +136,23 @@ e.g. ``http://localhost:6543/add_page/SomeName``, the ``pagename``
 value in the matchdict will be ``SomeName``.
 
 If the view execution is *not* a result of a form submission (if the
-expression ``'form.submitted' in request.params`` is False), the view
-renders a template.  To do so, it generates a "save url" which the
-template use as the form post URL during rendering.  We're lazy here,
-so we're trying to use the same template (``templates/edit.pt``) for
-the add view as well as the page edit view, so we create a dummy Page
-object in order to satisfy the edit form's desire to have *some* page
-object exposed as ``page``, and BFG will render the template
-associated with this view to a response.
+expression ``'form.submitted' in request.params`` is ``False``), the
+view callable renders a template.  To do so, it generates a "save url"
+which the template use as the form post URL during rendering.  We're
+lazy here, so we're trying to use the same template
+(``templates/edit.pt``) for the add view as well as the page edit
+view, so we create a dummy Page object in order to satisfy the edit
+form's desire to have *some* page object exposed as ``page``, and
+:mod:`repoze.bfg` will render the template associated with this view
+to a response.
 
 If the view execution *is* a result of a form submission (if the
-expression ``'form.submitted' in request.params`` is True), we scrape
-the page body from the form data, create a Page object using the name
-in the matchdict ``pagename``, and obtain the page body from the
-request, and save it into the database using ``session.add``.  We then
-redirect back to the ``view_page`` view (the default view for a page)
-for the newly created page.
+expression ``'form.submitted' in request.params`` is ``True``), we
+scrape the page body from the form data, create a Page object using
+the name in the matchdict ``pagename``, and obtain the page body from
+the request, and save it into the database using ``session.add``.  We
+then redirect back to the ``view_page`` view (the :term:`default view`
+for a Page) for the newly created page.
 
 The ``edit_page`` view function
 -------------------------------
@@ -162,15 +165,17 @@ will have a ``pagename`` key matching the name of the page the user
 wants to edit.
 
 If the view execution is *not* a result of a form submission (if the
-expression ``'form.submitted' in request.params`` is False), the view
-simply renders the edit form, passing the request, the page object,
-and a save_url which will be used as the action of the generated form.
+expression ``'form.submitted' in request.params`` is ``False``), the
+view simply renders the edit form, passing the request, the page
+object, and a save_url which will be used as the action of the
+generated form.
 
 If the view execution *is* a result of a form submission (if the
-expression ``'form.submitted' in request.params`` is True), the view
-grabs the ``body`` element of the request parameter and sets it as the
-``data`` key in the matchdict.  It then redirects to the default view
-of the wiki page, which will always be the ``view_page`` view.
+expression ``'form.submitted' in request.params`` is ``True``), the
+view grabs the ``body`` element of the request parameter and sets it
+as the ``data`` key in the matchdict.  It then redirects to the
+default view of the wiki page, which will always be the ``view_page``
+view.
 
 Viewing the Result of Our Edits to ``views.py``
 ===============================================
@@ -187,9 +192,9 @@ Adding Templates
 
 The views we've added all reference a :term:`template`.  Each template
 is a :term:`Chameleon` template.  The default templating system in
-:mod:`repoze.bfg` is a variant of :term:`ZPT` provided by Chameleon.
-These templates will live in the ``templates`` directory of our
-tutorial package.
+:mod:`repoze.bfg` is a variant of :term:`ZPT` provided by
+:term:`Chameleon`.  These templates will live in the ``templates``
+directory of our tutorial package.
 
 The ``view.pt`` Template
 ------------------------
@@ -270,7 +275,8 @@ Note that the *ordering* of these declarations is very important.
 
 #. Add a declaration which maps the empty path (signifying the root
    URL) to the view named ``view_wiki`` in our ``views.py`` file with
-   the name ``view_wiki``.  This is the default view for the wiki.
+   the name ``view_wiki``.  This is the :term:`default view` for the
+   wiki.
 
 #. Add a declaration which maps the path pattern ``:pagename`` to the
    view named ``view_page`` in our ``views.py`` file with the view
@@ -316,7 +322,7 @@ Let's add a piece of middleware to the WSGI pipeline.  We'll add
 ``egg:Paste#evalerror`` middleware which displays debuggable errors in
 the browser while you're developing (this is *not* recommended for
 deployment as it is a security risk).  Let's insert evalerror into the
-pipeline right above "egg:repoze.tm2#tm", making our resulting
+pipeline right above ``egg:repoze.tm2#tm``, making our resulting
 ``tutorial.ini`` file look like so:
 
 .. literalinclude:: src/views/tutorial.ini