From 83dc23642c766caf10fed0c98984e60a6b08fc14 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 27 May 2009 23:01:11 +0000 Subject: Add bfgwiki tutorial. --- docs/tutorials/bfgwiki/authorization.rst | 337 ++++++++++++++++++ docs/tutorials/bfgwiki/background.rst | 16 + docs/tutorials/bfgwiki/basiclayout.rst | 104 ++++++ docs/tutorials/bfgwiki/definingmodels.rst | 147 ++++++++ docs/tutorials/bfgwiki/definingviews.rst | 364 ++++++++++++++++++++ docs/tutorials/bfgwiki/distributing.rst | 96 ++++++ docs/tutorials/bfgwiki/index.rst | 22 ++ docs/tutorials/bfgwiki/installation.rst | 255 ++++++++++++++ .../bfgwiki/src/authorization/CHANGES.txt | 3 + .../tutorials/bfgwiki/src/authorization/README.txt | 4 + .../bfgwiki/src/authorization/ez_setup.py | 276 +++++++++++++++ docs/tutorials/bfgwiki/src/authorization/setup.cfg | 2 + docs/tutorials/bfgwiki/src/authorization/setup.py | 49 +++ .../bfgwiki/src/authorization/tutorial.ini | 26 ++ .../bfgwiki/src/authorization/tutorial/__init__.py | 2 + .../src/authorization/tutorial/configure.zcml | 8 + .../bfgwiki/src/authorization/tutorial/models.py | 26 ++ .../bfgwiki/src/authorization/tutorial/run.py | 22 ++ .../src/authorization/tutorial/templates/edit.pt | 31 ++ .../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 | 27 ++ .../bfgwiki/src/authorization/tutorial/tests.py | 150 ++++++++ .../bfgwiki/src/authorization/tutorial/views.py | 102 ++++++ docs/tutorials/bfgwiki/src/authorization/who.ini | 40 +++ .../bfgwiki/src/authorization/wiki.passwd | 1 + docs/tutorials/bfgwiki/src/basiclayout/CHANGES.txt | 3 + docs/tutorials/bfgwiki/src/basiclayout/README.txt | 4 + docs/tutorials/bfgwiki/src/basiclayout/ez_setup.py | 276 +++++++++++++++ docs/tutorials/bfgwiki/src/basiclayout/setup.cfg | 2 + docs/tutorials/bfgwiki/src/basiclayout/setup.py | 47 +++ .../tutorials/bfgwiki/src/basiclayout/tutorial.ini | 20 ++ .../bfgwiki/src/basiclayout/tutorial/__init__.py | 2 + .../src/basiclayout/tutorial/configure.zcml | 17 + .../bfgwiki/src/basiclayout/tutorial/models.py | 12 + .../bfgwiki/src/basiclayout/tutorial/run.py | 17 + .../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 +++++++++++++ .../bfgwiki/src/basiclayout/tutorial/tests.py | 73 ++++ .../bfgwiki/src/basiclayout/tutorial/views.py | 9 + docs/tutorials/bfgwiki/src/models/CHANGES.txt | 3 + docs/tutorials/bfgwiki/src/models/README.txt | 4 + docs/tutorials/bfgwiki/src/models/ez_setup.py | 276 +++++++++++++++ docs/tutorials/bfgwiki/src/models/setup.cfg | 2 + docs/tutorials/bfgwiki/src/models/setup.py | 48 +++ docs/tutorials/bfgwiki/src/models/tutorial.ini | 20 ++ .../bfgwiki/src/models/tutorial/__init__.py | 2 + .../bfgwiki/src/models/tutorial/configure.zcml | 17 + .../bfgwiki/src/models/tutorial/models.py | 22 ++ docs/tutorials/bfgwiki/src/models/tutorial/run.py | 17 + .../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 +++++++++++++ .../tutorials/bfgwiki/src/models/tutorial/tests.py | 75 ++++ .../tutorials/bfgwiki/src/models/tutorial/views.py | 9 + .../bfgwiki/src/viewdecorators/CHANGES.txt | 3 + .../bfgwiki/src/viewdecorators/README.txt | 4 + .../bfgwiki/src/viewdecorators/ez_setup.py | 276 +++++++++++++++ .../tutorials/bfgwiki/src/viewdecorators/setup.cfg | 2 + docs/tutorials/bfgwiki/src/viewdecorators/setup.py | 48 +++ .../bfgwiki/src/viewdecorators/tutorial.ini | 21 ++ .../src/viewdecorators/tutorial/__init__.py | 2 + .../src/viewdecorators/tutorial/configure.zcml | 8 + .../bfgwiki/src/viewdecorators/tutorial/models.py | 22 ++ .../bfgwiki/src/viewdecorators/tutorial/run.py | 17 + .../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 ++ .../bfgwiki/src/viewdecorators/tutorial/tests.py | 150 ++++++++ .../bfgwiki/src/viewdecorators/tutorial/views.py | 81 +++++ docs/tutorials/bfgwiki/src/views/CHANGES.txt | 3 + docs/tutorials/bfgwiki/src/views/README.txt | 4 + docs/tutorials/bfgwiki/src/views/ez_setup.py | 276 +++++++++++++++ docs/tutorials/bfgwiki/src/views/setup.cfg | 2 + docs/tutorials/bfgwiki/src/views/setup.py | 48 +++ docs/tutorials/bfgwiki/src/views/tutorial.ini | 21 ++ .../bfgwiki/src/views/tutorial/__init__.py | 2 + .../bfgwiki/src/views/tutorial/configure.zcml | 34 ++ .../tutorials/bfgwiki/src/views/tutorial/models.py | 22 ++ docs/tutorials/bfgwiki/src/views/tutorial/run.py | 17 + .../bfgwiki/src/views/tutorial/templates/edit.pt | 30 ++ .../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 +++++++++++++ .../bfgwiki/src/views/tutorial/templates/view.pt | 26 ++ docs/tutorials/bfgwiki/src/views/tutorial/tests.py | 150 ++++++++ docs/tutorials/bfgwiki/src/views/tutorial/views.py | 71 ++++ docs/tutorials/bfgwiki/viewdecorators.rst | 257 ++++++++++++++ 120 files changed, 8677 insertions(+) create mode 100644 docs/tutorials/bfgwiki/authorization.rst create mode 100644 docs/tutorials/bfgwiki/background.rst create mode 100644 docs/tutorials/bfgwiki/basiclayout.rst create mode 100644 docs/tutorials/bfgwiki/definingmodels.rst create mode 100644 docs/tutorials/bfgwiki/definingviews.rst create mode 100644 docs/tutorials/bfgwiki/distributing.rst create mode 100644 docs/tutorials/bfgwiki/index.rst create mode 100644 docs/tutorials/bfgwiki/installation.rst create mode 100644 docs/tutorials/bfgwiki/src/authorization/CHANGES.txt create mode 100644 docs/tutorials/bfgwiki/src/authorization/README.txt create mode 100644 docs/tutorials/bfgwiki/src/authorization/ez_setup.py create mode 100644 docs/tutorials/bfgwiki/src/authorization/setup.cfg create mode 100644 docs/tutorials/bfgwiki/src/authorization/setup.py create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial.ini create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/__init__.py create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/configure.zcml create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/models.py create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/run.py create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/edit.pt create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/static/default.css create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/static/style.css create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/templates/view.pt create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/tests.py create mode 100644 docs/tutorials/bfgwiki/src/authorization/tutorial/views.py create mode 100644 docs/tutorials/bfgwiki/src/authorization/who.ini create mode 100644 docs/tutorials/bfgwiki/src/authorization/wiki.passwd create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/CHANGES.txt create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/README.txt create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/ez_setup.py create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/setup.cfg create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/setup.py create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial.ini create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/__init__.py create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/configure.zcml create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/models.py create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/run.py create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/templates/static/default.css create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/tests.py create mode 100644 docs/tutorials/bfgwiki/src/basiclayout/tutorial/views.py create mode 100644 docs/tutorials/bfgwiki/src/models/CHANGES.txt create mode 100644 docs/tutorials/bfgwiki/src/models/README.txt create mode 100644 docs/tutorials/bfgwiki/src/models/ez_setup.py create mode 100644 docs/tutorials/bfgwiki/src/models/setup.cfg create mode 100644 docs/tutorials/bfgwiki/src/models/setup.py create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial.ini create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/__init__.py create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/configure.zcml create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/models.py create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/run.py create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/templates/static/default.css create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/tests.py create mode 100644 docs/tutorials/bfgwiki/src/models/tutorial/views.py create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/CHANGES.txt create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/README.txt create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/ez_setup.py create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/setup.cfg create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/setup.py create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial.ini create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/__init__.py create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/configure.zcml create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/models.py create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/run.py create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/edit.pt create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/static/default.css create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/static/style.css create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/templates/view.pt create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/tests.py create mode 100644 docs/tutorials/bfgwiki/src/viewdecorators/tutorial/views.py create mode 100644 docs/tutorials/bfgwiki/src/views/CHANGES.txt create mode 100644 docs/tutorials/bfgwiki/src/views/README.txt create mode 100644 docs/tutorials/bfgwiki/src/views/ez_setup.py create mode 100644 docs/tutorials/bfgwiki/src/views/setup.cfg create mode 100644 docs/tutorials/bfgwiki/src/views/setup.py create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial.ini create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/__init__.py create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/configure.zcml create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/models.py create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/run.py create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/edit.pt create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/mytemplate.pt create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/static/default.css create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/static/images/img01.gif create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/static/images/img02.gif create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/static/images/img03.gif create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/static/images/img04.gif create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/static/images/spacer.gif create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/static/style.css create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/static/templatelicense.txt create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/templates/view.pt create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/tests.py create mode 100644 docs/tutorials/bfgwiki/src/views/tutorial/views.py create mode 100644 docs/tutorials/bfgwiki/viewdecorators.rst (limited to 'docs') diff --git a/docs/tutorials/bfgwiki/authorization.rst b/docs/tutorials/bfgwiki/authorization.rst new file mode 100644 index 000000000..3b5c2e3de --- /dev/null +++ b/docs/tutorials/bfgwiki/authorization.rst @@ -0,0 +1,337 @@ +==================== +Adding Authorization +==================== + +Our application currently allows anyone with access to the server to +view, edit, and add pages to our wiki. For purposes of demonstration +we'll change our application to allow people whom possess a specific +username (`editor`) to add and edit wiki pages but we'll continue +allowing anyone with access to the server to view pages. + +:mod:`repoze.bfg` provides a facility for *authorization*, but it +relies on "upstream" software to provide *authentication* information. +We're going to use a package named ``repoze.who`` to our setup, and +we'll rely on it to give us authentication information. + +Adding a Dependency on ``repoze.who`` to Our ``setup.py`` File +-------------------------------------------------------------- + +We need to change our ``setup.py`` file, adding a dependency on the +``repoze.who`` package. The ``repoze.who`` package provides a +mechanism for providing *authentication* data via :term:`WSGI` +middleware. We'll add the ``repoze.who`` package to our ``requires`` +list. + +The resulting setup.py file: + +.. literalinclude:: src/authorization/setup.py + :linenos: + :language: python + +Changing our ``tutorial.ini`` file to Include the ``repoze.who`` Middleware +--------------------------------------------------------------------------- + +In order to make use of the ``repoze.who`` middleware which provides +authentication services, we need to wire it into our ``tutorial.ini`` +file. We'll add a ``[filter:who]`` section to our ``tutorial.ini`` +file and wire it into our pipeline. Our resulting ``tutorial.ini`` +file will look like so: + +.. literalinclude:: src/authorization/tutorial.ini + :linenos: + :language: ini + +Note that we added a ``who`` line to our pipeline. This refers to the +``[filter:who]`` section above it. The ``[filter:who]`` section has a +``use`` line that points at an egg entry point for configuring the +repoze.who middleware via a config file. The ``config_file`` line +points at an .ini config file named ``who.ini``. This file is assumed +to live in the same directory as the ``tutorial.ini`` file. We'll +need to create this file in order to get authentication working. + +Adding a ``who.ini`` File +------------------------- + +We'll create a file in our package directory named ``who.ini``. It +will have the following contents. + +.. literalinclude:: src/authorization/who.ini + :linenos: + :language: ini + +The ``[general]``, ``[identifiers]``, ``[authenticators]``, and +``[challengers]`` section of this file are the meat of the +configuration in this file. + +The ``[general]`` Section +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``[general]`` section configures the default "request classifier" +and "challenge decider". For the purposes of this tutorial, it is not +important that you understand these settings. + +The ``[identifiers]`` Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``[identifiers]`` section configures the identifier plugins that +will be used for this application. In our case, our identifiers are +both the ``form`` plugin (configured above the ``[identifiers]`` +section within ``[plugin:form]``) and the ``auth_tkt`` plugin +(configured above the ``[identifiers]`` section within +``[plugin:auth_tkt]``. The ``form`` identifier will only be used when +the request is a "browser request" (for example, it *won't* be used +when the request is an XML-RPC request). + +The ``[authenticators]`` Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``[authenticators]`` section configures the "authenticator" +plugins that will be used in our setup. An authenticator plugin is +one which checks a username and password provided by a user against a +database of valid username/password combinations. We'll use an +htpasswd file as this database. Since the ``htpasswd`` plugin +requires a file, we'll need to add a ``wiki.passwd`` file to our +``tutorial`` package with these contents: + +.. literalinclude:: src/authorization/wiki.passwd + :linenos: + :language: ini + +The ``[challengers]`` Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``[challengers]`` section configures a "challenger" which is a +``repoze.who`` plugin which displays a login form. We'll use the +standard ``repoze.who.plugins.form`` plugin for this, configured +within the ``[plugin:form]`` section of the file. + +The ``[plugin:*]`` Sections +--------------------------- + +The ``[plugin:*]`` sections of the configuration file configure +individual plugins used by the more general configuration sections +(``[identifiers]``, ``[authenticators]``, ``[challengers]``). The +``auth_tkt`` plugin is an identifier plugin which obtains credentials +from a cookie, the ``form`` plugin is an identifier and challenger +plugin which obtains credentials from a form post, the ``htpasswd`` +plugin is an authenticator plugin which checks credentials against +valid usernames and files specified in an htpasswd file. + +Configuring a ``repoze.bfg`` Authentication Policy +-------------------------------------------------- + +For any :mod:`repoze.bfg` application to perform authorization, we +need to change our ``run.py`` module to add an :term:`authentication +policy`. Adding an authentication policy causes the system to use +authorization. + +Change your run.py to import the ``RepozeWho1AuthenticationPolicy`` +from ``repoze.who.authentication``, construct an instance of the +policy, and pass it as the ``authentication_policy`` argument to the +``make_app`` function. When you're done, your application's +``run.py`` will look like this. + +.. literalinclude:: src/authorization/tutorial/run.py + :linenos: + :language: python + +Giving Our Root Model Object an ACL +----------------------------------- + +We need to give our root model object an ACL. This ACL will be +sufficient to provide enough information to the BFG 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 repoze.bfg.security import Allow + from repoze.bfg.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, 'editor', '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:`repoze.bfg` 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 ``bfg_view`` decorators. +To do so, within ``views.py``: + +- We add ``permission='view'`` to the ``bfg_view`` decorator attached + to the ``static_view`` 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 ``Everyone`` the + view permission at the root model via its ACL, so everyone will be + able to invoke the ``static_view`` view. + +- We add ``permission='view'`` to the ``bfg_view`` 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 ``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 ``bfg_view`` 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 ``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 ``bfg_view`` decorator attached + to the ``add_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 ``editor`` the + view permission at the root model via its ACL, so only the user + named ``editor`` will able to invoke the ``add_page`` view. + +- 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 ``view`` permission at the time + of the request may invoke this view. We've granted ``editor`` the + view permission at the root model via its ACL, so only the user + named ``editor`` will able to invoke the ``edit_page`` view. + +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. 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 *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. + +Add A Logout View +------------------- + +We'll 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. The logout view will look someting +like this: + +.. code-block:: python + :linenos: + + @bfg_view(for_=Wiki, name='logout') + def logout(context, request): + identity = request.environ.get('repoze.who.identity') + headers = [] + if identity is not None: + auth_tkt = request.environ['repoze.who.plugins']['auth_tkt'] + headers = auth_tkt.forget(request.environ, identity) + return HTTPFound(location = model_url(context, request), + headers = headers) + + +We'll also change our ``edit.pt`` template 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 + +Then we need to change each opf our ``view_page``, ``edit_page`` and +``add_page`` views to pass a "logged in" parameter into its template. +We'll add something like this to each view body: + +.. code-block:: python + :linenos: + + logged_in = 'repoze.who.identity' in request.environ + +We'll then change the return value of ``render_template_to_response`` +to pass the `resulting `logged_in`` value to the template, e.g.: + +.. code-block:: python + :linenos: + + return render_template_to_response('templates/view.pt', + request = request, + page = context, + content = content, + logged_in = logged_in, + edit_url = edit_url) + +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/bfgwiki/background.rst b/docs/tutorials/bfgwiki/background.rst new file mode 100644 index 000000000..9e458a9a1 --- /dev/null +++ b/docs/tutorials/bfgwiki/background.rst @@ -0,0 +1,16 @@ +========== +Background +========== + +To code along with the BFG wiki 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. + +The tutorial makes mention of a CDROM disk. This is due to the fact +that the tutorial is taught "live" under some circumstances. When it +mentions use of a CD, there are alternate instructions which follow +for people who do not have the CD. + +This tutorial is known to work under :mod:`repoze.bfg` version 0.9a2. + +Have fun! diff --git a/docs/tutorials/bfgwiki/basiclayout.rst b/docs/tutorials/bfgwiki/basiclayout.rst new file mode 100644 index 000000000..1ec10094e --- /dev/null +++ b/docs/tutorials/bfgwiki/basiclayout.rst @@ -0,0 +1,104 @@ +============ +Basic Layout +============ + +The starter files generated by the ``bfg_zodb`` template are basic, +but they provide a good orientation for the high-level patterns common +to most :term:`traversal` -based BFG (and BFG with ZODB) projects. + +``__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`` +-------------------------------------- + +BFG uses a markup language syntactically the same as Zope's +implementation of :term:`ZCML`, but using a different default XML +namespace. Our sample ZCML file looks like the following: + + .. literalinclude:: src/basiclayout/tutorial/configure.zcml + :linenos: + :language: xml + +#. *Line 1*. The root ```` element, in a *BFG* namespace. + +#. *Line 3*. Boilerplate, the comment explains. + +#. *Lines 6-9*. Register a ```` that is bound to a class. + ``.views.my_view`` is a *function* we write (generated by the + ``bfg_zodb`` template) that is given a ``context`` and a + ``request`` and returns a response. + + Since this ```` doesn't have a ``name`` attribute, it is the + "default" view for that class. + +#. *Lines 11-15*. Register a view on the ``MyModels`` class that + answers URL segments of ``static``. This is a view that will serve + up static resources for us, in this case, at + ``http://localhost:6543/static/`` and below. + +Content Models with ``models.py`` +--------------------------------- + +BFG often uses the word *model* when talking about content resources +arranged in a hierarchical *model graph*. The ``models.py`` file is +where the ``bfg_zodb`` Paster template put the classes that implement +our models. + +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 is + implemented here. It is persistent (via PersistentMapping). The + ``__parent__`` and ``__name__`` are important parts of the + 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 BFG + application (it is essentially a :term:`root factory`). 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`` +--------------------------- + +How does a BFG application start up? When you run under ``paster`` +using the ``tutorial.ini`` generated config file, the application area +points at an entry point. Our entry point happens to be in ``run.py`` +and its ``app`` function: + + .. literalinclude:: src/basiclayout/tutorial/run.py + :linenos: + :language: py + +#. *Line 11*. After importing our application, get the ``appmaker`` + function described above. + +#. *Line 12*. Get the ZODB configuration from the ``tutorial.ini`` + file's ``[app:main]`` section. This will be a URI (something like + ``file:///path/to/Data.fs``). + +#. Line *16*. We create a :term:`root factory` using the + ``PersistentApplicationFinder`` helper class, passing it the + ZODB URI and our appmaker. + +#. Line *17*. We use the ``repoze.bfg.router.make_app`` to return a + :term:`WSGI` application. The ``make_app`` function takes the root + factory (``get_root``), the *package* representing our application, + and the keywords parsed by PasteDeploy. + +We'll later change ``run.py`` when we add :term:`authorization` to our +wiki application. diff --git a/docs/tutorials/bfgwiki/definingmodels.rst b/docs/tutorials/bfgwiki/definingmodels.rst new file mode 100644 index 000000000..61eb5f112 --- /dev/null +++ b/docs/tutorials/bfgwiki/definingmodels.rst @@ -0,0 +1,147 @@ +=============== +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. + +Adding Model Classes +-------------------- + +The first 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 +``persistent.mapping.PersistentMapping``. We want it to inherit from +the ``PersistentMapping`` class because our Wiki class will be a +mapping of wiki page names to ``Page`` objects. The +``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:`repoze.bfg` +application, it means that it's the :term:`root` model. The +``__name__`` of the root model is always ``None``. + +Then we'll add a ``Page`` class. This class should inherit from +``persistent.Persistent``. 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 +``repoze.zodbconn.finder.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 ``bfg_zodb`` project generator but we'll disuse the +``ViewIntegrationTests`` class. The ``ViewIntegrationTests`` class is +too "heavy-hammer" for our tastes. 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:: bash + + $ ../bin/python setup.py test -q + +On Windows: + +.. code-block:: bash + + c:\bigfntut\tutorial> ..\Scripts\python setup.py test -q + +The expected output is something like this: + +.. code-block:: bash + + ..... + ---------------------------------------------------------------------- + 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/bfgwiki/definingviews.rst b/docs/tutorials/bfgwiki/definingviews.rst new file mode 100644 index 000000000..bf47c37ad --- /dev/null +++ b/docs/tutorials/bfgwiki/definingviews.rst @@ -0,0 +1,364 @@ +============== +Defining Views +============== + +Views in BFG are typically simple Python functions that accept two +parameters: :term:`context`, and :term:`request`. A view is assumed +to return a :term:`response` object. + +Adding View Functions +===================== + +We're going to add four :term:`view` functions to our ``views.py`` +module. One view (named ``view_wiki``) will display the wiki itself +(it will answer on the root URL), another named ``view_page`` will +display an individual page, another named ``add_page`` will allow a +page to be added, and a final view named ``edit_page`` will allow a +page to be edited. + +.. 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 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 +``webob.exc.HTTPFound`` class (instances of which implement the WebOb +:term:`response` interface), and the ``repoze.bfg.model_url`` API. +``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 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, which 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 subsitution 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 call the +``repoze.bfg.chameleon_zpt.render_template_to_response`` function with +a number of arguments. The first argument is the *relative* path to a +:term:`Chameleon` ZPT template. It is relative to the directory of +the file in which we're creating the ``view_page`` function. The +``render_template_to_response`` function also accepts ``request``, +``page``, ``content``, and ``edit_url`` as keyword arguments. As a +result, the template will be able to use these names to perform +various rendering tasks. + +The result of ``render_template_to_response`` is returned to +:mod:`repoze.bfg`. Unsurprisingly, it is a response object. + +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 BFG is the sequence of names that are +found *after* the view name in the URL segments given to BFG as the +result of a request. If our add view is invoked via, +e.g. ``http://localhost:6543/add_page/SomeName``, the :term:`subpath` +will be ``['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, 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 rendering 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 rendering *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 +================ + +The views we've added all reference a :term:`template`. Each template +is a :term:`Chameleon` template. The default templating system in +:mod:`repoze.bfg` is a variant of :term:`ZPT` provided by Chameleon. +These templates will live in the ``templates`` directory of our +tutorial package. + +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 + + +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: + +.. literalinclude:: src/views/tutorial/templates/static/style.css + :linenos: + :language: css + +This CSS file will be accessed via +e.g. ``http://localhost:6543/static/style.css`` by virtue of the +``static_view`` view we've defined in the ``views.py`` 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:: bash + + $ ../bin/python setup.py test -q + +On Windows: + +.. code-block:: bash + + + c:\bigfntut\tutorial> ..\Scripts\python setup.py test -q + +The expected result looks something like: + +.. code-block:: bash + + ......... + ---------------------------------------------------------------------- + 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. You'll need to +add five ``view`` declarations to ``configure.zcml``. + +#. Add a declaration which maps the "Wiki" class in our ``models.py`` + file to the view named ``static_view`` in our ``views.py`` file with + the view name ``static``. + +#. 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. + +#. 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. This is the default view for a Page. + +#. 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``. 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 ``edit_page`` in our ``views.py`` file with + the view name ``edit_page``. 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 recommeded 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, do `http://localhost:6543/add_page + `_. IndexError for + ``request.subpath[0]``. You'll see an interactive traceback + facility provided by evalerror. + + + + + diff --git a/docs/tutorials/bfgwiki/distributing.rst b/docs/tutorials/bfgwiki/distributing.rst new file mode 100644 index 000000000..2b99c9e3a --- /dev/null +++ b/docs/tutorials/bfgwiki/distributing.rst @@ -0,0 +1,96 @@ +============================= +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 BFG environment. + +On UNIX: + +.. code-block:: bash + + $ ../bin/python setup.py sdist + +On Windows: + +.. code-block:: bash + + 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:: bash + + running sdist + running egg_info + writing requirements to tutorial.egg-info/requires.txt + writing tutorial.egg-info/PKG-INFO + writing top-level names to tutorial.egg-info/top_level.txt + writing dependency_links to tutorial.egg-info/dependency_links.txt + writing entry points to tutorial.egg-info/entry_points.txt + writing manifest file 'tutorial.egg-info/SOURCES.txt' + warning: sdist: missing required meta-data: url + warning: sdist: missing meta-data: either (author and author_email) or (maintainer and maintainer_email) must be supplied + creating tutorial-0.1 + creating tutorial-0.1/tutorial + creating tutorial-0.1/tutorial.egg-info + creating tutorial-0.1/tutorial/templates + creating tutorial-0.1/tutorial/templates/static + creating tutorial-0.1/tutorial/templates/static/images + making hard links in tutorial-0.1... + hard linking CHANGES.txt -> tutorial-0.1 + hard linking README.txt -> tutorial-0.1 + hard linking ez_setup.py -> tutorial-0.1 + hard linking setup.cfg -> tutorial-0.1 + hard linking setup.py -> tutorial-0.1 + hard linking tutorial.ini -> tutorial-0.1 + hard linking tutorial/__init__.py -> tutorial-0.1/tutorial + hard linking tutorial/configure.zcml -> tutorial-0.1/tutorial + hard linking tutorial/models.py -> tutorial-0.1/tutorial + hard linking tutorial/run.py -> tutorial-0.1/tutorial + hard linking tutorial/tests.py -> tutorial-0.1/tutorial + hard linking tutorial/views.py -> tutorial-0.1/tutorial + hard linking tutorial.egg-info/PKG-INFO -> tutorial-0.1/tutorial.egg-info + hard linking tutorial.egg-info/SOURCES.txt -> tutorial-0.1/tutorial.egg-info + hard linking tutorial.egg-info/dependency_links.txt -> tutorial-0.1/tutorial.egg-info + hard linking tutorial.egg-info/entry_points.txt -> tutorial-0.1/tutorial.egg-info + hard linking tutorial.egg-info/not-zip-safe -> tutorial-0.1/tutorial.egg-info + hard linking tutorial.egg-info/requires.txt -> tutorial-0.1/tutorial.egg-info + hard linking tutorial.egg-info/top_level.txt -> tutorial-0.1/tutorial.egg-info + hard linking tutorial/templates/edit.pt -> tutorial-0.1/tutorial/templates + hard linking tutorial/templates/mytemplate.pt -> tutorial-0.1/tutorial/templates + hard linking tutorial/templates/view.pt -> tutorial-0.1/tutorial/templates + hard linking tutorial/templates/static/default.css -> tutorial-0.1/tutorial/templates/static + hard linking tutorial/templates/static/style.css -> tutorial-0.1/tutorial/templates/static + hard linking tutorial/templates/static/templatelicense.txt -> tutorial-0.1/tutorial/templates/static + hard linking tutorial/templates/static/images/img01.gif -> tutorial-0.1/tutorial/templates/static/images + hard linking tutorial/templates/static/images/img02.gif -> tutorial-0.1/tutorial/templates/static/images + hard linking tutorial/templates/static/images/img03.gif -> tutorial-0.1/tutorial/templates/static/images + hard linking tutorial/templates/static/images/img04.gif -> tutorial-0.1/tutorial/templates/static/images + hard linking tutorial/templates/static/images/spacer.gif -> tutorial-0.1/tutorial/templates/static/images + copying setup.cfg -> tutorial-0.1 + Writing tutorial-0.1/setup.cfg + 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/bfgwiki/index.rst b/docs/tutorials/bfgwiki/index.rst new file mode 100644 index 000000000..cabfa3d22 --- /dev/null +++ b/docs/tutorials/bfgwiki/index.rst @@ -0,0 +1,22 @@ +BFG Tutorial: BFG Wiki +====================== + +This tutorial introduces a :term:`traversal` -based BFG application to +a developer with at least passing familiarity to Python. When we're +done with the tutorial, the developer will have created a basic Wiki +application with authentication. + +Contents: + +.. toctree:: + :maxdepth: 2 + + background + installation + basiclayout + definingmodels + definingviews + viewdecorators + authorization + distributing + diff --git a/docs/tutorials/bfgwiki/installation.rst b/docs/tutorials/bfgwiki/installation.rst new file mode 100644 index 000000000..ceeb83f06 --- /dev/null +++ b/docs/tutorials/bfgwiki/installation.rst @@ -0,0 +1,255 @@ +============ +Installation +============ + +For the most part, the installation process for this tutorial follows +the `Installing repoze.bfg +`_ and `Creating a +repoze.bfg Project `_ +pages. + +Preparation (with CD) +===================== + +Follow the instructions within the ``INSTALL.txt`` file found on the +CD. + +Preparation (without CD) +======================== + +If you don't possess a CDROM with the tutorial files on it, take the +following steps. The steps are slightly different depending on +whether you're using UNIX or Windows. + +Preparation (without CD), UNIX +------------------------------ + +#. Obtain, install, or find `Python 2.5 + `_ for your system. + +#. Install 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.5 installation: + + .. code-block:: bash + + $ /path/to/my/Python-2.5/bin/python ez_setup.py + +#. Use that Python's `bin/easy_install` to install `virtualenv`: + + .. code-block:: bash + + $ /path/to/my/Python-2.5/bin/easy_install virtualenv + +#. Use that Python's virtualenv to make a workspace: + + .. code-block:: bash + + $ path/to/my/Python-25/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`` and point to the BFG "current" index to get + BFG and its direct dependencies installed: + + .. code-block:: bash + + $ bin/easy_install -i http://dist.repoze.org/bfg/current/simple repoze.bfg + +#. Use ``easy_install`` to install ``docutils``, ``repoze.tm``, + ``repoze.zodbconn``, ``repoze.who``, ``nose`` and ``coverage`` from + a *different* index (the "lemonade" index). + + .. code-block:: bash + + $ bin/easy_install -i http://dist.repoze.org/lemonade/dev/simple \ + docutils repoze.tm repoze.zodbconn repoze.who nose coverage + +Preparation (without CD), Windows +--------------------------------- + +#. Install, or find `Python 2.5 + `_ for your system. + +#. Install 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.5 installation using a + command prompt: + + .. code-block:: bash + + c:\> c:\Python25\python ez_setup.py + +#. Use that Python's `bin/easy_install` to install `virtualenv`: + + .. code-block:: bash + + c:\> c:\Python25\Scripts\easy_install virtualenv + +#. Use that Python's virtualenv to make a workspace: + + .. code-block:: bash + + c:\> c:\Python25\Scripts\virtualenv --no-site-packages bigfntut + +#. Switch to the ``bigfntut`` directory: + + .. code-block:: bash + + c:\> cd bigfntut + +#. (Optional) Consider using ``bin\activate.bat`` to make your shell + environment wired to use the virtualenv. + +#. Use ``easy_install`` and point to the BFG "current index to get BFG + and its direct dependencies installed: + + .. code-block:: bash + + c:\bigfntut> Scripts/easy_install -i http://dist.repoze.org/bfg/current/simple repoze.bfg + +#. Use ``easy_install`` to install ``docutils``, ``repoze.tm``, + ``repoze.zodbconn``, ``repoze.who``, ``nose`` and ``coverage`` from + a *different* index (the "lemonade" index). + + .. code-block:: bash + + c:\bigfntut> Scripts\easy_install -i http://dist.repoze.org/lemonade/dev/simple docutils repoze.tm repoze.zodbconn repoze.who nose coverage + +.. _making_a_project: + +Making a Project +================ + +Whether you arrived at this point by installing your own environment +using the steps above, or you used the instructions in the tutorial +disc, your next steps are to create a project. + +BFG supplies a variety of templates to generate sample projects. We +will use the :term:`ZODB` -oriented template. + +The below instructions assume your current working directory is the +"virtualenv" named "bigfntut". + +On UNIX: + +.. code-block:: bash + + $ bin/paster create -t bfg_zodb tutorial + +On Windows: + +.. code-block:: bash + + c:\bigfntut> Scripts\paster create -t bfg_zodb tutorial + +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:: bash + + 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:: bash + + 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:: bash + + 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:: bash + + c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial --cover-erase --with-coverage + +Looks like the BFG 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 ``bfg_zodb`` Template Has Made For You +===================================================== + +Creating a project using the ``bfg_zodb`` template makes the +assumption that you are willing to use :term:`ZODB` as persistent +storage and :term:`traversal` to map URLs to code. BFG supports any +persistent storage mechanism (e.g. a SQL database or filesystem files, +etc), and supports an additional mechanism to map URLs to code +(:term:`URL dispatch`). However, for the purposes of this tutorial, +we'll be using traversal and ZODB. + diff --git a/docs/tutorials/bfgwiki/src/authorization/CHANGES.txt b/docs/tutorials/bfgwiki/src/authorization/CHANGES.txt new file mode 100644 index 000000000..1544cf53b --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/CHANGES.txt @@ -0,0 +1,3 @@ +0.1 + + Initial version diff --git a/docs/tutorials/bfgwiki/src/authorization/README.txt b/docs/tutorials/bfgwiki/src/authorization/README.txt new file mode 100644 index 000000000..d41f7f90f --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/README.txt @@ -0,0 +1,4 @@ +tutorial README + + + diff --git a/docs/tutorials/bfgwiki/src/authorization/ez_setup.py b/docs/tutorials/bfgwiki/src/authorization/ez_setup.py new file mode 100644 index 000000000..d24e845e5 --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/ez_setup.py @@ -0,0 +1,276 @@ +#!python +"""Bootstrap setuptools installation + +If you want to use setuptools in your package's setup.py, just include this +file in the same directory with it, and add this to the top of your setup.py:: + + from ez_setup import use_setuptools + use_setuptools() + +If you want to require a specific version of setuptools, set a download +mirror, or use an alternate download directory, you can do so by supplying +the appropriate options to ``use_setuptools()``. + +This file can also be run as a script to install or upgrade setuptools. +""" +import sys +DEFAULT_VERSION = "0.6c9" +DEFAULT_URL = "http://pypi.python.org/packages/%s/s/setuptools/" % sys.version[:3] + +md5_data = { + 'setuptools-0.6b1-py2.3.egg': '8822caf901250d848b996b7f25c6e6ca', + 'setuptools-0.6b1-py2.4.egg': 'b79a8a403e4502fbb85ee3f1941735cb', + 'setuptools-0.6b2-py2.3.egg': '5657759d8a6d8fc44070a9d07272d99b', + 'setuptools-0.6b2-py2.4.egg': '4996a8d169d2be661fa32a6e52e4f82a', + 'setuptools-0.6b3-py2.3.egg': 'bb31c0fc7399a63579975cad9f5a0618', + 'setuptools-0.6b3-py2.4.egg': '38a8c6b3d6ecd22247f179f7da669fac', + 'setuptools-0.6b4-py2.3.egg': '62045a24ed4e1ebc77fe039aa4e6f7e5', + 'setuptools-0.6b4-py2.4.egg': '4cb2a185d228dacffb2d17f103b3b1c4', + 'setuptools-0.6c1-py2.3.egg': 'b3f2b5539d65cb7f74ad79127f1a908c', + 'setuptools-0.6c1-py2.4.egg': 'b45adeda0667d2d2ffe14009364f2a4b', + 'setuptools-0.6c2-py2.3.egg': 'f0064bf6aa2b7d0f3ba0b43f20817c27', + 'setuptools-0.6c2-py2.4.egg': '616192eec35f47e8ea16cd6a122b7277', + 'setuptools-0.6c3-py2.3.egg': 'f181fa125dfe85a259c9cd6f1d7b78fa', + 'setuptools-0.6c3-py2.4.egg': 'e0ed74682c998bfb73bf803a50e7b71e', + 'setuptools-0.6c3-py2.5.egg': 'abef16fdd61955514841c7c6bd98965e', + 'setuptools-0.6c4-py2.3.egg': 'b0b9131acab32022bfac7f44c5d7971f', + 'setuptools-0.6c4-py2.4.egg': '2a1f9656d4fbf3c97bf946c0a124e6e2', + 'setuptools-0.6c4-py2.5.egg': '8f5a052e32cdb9c72bcf4b5526f28afc', + 'setuptools-0.6c5-py2.3.egg': 'ee9fd80965da04f2f3e6b3576e9d8167', + 'setuptools-0.6c5-py2.4.egg': 'afe2adf1c01701ee841761f5bcd8aa64', + 'setuptools-0.6c5-py2.5.egg': 'a8d3f61494ccaa8714dfed37bccd3d5d', + 'setuptools-0.6c6-py2.3.egg': '35686b78116a668847237b69d549ec20', + 'setuptools-0.6c6-py2.4.egg': '3c56af57be3225019260a644430065ab', + 'setuptools-0.6c6-py2.5.egg': 'b2f8a7520709a5b34f80946de5f02f53', + 'setuptools-0.6c7-py2.3.egg': '209fdf9adc3a615e5115b725658e13e2', + 'setuptools-0.6c7-py2.4.egg': '5a8f954807d46a0fb67cf1f26c55a82e', + 'setuptools-0.6c7-py2.5.egg': '45d2ad28f9750e7434111fde831e8372', + 'setuptools-0.6c8-py2.3.egg': '50759d29b349db8cfd807ba8303f1902', + 'setuptools-0.6c8-py2.4.egg': 'cba38d74f7d483c06e9daa6070cce6de', + 'setuptools-0.6c8-py2.5.egg': '1721747ee329dc150590a58b3e1ac95b', + 'setuptools-0.6c9-py2.3.egg': 'a83c4020414807b496e4cfbe08507c03', + 'setuptools-0.6c9-py2.4.egg': '260a2be2e5388d66bdaee06abec6342a', + 'setuptools-0.6c9-py2.5.egg': 'fe67c3e5a17b12c0e7c541b7ea43a8e6', + 'setuptools-0.6c9-py2.6.egg': 'ca37b1ff16fa2ede6e19383e7b59245a', +} + +import sys, os +try: from hashlib import md5 +except ImportError: from md5 import md5 + +def _validate_md5(egg_name, data): + if egg_name in md5_data: + digest = md5(data).hexdigest() + if digest != md5_data[egg_name]: + print >>sys.stderr, ( + "md5 validation of %s failed! (Possible download problem?)" + % egg_name + ) + sys.exit(2) + return data + +def use_setuptools( + version=DEFAULT_VERSION, download_base=DEFAULT_URL, to_dir=os.curdir, + download_delay=15 +): + """Automatically find/download setuptools and make it available on sys.path + + `version` should be a valid setuptools version number that is available + as an egg for download under the `download_base` URL (which should end with + a '/'). `to_dir` is the directory where setuptools will be downloaded, if + it is not already available. If `download_delay` is specified, it should + be the number of seconds that will be paused before initiating a download, + should one be required. If an older version of setuptools is installed, + this routine will print a message to ``sys.stderr`` and raise SystemExit in + an attempt to abort the calling script. + """ + was_imported = 'pkg_resources' in sys.modules or 'setuptools' in sys.modules + def do_download(): + egg = download_setuptools(version, download_base, to_dir, download_delay) + sys.path.insert(0, egg) + import setuptools; setuptools.bootstrap_install_from = egg + try: + import pkg_resources + except ImportError: + return do_download() + try: + pkg_resources.require("setuptools>="+version); return + except pkg_resources.VersionConflict, e: + if was_imported: + print >>sys.stderr, ( + "The required version of setuptools (>=%s) is not available, and\n" + "can't be installed while this script is running. Please install\n" + " a more recent version first, using 'easy_install -U setuptools'." + "\n\n(Currently using %r)" + ) % (version, e.args[0]) + sys.exit(2) + else: + del pkg_resources, sys.modules['pkg_resources'] # reload ok + return do_download() + except pkg_resources.DistributionNotFound: + return do_download() + +def download_setuptools( + version=DEFAULT_VERSION, download_base=DEFAULT_URL, to_dir=os.curdir, + delay = 15 +): + """Download setuptools from a specified location and return its filename + + `version` should be a valid setuptools version number that is available + as an egg for download under the `download_base` URL (which should end + with a '/'). `to_dir` is the directory where the egg will be downloaded. + `delay` is the number of seconds to pause before an actual download attempt. + """ + import urllib2, shutil + egg_name = "setuptools-%s-py%s.egg" % (version,sys.version[:3]) + url = download_base + egg_name + saveto = os.path.join(to_dir, egg_name) + src = dst = None + if not os.path.exists(saveto): # Avoid repeated downloads + try: + from distutils import log + if delay: + log.warn(""" +--------------------------------------------------------------------------- +This script requires setuptools version %s to run (even to display +help). I will attempt to download it for you (from +%s), but +you may need to enable firewall access for this script first. +I will start the download in %d seconds. + +(Note: if this machine does not have network access, please obtain the file + + %s + +and place it in this directory before rerunning this script.) +---------------------------------------------------------------------------""", + version, download_base, delay, url + ); from time import sleep; sleep(delay) + log.warn("Downloading %s", url) + src = urllib2.urlopen(url) + # Read/write all in one block, so we don't create a corrupt file + # if the download is interrupted. + data = _validate_md5(egg_name, src.read()) + dst = open(saveto,"wb"); dst.write(data) + finally: + if src: src.close() + if dst: dst.close() + return os.path.realpath(saveto) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +def main(argv, version=DEFAULT_VERSION): + """Install or upgrade setuptools and EasyInstall""" + try: + import setuptools + except ImportError: + egg = None + try: + egg = download_setuptools(version, delay=0) + sys.path.insert(0,egg) + from setuptools.command.easy_install import main + return main(list(argv)+[egg]) # we're done here + finally: + if egg and os.path.exists(egg): + os.unlink(egg) + else: + if setuptools.__version__ == '0.0.1': + print >>sys.stderr, ( + "You have an obsolete version of setuptools installed. Please\n" + "remove it from your system entirely before rerunning this script." + ) + sys.exit(2) + + req = "setuptools>="+version + import pkg_resources + try: + pkg_resources.require(req) + except pkg_resources.VersionConflict: + try: + from setuptools.command.easy_install import main + except ImportError: + from easy_install import main + main(list(argv)+[download_setuptools(delay=0)]) + sys.exit(0) # try to force an exit + else: + if argv: + from setuptools.command.easy_install import main + main(argv) + else: + print "Setuptools version",version,"or greater has been installed." + print '(Run "ez_setup.py -U setuptools" to reinstall or upgrade.)' + +def update_md5(filenames): + """Update our built-in md5 registry""" + + import re + + for name in filenames: + base = os.path.basename(name) + f = open(name,'rb') + md5_data[base] = md5(f.read()).hexdigest() + f.close() + + data = [" %r: %r,\n" % it for it in md5_data.items()] + data.sort() + repl = "".join(data) + + import inspect + srcfile = inspect.getsourcefile(sys.modules[__name__]) + f = open(srcfile, 'rb'); src = f.read(); f.close() + + match = re.search("\nmd5_data = {\n([^}]+)}", src) + if not match: + print >>sys.stderr, "Internal error!" + sys.exit(2) + + src = src[:match.start(1)] + repl + src[match.end(1):] + f = open(srcfile,'w') + f.write(src) + f.close() + + +if __name__=='__main__': + if len(sys.argv)>2 and sys.argv[1]=='--md5update': + update_md5(sys.argv[2:]) + else: + main(sys.argv[1:]) + + + + + + diff --git a/docs/tutorials/bfgwiki/src/authorization/setup.cfg b/docs/tutorials/bfgwiki/src/authorization/setup.cfg new file mode 100644 index 000000000..8ce7ae0fb --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/setup.cfg @@ -0,0 +1,2 @@ +[easy_install] +index_url = http://dist.repoze.org/bfg/current/simple diff --git a/docs/tutorials/bfgwiki/src/authorization/setup.py b/docs/tutorials/bfgwiki/src/authorization/setup.py new file mode 100644 index 000000000..6d300b473 --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/setup.py @@ -0,0 +1,49 @@ +import os + +from ez_setup import use_setuptools +use_setuptools() + +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 = [ + 'repoze.bfg', + 'docutils', + 'ZODB3', + 'repoze.zodbconn', + 'repoze.tm', + 'repoze.who', + ] + +setup(name='tutorial', + version='0.1', + description='tutorial', + long_description=README + '\n\n' + CHANGES, + classifiers=[ + "Development Status :: 3 - Alpha", + "Intended Audience :: Developers", + "Programming Language :: Python", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: Dynamic Content", + "Topic :: Internet :: WWW/HTTP :: WSGI", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], + author='', + author_email='', + url='', + keywords='web wsgi bfg zope', + 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/bfgwiki/src/authorization/tutorial.ini b/docs/tutorials/bfgwiki/src/authorization/tutorial.ini new file mode 100644 index 000000000..d30aa2672 --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/tutorial.ini @@ -0,0 +1,26 @@ +[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 + +[filter:who] +use = egg:repoze.who#config +config_file = %(here)s/who.ini + +[pipeline:main] +pipeline = + egg:repoze.zodbconn#closer + egg:Paste#evalerror + egg:repoze.tm#tm + who + zodb + +[server:main] +use = egg:Paste#http +host = 0.0.0.0 +port = 6543 diff --git a/docs/tutorials/bfgwiki/src/authorization/tutorial/__init__.py b/docs/tutorials/bfgwiki/src/authorization/tutorial/__init__.py new file mode 100644 index 000000000..cbdfd3ac6 --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/tutorial/__init__.py @@ -0,0 +1,2 @@ +# A package + diff --git a/docs/tutorials/bfgwiki/src/authorization/tutorial/configure.zcml b/docs/tutorials/bfgwiki/src/authorization/tutorial/configure.zcml new file mode 100644 index 000000000..b1501597d --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/tutorial/configure.zcml @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/docs/tutorials/bfgwiki/src/authorization/tutorial/models.py b/docs/tutorials/bfgwiki/src/authorization/tutorial/models.py new file mode 100644 index 000000000..976f5e3e9 --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/tutorial/models.py @@ -0,0 +1,26 @@ +from persistent import Persistent +from persistent.mapping import PersistentMapping + +from repoze.bfg.security import Allow +from repoze.bfg.security import Everyone + +class Wiki(PersistentMapping): + __name__ = None + __parent__ = None + __acl__ = [ (Allow, Everyone, 'view'), (Allow, 'editor', '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/bfgwiki/src/authorization/tutorial/run.py b/docs/tutorials/bfgwiki/src/authorization/tutorial/run.py new file mode 100644 index 000000000..45920615f --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/tutorial/run.py @@ -0,0 +1,22 @@ +from repoze.bfg.router import make_app +from repoze.bfg.authentication import RepozeWho1AuthenticationPolicy +from repoze.zodbconn.finder import PersistentApplicationFinder + + +def app(global_config, **kw): + """ This function returns a repoze.bfg.router.Router object. + + It is usually called by the PasteDeploy framework during ``paster serve``. + """ + # paster app config callback + import tutorial + from tutorial.models import appmaker + zodb_uri = kw.get('zodb_uri') + if zodb_uri is None: + raise ValueError("No 'zodb_uri' in application configuration.") + + authpolicy = RepozeWho1AuthenticationPolicy() + + get_root = PersistentApplicationFinder(zodb_uri, appmaker) + return make_app(get_root, tutorial, authentication_policy=authpolicy, + options=kw) diff --git a/docs/tutorials/bfgwiki/src/authorization/tutorial/templates/edit.pt b/docs/tutorials/bfgwiki/src/authorization/tutorial/templates/edit.pt new file mode 100644 index 000000000..d6b3ad466 --- /dev/null +++ b/docs/tutorials/bfgwiki/src/authorization/tutorial/templates/edit.pt @@ -0,0 +1,31 @@ + + + + + + bfg tutorial wiki (based on TurboGears 20-Minute Wiki) Editing: ${page.__name__} + + + + + +
+
Viewing + Page Name Goes Here
+ You can return to the FrontPage. + Logout +
+ +
+
+