Permalink
Browse files

rename bfgwiki to wiki

  • Loading branch information...
1 parent ae8e4ad commit e53e13423685eac190676c4be32716c3a42603e4 @mcdonc mcdonc committed Oct 25, 2010
Showing with 7,287 additions and 0 deletions.
  1. +300 −0 docs/tutorials/wiki/authorization.rst
  2. +18 −0 docs/tutorials/wiki/background.rst
  3. +137 −0 docs/tutorials/wiki/basiclayout.rst
  4. +162 −0 docs/tutorials/wiki/definingmodels.rst
  5. +416 −0 docs/tutorials/wiki/definingviews.rst
  6. +49 −0 docs/tutorials/wiki/distributing.rst
  7. +27 −0 docs/tutorials/wiki/index.rst
  8. +254 −0 docs/tutorials/wiki/installation.rst
  9. +5 −0 docs/tutorials/wiki/src/authorization/CHANGES.txt
  10. +4 −0 docs/tutorials/wiki/src/authorization/README.txt
  11. +28 −0 docs/tutorials/wiki/src/authorization/setup.cfg
  12. +43 −0 docs/tutorials/wiki/src/authorization/setup.py
  13. +21 −0 docs/tutorials/wiki/src/authorization/tutorial.ini
  14. +2 −0 docs/tutorials/wiki/src/authorization/tutorial/__init__.py
  15. +25 −0 docs/tutorials/wiki/src/authorization/tutorial/configure.zcml
  16. +44 −0 docs/tutorials/wiki/src/authorization/tutorial/login.py
  17. +27 −0 docs/tutorials/wiki/src/authorization/tutorial/models.py
  18. +23 −0 docs/tutorials/wiki/src/authorization/tutorial/run.py
  19. +8 −0 docs/tutorials/wiki/src/authorization/tutorial/security.py
  20. +34 −0 docs/tutorials/wiki/src/authorization/tutorial/templates/edit.pt
  21. +32 −0 docs/tutorials/wiki/src/authorization/tutorial/templates/login.pt
  22. +99 −0 docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt
  23. +380 −0 docs/tutorials/wiki/src/authorization/tutorial/templates/static/default.css
  24. BIN docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/img01.gif
  25. BIN docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/img02.gif
  26. BIN docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/img03.gif
  27. BIN docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/img04.gif
  28. BIN docs/tutorials/wiki/src/authorization/tutorial/templates/static/images/spacer.gif
  29. +109 −0 docs/tutorials/wiki/src/authorization/tutorial/templates/static/style.css
  30. +243 −0 docs/tutorials/wiki/src/authorization/tutorial/templates/static/templatelicense.txt
  31. +31 −0 docs/tutorials/wiki/src/authorization/tutorial/templates/view.pt
  32. +123 −0 docs/tutorials/wiki/src/authorization/tutorial/tests.py
  33. +76 −0 docs/tutorials/wiki/src/authorization/tutorial/views.py
  34. +4 −0 docs/tutorials/wiki/src/basiclayout/CHANGES.txt
  35. +4 −0 docs/tutorials/wiki/src/basiclayout/README.txt
  36. +28 −0 docs/tutorials/wiki/src/basiclayout/setup.cfg
  37. +42 −0 docs/tutorials/wiki/src/basiclayout/setup.py
  38. +20 −0 docs/tutorials/wiki/src/basiclayout/tutorial.ini
  39. +2 −0 docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
  40. +17 −0 docs/tutorials/wiki/src/basiclayout/tutorial/configure.zcml
  41. +12 −0 docs/tutorials/wiki/src/basiclayout/tutorial/models.py
  42. +22 −0 docs/tutorials/wiki/src/basiclayout/tutorial/run.py
  43. +99 −0 docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt
  44. +380 −0 docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/default.css
  45. BIN docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/img01.gif
  46. BIN docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/img02.gif
  47. BIN docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/img03.gif
  48. BIN docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/img04.gif
  49. BIN docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/images/spacer.gif
  50. +243 −0 docs/tutorials/wiki/src/basiclayout/tutorial/templates/static/templatelicense.txt
  51. +19 −0 docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
  52. +2 −0 docs/tutorials/wiki/src/basiclayout/tutorial/views.py
  53. +4 −0 docs/tutorials/wiki/src/models/CHANGES.txt
  54. +4 −0 docs/tutorials/wiki/src/models/README.txt
  55. +28 −0 docs/tutorials/wiki/src/models/setup.cfg
  56. +42 −0 docs/tutorials/wiki/src/models/setup.py
  57. +20 −0 docs/tutorials/wiki/src/models/tutorial.ini
  58. +2 −0 docs/tutorials/wiki/src/models/tutorial/__init__.py
  59. +17 −0 docs/tutorials/wiki/src/models/tutorial/configure.zcml
  60. +22 −0 docs/tutorials/wiki/src/models/tutorial/models.py
  61. +22 −0 docs/tutorials/wiki/src/models/tutorial/run.py
  62. +99 −0 docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt
  63. +380 −0 docs/tutorials/wiki/src/models/tutorial/templates/static/default.css
  64. BIN docs/tutorials/wiki/src/models/tutorial/templates/static/images/img01.gif
  65. BIN docs/tutorials/wiki/src/models/tutorial/templates/static/images/img02.gif
  66. BIN docs/tutorials/wiki/src/models/tutorial/templates/static/images/img03.gif
  67. BIN docs/tutorials/wiki/src/models/tutorial/templates/static/images/img04.gif
  68. BIN docs/tutorials/wiki/src/models/tutorial/templates/static/images/spacer.gif
  69. +243 −0 docs/tutorials/wiki/src/models/tutorial/templates/static/templatelicense.txt
  70. +64 −0 docs/tutorials/wiki/src/models/tutorial/tests.py
  71. +2 −0 docs/tutorials/wiki/src/models/tutorial/views.py
  72. +4 −0 docs/tutorials/wiki/src/viewdecorators/CHANGES.txt
  73. +4 −0 docs/tutorials/wiki/src/viewdecorators/README.txt
  74. +28 −0 docs/tutorials/wiki/src/viewdecorators/setup.cfg
  75. +42 −0 docs/tutorials/wiki/src/viewdecorators/setup.py
  76. +21 −0 docs/tutorials/wiki/src/viewdecorators/tutorial.ini
  77. +2 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/__init__.py
  78. +13 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/configure.zcml
  79. +22 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/models.py
  80. +22 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/run.py
  81. +30 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/edit.pt
  82. +99 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/mytemplate.pt
  83. +380 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/default.css
  84. BIN docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/img01.gif
  85. BIN docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/img02.gif
  86. BIN docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/img03.gif
  87. BIN docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/img04.gif
  88. BIN docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/images/spacer.gif
  89. +109 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/style.css
  90. +243 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/static/templatelicense.txt
  91. +26 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/templates/view.pt
  92. +123 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/tests.py
  93. +62 −0 docs/tutorials/wiki/src/viewdecorators/tutorial/views.py
  94. +3 −0 docs/tutorials/wiki/src/views/CHANGES.txt
  95. +4 −0 docs/tutorials/wiki/src/views/README.txt
  96. +28 −0 docs/tutorials/wiki/src/views/setup.cfg
  97. +42 −0 docs/tutorials/wiki/src/views/setup.py
  98. +21 −0 docs/tutorials/wiki/src/views/tutorial.ini
  99. +2 −0 docs/tutorials/wiki/src/views/tutorial/__init__.py
  100. +36 −0 docs/tutorials/wiki/src/views/tutorial/configure.zcml
  101. +22 −0 docs/tutorials/wiki/src/views/tutorial/models.py
  102. +22 −0 docs/tutorials/wiki/src/views/tutorial/run.py
  103. +32 −0 docs/tutorials/wiki/src/views/tutorial/templates/edit.pt
  104. +99 −0 docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt
  105. +380 −0 docs/tutorials/wiki/src/views/tutorial/templates/static/default.css
  106. BIN docs/tutorials/wiki/src/views/tutorial/templates/static/images/img01.gif
  107. BIN docs/tutorials/wiki/src/views/tutorial/templates/static/images/img02.gif
  108. BIN docs/tutorials/wiki/src/views/tutorial/templates/static/images/img03.gif
  109. BIN docs/tutorials/wiki/src/views/tutorial/templates/static/images/img04.gif
  110. BIN docs/tutorials/wiki/src/views/tutorial/templates/static/images/spacer.gif
  111. +109 −0 docs/tutorials/wiki/src/views/tutorial/templates/static/style.css
  112. +243 −0 docs/tutorials/wiki/src/views/tutorial/templates/static/templatelicense.txt
  113. +29 −0 docs/tutorials/wiki/src/views/tutorial/templates/view.pt
  114. +127 −0 docs/tutorials/wiki/src/views/tutorial/tests.py
  115. +56 −0 docs/tutorials/wiki/src/views/tutorial/views.py
  116. +239 −0 docs/tutorials/wiki/viewdecorators.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/
+<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 <http://docs.repoze.org/bfgwiki-1.3/authorization>`_.
+
+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
+class="main_content">`` div:
+
+.. code-block:: xml
+ :linenos:
+
+ <span tal:condition="logged_in">
+ <a href="${request.application_url}/logout">Logout</a>
+ </span>
+
+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.
+
+
+
@@ -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!
Oops, something went wrong. Retry.

0 comments on commit e53e134

Please sign in to comment.