summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--docs/api/paster.rst9
-rw-r--r--docs/api/template.rst3
-rw-r--r--docs/glossary.rst29
-rw-r--r--docs/narr/views.rst2
-rw-r--r--docs/tutorials/bfgwiki2/authorization.rst86
-rw-r--r--docs/tutorials/bfgwiki2/background.rst2
-rw-r--r--docs/tutorials/bfgwiki2/definingmodels.rst2
-rw-r--r--docs/tutorials/bfgwiki2/definingviews.rst48
8 files changed, 104 insertions, 77 deletions
diff --git a/docs/api/paster.rst b/docs/api/paster.rst
index 52b3048c1..66049ac64 100644
--- a/docs/api/paster.rst
+++ b/docs/api/paster.rst
@@ -3,6 +3,11 @@
:mod:`repoze.bfg.paster`
---------------------------
-.. automodule:: repoze.bfg.paster
+.. module:: repoze.bfg.paster
- .. autofunction:: get_app(config_file, name)
+.. function:: get_app(config_file, name)
+
+ Return the WSGI application named ``name`` in the PasteDeploy
+ config file ``config_file``.
+
+
diff --git a/docs/api/template.rst b/docs/api/template.rst
index 026f1673a..763dc9dfe 100644
--- a/docs/api/template.rst
+++ b/docs/api/template.rst
@@ -55,6 +55,3 @@ statement, e.g.:
.. autofunction:: render_template_to_response
-.. note:: For backwards compatibility purposes, these functions may
- also be imported from ``repoze.bfg.template``.
-
diff --git a/docs/glossary.rst b/docs/glossary.rst
index c8e978bd8..08844c953 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -45,10 +45,12 @@ Glossary
used; in its place is a dot.
View
A "view" is a callable which returns a response object. It should
- accept two values: :term:`context` and :term:`request`. A view is
- the primary mechanism by which a developer writes user interface
- code within :mod:`repoze.bfg`. See :ref:`views_chapter` for more
- information about :mod:`repoze.bfg` views.
+ accept two values: :term:`context` and :term:`request`. An
+ alternate calling convention allows a view to be defined as a a
+ callable which only accepts a single ``request`` argument. A view
+ is the primary mechanism by which a developer writes user
+ interface code within :mod:`repoze.bfg`. See :ref:`views_chapter`
+ for more information about :mod:`repoze.bfg` views.
View name
The "URL name" of a view, e.g ``index.html``. If a view is
configured without a name, its name is considered to be the empty
@@ -61,9 +63,11 @@ Glossary
Model
An object representing data in the system. If :mod:`traversal` is
used, a model is a node in the object graph traversed by the
- system. If :mod:`url dispatch` is used, a model is generated for
- each request. A model instance becomes the :term:`context` of a
- :term:`view`.
+ system. When traversal is used, a model instance becomes the
+ :term:`context` of a :term:`view`. If :mod:`url dispatch` is
+ used, a single :term:`context` (which isn't really a model,
+ because it contains no data except security elements) is generated
+ for each request and is used as the context of a view.
Traversal
The act of descending "down" a graph of model objects from a root
model in order to find a :term:`context`. The :mod:`repoze.bfg`
@@ -87,7 +91,7 @@ Glossary
:term:`URL dispatch` based on URL data; if it's found via
traversal, it's usually a :term:`model` object that is part of an
object graph; if it's found via :term:`URL dispatch`, it's a
- manufactured context object that contains routing information. A
+ manufactured context object that contains security information. A
context becomes the subject of a :term:`view`, and typically has
security information attached to it. See the
:ref:`traversal_chapter` chapter and the
@@ -248,6 +252,10 @@ Glossary
graph traversal when deciding which *view* should be called. See
:ref:`urldispatch_chapter` for more information about Routes integration
in bfg.
+ Route
+ A single pattern matched by the :term:`Routes` subsystem, which
+ generally resolves to a :term:`root factory` (and then ultimately
+ a :term:`view`). See also :term:`url dispatch`.
ZCML
`Zope Configuration Markup Language
<http://www.muthukadan.net/docs/zca.html#zcml>`_, the XML dialect
@@ -362,8 +370,9 @@ Glossary
root factory to :mod:`repoze.bfg` within a call to
``repoze.bfg.router.make_app``; however, an application's root
factory may be passed to ``make_app`` as ``None``, in which case
- the application performs no graph traversal and uses :term:`URL
- dispatch` for all URL-to-view code mappings.
+ the application uses a default root object (this pattern is often
+ used in application which use :term:`URL dispatch` for all
+ URL-to-view code mappings).
SQLAlchemy
`SQLAlchemy' <http://www.sqlalchemy.org/>`_ is an object
relational mapper used in tutorials within this documentation.
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 296ed674f..2b465b1d1 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -103,7 +103,7 @@ following types work as views in this style:
return Response('OK')
#. Arbitrary callables that have a ``__call__`` method that accepts
- ``self, request``, e.g.::
+ ``self, request``, e.g.::
from webob import Response
diff --git a/docs/tutorials/bfgwiki2/authorization.rst b/docs/tutorials/bfgwiki2/authorization.rst
index 9988602d5..4ee4e6ac4 100644
--- a/docs/tutorials/bfgwiki2/authorization.rst
+++ b/docs/tutorials/bfgwiki2/authorization.rst
@@ -16,10 +16,14 @@ to our application.
Adding A Root Factory
---------------------
-We're going to start to use a custom *root factory* within our
-``run.py`` file in order to be able to attach security declarations to
-a :term:`context` object. When we do this, we can begin to make use
-of the declarative security features of :mod:`repoze.bfg`.
+We're going to start to use a custom :term:`root factory` within our
+``run.py`` file. The objects generated by the root factory will be
+used as the :term:`context` of each of request to our application. In
+order for BFG declarative security to work properly, the context
+object generated during a request must be decorated with security
+declarations; when we begin to use a custom root factory to generate
+our contexts, we can begin to make use of the declarative security
+features of :mod:`repoze.bfg`.
Let's modify our ``run.py``, passing in a :term:`root factory` as the
first argument to ``repoze.bfg.router.make_app``. We'll point it at a
@@ -32,25 +36,25 @@ statements to your ``models.py`` file:
from repoze.bfg.security import Everyone
class RootFactory(object):
- __acl__ = [ (Allow, Everyone, 'view'), (Allow, 'editor', 'edit') ]
- def __init__(self, environ):
- self.__dict__.update(environ['bfg.routes.matchdict'])
-
-Defining a root factory allows us to use declarative security features
-of :mod:`repoze.bfg`. The ``RootFactory`` class we added will be used
-to construct each of the ``context`` objects. The context is attached
-to our request as the ``context`` attribute. All of our ``context``
-objects will possess an ``__acl__`` attribute that allows "Everyone"
-(a special principal) to view all pages, while allowing only a user
-named ``editor`` to edit and add pages. The ``__acl__`` attribute
-attached to a context is interpreted specially by :mod:`repoze.bfg` as
-an access control list during view execution. See
-:ref:`assigning_acls` for more information about what an :term:`ACL`
-represents.
+ __acl__ = [ (Allow, Everyone, 'view'), (Allow, 'editor', 'edit') ]
+ def __init__(self, environ):
+ self.__dict__.update(environ['bfg.routes.matchdict'])
+
+The ``RootFactory`` class we've just added will be used by BFG to
+construct a ``context`` object. The context is attached to our
+request as the ``context`` attribute.
+
+All of our context objects will possess an ``__acl__`` attribute that
+allows "Everyone" (a special principal) to view all pages, while
+allowing only a user named ``editor`` to edit and add pages. The
+``__acl__`` attribute attached to a context is interpreted specially
+by :mod:`repoze.bfg` as an access control list during view execution.
+See :ref:`assigning_acls` for more information about what an
+:term:`ACL` represents.
.. note: Although we don't use the functionality here, the ``factory``
- used to create route contexts may differ per-route instead of
- globally via a ZCML directive. See the ``factory`` attribute in
+ used to create route contexts may differ per-route as opposed to
+ globally. See the ``factory`` attribute in
:ref:`route_zcml_directive` for more info.
Configuring a ``repoze.bfg`` Authentication Policy
@@ -71,22 +75,25 @@ the policy, and pass it as the ``authentication_policy`` argument to
the ``make_app`` function. The first positional argument of an
``AuthTktAuthenticationPolicy`` is a secret used to encrypt cookie
data. Its second argument ("callback") should be a callable that
-accepts a userid. If the userid exists in the system, the callback
-should return a sequence of group identifiers (or an empty sequence if
-the user isn't a member of any groups). If the userid *does not*
-exist in the system, the callback should return ``None``. We'll use
-"dummy" data to represent user and groups sources.
-
-We'll also use the opportunity to pass our ``RootFactory`` in as the
-first argument to ``make_app``. When we're done, your application's
-``run.py`` will look like this.
+accepts a userid (usually a string). If the userid exists in the
+system, the callback should return a sequence of group identifiers (or
+an empty sequence if the user isn't a member of any groups). If the
+userid *does not* exist in the system, the callback should return
+``None``. We'll use "dummy" data to represent user and groups sources
+within ``run.py``. In a "real" application this information would
+almost certainly come from some database.
+
+We'll also use the opportunity to pass the ``RootFactory`` we created
+in the step above in as the first argument to ``make_app``. When
+we're done, your application's ``run.py`` will look like this.
.. literalinclude:: src/authorization/tutorial/run.py
:linenos:
:language: python
-BFG's ``make_app`` callable also can accept an authorization policy
-parameter. We don't need to specify one, we'll use the default.
+BFG's ``make_app`` callable also can accept an "authorization_policy"
+parameter. We don't need to specify one, because we'll be using the
+default; it is the policy that scans the context for ACLs.
Adding Login and Logout Views
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -160,13 +167,14 @@ Changing ``configure.zcml``
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Change your application's ``configure.zcml`` to add a ``forbidden``
-stanza which points at our login view. This configures our login view
-to show up when BFG detects that a view invocation can not be
-authorized. Also, add ``permission`` attributes with the value
-``edit`` to the ``edit_page`` and ``add_page`` routes. This indicates
-that the views which these routes reference cannot be invoked without
-the authenticated user possessing the ``edit`` permission. When
-you're done, your ``configure.zcml`` will look like so:
+stanza which points at our login view. This configures our newly
+created login view to show up when BFG detects that a view invocation
+can not be authorized. Also, add ``permission`` attributes with the
+value ``edit`` to the ``edit_page`` and ``add_page`` routes. This
+indicates that the views which these routes reference cannot be
+invoked without the authenticated user possessing the ``edit``
+permission with respect to the current context. When you're done,
+your ``configure.zcml`` will look like so:
.. literalinclude:: src/authorization/tutorial/configure.zcml
:linenos:
diff --git a/docs/tutorials/bfgwiki2/background.rst b/docs/tutorials/bfgwiki2/background.rst
index 097298d1b..934fbcd42 100644
--- a/docs/tutorials/bfgwiki2/background.rst
+++ b/docs/tutorials/bfgwiki2/background.rst
@@ -13,6 +13,6 @@ To code along with this tutorial, the developer will need a UNIX
machine with development tools (Mac OS X with XCode, any Linux or BSD
variant, etc) *or* he will need a Windows system of any kind.
-This tutorial is known to work under :mod:`repoze.bfg` version 0.9.
+This tutorial is known to work under :mod:`repoze.bfg` version 1.0.
Have fun!
diff --git a/docs/tutorials/bfgwiki2/definingmodels.rst b/docs/tutorials/bfgwiki2/definingmodels.rst
index 0ba2b6f5d..5e9078ce8 100644
--- a/docs/tutorials/bfgwiki2/definingmodels.rst
+++ b/docs/tutorials/bfgwiki2/definingmodels.rst
@@ -4,7 +4,7 @@ Defining Models
The first change we'll make to our bone-stock paster-generated
application will be to define a :term:`model` constructor representing
-a wiki page. We'll do this inside our ``models.py`` file.
+a wiki page. We'll do this inside our ``models.py`` file.
Making Edits to ``models.py``
-----------------------------
diff --git a/docs/tutorials/bfgwiki2/definingviews.rst b/docs/tutorials/bfgwiki2/definingviews.rst
index df19a21c2..515090e91 100644
--- a/docs/tutorials/bfgwiki2/definingviews.rst
+++ b/docs/tutorials/bfgwiki2/definingviews.rst
@@ -4,9 +4,18 @@ Defining Views
Views in a :term:`url dispatch` -based BFG application are typically
simple Python functions that accept a single parameter:
-::term:`request`. A view is assumed to return a :term:`response`
+:term:`request`. A view is assumed to return a :term:`response`
object.
+.. note:: A BFG view can also be defined as callable which accepts
+ *two* arguments: a :term:`context` and ` :term:`request`. You'll
+ see that two-argument pattern used in other BFG tutorials and
+ applications. Either calling convention will work in any
+ application. In :term:`url dispatch` based applications, however,
+ the context object is rarely used in the view body itself, so
+ within this tutorial we define views as callables that accept only
+ a request to avoid the noise.
+
The request passed to every view that is called as the result of a
route match has an attribute named ``matchdict`` that contains the
elements placed into the URL by the ``path`` of a ``route`` statement.
@@ -19,13 +28,12 @@ request passed to the view would have a ``one`` key withe the value
Declaring Dependencies in Our ``setup.py`` File
===============================================
-Our application will depend 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.
+The view code in our application will depend a package which is not a
+dependency of the original "tutorial" application as it was generated
+by the ``paster create`` command. We need to add a dependency on the
+``docutils`` package to our ``tutorial`` package's ``setup.py`` file
+by assigning this dependency to the ``install_requires`` parameter in
+the ``setup`` function.
Our resulting ``setup.py`` should look like so:
@@ -36,15 +44,16 @@ Our resulting ``setup.py`` should look like so:
Adding View Functions
=====================
-We'll get rid of our ``my_view`` view in our ``views.py`` file. It's
-only an example and isn't relevant to our application.
+We'll get rid of our ``my_view`` view function in our ``views.py``
+file. It's only an example and isn't relevant to our application.
Then 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.
+``edit_page`` will allow a page to be edited. We'll describe each one
+briefly and show the resulting ``views.py`` file afterwards.
.. note::
@@ -67,7 +76,6 @@ API to construct a URL to the ``FrontPage`` page
(e.g. ``http://localhost:6543/FrontPage``), and will use it as the
"location" of the HTTPFound response, forming an HTTP redirect.
-
The ``view_page`` view function
-------------------------------
@@ -236,8 +244,8 @@ Mapping Views to URLs in ``configure.zcml``
===========================================
The ``configure.zcml`` file contains ``route`` declarations (and a
-lone ``view`` declaration) which serve to map URLs (via :term:`url
-dispatch`) to view functions. First, we’ll get rid of the existing
+lone ``view`` declaration) which serve to map URLs via :term:`url
+dispatch` to view functions. First, we’ll get rid of the existing
``route`` created by the template using the name ``home``. It’s only
an example and isn’t relevant to our application. We'll leave the
static ``view`` declaration as it is, since we are going to use it to
@@ -292,12 +300,12 @@ commits and aborts of our database connection in view code.
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 above
-"egg:repoze.tm2#tm", making our resulting ``tutorial.ini`` file look
-like so:
+Let's add a piece of middleware to the WSGI pipeline. We'll add
+``egg:Paste#evalerror`` middleware which displays debuggable errors in
+the browser while you're developing (this is *not* recommeded for
+deployment as it is a security risk). Let's insert evalerror into the
+pipeline right above "egg:repoze.tm2#tm", making our resulting
+``tutorial.ini`` file look like so:
.. literalinclude:: src/views/tutorial.ini
:linenos:
generated by cgit v1.2.3 (git 2.25.1) at 2026-01-11 08:52:21 +0000