Merge pull request #479 from ppaez/wiki-documentation

Adding Authorization chapter of SQL wiki tutorial

1 files changed, 70 insertions, 49 deletions

diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 5c60640b7..b76fd9a6c 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -12,28 +12,34 @@ 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.
 
-To do so, we'll add an :term:`authentication policy` and an
-:term:`authorization policy`.  We'll also add a ``security.py`` module,
-create a :term:`root factory` with an :term:`ACL`, and add :term:`permission`
-declarations to the ``edit_page`` and ``add_page`` views.  Then we'll add
-``login`` and ``logout`` views, and modify the existing views to make them
-return a ``logged_in`` flag to the renderer.  Finally, we will add a
-``login.pt`` template and change the existing ``view.pt`` and ``edit.pt`` to
-show a "Logout" link when not logged in.
+We will do the following steps:
+
+* Add a :term:`root factory` with an :term:`ACL` (``models.py``).
+* Add an :term:`authentication policy` and an :term:`authorization policy`
+  (``__init__.py``).
+* Add an authentication policy callback (new ``security.py`` module).
+* Add ``login`` and ``logout`` views (``views.py``).
+* Add :term:`permission` declarations to the ``edit_page`` and ``add_page``
+  views (``views.py``).
+* Make the existing views return a ``logged_in`` flag to the renderer (``views.py``).
+* Add a login template (new ``login.pt``).
+* Add a "Logout" link to be shown when logged in and viewing or editing a page
+  (``view.pt``, ``edit.pt``).
 
 The source code for this tutorial stage can be browsed at
 `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/
 <http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/>`_.
 
-Changing ``__init__.py`` For Authorization
--------------------------------------------
-
-We're going to be making several changes to our ``__init__.py`` file which
-will help us configure an authorization policy.
-
 Adding A Root Factory
 ~~~~~~~~~~~~~~~~~~~~~
 
+Open ``models.py`` and add the following statements:
+
+.. literalinclude:: src/authorization/tutorial/models.py
+   :lines: 1-4,35-39
+   :linenos:
+   :language: python
+
 We're going to start to use a custom :term:`root factory` within our
 ``__init__.py`` file.  The objects generated by the root factory will be used
 as the :term:`context` of each request to our application.  We do this to
@@ -44,14 +50,8 @@ our contexts, we can begin to make use of the declarative security features
 of :app:`Pyramid`.
 
 We'll modify our ``__init__.py``, passing in a :term:`root factory` to our
-:term:`Configurator` constructor.  We'll point it at a new class we create
-inside our ``models.py`` file.  Add the following statements to your
-``models.py`` file:
-
-.. literalinclude:: src/authorization/tutorial/models.py
-   :lines: 1-4,35-39
-   :linenos:
-   :language: python
+:term:`Configurator` constructor.  We'll point it at the new class we created
+inside our ``models.py`` file.
 
 The ``RootFactory`` class we've just added will be used by :app:`Pyramid` to
 construct a ``context`` object.  The context is attached to the request
@@ -73,8 +73,11 @@ information about what an :term:`ACL` represents.
 We'll pass the ``RootFactory`` we created in the step above in as the
 ``root_factory`` argument to a :term:`Configurator`.
 
-Configuring an Authorization Policy
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add an Authorization Policy and an Authentication Policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We're going to be making several changes to our ``__init__.py`` file which
+will help us configure an authorization policy.
 
 For any :app:`Pyramid` application to perform authorization, we need to add a
 ``security.py`` module (we'll do that shortly) and we'll need to change our
@@ -82,23 +85,23 @@ For any :app:`Pyramid` application to perform authorization, we need to add a
 :term:`authorization policy` which uses the ``security.py`` file for a
 *callback*.
 
-We'll change our ``__init__.py`` file to enable an
-``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to enable
-declarative security checking. We need to import the new policies:
+We'll enable an ``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy``
+to implement declarative security checking. Open ``tutorial/__init__.py`` and
+add these import statements:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
    :lines: 2-3,7
    :linenos:
    :language: python
 
-Then, we'll add those policies to the configuration:
+Now add those policies to the configuration:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
    :lines: 16-22
    :linenos:
    :language: python
 
-Note that that the
+Note that the
 :class:`pyramid.authentication.AuthTktAuthenticationPolicy` constructor
 accepts two arguments: ``secret`` and ``callback``.  ``secret`` is a string
 representing an encryption key used by the "authentication ticket" machinery
@@ -107,7 +110,7 @@ represented by this policy: it is required.  The ``callback`` is a
 haven't added that module yet, but we're about to.
 
 Viewing Your Changes
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 When we're done configuring a root factory, adding a authentication and
 authorization policies, and adding routes for ``/login`` and ``/logout``,
@@ -115,13 +118,15 @@ your application's ``__init__.py`` will look like this:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
    :linenos:
+   :emphasize-lines: 2-3,7,16-18,20-22,25-26
    :language: python
 
-Adding ``security.py``
-----------------------
+Adding an authentication policy callback
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Add a ``security.py`` module within your package (in the same directory as
-:file:`__init__.py`, :file:`views.py`, etc.) with the following content:
+Add a ``tutorial/security.py`` module within your package (in the same
+directory as :file:`__init__.py`, :file:`views.py`, etc.) with the
+following content:
 
 .. literalinclude:: src/authorization/tutorial/security.py
    :linenos:
@@ -147,7 +152,7 @@ and the permission associated with the ``add_page`` and ``edit_page``
 views, the ``editor`` user should be able to add and edit pages.
 
 Adding Login and Logout Views
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To our ``views.py`` we'll add a ``login`` view callable which renders a login
 form and processes the post from the login form, checking credentials.
@@ -198,7 +203,10 @@ head of the ``views.py`` file:
    :language: python
 
 Changing Existing Views
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Add permision declarations
+--------------------------
 
 Then we need to change each of our ``view_page``, ``edit_page`` and
 ``add_page`` view callables in ``views.py``.  Within each of these views,
@@ -211,6 +219,9 @@ something like this to each view body:
    from pyramid.security import authenticated_userid
    logged_in = authenticated_userid(request)
 
+Return a logged_in flag to the renderer
+---------------------------------------
+
 We'll then change the return value of these views to pass the `resulting
 `logged_in`` value to the template, e.g.:
 
@@ -245,16 +256,16 @@ a user whom is a member of the group named ``group:editors`` will able to
 invoke the views associated with the ``add_page`` or ``edit_page`` routes.
 
 Adding the ``login.pt`` Template
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Add a ``login.pt`` template to your templates directory.  It's
-referred to within the login view we just added to ``login.py``.
+referred to within the login view we just added to ``views.py``.
 
 .. literalinclude:: src/authorization/tutorial/templates/login.pt
    :language: xml
 
-Change ``view.pt`` and ``edit.pt``
-----------------------------------
+Add a "Logout" link when logged in
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We'll also need to change our ``edit.pt`` and ``view.pt`` templates to
 display a "Logout" link if someone is logged in.  This link will
@@ -270,46 +281,56 @@ class="app-welcome align-right">`` div:
    </span>
 
 Seeing Our Changes To ``views.py`` and our Templates
-----------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Our ``views.py`` module will look something like this when we're done:
 
 .. literalinclude:: src/authorization/tutorial/views.py
    :linenos:
+   :emphasize-lines: 11,14-18,56,59,71,74,89-115,117-121
    :language: python
 
+(Only the highlighted lines need to be added.)
+
 Our ``edit.pt`` template will look something like this when we're done:
 
 .. literalinclude:: src/authorization/tutorial/templates/edit.pt
+   :emphasize-lines: 41-43
    :language: xml
 
+(Only the highlighted lines need to be added.)
+
 Our ``view.pt`` template will look something like this when we're done:
 
 .. literalinclude:: src/authorization/tutorial/templates/view.pt
+   :emphasize-lines: 41-43
    :language: xml
 
+(Only the highlighted lines need to be added.)
+
 Viewing the Application in a Browser
-------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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 (See
+:ref:`wiki2-start-the-application`).  Launch a browser and visit
+each of the following URLs, check that the result is as expected:
 
-- Visiting ``http://localhost:6543/`` in a browser invokes the
+- ``http://localhost:6543/`` invokes the
   ``view_wiki`` view.  This always redirects to the ``view_page`` view
   of the FrontPage page object.  It is executable by any user.
 
-- Visiting ``http://localhost:6543/FrontPage`` in a browser invokes
+- ``http://localhost:6543/FrontPage`` invokes
   the ``view_page`` view of the FrontPage page object.
 
-- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser
+- ``http://localhost:6543/edit_page/FrontPage``
   invokes the edit view for the FrontPage object.  It is executable by
   only the ``editor`` user.  If a different user (or the anonymous
   user) invokes it, a login form will be displayed.  Supplying the
   credentials with the username ``editor``, password ``editor`` will
   display the edit page form.
 
-- Visiting ``http://localhost:6543/add_page/SomePageName`` in a
-  browser invokes the add view for a page.  It is executable by only
+- ``http://localhost:6543/add_page/SomePageName``
+  invokes the add view for a page.  It is executable by only
   the ``editor`` user.  If a different user (or the anonymous user)
   invokes it, a login form will be displayed.  Supplying the
   credentials with the username ``editor``, password ``editor`` will