Skip to content
Browse files

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

  • Loading branch information...
2 parents f9f8c67 + fbe74a8 commit 3c48872ca9f08bf87d2bf5df9516861216210a49 @mcdonc mcdonc committed Mar 13, 2012
View
127 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,32 +73,35 @@ 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
``__init__.py`` file to add an :term:`authentication policy` and an
: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,21 +110,23 @@ 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``,
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.
@@ -189,10 +194,19 @@ visit ``/login``.
We'll need to import some stuff to service the needs of these two functions:
the ``pyramid.view.forbidden_view_config`` class, a number of values from the
``pyramid.security`` module, and a value from our newly added
-``tutorial.security`` package.
+``tutorial.security`` package. Add the following import statements to the
+head of the ``views.py`` file:
+
+.. literalinclude:: src/authorization/tutorial/views.py
+ :lines: 9-18,24-25
+ :linenos:
+ :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,
@@ -205,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.:
@@ -239,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
@@ -264,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
View
7 docs/tutorials/wiki2/definingmodels.rst
@@ -67,12 +67,15 @@ script. In particular, we'll replace our import of ``MyModel`` with one of
``Page`` and we'll change the very end of the script to create a ``Page``
rather than a ``MyModel`` and add it to our ``DBSession``.
-The result of all of our edits to ``populate.py`` will end up looking
-something like this:
+Open ``tutorial/tutorial/scripts/populate.py`` and edit it to look like the
+following:
.. literalinclude:: src/models/tutorial/scripts/populate.py
:linenos:
:language: python
+ :emphasize-lines: 14,34
+
+(Only the highlighted lines need to be changed.)
Repopulating the Database
-------------------------
View
7 docs/tutorials/wiki2/definingviews.rst
@@ -28,15 +28,18 @@ dependency of the original "tutorial" application. The original "tutorial"
application was generated by the ``pcreate`` command; it doesn't know
about our custom application requirements. We need to add a dependency on
the ``docutils`` package to our ``tutorial`` package's ``setup.py`` file by
-assigning this dependency to the ``install_requires`` parameter in the
+assigning this dependency to the ``requires`` parameter in the
``setup`` function.
-Our resulting ``setup.py`` should look like so:
+Open ``tutorial/setup.py`` and edit it to look like the following:
.. literalinclude:: src/views/setup.py
:linenos:
+ :emphasize-lines: 17
:language: python
+(Only the highlighted line needs to be added)
+
Running ``setup.py develop``
============================

0 comments on commit 3c48872

Please sign in to comment.
Something went wrong with that request. Please try again.