From c44a950c296f3af9018da603a2a1900bbd381af5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 16 Jan 2010 07:55:45 +0000 Subject: Stray text. --- docs/narr/traversal.rst | 100 +++++++++++++++++++++------------------------- docs/narr/urldispatch.rst | 5 +-- docs/narr/urlmapping.rst | 23 +++++------ 3 files changed, 58 insertions(+), 70 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 812861412..08375d599 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -10,7 +10,8 @@ graph*, starting from a :term:`root` object, using a :term:`request` object as a source of path information. In this chapter, we'll provide a high-level overview of traversal, -explain the concept of an *object graph*, +explain the concept of an *object graph*, and show how traversal might +be used within an application. .. index:: pair: traversal; high-level overview @@ -62,28 +63,39 @@ The Object Graph When your application uses :term:`traversal` to resolve URLs to code, your application must supply an *object graph* to :mod:`repoze.bfg`. -Users interact with your :mod:`repoze.bfg` -based application via a -:term:`router`, which is just a fancy :term:`WSGI` application. At -system startup time, the router is configured with a callback known as -a :term:`root factory`, supplied by the application developer. The -root factory is passed a :term:`request` object and it is expected to -return an object which represents the root of the object graph. All -:term:`traversal` will begin at this root object. The root object is -usually a *mapping* object (such as a Python dictionary). - -.. note:: If a :term:`root factory` is passed to the :mod:`repoze.bfg` - :term:`Configurator` constructor as the value ``None``, a *default* - root factory is used. This is most useful when you're using - :term:`URL dispatch` and you don't care very much about traversing - any particular graph to resolve URLs to code. It is also possible - to use traversal and URL dispatch together. When both a root - factory (and therefore traversal) *and* "routes" declarations (and - therefore url dispatch) are used, the url dispatch routes are - checked first, and if none match, :mod:`repoze.bfg` will fall back - to using traversal to attempt to map the request to a view. If the - name ``*traverse`` is in a route's ``path`` pattern, when it is - matched, it is also possible to do traversal *after* a route has - been matched. See :ref:`hybrid_chapter` for more information. +At system startup time, the :mod:`repoze.bfg` :term:`Router` is +configured with a callback known as a :term:`root factory`, supplied +by the application developer as the ``root_factory`` argument to a +:term:`Configurator`. + +Here's an example of a simple root factory: + +.. code-block:: python + :linenos: + + class Root(dict): + def __init__(self, request): + pass + +Here's an example of using this root factory within startup +configuration, by passing it to an instance of a :term:`Configurator` +named ``config``: + + config = Configurator(root_factory=Root) + +Making a declaration like this at startup means that your +:mod:`repoze.bfg` application will call the root factory (in this +case, the class ``Root``) to generate a root object whenever a request +enters the application. Usually a root factory for a traversal-based +application will be more complicated than the above ``Root`` object; +in particular it may be associated with a database connection or +another persistence mechanism. + +A root factory is passed a :term:`request` object and it is expected +to return an object which represents the root of the object graph. +All :term:`traversal` will begin at this root object. The root object +is usually a *mapping* object (such as a Python dictionary, or at +least a class which has many of the same methods as a dictionary). .. warning:: In :mod:`repoze.bfg` 1.0 and prior versions, the root factory was passed a term WSGI *environment* object (a dictionary) @@ -93,6 +105,10 @@ usually a *mapping* object (such as a Python dictionary). emulates the WSGI environment, so code expecting the argument to be a dictionary will continue to work. +If a :term:`root factory` is passed to the :mod:`repoze.bfg` +:term:`Configurator` constructor as the value ``None``, a *default* +root factory is used. + .. sidebar:: Emulating the Default Root Factory For purposes of understanding the default root factory better, @@ -109,35 +125,10 @@ usually a *mapping* object (such as a Python dictionary). config = Configurator(root_factory=Root) The default root factory is just a really stupid object that has no - behavior or state. - -Using :term:`traversal` against an application that uses the object -graph supplied by the default root object is not very interesting, -because the default root object has no children. In a more complex -:mod:`repoze.bfg` application, a root factory would be supplied which -would return an object that had children capable of being traversed, -and therefore there might be many :term:`context` objects to which -URLs might resolve, depending on the URL path. However, in this toy -application, there's exactly one object in our object graph; the -default root object. Therefore, there can only ever be one context: -the :term:`root` object itself. - -We have only a single :term:`default view` registered (the -registration for the ``hello_world`` view callable). Due to this set -of circumstances, you can consider the sole possible URL that will -resolve to a :term:`default view` in this application the root URL -``'/'``. It is the only URL that will resolve to the :term:`view -name` of ``''`` (the empty string) when the default object graph is -traversed. - -We have only a single view registered for the :term:`view name` -``goodbye`` (the registration for the ``goodbye_world`` view -callable). Due to this set of circumstances, you can consider the -sole possible URL that will resolve to the ``goodbye_world`` in this -application the URL ``'/goodbye'`` because it is the only URL that -will result in the :term:`view name` of ``goodbye`` when the default -object graph is traversed. - + behavior or state. Using :term:`traversal` against an application + that uses the object graph supplied by the default root object is + not very interesting, because the default root object has no + children. Items contained within the object graph are sometimes analogous to the concept of :term:`model` objects used by many other frameworks (and @@ -479,6 +470,5 @@ model object during traversal. References ---------- -For a contextual example of how :term:`traversal` can be used to -create a :mod:`repoze.bfg` application, see the -:ref:`bfg_wiki_tutorial`. +A tutorial showing how :term:`traversal` can be used to create a +:mod:`repoze.bfg` application exists in :ref:`bfg_wiki_tutorial`. diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 44515cd54..604eb6814 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -857,7 +857,6 @@ See :ref:`request_and_context_view_definitions` for more information. References ---------- -For a contextual example of how :term:`URL dispatch` can be used to -create a :mod:`repoze.bfg` application, see the -:ref:`bfg_sql_wiki_tutorial`. +A tutorial showing how :term:`URL dispatch` can be used to create a +:mod:`repoze.bfg` application exists in :ref:`bfg_sql_wiki_tutorial`. diff --git a/docs/narr/urlmapping.rst b/docs/narr/urlmapping.rst index b7ba7021b..da8d6ab9f 100644 --- a/docs/narr/urlmapping.rst +++ b/docs/narr/urlmapping.rst @@ -36,18 +36,17 @@ application developer, and invokes it. A view callable returns a .. sidebar:: What Good is A Context Finding Subsystem? - Many other web frameworks such as :term:`Pylons` or :term:`Django` + The :term:`URL dispatch` mode of :mod:`repoze.bfg` as well as many + other web frameworks such as :term:`Pylons` or :term:`Django` actually collapse the two steps of context finding and view lookup - into a single step. In such systems, a URL maps *directly* to a - view callable. These systems possess no analogue to a - context finding subsystem: they are "context-free". This makes - them simpler to understand than systems which use "context". - However, using an explicit context finding step provides extra - flexibility. For example, it makes it possible to protect your - application with declarative context-sensitive instance-level - :term:`authorization`, which is not well supported in frameworks - that do not provide a notion of a context. See the - :ref:`security_chapter` for more information. + into a single step. In these systems, a URL can map *directly* to + a view callable. This makes them simpler to understand than + systems which use distinct subsystems to locate a context and find + a view. However, explicitly using context finding step provides + extra flexibility. For example, it makes it possible to protect + your application with declarative context-sensitive instance-level + :term:`authorization`, which is not well-supported in frameworks + that do not provide a notion of a context. There are two separate context finding subsystems in :mod:`repoze.bfg`: :term:`traversal` and :term:`URL dispatch`. The @@ -55,7 +54,7 @@ subsystems are documented within this chapter. They can be used separately or they can be combined. There is only one view lookup subsystem present in :mod:`repoze.bfg`. -It is not documented in this chapter. Instead, it is documented +It is not documented within this chapter. Instead, it is documented within :ref:`views_chapter`. .. toctree:: -- cgit v1.2.3