From 649923746d5a1e8d3d3487640d99903fd0169c08 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 26 Jul 2008 06:21:00 +0000 Subject: Tweaks. --- docs/glossary.rst | 17 +++++++++++++++-- docs/narr/install.rst | 23 +++++++++++------------ docs/narr/models.rst | 35 ++++++++++++++++++++++------------- docs/narr/project.rst | 25 ++++++++++++++++--------- docs/narr/security.rst | 37 ++++++++++++++++++++----------------- docs/narr/templates.rst | 20 +++++++++----------- docs/narr/traversal.rst | 6 ++++-- docs/narr/views.rst | 4 ++-- 8 files changed, 99 insertions(+), 68 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 8251133b3..b42d2cc7e 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -122,5 +122,18 @@ Glossary deployment system developed by Ian Bicking. LXML `lxml `_ is a XML processing library - for Python. - + for Python by Martijn Faassen and others. + z3c.pt + `z3c.pt `_ is an + implementation of the `Zope Page Template + `_ templating language by + Malthe Borch. It has serveral extensions, such as the ability + to use bracketed- ``${name}`` syntax. It is also much faster + than the reference implementation of ZPT. + Routes + A `system by Ben Bangert `_ which + parses URLs and compares them against a number of user defined + mappings. In terms of :mod:`repoze.bfg`, a Route can supplant + graph traversal when deciding which *view* should be called. See + :ref:`urldispatch_module` for more information about (optional) + Routes integration in bfg. diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 69e244515..7a970d437 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -10,23 +10,16 @@ primarily under Python 2.4, so that version is recommended. :mod:`repoze.bfg` does *not* run under any version of Python before 2.4, and does *not* run under Python 3.X. -.. warning:: To succesfully install :mod:`repoze.bfg`, you will need an - environment capable of compiling C code. See the documentation +.. warning:: To succesfully install :mod:`repoze.bfg`, you will need + an environment capable of compiling C code. See the documentation about installing, e.g. ``gcc`` for your system. Additionally, the Python development libraries for your Python version will need to be installed and the ``lixbml2`` and ``libxslt`` development libraries will need to be installed. These requirements are often satisfied by installing the ``python-devel``, ``libxml2-devel`` and - ``libxslt-devel`` packages into your system. - -After you've got the requisite dependencies installed, you may install -:mod:`repoze.bfg` into your Python environment using the following -command:: - - $ easy_install -i http://dist.repoze.org/lemonade/dev/simple repoze.bfg - -You will need :term:`setuptools` installed on within your Python -system in order to run the ``easy_install`` command. + ``libxslt-devel`` packages into your system. You will also need + :term:`setuptools` installed on within your Python system in order + to run the ``easy_install`` command. It is advisable to install :mod:`repoze.bfg` into a :term:`virtualenv` in order to obtain isolation from any "system" packages you've got @@ -34,6 +27,12 @@ installed in your Python version (and likewise, to prevent :mod:`repoze.bfg` from globally installing versions of packages that are not compatible with your system Python). +After you've got the requisite dependencies installed, you may install +:mod:`repoze.bfg` into your Python environment using the following +command:: + + $ easy_install -i http://dist.repoze.org/lemonade/dev/simple repoze.bfg + What Gets Installed ------------------- diff --git a/docs/narr/models.rst b/docs/narr/models.rst index 045bcad52..cff04ea18 100644 --- a/docs/narr/models.rst +++ b/docs/narr/models.rst @@ -25,11 +25,17 @@ An example of a model describing a blog entry:: self.author = author self.created = datetime.datetime.now() -A model consists of basically two things: the object which defines the -model (above as the class ``IBlogEntry``), and an *interface* attached -to the model object. An interface simply tags the model object with a +A model consists of two things: the object which defines the model +(above as the class ``IBlogEntry``), and an *interface* attached to +the model object. An interface simply tags the model object with a "type" that can be referred to within view configuration. A model -object can implement zero or more interfaces. +object can implement zero or more interfaces. The interface must be +an instance of a class that inherits from +``zope.interface.Interface``. + +You specify that a model *implements* an interface by using the +``zope.interface.implements`` function at class scope. The above +``BlogEntry`` model implements the ``IBlogEntry`` interface. Defining a Graph of Model Instances ----------------------------------- @@ -41,12 +47,13 @@ instance nodes in the graph: - Nodes which contain other nodes (aka "container" nodes) must supply a ``__getitem__`` method which is willing to resolve a string or unicode name to a subobject. If a subobject by that name does not - exist in the container, ``__getitem__`` must raise a KeyError. If - a subobject by that name *does* exist, the container should return - the subobject (another model instance). + exist in the container, ``__getitem__`` must raise a ``KeyError``. + If a subobject by that name *does* exist, the container should + return the subobject (another model instance). - Nodes which do not contain other nodes (aka "leaf" nodes) must not - implement ``__getitem__``. + implement a ``__getitem__``, or if they do, their ``__getitem__`` + method must raise a ``KeyError``. Location-Aware Model Instances ------------------------------ @@ -68,8 +75,10 @@ Location-Aware Model Instances LocationProxy which will dynamically assign a ``__name__`` and a ``__parent__`` to it, recursively. - If you choose to make use of the dynamic assignment of ``__parent__`` - and ``__name__``, the root node must have a ``__parent__`` and a - ``__name__`` that are both ``None``, and it must provide the - ``ILocation`` interface. The easiest way to do this is to claim that - the class representing the root node ``implements(ILocation)``. + If you choose to make use of the location-based dynamic assignment of + ``__parent__`` and ``__name__``, the root node must have a + ``__parent__`` and a ``__name__`` that are both ``None``, and it must + provide the ``ILocation`` interface. The easiest way to do this is + to claim that the class representing the root node + ``implements(ILocation)``, as above. + diff --git a/docs/narr/project.rst b/docs/narr/project.rst index b87197b9a..f67e28e1e 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -4,8 +4,8 @@ Starting a :mod:`repoze.bfg` Project ==================================== You can use :mod:`repoze.bfg` 's sample application generator to get -started. This generator leverages Paste templates to allow creation -of a new project by answering a series of questions. +started. This generator uses :term:`Paste` templates to allow +creation of a new project by answering a series of questions. Creating the Project -------------------- @@ -53,9 +53,9 @@ As a result of the above, a project is created in a directory named directory from which a Python setuptools *distribution* can be created. The ``setup.py`` file in that directory can be used to distribute your application, or install your application for -deployment or development. A sample PasteDeploy ``.ini`` file named -``myproject.ini`` will also be created in the project directory. You -can use this to run your application. +deployment or development. A sample ``PasteDeploy`` ``.ini`` file +named ``myproject.ini`` will also be created in the project directory. +You can use this to run your application. The main ``myproject`` contains an additional subdirectory (also named ``myproject``) representing a Python pakckage which holds very simple @@ -237,7 +237,7 @@ like so: #. Lines 1-3 provide the root node and namespaces for the configuration language. ``bfg`` is the namespace for - :mod:`repoze.bfg`-specific configuration directives. + :mod:`repoze.bfg` -specific configuration directives. #. Line 6 initializes :mod:`repoze.bfg`-specific configuration directives by including it as a package. @@ -250,8 +250,8 @@ like so: ~~~~~~~~~~~~ Much of the heavy lifting in a :mod:`repoze.bfg` application comes in -the views. Views are the bridge between the content in the model, and -the HTML given back to the browser. +the form of *views*. A :term:`view` is the bridge between the content +in the model, and the HTML given back to the browser. .. literalinclude:: myproject/myproject/views.py :linenos: @@ -273,7 +273,7 @@ the HTML given back to the browser. This example uses ``render_template_to_response`` which allows the view author to think only in terms of templates. If you want more control over the response, use ``render_template`` and create your - own WebOb Response object to return. + own ``WebOb`` Response object to return. ``models.py`` ~~~~~~~~~~~~~ @@ -331,6 +331,10 @@ The single template in the project looks like so: :linenos: :language: xml +This is a :term:`z3c.pt` template. It displays the current project +name when it is rendered. It is referenced by the ``my_view`` +function in the ``views.py`` module. + ``tests.py`` ~~~~~~~~~~~~ @@ -339,4 +343,7 @@ The ``tests.py`` module includes unit tests for your application. .. literalinclude:: myproject/myproject/tests.py :linenos: +This sample ``tests.py`` file has a single unit test defined within +it. This is the code that is executed when you run ``setup.py test +-q``. You may add more tests here as you build your application. diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 6215bf1bc..7adeda3b9 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -6,11 +6,8 @@ prevents views that are protected by a :term:`permission` from being rendered when the user represented by the request does not have the appropriate level of access in a context. -Jargon ------- - -To learn about the jargon tossed around in this chapter, you may want -to review the :ref:`glossary`. +Security is enabled by adding configuration to your ``configure.zcml`` +which specifies a :term:`security policy`. Enabling a Security Policy -------------------------- @@ -30,18 +27,19 @@ The above insrcutable stanza enables the ``RemoteUserACLSecurityPolicy`` to be in effect for every request to your application. The ``RemoteUserACLSecurityPolicy`` is a policy which compares the ``REMOTE_USER`` variable passed in the reqest's -environment (as the sole *principal*) against any *ACL* found in model -data when attempting to call some *view*. The policy either allows -the view that the permission was declared for to be called, or returns -a ``401 Unathorized`` response code to the upstream WSGI server. +environment (as the sole :term:`principal`) against any *ACL* found in +model data when attempting to call some :term:`view`. The policy +either allows the view that the permission was declared for to be +called, or returns a ``401 Unathorized`` response code to the upstream +WSGI server. Protecting Views with Permissions --------------------------------- You declaratively protected a particular view with a permisson via the ``configure.zcml`` application registry. For example, the following -declaration protects the view named "add_entry.html" when invoked -against an IBlog context with the ``add`` permission:: +declaration protects the view named ``add_entry.html`` when invoked +against an ``IBlog`` context with the ``add`` permission:: `_ templating engine. This -templating engine complies with the `Zope Page Template -`_ template specification. While -``z3c.pt`` doesn't implement the METAL specification (feature or -drawback, depending on your viewpoint), it is significantly -faster. And faster, of course, is the zen of :mod:`repoze.bfg`. +different implementation of the ZPT specification: the :term:`z3c.pt` +templating engine. This templating engine complies with the `Zope Page +Template `_ template +specification. While :term:`z3c.pt` doesn't implement the *METAL* +specification (feature or drawback, depending on your viewpoint), it +is significantly faster. Given a template named ``foo.html`` in a directory in your application named "templates", you can render the template in a view via:: @@ -24,7 +22,7 @@ named "templates", you can render the template in a view via:: from repoze.bfg.template import render_template_to_response return render_template_to_response('templates/foo.html', foo=1, bar=2) -You can also wire up page templates via ZCML: +You associate a view with a URL by adding information to your ZCML. .. sourcecode:: xml @@ -34,7 +32,7 @@ You can also wire up page templates via ZCML: name="contents.html" /> -Both approaches load the template and keep it in memory between +:mod:`repoze.bfg` loads the template and keeps it in memory between requests. This means that modifications to the ZPT require a restart before you can see the changes. diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 1044c25f1..64e92c570 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -22,8 +22,10 @@ items. .. note:: :mod:`repoze.bfg` features graph traversal. However, via the - inclusion of Routes, URL dispatch is also supported for the parts of - your URL space that better fit that model. + inclusion of :term:`Routes`, URL dispatch is also supported for the + parts of your URL space that better fit that model. See the + :ref:`urldispatch_module` for more information about using URL + dispatch. Non-graph traversal based URL dispatch can easily handle URLs such as ``http://example.com/members/Chris``, where it's assumed that each diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 91eaa91ff..a2a0c79ca 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -20,11 +20,11 @@ world view implemented as a function:: View Arguments -------------- -context +:term:`context` An instance of a model found via graph traversal. -request +:term:`request` A WebOb request object representing the current request. -- cgit v1.2.3