From e53e13423685eac190676c4be32716c3a42603e4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 25 Oct 2010 17:40:43 -0400 Subject: rename bfgwiki to wiki --- docs/tutorials/wiki/authorization.rst | 300 +++++++++++++++ docs/tutorials/wiki/background.rst | 18 + docs/tutorials/wiki/basiclayout.rst | 137 +++++++ docs/tutorials/wiki/definingmodels.rst | 162 ++++++++ docs/tutorials/wiki/definingviews.rst | 416 +++++++++++++++++++++ docs/tutorials/wiki/distributing.rst | 49 +++ docs/tutorials/wiki/index.rst | 27 ++ docs/tutorials/wiki/installation.rst | 254 +++++++++++++ docs/tutorials/wiki/src/authorization/CHANGES.txt | 5 + docs/tutorials/wiki/src/authorization/README.txt | 4 + docs/tutorials/wiki/src/authorization/setup.cfg | 28 ++ docs/tutorials/wiki/src/authorization/setup.py | 43 +++ docs/tutorials/wiki/src/authorization/tutorial.ini | 21 ++ .../wiki/src/authorization/tutorial/__init__.py | 2 + .../wiki/src/authorization/tutorial/configure.zcml | 25 ++ .../wiki/src/authorization/tutorial/login.py | 44 +++ .../wiki/src/authorization/tutorial/models.py | 27 ++ .../wiki/src/authorization/tutorial/run.py | 23 ++ .../wiki/src/authorization/tutorial/security.py | 8 + .../src/authorization/tutorial/templates/edit.pt | 34 ++ .../src/authorization/tutorial/templates/login.pt | 32 ++ .../authorization/tutorial/templates/mytemplate.pt | 99 +++++ .../tutorial/templates/static/default.css | 380 +++++++++++++++++++ .../tutorial/templates/static/images/img01.gif | Bin 0 -> 3840 bytes .../tutorial/templates/static/images/img02.gif | Bin 0 -> 4689 bytes .../tutorial/templates/static/images/img03.gif | Bin 0 -> 229 bytes .../tutorial/templates/static/images/img04.gif | Bin 0 -> 92 bytes .../tutorial/templates/static/images/spacer.gif | Bin 0 -> 43 bytes .../tutorial/templates/static/style.css | 109 ++++++ .../tutorial/templates/static/templatelicense.txt | 243 ++++++++++++ .../src/authorization/tutorial/templates/view.pt | 31 ++ .../wiki/src/authorization/tutorial/tests.py | 123 ++++++ .../wiki/src/authorization/tutorial/views.py | 76 ++++ docs/tutorials/wiki/src/basiclayout/CHANGES.txt | 4 + docs/tutorials/wiki/src/basiclayout/README.txt | 4 + docs/tutorials/wiki/src/basiclayout/setup.cfg | 28 ++ docs/tutorials/wiki/src/basiclayout/setup.py | 42 +++ docs/tutorials/wiki/src/basiclayout/tutorial.ini | 20 + .../wiki/src/basiclayout/tutorial/__init__.py | 2 + .../wiki/src/basiclayout/tutorial/configure.zcml | 17 + .../wiki/src/basiclayout/tutorial/models.py | 12 + .../tutorials/wiki/src/basiclayout/tutorial/run.py | 22 ++ .../basiclayout/tutorial/templates/mytemplate.pt | 99 +++++ .../tutorial/templates/static/default.css | 380 +++++++++++++++++++ .../tutorial/templates/static/images/img01.gif | Bin 0 -> 3840 bytes .../tutorial/templates/static/images/img02.gif | Bin 0 -> 4689 bytes .../tutorial/templates/static/images/img03.gif | Bin 0 -> 229 bytes .../tutorial/templates/static/images/img04.gif | Bin 0 -> 92 bytes .../tutorial/templates/static/images/spacer.gif | Bin 0 -> 43 bytes .../tutorial/templates/static/templatelicense.txt | 243 ++++++++++++ .../wiki/src/basiclayout/tutorial/tests.py | 19 + .../wiki/src/basiclayout/tutorial/views.py | 2 + docs/tutorials/wiki/src/models/CHANGES.txt | 4 + docs/tutorials/wiki/src/models/README.txt | 4 + docs/tutorials/wiki/src/models/setup.cfg | 28 ++ docs/tutorials/wiki/src/models/setup.py | 42 +++ docs/tutorials/wiki/src/models/tutorial.ini | 20 + .../tutorials/wiki/src/models/tutorial/__init__.py | 2 + .../wiki/src/models/tutorial/configure.zcml | 17 + docs/tutorials/wiki/src/models/tutorial/models.py | 22 ++ docs/tutorials/wiki/src/models/tutorial/run.py | 22 ++ .../src/models/tutorial/templates/mytemplate.pt | 99 +++++ .../models/tutorial/templates/static/default.css | 380 +++++++++++++++++++ .../tutorial/templates/static/images/img01.gif | Bin 0 -> 3840 bytes .../tutorial/templates/static/images/img02.gif | Bin 0 -> 4689 bytes .../tutorial/templates/static/images/img03.gif | Bin 0 -> 229 bytes .../tutorial/templates/static/images/img04.gif | Bin 0 -> 92 bytes .../tutorial/templates/static/images/spacer.gif | Bin 0 -> 43 bytes .../tutorial/templates/static/templatelicense.txt | 243 ++++++++++++ docs/tutorials/wiki/src/models/tutorial/tests.py | 64 ++++ docs/tutorials/wiki/src/models/tutorial/views.py | 2 + docs/tutorials/wiki/src/viewdecorators/CHANGES.txt | 4 + docs/tutorials/wiki/src/viewdecorators/README.txt | 4 + docs/tutorials/wiki/src/viewdecorators/setup.cfg | 28 ++ docs/tutorials/wiki/src/viewdecorators/setup.py | 42 +++ .../tutorials/wiki/src/viewdecorators/tutorial.ini | 21 ++ .../wiki/src/viewdecorators/tutorial/__init__.py | 2 + .../src/viewdecorators/tutorial/configure.zcml | 13 + .../wiki/src/viewdecorators/tutorial/models.py | 22 ++ .../wiki/src/viewdecorators/tutorial/run.py | 22 ++ .../src/viewdecorators/tutorial/templates/edit.pt | 30 ++ .../tutorial/templates/mytemplate.pt | 99 +++++ .../tutorial/templates/static/default.css | 380 +++++++++++++++++++ .../tutorial/templates/static/images/img01.gif | Bin 0 -> 3840 bytes .../tutorial/templates/static/images/img02.gif | Bin 0 -> 4689 bytes .../tutorial/templates/static/images/img03.gif | Bin 0 -> 229 bytes .../tutorial/templates/static/images/img04.gif | Bin 0 -> 92 bytes .../tutorial/templates/static/images/spacer.gif | Bin 0 -> 43 bytes .../tutorial/templates/static/style.css | 109 ++++++ .../tutorial/templates/static/templatelicense.txt | 243 ++++++++++++ .../src/viewdecorators/tutorial/templates/view.pt | 26 ++ .../wiki/src/viewdecorators/tutorial/tests.py | 123 ++++++ .../wiki/src/viewdecorators/tutorial/views.py | 62 +++ docs/tutorials/wiki/src/views/CHANGES.txt | 3 + docs/tutorials/wiki/src/views/README.txt | 4 + docs/tutorials/wiki/src/views/setup.cfg | 28 ++ docs/tutorials/wiki/src/views/setup.py | 42 +++ docs/tutorials/wiki/src/views/tutorial.ini | 21 ++ docs/tutorials/wiki/src/views/tutorial/__init__.py | 2 + .../wiki/src/views/tutorial/configure.zcml | 36 ++ docs/tutorials/wiki/src/views/tutorial/models.py | 22 ++ docs/tutorials/wiki/src/views/tutorial/run.py | 22 ++ .../wiki/src/views/tutorial/templates/edit.pt | 32 ++ .../src/views/tutorial/templates/mytemplate.pt | 99 +++++ .../views/tutorial/templates/static/default.css | 380 +++++++++++++++++++ .../tutorial/templates/static/images/img01.gif | Bin 0 -> 3840 bytes .../tutorial/templates/static/images/img02.gif | Bin 0 -> 4689 bytes .../tutorial/templates/static/images/img03.gif | Bin 0 -> 229 bytes .../tutorial/templates/static/images/img04.gif | Bin 0 -> 92 bytes .../tutorial/templates/static/images/spacer.gif | Bin 0 -> 43 bytes .../src/views/tutorial/templates/static/style.css | 109 ++++++ .../tutorial/templates/static/templatelicense.txt | 243 ++++++++++++ .../wiki/src/views/tutorial/templates/view.pt | 29 ++ docs/tutorials/wiki/src/views/tutorial/tests.py | 127 +++++++ docs/tutorials/wiki/src/views/tutorial/views.py | 56 +++ docs/tutorials/wiki/viewdecorators.rst | 239 ++++++++++++ 116 files changed, 7287 insertions(+) create mode 100644 docs/tutorials/wiki/authorization.rst create mode 100644 docs/tutorials/wiki/background.rst create mode 100644 docs/tutorials/wiki/basiclayout.rst create mode 100644 docs/tutorials/wiki/definingmodels.rst create mode 100644 docs/tutorials/wiki/definingviews.rst create mode 100644 docs/tutorials/wiki/distributing.rst create mode 100644 docs/tutorials/wiki/index.rst create mode 100644 docs/tutorials/wiki/installation.rst create mode 100644 docs/tutorials/wiki/src/authorization/CHANGES.txt create mode 100644 docs/tutorials/wiki/src/authorization/README.txt create mode 100644 docs/tutorials/wiki/src/authorization/setup.cfg create mode 100644 docs/tutorials/wiki/src/authorization/setup.py create mode 100644 docs/tutorials/wiki/src/authorization/tutorial.ini create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/__init__.py create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/configure.zcml create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/login.py create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/models.py create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/run.py create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/security.py create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/static/default.css create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/static/style.css create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/tests.py create mode 100644 docs/tutorials/wiki/src/authorization/tutorial/views.py create mode 100644 docs/tutorials/wiki/src/basiclayout/CHANGES.txt create mode 100644 docs/tutorials/wiki/src/basiclayout/README.txt create mode 100644 docs/tutorials/wiki/src/basiclayout/setup.cfg create mode 100644 docs/tutorials/wiki/src/basiclayout/setup.py create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial.ini create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/configure.zcml create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/models.py create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/run.py create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/default.css create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/tests.py create mode 100644 docs/tutorials/wiki/src/basiclayout/tutorial/views.py create mode 100644 docs/tutorials/wiki/src/models/CHANGES.txt create mode 100644 docs/tutorials/wiki/src/models/README.txt create mode 100644 docs/tutorials/wiki/src/models/setup.cfg create mode 100644 docs/tutorials/wiki/src/models/setup.py create mode 100644 docs/tutorials/wiki/src/models/tutorial.ini create mode 100644 docs/tutorials/wiki/src/models/tutorial/__init__.py create mode 100644 docs/tutorials/wiki/src/models/tutorial/configure.zcml create mode 100644 docs/tutorials/wiki/src/models/tutorial/models.py create mode 100644 docs/tutorials/wiki/src/models/tutorial/run.py create mode 100644 docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/wiki/src/models/tutorial/templates/static/default.css create mode 100644 docs/tutorials/wiki/src/models/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/wiki/src/models/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/wiki/src/models/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/wiki/src/models/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/wiki/src/models/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/wiki/src/models/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/wiki/src/models/tutorial/tests.py create mode 100644 docs/tutorials/wiki/src/models/tutorial/views.py create mode 100644 docs/tutorials/wiki/src/viewdecorators/CHANGES.txt create mode 100644 docs/tutorials/wiki/src/viewdecorators/README.txt create mode 100644 docs/tutorials/wiki/src/viewdecorators/setup.cfg create mode 100644 docs/tutorials/wiki/src/viewdecorators/setup.py create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial.ini create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/__init__.py create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/configure.zcml create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/models.py create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/run.py create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/edit.pt create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/default.css create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/style.css create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/view.pt create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/tests.py create mode 100644 docs/tutorials/wiki/src/viewdecorators/tutorial/views.py create mode 100644 docs/tutorials/wiki/src/views/CHANGES.txt create mode 100644 docs/tutorials/wiki/src/views/README.txt create mode 100644 docs/tutorials/wiki/src/views/setup.cfg create mode 100644 docs/tutorials/wiki/src/views/setup.py create mode 100644 docs/tutorials/wiki/src/views/tutorial.ini create mode 100644 docs/tutorials/wiki/src/views/tutorial/__init__.py create mode 100644 docs/tutorials/wiki/src/views/tutorial/configure.zcml create mode 100644 docs/tutorials/wiki/src/views/tutorial/models.py create mode 100644 docs/tutorials/wiki/src/views/tutorial/run.py create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/edit.pt create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/static/default.css create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/static/style.css create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/wiki/src/views/tutorial/templates/view.pt create mode 100644 docs/tutorials/wiki/src/views/tutorial/tests.py create mode 100644 docs/tutorials/wiki/src/views/tutorial/views.py create mode 100644 docs/tutorials/wiki/viewdecorators.rst (limited to 'docs') diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst new file mode 100644 index 000000000..48908a97b --- /dev/null +++ b/docs/tutorials/wiki/authorization.rst @@ -0,0 +1,300 @@ +==================== +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 are members of a +*group* named ``group:editors`` to add and edit wiki pages but we'll +continue allowing anyone with access to the server to view pages. +:mod:`pyramid` provides facilities for *authorization* and +*authentication*. We'll make use of both features to provide security +to our application. + +The source code for this tutorial stage can be browsed via +`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/authorization/ +`_. + + +The source code for this tutorial stage can be browsed at +`docs.repoze.org `_. + +Configuring a ``pyramid`` Authentication Policy +-------------------------------------------------- + +For any :mod:`pyramid` 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 a :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 add a new view +stanza, which specifies a :term:`forbidden view`. This configures our +login view to show up when :mod:`pyramid` detects that a view +invocation can not be authorized. When you're done, your +``configure.zcml`` will look like so: + +.. literalinclude:: src/authorization/tutorial/configure.zcml + :linenos: + :language: xml + +Note that the ``authtktauthenticationpolicy`` tag has two attributes: +``secret`` and ``callback``. ``secret`` is a string representing an +encryption key used by the "authentication ticket" machinery +represented by this policy: it is required. The ``callback`` is a +string, representing a :term:`dotted Python name`, which points at the +``groupfinder`` function in the current directory's ``security.py`` +file. We haven't added that module yet, but we're about to. + +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: + +.. literalinclude:: src/authorization/tutorial/security.py + :linenos: + :language: python + +The ``groupfinder`` function defined here is an authorization policy +"callback"; it is a callable that accepts a userid and a request. If +the userid exists in the set of users known by 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``. In +a production system this data will most often come from a database, +but here we use "dummy" data to represent user and groups +sources. Note that the ``editor`` user is a member of the +``group:editors`` group in our dummy group data (the ``GROUPS`` data +structure). + +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 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 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: + +.. literalinclude:: src/authorization/tutorial/login.py + :linenos: + :language: python + +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: + +.. ignore-next-block +.. code-block:: python + :linenos: + + from pyramid.security import authenticated_userid + logged_in = authenticated_userid(request) + +We'll then change the return value of each view that has an associated +``renderer`` to pass the `resulting `logged_in`` value to the +template. For example: + +.. ignore-next-block +.. code-block:: python + :linenos: + + return dict(page = context, + content = content, + logged_in = logged_in, + edit_url = edit_url) + +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``. + +.. literalinclude:: src/authorization/tutorial/templates/login.pt + :linenos: + :language: xml + +Change ``view.pt`` and ``edit.pt`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 +invoke the logout view. + +To do so we'll add this to both templates within the ``
`` div: + +.. code-block:: xml + :linenos: + + + Logout + + +Giving Our Root Model Object an ACL +----------------------------------- + +We need to give our root model object an :term:`ACL`. This ACL will +be sufficient to provide enough information to the :mod:`pyramid` +security machinery to challenge a user who doesn't have appropriate +credentials when he attempts to invoke the ``add_page`` or +``edit_page`` views. + +We need to perform some imports at module scope in our ``models.py`` +file: + +.. code-block:: python + :linenos: + + from pyramid.security import Allow + from pyramid.security import Everyone + +Our root model is a ``Wiki`` object. We'll add the following line at +class scope to our ``Wiki`` class: + +.. code-block:: python + :linenos: + + __acl__ = [ (Allow, Everyone, 'view'), + (Allow, 'group:editors', 'edit') ] + +It's only happenstance that we're assigning this ACL at class scope. +An ACL can be attached to an object *instance* too; this is how "row +level security" can be achieved in :mod:`pyramid` applications. We +actually only need *one* ACL for the entire system, however, because +our security requirements are simple, so this feature is not +demonstrated. + +Our resulting ``models.py`` file will now look like so: + +.. literalinclude:: src/authorization/tutorial/models.py + :linenos: + :language: python + +Adding ``permission`` Declarations to our ``bfg_view`` Decorators +----------------------------------------------------------------- + +To protect each of our views with a particular permission, we need to +pass a ``permission`` argument to each of our +:class:`pyramid.view.bfg_view` decorators. To do so, within +``views.py``: + +- We add ``permission='view'`` to the decorator attached to the + ``view_wiki`` view function. This makes the assertion that only + users who possess the effective ``view`` permission at the time of + the request may invoke this view. We've granted + :data:`pyramid.security.Everyone` the view permission at the root + model via its ACL, so everyone will be able to invoke the + ``view_wiki`` view. + +- We add ``permission='view'`` to the decorator attached to the + ``view_page`` view function. This makes the assertion that only + users who possess the effective ``view`` permission at the time of + the request may invoke this view. We've granted + :data:`pyramid.security.Everyone` the view permission at the root + model via its ACL, so everyone will be able to invoke the + ``view_page`` view. + +- We add ``permission='edit'`` to the decorator attached to the + ``add_page`` view function. This makes the assertion that only + users who possess the effective ``edit`` permission at the time of + the request may invoke this view. We've granted the + ``group:editors`` principal the ``edit`` permission at the root + model via its ACL, so only the a user whom is a member of the group + named ``group:editors`` will able to invoke the ``add_page`` view. + We've likewise given the ``editor`` user membership to this group + via thes ``security.py`` file by mapping him to the + ``group:editors`` group in the ``GROUPS`` data structure (``GROUPS = + {'editor':['group:editors']}``); the ``groupfinder`` function + consults the ``GROUPS`` data structure. This means that the + ``editor`` user can add pages. + +- We add ``permission='edit'`` to the ``bfg_view`` decorator attached + to the ``edit_page`` view function. This makes the assertion that + only users who possess the effective ``edit`` permission at the time + of the request may invoke this view. We've granted the + ``group:editors`` principal the ``edit`` permission at the root + model via its ACL, so only the a user whom is a member of the group + named ``group:editors`` will able to invoke the ``edit_page`` view. + We've likewise given the ``editor`` user membership to this group + via thes ``security.py`` file by mapping him to the + ``group:editors`` group in the ``GROUPS`` data structure (``GROUPS = + {'editor':['group:editors']}``); the ``groupfinder`` function + consults the ``GROUPS`` data structure. This means that the + ``editor`` user can edit pages. + +Viewing the Application in a Browser +------------------------------------ + +We can finally examine our application in a browser. The views we'll +try are as follows: + +- Visiting ``http://localhost:6543/`` in a browser 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 + the ``view_page`` view of the front page page object. This is + because it's the :term:`default view` (a view without a ``name``) + for ``Page`` objects. It is executable by any user. + +- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser + invokes the edit view for the front page 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 + show the edit page form being displayed. + +- Visiting ``http://localhost:6543/add_page/SomePageName`` in a + browser 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 + show the edit page form being displayed. + +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: + :language: python + +Our ``edit.pt`` template will look something like this when we're done: + +.. literalinclude:: src/authorization/tutorial/templates/edit.pt + :linenos: + :language: xml + +Our ``view.pt`` template will look something like this when we're done: + +.. literalinclude:: src/authorization/tutorial/templates/view.pt + :linenos: + :language: xml + +Revisiting the Application +--------------------------- + +When we revisit the application in a browser, and log in (as a result +of hitting an edit or add page and submitting the login form with the +``editor`` credentials), we'll see a Logout link in the upper right +hand corner. When we click it, we're logged out, and redirected back +to the front page. + + + diff --git a/docs/tutorials/wiki/background.rst b/docs/tutorials/wiki/background.rst new file mode 100644 index 000000000..e81cf8192 --- /dev/null +++ b/docs/tutorials/wiki/background.rst @@ -0,0 +1,18 @@ +========== +Background +========== + +This version of the :mod:`pyramid` wiki tutorial presents a +:mod:`pyramid` application that uses technologies which will be +familiar to someone with :term:`Zope` experience. It uses +:term:`ZODB` as a persistence mechanism and :term:`traversal` to map +URLs to code. It can also be followed by people without any prior +Python web framework experience. + +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 targets :mod:`pyramid` version 1.3. + +Have fun! diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst new file mode 100644 index 000000000..2649a345f --- /dev/null +++ b/docs/tutorials/wiki/basiclayout.rst @@ -0,0 +1,137 @@ +============ +Basic Layout +============ + +The starter files generated by the ``pyramid_zodb`` template are basic, +but they provide a good orientation for the high-level patterns common +to most :term:`traversal` -based :mod:`pyramid` (and :term:`ZODB` +based) projects. + +The source code for this tutorial stage can be browsed via +`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/ +`_. + +``__init__.py`` +--------------- + +A directory on disk can be turned into a Python :term:`package` by +containing an ``__init__.py`` file. Even if empty, this marks a +directory as a Python package. + +Configuration With ``configure.zcml`` +-------------------------------------- + +The ``pyramid_zodb`` template uses :term:`ZCML` to perform system +configuration. The ZCML file generated by the template looks like the +following: + + .. literalinclude:: src/basiclayout/tutorial/configure.zcml + :linenos: + :language: xml + +#. *Line 1*. The root ```` element. + +#. *Line 4*. Boilerplate, the comment explains. + +#. *Lines 6-10*. Register a ```` that names a ``context`` type + that is a class. ``.views.my_view`` is a *function* we write + (generated by the ``pyramid_zodb`` template) that is given a + ``context`` object and a ``request`` and which returns a + dictionary. The ``renderer`` tag indicates that the + ``templates/mytemplate.pt`` template should be used to turn the + dictionary returned by the view into a response. + ``templates/mytemplate.pt`` is a *relative* path: it names the + ``mytemplate.pt`` file which lives in the ``templates`` + subdirectory of the directory in which this ``configure.zcml`` + lives in. In this case, it means it lives in the ``tutorial`` + package's ``templates`` directory as ``mytemplate.pt`` + + Since this ```` doesn't have a ``name`` attribute, it is the + "default" view for that class. + +#. *Lines 12-15*. Register a ``static`` view which answers requests + which start with ``/static``. This is a view that will serve up + static resources for us, in this case, at + ``http://localhost:6543/static/`` and below. The ``path`` element + of this tag is a relative directory name, so it finds the resources + it should serve within the ``templates/static`` directory inside + the ``tutorial`` package. + +Content Models with ``models.py`` +--------------------------------- + +:mod:`pyramid` often uses the word :term:`model` when talking about +content resources arranged in the hierarchical *object graph* +consulted by :term:`traversal`. The ``models.py`` file is where the +``pyramid_zodb`` Paster template put the classes that implement our +model objects. + +Here is the source for ``models.py``: + + .. literalinclude:: src/basiclayout/tutorial/models.py + :linenos: + :language: py + +#. *Lines 3-4*. The ``MyModel`` class we referred to in the ZCML file + named ``configure.zcml`` is implemented here. Instances of this + class will be capable of being persisted in :term:`ZODB` because + the class inherits from the + :class:`persistent.mapping.PersistentMapping` class. The + ``__parent__`` and ``__name__`` are important parts of the + :term:`traversal` protocol. By default, have these as ``None`` + indicating that this is the :term:`root` object. + +#. *Lines 6-12*. ``appmaker`` is used to return the *application + root* object. It is called on *every request* to the + :mod:`pyramid` application. It also performs bootstrapping by + *creating* an application root (inside the ZODB root object) if one + does not already exist. + + We do so by first seeing if the database has the persistent + application root. If not, we make an instance, store it, and + commit the transaction. We then return the application root + object. + +App Startup with ``run.py`` +--------------------------- + +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-2*. Perform some dependency imports. + +#. *Line 12*. Get the ZODB configuration from the ``tutorial.ini`` + file's ``[app:main]`` section represented by the ``settings`` + dictionary passed to our ``app`` function. This will be a URI + (something like ``file:///path/to/Data.fs``). + +#. *Line 15*. We create a "finder" object using the + ``PersistentApplicationFinder`` helper class, passing it the ZODB + URI and the "appmaker" we've imported from ``models.py``. + +#. *Lines 16 - 17*. We create a :term:`root factory` which uses the + finder to return a ZODB root object. + +#. *Line 18*. We construct a :term:`Configurator` with a :term:`root + factory` and the settings keywords parsed by PasteDeploy. The root + factory is named ``get_root``. + +#. *Lines 19-21*. Begin configuration using the ``begin`` method of + the :meth:`pyramid.configuration.Configurator` class, load the + ``configure.zcml`` file from our package using the + :meth:`pyramid.configuration.Configurator.load_zcml` method, and + end configuration using the + :meth:`pyramid.configuration.Configurator.end` method. + +#. *Line 22*. Use the + :meth:`pyramid.configuration.Configurator.make_wsgi_app` method + to return a :term:`WSGI` application. + diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst new file mode 100644 index 000000000..b63d0c21b --- /dev/null +++ b/docs/tutorials/wiki/definingmodels.rst @@ -0,0 +1,162 @@ +=============== +Defining Models +=============== + +The first change we'll make to our bone-stock ``paster`` -generated +application will be to define a number of :term:`model` constructors. +For this application, which will be a Wiki, we will need two kinds of +model constructors: a "Wiki" model constructor, and a "Page" model +constructor. Both our Page and Wiki constructors will be class +objects. A single instance of the "Wiki" class will serve as a +container for "Page" objects, which will be instances of the "Page" +class. + +The source code for this tutorial stage can be browsed via +`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/models/ +`_. + +Deleting the Database +--------------------- + +We're going to remove the ``MyModel`` Python model class from our +``models.py`` file. Since this class is referred to within our +persistent storage (represented on disk as a file named ``Data.fs``), +we'll have strange things happen the next time we want to visit the +application in a browser. Remove the ``Data.fs`` from the +``tutorial`` directory before proceeding any further. It's always +fine to do this as long as you don't care about the content of the +database; the database itself will be recreated as necessary. + +Adding Model Classes +-------------------- + +The next thing we want to do is remove the ``MyModel`` class from the +generated ``models.py`` file. The ``MyModel`` class is only a sample +and we're not going to use it. + +.. note:: + + There is nothing automagically special about the filename + ``models.py``. A project may have many models throughout its + codebase in arbitrarily-named files. Files implementing models + often have ``model`` in their filenames (or they may live in a + Python subpackage of your application package named ``models``) , + but this is only by convention. + +Then, we'll add a ``Wiki`` class. Because this is a ZODB application, +this class should inherit from +:class:`persistent.mapping.PersistentMapping`. We want it to inherit +from the :class:`persistent.mapping.PersistentMapping` class because +our Wiki class will be a mapping of wiki page names to ``Page`` +objects. The :class:`persistent.mapping.PersistentMapping` class +provides our class with mapping behavior, and makes sure that our Wiki +page is stored as a "first-class" persistent object in our ZODB +database. + +Our ``Wiki`` class should also have a ``__name__`` attribute set to +``None`` at class scope, and should have a ``__parent__`` attribute +set to ``None`` at class scope as well. If a model has a +``__parent__`` attribute of ``None`` in a traversal-based +:mod:`pyramid` application, it means that it's the :term:`root` +model. The ``__name__`` of the root model is also always ``None``. + +Then we'll add a ``Page`` class. This class should inherit from the +:class:`persistent.Persistent` class. We'll also give it an +``__init__`` method that accepts a single parameter named ``data``. +This parameter will contain the :term:`ReStructuredText` body +representing the wiki page content. Note that ``Page`` objects don't +have an initial ``__name__`` or ``__parent__`` attribute. All objects +in a traversal graph must have a ``__name__`` and a ``__parent__`` +attribute. We don't specify these here because both ``__name__`` and +``__parent__`` will be set by by a :term:`view` function when a Page +is added to our Wiki mapping. + +Add an Appmaker +--------------- + +We're using a mini-framework callable named +``PersistentApplicationFinder`` in our application (see ``run.py``). +A ``PersistentApplicationFinder`` accepts a ZODB URL as well as an +"appmaker" callback. This callback typically lives in the +``models.py`` file. + +We want to change the appmaker function in our ``models.py`` file so +that our application root is a Wiki instance, and we'll also slot a +single page object (the front page) into the wiki. + +Looking at the Result of Our Edits to ``models.py`` +--------------------------------------------------- + +The result of all of our edits to ``models.py`` will end up looking +something like this: + +.. literalinclude:: src/models/tutorial/models.py + :linenos: + :language: python + +Testing the Models +------------------ + +To make sure the code we just wrote works, we write tests for the +model classes and the appmaker. Changing ``tests.py``, we'll write a +separate test class for each model class, and we'll write a test class +for the ``appmaker``. + +To do so, we'll retain the ``tutorial.tests.ViewTests`` class provided +as a result of the ``pyramid_zodb`` project generator. We'll add +three test classes: one for the ``Page`` model named +``PageModelTests``, one for the ``Wiki`` model named +``WikiModelTests``, and one for the appmaker named ``AppmakerTests``. + +When we're done changing ``tests.py``, it will look something like so: + +.. literalinclude:: src/models/tutorial/tests.py + :linenos: + :language: python + +Running the Tests +----------------- + +We can run these tests by using ``setup.py test`` in the same way we +did in :ref:`running_tests`. Assuming our shell's current working +directory is the "tutorial" distribution directory: + +On UNIX: + +.. code-block:: text + + $ ../bin/python setup.py test -q + +On Windows: + +.. code-block:: text + + c:\bigfntut\tutorial> ..\Scripts\python setup.py test -q + +The expected output is something like this: + +.. code-block:: text + + ..... + ---------------------------------------------------------------------- + Ran 5 tests in 0.008s + + OK + +Declaring Dependencies in Our ``setup.py`` File +----------------------------------------------- + +Our application depends on packages which are not dependencies of the +original "tutorial" application as it was generated by the ``paster +create`` command. We'll add these dependencies to our ``tutorial`` +package's ``setup.py`` file by assigning these dependencies to both +the ``install_requires`` and the ``tests_require`` parameters to the +``setup`` function. In particular, we require the ``docutils`` +package. + +Our resulting ``setup.py`` should look like so: + +.. literalinclude:: src/models/setup.py + :linenos: + :language: python + diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst new file mode 100644 index 000000000..f4d92371a --- /dev/null +++ b/docs/tutorials/wiki/definingviews.rst @@ -0,0 +1,416 @@ +============== +Defining Views +============== + +A :term:`view callable` in a traversal-based :mod:`pyramid` +application is typically a simple Python function that accepts two +parameters: :term:`context`, and :term:`request`. A view callable is +assumed to return a :term:`response` object. + +.. note:: A :mod:`pyramid` view can also be defined as callable + which accepts *one* arguments: a :term:`request`. You'll see this + one-argument pattern used in other :mod:`pyramid` tutorials and + applications. Either calling convention will work in any + :mod:`pyramid` application; the calling conventions can be used + interchangeably as necessary. In :term:`traversal` based + applications, such as this tutorial, the context is used frequently + within the body of a view method, so it makes sense to use the + two-argument syntax in this application. However, in :term:`url + dispatch` based applications, the context object is rarely used in + the view body itself, so within code that uses URL-dispatch-only, + it's common to define views as callables that accept only a request + to avoid the visual "noise". + +We're going to define several :term:`view callable` functions then +wire them into :mod:`pyramid` using some :term:`view +configuration` via :term:`ZCML`. + +The source code for this tutorial stage can be browsed via +`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/views/ +`_. + +Adding View Functions +===================== + +We're going to add four :term:`view callable` 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. + +.. note:: + + There is nothing automagically 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. + +The ``view_wiki`` view function +------------------------------- + +The ``view_wiki`` function will be configured to respond as the +default view of a ``Wiki`` model object. It always redirects to the +``Page`` object named "FrontPage". It returns an instance of the +:class:`webob.exc.HTTPFound` class (instances of which implement the +WebOb :term:`response` interface), and the +:func:`pyramid.url.model_url` API. +:func:`pyramid.url.model_url` constructs a URL to the ``FrontPage`` +page (e.g. ``http://localhost:6543/FrontPage``), and uses it as the +"location" of the HTTPFound response, forming an HTTP redirect. + +The ``view_page`` view function +------------------------------- + +The ``view_page`` function will be configured to respond as the +default view of a ``Page`` object. The ``view_page`` function renders +the :term:`ReStructuredText` body of a page (stored as the ``data`` +attribute of the context passed to the view; the context will be a +Page object) as HTML. Then it substitutes an HTML anchor for each +*WikiWord* reference in the rendered HTML using a compiled regular +expression. + +The curried function named ``check`` is used as the first argument to +``wikiwords.sub``, indicating that it should be called to provide a +value for each WikiWord match found in the content. If the wiki (our +page's ``__parent__``) already contains a page with the matched +WikiWord name, the ``check`` function generates a view link to be used +as the substitution value and returns it. If the wiki does not +already contain a page with with the matched WikiWord name, the +function generates an "add" link as the substitution value and returns +it. + +As a result, the ``content`` variable is now a fully formed bit of +HTML containing various view and add links for WikiWords based on the +content of our current page object. + +We then generate an edit URL (because it's easier to do here than in +the template), and we wrap up a number of arguments in a dictionary +and return it. + +The arguments we wrap into a dictionary include ``page``, ``content``, +and ``edit_url``. As a result, the *template* associated with this +view callable will be able to use these names to perform various +rendering tasks. The template associated with this view callable will +be a template which lives in ``templates/view.pt``, which we'll +associate with this view via the :term:`view configuration` which +lives in the ``configure.zcml`` file. + +Note the contrast between this view callable and the ``view_wiki`` +view callable. In the ``view_wiki`` view callable, we return a +:term:`response` object. In the ``view_page`` view callable, we +return a *dictionary*. It is *always* fine to return a +:term:`response` object from a :mod:`pyramid` view. Returning a +dictionary is allowed only when there is a :term:`renderer` associated +with the view callable in the view configuration. + +The ``add_page`` view function +------------------------------ + +The ``add_page`` function will be invoked when a user clicks on a +WikiWord which isn't yet represented as a page in the system. The +``check`` function within the ``view_page`` view generates URLs to +this view. It also acts as a handler for the form that is generated +when we want to add a page object. The ``context`` of the +``add_page`` view is always a Wiki object (*not* a Page object). + +The request :term:`subpath` in :mod:`pyramid` is the sequence of +names that are found *after* the view name in the URL segments given +in the ``PATH_INFO`` of the WSGI request as the result of +:term:`traversal`. If our add view is invoked via, +e.g. ``http://localhost:6543/add_page/SomeName``, the :term:`subpath` +will be a tuple: ``('SomeName',)``. + +The add view takes the zeroth element of the subpath (the wiki page +name), and aliases it to the name attribute in order to know the name +of the page we're trying to add. + +If the view rendering 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. To do 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 we'll render the template +to a response. + +If the view rendering *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 subpath and the page body, and save it into "our +context" (the wiki) using the ``__setitem__`` method of the +context. We then redirect back to the ``view_page`` view (the default +view for a page) for the newly created page. + +The ``edit_page`` view function +------------------------------- + +The ``edit_page`` function will be invoked when a user clicks the +"Edit this Page" button on the view form. It renders an edit form but +it also acts as the handler for the form it renders. The ``context`` +of the ``edit_page`` view will *always* be a Page object (never a Wiki +object). + +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. + +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`` attribute of the page context. It then redirects to +the default view of the context (the page), which will always be the +``view_page`` view. + +Viewing the Result of Our Edits to ``views.py`` +=============================================== + +The result of all of our edits to ``views.py`` will leave it looking +like this: + +.. literalinclude:: src/views/tutorial/views.py + :linenos: + :language: python + +Adding Templates +================ + +Most view callables we've added expected to be rendered via a +:term:`template`. Each template is a :term:`Chameleon` template. The +default templating system in :mod:`pyramid` is a variant of +:term:`ZPT` provided by Chameleon. These templates will live in the +``templates`` directory of our tutorial package. + +The ``view.pt`` Template +------------------------ + +The ``view.pt`` template is used for viewing a single wiki page. It +is used by the ``view_page`` view function. It should have a div that +is "structure replaced" with the ``content`` value provided by the +view. It should also have a link on the rendered page that points at +the "edit" URL (the URL which invokes the ``edit_page`` view for the +page being viewed). + +Once we're done with the ``view.pt`` template, it will look a lot like +the below: + +.. literalinclude:: src/views/tutorial/templates/view.pt + :linenos: + :language: xml + +.. note:: The names available for our use in a template are always + those that are present in the dictionary returned by the view + callable. But our templates make use of a ``request`` object that + none of our tutorial views return in their dictionary. This value + appears as if "by magic". However, ``request`` is one of several + names that are available "by default" in a template when a template + renderer is used. See :ref:`chameleon_template_renderers` for more + information about other names that are available by default in a + template when a Chameleon template is used as a renderer. + +The ``edit.pt`` Template +------------------------ + +The ``edit.pt`` template is used for adding and editing a wiki page. +It is used by the ``add_page`` and ``edit_page`` view functions. It +should display a page containing a form that POSTs back to the +"save_url" argument supplied by the view. The form should have a +"body" textarea field (the page data), and a submit button that has +the name "form.submitted". The textarea in the form should be filled +with any existing page data when it is rendered. + +Once we're done with the ``edit.pt`` template, it will look a lot like +the below: + +.. literalinclude:: src/views/tutorial/templates/edit.pt + :linenos: + :language: xml + +Static Resources +---------------- + +Our templates name a single static resource named ``style.css``. We +need to create this and place it in a file named ``style.css`` within +our package's ``templates/static`` directory. This file is a little +too long to replicate within the body of this guide, however it is +available `online +`_. + +This CSS file will be accessed via +e.g. ``http://localhost:6543/static/style.css`` by virtue of the +``static`` directive we've defined in the ``configure.zcml`` file. +Any number and type of static resources can be placed in this +directory (or subdirectories) and are just referred to by URL within +templates. + +Testing the Views +================= + +We'll modify our ``tests.py`` file, adding tests for each view +function we added above. As a result, we'll *delete* the +``ViewTests`` test in the file, and add four other test classes: +``ViewWikiTests``, ``ViewPageTests``, ``AddPageTests``, and +``EditPageTests``. These test the ``view_wiki``, ``view_page``, +``add_page``, and ``edit_page`` views respectively. + +Once we're done with the ``tests.py`` module, it will look a lot like +the below: + +.. literalinclude:: src/views/tutorial/tests.py + :linenos: + :language: python + +Running the Tests +================= + +We can run these tests by using ``setup.py test`` in the same way we +did in :ref:`running_tests`. Assuming our shell's current working +directory is the "tutorial" distribution directory: + +On UNIX: + +.. code-block:: text + + $ ../bin/python setup.py test -q + +On Windows: + +.. code-block:: text + + c:\bigfntut\tutorial> ..\Scripts\python setup.py test -q + +The expected result looks something like: + +.. code-block:: text + + ......... + ---------------------------------------------------------------------- + Ran 9 tests in 0.203s + + OK + +Mapping Views to URLs in ``configure.zcml`` +=========================================== + +The ``configure.zcml`` file contains ``view`` declarations which serve +to map URLs (via :term:`traversal`) to view functions. This is also +known as :term:`view configuration`. You'll need to add four ``view`` +declarations to ``configure.zcml``. + +#. Add a declaration which maps the "Wiki" class in our ``models.py`` + file to the view named ``view_wiki`` in our ``views.py`` file with + no view name. This is the default view for a Wiki. It does not + use a ``renderer`` because the ``view_wiki`` view callable always + returns a *response* object rather than a dictionary. + +#. Add a declaration which maps the "Wiki" class in our ``models.py`` + file to the view named ``add_page`` in our ``views.py`` file with + the view name ``add_page``. Associate this view with the + ``templates/edit.pt`` template file via the ``renderer`` attribute. + This view will use the :term:`Chameleon` ZPT renderer configured + with the ``templates/edit.pt`` template to render non-*response* + return values from the ``add_page`` view. This is the add view for + a new Page. + +#. Add a declaration which maps the "Page" class in our ``models.py`` + file to the view named ``view_page`` in our ``views.py`` file with + no view name. Associate this view with the ``templates/view.pt`` + template file via the ``renderer`` attribute. This view will use + the :term:`Chameleon` ZPT renderer configured with the + ``templates/view.pt`` template to render non-*response* return + values from the ``view_page`` view. This is the default view for a + Page. + +#. Add a declaration which maps the "Page" class in our ``models.py`` + file to the view named ``edit_page`` in our ``views.py`` file with + the view name ``edit_page``. Associate this view with the + ``templates/edit.pt`` template file via the ``renderer`` attribute. + This view will use the :term:`Chameleon` ZPT renderer configured + with the ``templates/edit.pt`` template to render non-*response* + return values from the ``edit_page`` view. This is the edit view + for a page. + +As a result of our edits, the ``configure.zcml`` file should look +something like so: + +.. literalinclude:: src/views/tutorial/configure.zcml + :linenos: + :language: xml + +Examining ``tutorial.ini`` +========================== + +Let's take a look at our ``tutorial.ini`` file. The contents of the +file are as follows: + +.. literalinclude:: src/models/tutorial.ini + :linenos: + :language: ini + +The WSGI Pipeline +----------------- + +Within ``tutorial.ini``, note the existence of a ``[pipeline:main]`` +section which specifies our WSGI pipeline. This "pipeline" will be +served up as our WSGI application. As far as the WSGI server is +concerned the pipeline *is* our application. Simpler configurations +don't use a pipeline: instead they expose a single WSGI application as +"main". Our setup is more complicated, so we use a pipeline. + +``egg:repoze.zodbconn#closer`` is at the "top" of the pipeline. This +is a piece of middleware which closes the ZODB connection opened by +the PersistentApplicationFinder at the end of the request. + +``egg:repoze.tm#tm`` is the second piece of middleware in the +pipeline. This commits a transaction near the end of the request +unless there's an exception raised. + +Adding an Element to the Pipeline +--------------------------------- + +Let's add a piece of middleware to the WSGI pipeline: +``egg:Paste#evalerror`` middleware which displays debuggable errors in +the browser while you're developing (not recommended for deployment). +Let's insert evalerror into the pipeline right below +"egg:repoze.zodbconn#closer", making our resulting ``tutorial.ini`` +file look like so: + +.. literalinclude:: src/views/tutorial.ini + :linenos: + :language: ini + +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: + +- Visiting ``http://localhost:6543/`` in a browser invokes the + ``view_wiki`` view. This always redirects to the ``view_page`` view + of the FrontPage page object. + +- Visiting ``http://localhost:6543/FrontPage/`` in a browser invokes + the ``view_page`` view of the front page page object. This is + because it's the *default view* (a view without a ``name``) for Page + objects. + +- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser + invokes the edit view for the front page object. + +- Visiting ``http://localhost:6543/add_page/SomePageName`` in a + browser invokes the add view for a page. + +- To generate an error, visit ``http://localhost:6543/add_page`` which + will generate an ``IndexError`` for the expression + ``request.subpath[0]``. You'll see an interactive traceback + facility provided by evalerror. + + + + + diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst new file mode 100644 index 000000000..81ec61a63 --- /dev/null +++ b/docs/tutorials/wiki/distributing.rst @@ -0,0 +1,49 @@ +============================= +Distributing Your Application +============================= + +Once your application works properly, you can create a "tarball" from +it by using the ``setup.py sdist`` command. The following commands +assume your current working directory is the ``tutorial`` package +we've created and that the parent directory of the ``tutorial`` +package is a virtualenv representing a :mod:`pyramid` environment. + +On UNIX: + +.. code-block:: text + + $ ../bin/python setup.py sdist + +On Windows: + +.. code-block:: text + + c:\bigfntut> ..\Scripts\python setup.py sdist + +.. warning:: If your project files are not checked in to a version + control repository (such as Subversion), the dist tarball will + *not* contain all the files it needs to. In particular, it will + not contain non-Python-source files (such as templates and static + files). To ensure that these are included, check your files into a + version control repository before running ``setup.py sdist``. + +The output of such a command will be something like: + +.. code-block:: text + + running sdist + # .. more output .. + creating dist + tar -cf dist/tutorial-0.1.tar tutorial-0.1 + gzip -f9 dist/tutorial-0.1.tar + removing 'tutorial-0.1' (and everything under it) + +Note that this command creates a tarball in the "dist" subdirectory +named ``tutorial-0.1.tar.gz``. You can send this file to your friends +to show them your cool new application. They should be able to +install it by pointing the ``easy_install`` command directly at it. +Or you can upload it to `PyPI `_ and share it +with the rest of the world, where it can be downloaded via +``easy_install`` remotely like any other package people download from +PyPI. + diff --git a/docs/tutorials/wiki/index.rst b/docs/tutorials/wiki/index.rst new file mode 100644 index 000000000..cb7eedf86 --- /dev/null +++ b/docs/tutorials/wiki/index.rst @@ -0,0 +1,27 @@ +.. _bfg_wiki_tutorial: + +ZODB + Traversal Wiki Tutorial +============================== + +This tutorial introduces a :term:`traversal` -based :mod:`pyramid` +application to a developer familiar with Python. When we're done with +the tutorial, the developer will have created a basic Wiki application +with authentication. + +For cut and paste purposes, the source code for all stages of this +tutorial can be browsed at +`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki +`_. + +.. toctree:: + :maxdepth: 2 + + background + installation + basiclayout + definingmodels + definingviews + viewdecorators + authorization + distributing + diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst new file mode 100644 index 000000000..237abe7c3 --- /dev/null +++ b/docs/tutorials/wiki/installation.rst @@ -0,0 +1,254 @@ +============ +Installation +============ + +For the most part, the installation process for this tutorial +duplicates the steps described in :ref:`installing_chapter` and +:ref:`project_narr`, however it also explains how to install +additional libraries for tutorial purposes. + +Preparation +======================== + +Please take the following steps to prepare for the tutorial. The +steps to prepare for the tutorial are slightly different depending on +whether you're using UNIX or Windows. + +Preparation, UNIX +----------------- + +#. If you don't already have a Python 2.6 interpreter installed on + your system, obtain, install, or find `Python 2.6 + `_ for your system. + +#. Install the latest `setuptools` into the Python you + obtained/installed/found in the step above: download `ez_setup.py + `_ and run it using + the ``python`` interpreter of your Python 2.6 installation: + + .. code-block:: bash + + $ /path/to/my/Python-2.6/bin/python ez_setup.py + +#. Use that Python's `bin/easy_install` to install `virtualenv`: + + .. code-block:: bash + + $ /path/to/my/Python-2.6/bin/easy_install virtualenv + +#. Use that Python's virtualenv to make a workspace: + + .. code-block:: bash + + $ path/to/my/Python-2.6/bin/virtualenv --no-site-packages \ + bigfntut + +#. Switch to the ``bigfntut`` directory: + + .. code-block:: bash + + $ cd bigfntut + +#. (Optional) Consider using ``source bin/activate`` to make your + shell environment wired to use the virtualenv. + +#. Use ``easy_install`` to get :mod:`pyramid` and its direct + dependencies installed: + + .. code-block:: bash + + $ bin/easy_install pyramid + +#. Use ``easy_install`` to install ``docutils``, ``repoze.tm``, + ``repoze.zodbconn``, ``nose`` and ``coverage``: + + .. code-block:: bash + + $ bin/easy_install docutils repoze.tm repoze.zodbconn \ + nose coverage + +Preparation, Windows +-------------------- + +#. Install, or find `Python 2.6 + `_ for your system. + +#. Install the latest `setuptools` into the Python you + obtained/installed/found in the step above: download `ez_setup.py + `_ and run it using + the ``python`` interpreter of your Python 2.6 installation using a + command prompt: + + .. code-block:: bat + + c:\> c:\Python26\python ez_setup.py + +#. Use that Python's `bin/easy_install` to install `virtualenv`: + + .. code-block:: bat + + c:\> c:\Python26\Scripts\easy_install virtualenv + +#. Use that Python's virtualenv to make a workspace: + + .. code-block:: bat + + c:\> c:\Python26\Scripts\virtualenv --no-site-packages bigfntut + +#. Switch to the ``bigfntut`` directory: + + .. code-block:: bat + + c:\> cd bigfntut + +#. (Optional) Consider using ``bin\activate.bat`` to make your shell + environment wired to use the virtualenv. + +#. Use ``easy_install`` to get :mod:`pyramid` and its direct + dependencies installed: + + .. code-block:: bat + + c:\bigfntut> Scripts\easy_install pyramid + +#. Use ``easy_install`` to install ``docutils``, ``repoze.tm``, + ``repoze.zodbconn``, ``nose`` and ``coverage``: + + .. code-block:: bat + + c:\bigfntut> Scripts\easy_install docutils repoze.tm \ + repoze.zodbconn nose coverage + +.. _making_a_project: + +Making a Project +================ + +Your next step is to create a project. :mod:`pyramid` supplies a +variety of templates to generate sample projects. For this tutorial, +we will use the :term:`ZODB` -oriented template named ``pyramid_zodb``. + +The below instructions assume your current working directory is the +"virtualenv" named "bigfntut". + +On UNIX: + +.. code-block:: bash + + $ bin/paster create -t pyramid_zodb tutorial + +On Windows: + +.. code-block:: bat + + c:\bigfntut> Scripts\paster create -t pyramid_zodb tutorial + +.. note:: If you are using Windows, the ``pyramid_zodb`` Paster template + doesn't currently deal gracefully with installation into a location + that contains spaces in the path. If you experience startup + problems, try putting both the virtualenv and the project into + directories that do not contain spaces in their paths. + +Installing the Project in "Development Mode" +============================================ + +In order to do development on the project easily, you must "register" +the project as a development egg in your workspace using the +``setup.py develop`` command. In order to do so, cd to the "tutorial" +directory you created in :ref:`making_a_project`, and run the +"setup.py develop" command using virtualenv Python interpreter. + +On UNIX: + +.. code-block:: bash + + $ cd tutorial + $ ../bin/python setup.py develop + +On Windows: + +.. code-block:: bat + + C:\bigfntut> cd tutorial + C:\bigfntut\tutorial> ..\Scripts\python setup.py develop + +.. _running_tests: + +Running the Tests +================= + +After you've installed the project in development mode, you may run +the tests for the project. + +On UNIX: + +.. code-block:: bash + + $ ../bin/python setup.py test -q + +On Windows: + +.. code-block:: bat + + c:\bigfntut\tutorial> ..\Scripts\python setup.py test -q + +Starting the Application +======================== + +Start the application. + +On UNIX: + +.. code-block:: bash + + $ ../bin/paster serve tutorial.ini --reload + +On Windows: + +.. code-block:: bat + + c:\bifgfntut\tutorial> ..\Scripts\paster serve tutorial.ini --reload + +Exposing Test Coverage Information +================================== + +You can run the ``nosetests`` command to see test coverage +information. This runs the tests in the same way that ``setup.py +test`` does but provides additional "coverage" information, exposing +which lines of your project are "covered" (or not covered) by the +tests. + +On UNIX: + +.. code-block:: bash + + $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage + +On Windows: + +.. code-block:: bat + + c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \ + --cover-erase --with-coverage + +Looks like the code in the ``pyramid_zodb`` template for ZODB projects is +missing some test coverage, particularly in the file named +``models.py``. + +Visit the Application in a Browser +================================== + +In a browser, visit `http://localhost:6543/ `_. +You will see the generated application's default page. + +Decisions the ``pyramid_zodb`` Template Has Made For You +======================================================== + +Creating a project using the ``pyramid_zodb`` template makes the +assumption that you are willing to use :term:`ZODB` as persistent +storage and :term:`traversal` to map URLs to code. :mod:`pyramid` +supports any persistent storage mechanism (e.g. a SQL database or +filesystem files, etc). It also supports an additional mechanism to +map URLs to code (:term:`URL dispatch`). However, for the purposes of +this tutorial, we'll only be using traversal and ZODB. + diff --git a/docs/tutorials/wiki/src/authorization/CHANGES.txt b/docs/tutorials/wiki/src/authorization/CHANGES.txt new file mode 100644 index 000000000..e14f633ab --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/CHANGES.txt @@ -0,0 +1,5 @@ +0.0 +--- + +- Initial version + diff --git a/docs/tutorials/wiki/src/authorization/README.txt b/docs/tutorials/wiki/src/authorization/README.txt new file mode 100644 index 000000000..d41f7f90f --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/README.txt @@ -0,0 +1,4 @@ +tutorial README + + + diff --git a/docs/tutorials/wiki/src/authorization/setup.cfg b/docs/tutorials/wiki/src/authorization/setup.cfg new file mode 100644 index 000000000..3d7ea6e23 --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/setup.cfg @@ -0,0 +1,28 @@ +[nosetests] +match=^test +nocapture=1 +cover-package=tutorial +with-coverage=1 +cover-erase=1 + +[compile_catalog] +directory = tutorial/locale +domain = tutorial +statistics = true + +[extract_messages] +add_comments = TRANSLATORS: +output_file = tutorial/locale/tutorial.pot +width = 80 + +[init_catalog] +domain = tutorial +input_file = tutorial/locale/tutorial.pot +output_dir = tutorial/locale + +[update_catalog] +domain = tutorial +input_file = tutorial/locale/tutorial.pot +output_dir = tutorial/locale +previous = true + diff --git a/docs/tutorials/wiki/src/authorization/setup.py b/docs/tutorials/wiki/src/authorization/setup.py new file mode 100644 index 000000000..bb2482cce --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/setup.py @@ -0,0 +1,43 @@ +import os + +from setuptools import setup, find_packages + +here = os.path.abspath(os.path.dirname(__file__)) +README = open(os.path.join(here, 'README.txt')).read() +CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() + +requires = [ + 'pyramid', + 'docutils', + 'ZODB3', + 'repoze.zodbconn', + 'repoze.tm', + ] + +setup(name='tutorial', + version='0.0', + description='tutorial', + long_description=README + '\n\n' + CHANGES, + classifiers=[ + "Intended Audience :: Developers", + "Framework :: Pylons", + "Programming Language :: Python", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], + author='', + author_email='', + url='', + keywords='web wsgi pylons pyramid bfg', + packages=find_packages(), + include_package_data=True, + zip_safe=False, + install_requires=requires, + tests_require=requires, + test_suite="tutorial", + entry_points = """\ + [paste.app_factory] + app = tutorial.run:app + """ + ) + diff --git a/docs/tutorials/wiki/src/authorization/tutorial.ini b/docs/tutorials/wiki/src/authorization/tutorial.ini new file mode 100644 index 000000000..181682585 --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/tutorial.ini @@ -0,0 +1,21 @@ +[DEFAULT] +debug = true + +[app:zodb] +use = egg:tutorial#app +reload_templates = true +debug_authorization = false +debug_notfound = false +zodb_uri = file://%(here)s/Data.fs?connection_cache_size=20000 + +[pipeline:main] +pipeline = + egg:repoze.zodbconn#closer + egg:Paste#evalerror + egg:repoze.tm#tm + zodb + +[server:main] +use = egg:Paste#http +host = 0.0.0.0 +port = 6543 diff --git a/docs/tutorials/wiki/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py new file mode 100644 index 000000000..cbdfd3ac6 --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py @@ -0,0 +1,2 @@ +# A package + diff --git a/docs/tutorials/wiki/src/authorization/tutorial/configure.zcml b/docs/tutorials/wiki/src/authorization/tutorial/configure.zcml new file mode 100644 index 000000000..e8603d7c4 --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/tutorial/configure.zcml @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + diff --git a/docs/tutorials/wiki/src/authorization/tutorial/login.py b/docs/tutorials/wiki/src/authorization/tutorial/login.py new file mode 100644 index 000000000..c029f25ce --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/tutorial/login.py @@ -0,0 +1,44 @@ +from webob.exc import HTTPFound + +from pyramid.view import bfg_view +from pyramid.url import model_url + +from pyramid.security import remember +from pyramid.security import forget + +from tutorial.models import Wiki +from tutorial.security import USERS + +@bfg_view(context=Wiki, name='login', renderer='templates/login.pt') +def login(request): + login_url = model_url(request.context, request, 'login') + referrer = request.url + if referrer == login_url: + referrer = '/' # never use the login form itself as came_from + came_from = request.params.get('came_from', referrer) + message = '' + login = '' + password = '' + if 'form.submitted' in request.params: + login = request.params['login'] + password = request.params['password'] + if USERS.get(login) == password: + headers = remember(request, login) + return HTTPFound(location = came_from, + headers = headers) + message = 'Failed login' + + return dict( + message = message, + url = request.application_url + '/login', + came_from = came_from, + login = login, + password = password, + ) + +@bfg_view(context=Wiki, name='logout') +def logout(request): + headers = forget(request) + return HTTPFound(location = model_url(request.context, request), + headers = headers) + diff --git a/docs/tutorials/wiki/src/authorization/tutorial/models.py b/docs/tutorials/wiki/src/authorization/tutorial/models.py new file mode 100644 index 000000000..0a31c38be --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/tutorial/models.py @@ -0,0 +1,27 @@ +from persistent import Persistent +from persistent.mapping import PersistentMapping + +from pyramid.security import Allow +from pyramid.security import Everyone + +class Wiki(PersistentMapping): + __name__ = None + __parent__ = None + __acl__ = [ (Allow, Everyone, 'view'), + (Allow, 'group:editors', 'edit') ] + +class Page(Persistent): + def __init__(self, data): + self.data = data + +def appmaker(zodb_root): + if not 'app_root' in zodb_root: + app_root = Wiki() + frontpage = Page('This is the front page') + app_root['FrontPage'] = frontpage + frontpage.__name__ = 'FrontPage' + frontpage.__parent__ = app_root + zodb_root['app_root'] = app_root + import transaction + transaction.commit() + return zodb_root['app_root'] diff --git a/docs/tutorials/wiki/src/authorization/tutorial/run.py b/docs/tutorials/wiki/src/authorization/tutorial/run.py new file mode 100644 index 000000000..875e77590 --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/tutorial/run.py @@ -0,0 +1,23 @@ +from pyramid.configuration import Configurator +from repoze.zodbconn.finder import PersistentApplicationFinder + +from tutorial.models import appmaker + +def app(global_config, **settings): + """ This function returns a WSGI application. + + It is usually called by the PasteDeploy framework during + ``paster serve``. + """ + zodb_uri = settings.get('zodb_uri') + if zodb_uri is None: + raise ValueError("No 'zodb_uri' in application configuration.") + finder = PersistentApplicationFinder(zodb_uri, appmaker) + def get_root(request): + return finder(request.environ) + config = Configurator(root_factory=get_root, settings=settings) + config.begin() + config.load_zcml('configure.zcml') + config.end() + return config.make_wsgi_app() + diff --git a/docs/tutorials/wiki/src/authorization/tutorial/security.py b/docs/tutorials/wiki/src/authorization/tutorial/security.py new file mode 100644 index 000000000..cfd13071e --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/tutorial/security.py @@ -0,0 +1,8 @@ +USERS = {'editor':'editor', + 'viewer':'viewer'} +GROUPS = {'editor':['group:editors']} + +def groupfinder(userid, request): + if userid in USERS: + return GROUPS.get(userid, []) + diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt new file mode 100644 index 000000000..5f8b22207 --- /dev/null +++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt @@ -0,0 +1,34 @@ + + + + + + Pyramid tutorial wiki (based on TurboGears 20-Minute Wiki) + Editing: ${page.__name__} + + + + + +
+
Viewing + Page Name Goes Here
+ You can return to the FrontPage. + Logout +
+ +
+
+