diff options
| -rw-r--r-- | docs/narr/resourcelocation.rst | 109 | ||||
| -rw-r--r-- | docs/narr/traversal.rst | 117 |
2 files changed, 145 insertions, 81 deletions
diff --git a/docs/narr/resourcelocation.rst b/docs/narr/resourcelocation.rst new file mode 100644 index 000000000..aa8eaf23a --- /dev/null +++ b/docs/narr/resourcelocation.rst @@ -0,0 +1,109 @@ +.. index:: + single: resource location + +.. _resourcelocation_chapter: + +Resource Location and View Lookup +--------------------------------- + +As a primary job, :app:`Pyramid` provides a mechanism to find and invoke code +written by the application developer based on parameters present in the +:term:`request`. + +:app:`Pyramid` uses two separate but cooperating subsystems to find and +invoke code written by the application developer: :term:`resource location` +and :term:`view lookup`. + +- A :app:`Pyramid` :term:`resource location` subsystem is given a + :term:`request`; it is responsible for finding a :term:`resource` object + based on information present in the request. When a resource is found via + resource location, it becomes known as the :term:`context`. + +- Using the context provided by :term:`resource location`, the :app:`Pyramid` + :term:`view lookup` subsystem is provided with a :term:`request` and + :term:`context`. It is then responsible for finding and invoking a + :term:`view callable`. A view callable is a specific bit of code written + and registered by the application developer which receives the + :term:`request` and which returns a :term:`response`. + +These two subsystems are used by :app:`Pyramid` serially: first, a +:term:`resource location` subsystem does its job. Then the result of context +finding is passed to the :term:`view lookup` subsystem. The view lookup +system finds a :term:`view callable` written by an application developer, and +invokes it. A view callable returns a :term:`response`. The response is +returned to the requesting user. + +.. sidebar:: What Good is A Resource Location Subsystem? + + The :term:`URL dispatch` mode of :app:`Pyramid` as well as many other web + frameworks such as :term:`Pylons` or :term:`Django` actually collapse the + two steps of resource location and view lookup 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 resource and find a view. However, explicitly finding a resource + 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 resource. + +There are two separate :term:`resource location` subsystems in +:app:`Pyramid`: :term:`traversal` and :term:`URL dispatch`. They can be used +separately or they can be combined. Three chapters which follow describe +:term:`resource location`: :ref:`traversal_chapter`, +:ref:`urldispatch_chapter` and :ref:`hybrid_chapter`. + +There is only one :term:`view lookup` subsystem present in :app:`Pyramid`. +Where appropriate, we will describe how view lookup interacts with context +finding. One chapter which follows describes :term:`view lookup`: +:ref:`views_chapter`. + +Should I Use Traversal or URL Dispatch for Resource Location? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since :app:`Pyramid` provides support for both approaches, you can use either +exclusively or combine them as you see fit. + +:term:`URL dispatch` is very straightforward. When you limit your +application to using URL dispatch, you know every URL that your application +might generate or respond to, all the URL matching elements are listed in a +single place, and you needn't think about :term:`resource location` or +:term:`view lookup` at all. + +URL dispatch can easily handle URLs such as +``http://example.com/members/Chris``, where it's assumed that each item +"below" ``members`` in the URL represents a single member in some system. +You just match everything "below" ``members`` to a particular :term:`view +callable`, e.g. ``/members/{memberid}``. + +However, URL dispatch is not very convenient if you'd like your URLs to +represent an arbitrary hierarchy. For example, if you need to infer the +difference between sets of URLs such as these, where the ``document`` in the +first URL represents a PDF document, and ``/stuff/page`` in the second +represents an OpenOffice document in a "stuff" folder. + +.. code-block:: text + + http://example.com/members/Chris/document + http://example.com/members/Chris/stuff/page + +It takes more pattern matching assertions to be able to make hierarchies work +in URL-dispatch based systems, and some assertions just aren't possible. +Essentially, URL-dispatch based systems just don't deal very well with URLs +that represent arbitrary-depth hierarchies. + +But :term:`traversal` *does* work well for URLs that represent +arbitrary-depth hierarchies. Since the path segments that compose a URL are +addressed separately, it becomes very easy to form URLs that represent +arbitrary depth hierarchies in a system that uses traversal. When you're +willing to treat your application resources as a tree that can be traversed, +it also becomes easy to provide "instance-level security": you just attach a +security declaration to each resource in the tree. This is not nearly as +easy to do when using URL dispatch. + +In essence, the choice to use traversal vs. URL dispatch is largely +religious. Traversal dispatch probably just doesn't make any sense when you +possess completely "square" data stored in a relational database because it +requires the construction and maintenance of a tree and requires that the +developer think about mapping URLs to code in terms of traversing that tree. +However, when you have a hierarchical data store, using traversal can provide +significant advantages over using URL-based dispatch. diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 98a009341..6510f3555 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -13,73 +13,27 @@ explain the concept of a resource tree, and we'll show how traversal might be used within an application. .. index:: - single: traversal analogy - -A Traversal Analogy -------------------- - -We use an analogy to provide an introduction to :term:`traversal`. -Imagine an inexperienced UNIX computer user, wishing only to use the -command line to find a file and to invoke the ``cat`` command against -that file. Because he is inexperienced, the only commands he knows -how to use are ``cd``, which changes the current directory and -``cat``, which prints the contents of a file. And because he is -inexperienced, he doesn't understand that ``cat`` can take an absolute -path specification as an argument, so he doesn't know that you can -issue a single command command ``cat /an/absolute/path`` to get the -desired result. Instead, this user believes he must issue the ``cd`` -command, starting from the root, for each intermediate path segment, -*even the path segment that represents the file itself*. Once he gets -an error (because you cannot successfully ``cd`` into a file), he -knows he has reached the file he wants, and he will be able to execute -``cat`` against the resulting path segment. - -This inexperienced user's attempt to execute ``cat`` against the file -named ``/fiz/buz/myfile`` might be to issue the following set of UNIX -commands: - -.. code-block:: text - - cd / - cd fiz - cd buz - cd myfile - -The user now knows he has found a *file*, because the ``cd`` command -issues an error when he executed ``cd myfile``. Now he knows that he -can run the ``cat`` command: - -.. code-block:: text - - cat myfile - -The contents of ``myfile`` are now printed on the user's behalf. - -:app:`Pyramid` is very much like this inexperienced UNIX user as it uses -:term:`traversal` against a resource tree. In this analogy, we can map the -``cat`` program to the :app:`Pyramid` concept of a :term:`view callable`: it -is a program that can be run against some :term:`resource` (the "context") as -the result of :term:`view lookup`. The file being operated on in this -analogy is the :term:`context` resource; the context is the "last resource -found" in a traversal. The directory structure is the resource tree being -traversed. The act of progressively changing directories to find the file as -well as the handling of a ``cd`` error as a stop condition is analogous to -:term:`traversal`. - -The analogy we've used is not *exactly* correct, because, while the naive -user already knows which command he wants to invoke before he starts -"traversing" (``cat``), :app:`Pyramid` needs to obtain that information from -the path being traversed itself. In :term:`traversal`, the "command" meant -to be invoked is a :term:`view callable`. A view callable is derived via -:term:`view lookup` from the combination of the :term:`request` and the -:term:`context`. - -.. index:: single: traversal overview A High-Level Overview of Traversal ---------------------------------- +A :term:`traversal` uses the URL (Universal Resource Locator) to find a +:term:`resource`. This is done by mapping each segment of the path portion +of the URL into a set of nested dictionary-like objects called the +:term:`resource tree`. You might think of this as looking up files and +directories in a file system. Traversal walks down the path until it finds a +published "directory" or "file". The resource we find as the result of a +traversal becomes the :term:`context`. A separate :term:`view lookup` +subsystem is used to then find some code willing "publish" the context +resource. + +.. index:: + single: traversal details + +Traversal Details +----------------- + :term:`Traversal` is dependent on information in a :term:`request` object. Every :term:`request` object contains URL path information in the ``PATH_INFO`` portion of the :term:`WSGI` environment. The ``PATH_INFO`` @@ -149,14 +103,15 @@ The Resource Tree ----------------- When your application uses :term:`traversal` to resolve URLs to code, your -application must supply the a resource tree to :app:`Pyramid`. This tree is -represented by a :term:`root` resource. +application must supply a :term:`resource tree` to :app:`Pyramid`. The +resource tree is a set of nested dictionary-like objects. The root of the +tree is represented by a :term:`root` resource. In order to supply a root resource for an application, at system startup -time, the :app:`Pyramid` :term:`Router` is configured with a -callback known as a :term:`root factory`. The root factory is -supplied by the application developer as the ``root_factory`` argument -to the application's :term:`Configurator`. +time, the :app:`Pyramid` :term:`Router` is configured with a callback known +as a :term:`root factory`. The root factory is supplied by the application +developer as the ``root_factory`` argument to the application's +:term:`Configurator`. Here's an example of a simple root factory: @@ -167,9 +122,8 @@ Here's an example of a simple root factory: 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``: +Here's an example of using this root factory within startup configuration, by +passing it to an instance of a :term:`Configurator` named ``config``: .. code-block:: python :linenos: @@ -187,13 +141,13 @@ A root factory is passed a :term:`request` object and it is expected to return a resource which represents the root of the resource tree. All :term:`traversal` will begin at this root resource. Usually a root factory for a traversal-based application will be more complicated than the above -``Root`` class; in particular it may be associated with a database -connection or another persistence mechanism. +``Root`` class; in particular it may be associated with a database connection +or another persistence mechanism. If no :term:`root factory` is passed to the :app:`Pyramid` -:term:`Configurator` constructor, or the ``root_factory`` is specified -as the value ``None``, a *default* root factory is used. The default -root factory always returns a resource that has no child resources. +:term:`Configurator` constructor, or the ``root_factory`` is specified as the +value ``None``, a *default* root factory is used. The default root factory +always returns a resource that has no child resources. .. sidebar:: Emulating the Default Root Factory @@ -226,11 +180,12 @@ root factory always returns a resource that has no child resources. The resource tree consists of *container* resources and *leaf* resources. There is only one difference between a *container* resource and a *leaf* -resource: *container* resources possess a ``__getitem__`` method while *leaf* -resources do not. The ``__getitem__`` method was chosen as the signifying -difference between the two types of resources because the presence of this -method is how Python itself typically determines whether a resource is -"containerish" or not. +resource: *container* resources possess a ``__getitem__`` method (making it +"dictionary-like") while *leaf* resources do not. The ``__getitem__`` method +was chosen as the signifying difference between the two types of resources +because the presence of this method is how Python itself typically determines +whether an object is "containerish" or not (dictionary objects are +"containerish"). Each container resource is presumed to be willing to return a child resource or raise a ``KeyError`` based on a name passed to its ``__getitem__``. |