===================================
|
22: Basic Traversal With Site Roots
|
===================================
|
|
Model websites as a hierarchy of objects with operations.
|
|
Background
|
==========
|
|
Web applications have URLs which locate data and make operations on that
|
data. Pyramid supports two ways of mapping URLs into Python operations:
|
|
- The more-traditional approach of *URL dispatch* aka *routes*
|
|
- The more object-oriented approach of
|
:ref:`traversal <pyramid:traversal_chapter>` popularized by Zope
|
|
In this section we will introduce traversal bit-by-bit. Along the way,
|
we will try to show how easy and Pythonic it is to think in terms of
|
traversal.
|
|
Remember...traversal is easy, powerful, and useful.
|
|
With traversal, you think of your website as a tree of Python objects,
|
just like a dictionary of dictionaries. For example::
|
|
http://example.com/company1/aFolder/subFolder/search?term=hello
|
|
...is nothing more than::
|
|
>>> root['aFolder']['subFolder'].search(x=1)
|
|
To remove some mystery about traversal, we start with the smallest
|
possible step: an object at the top of our URL space. This object acts
|
as the "root" and has a view which shows some data on that object.
|
|
Objectives
|
==========
|
|
- Make a factory for the root object
|
|
- Pass it to the configurator
|
|
- Have a view which displays an attribute on that object
|
|
Steps
|
=====
|
|
#. We are going to use the view classes step as our starting point:
|
|
.. code-block:: bash
|
|
(env27)$ cd ..; cp -r view_classes traversal_siteroot; cd traversal_siteroot
|
(env27)$ python setup.py develop
|
|
#. In ``traversal_siteroot/tutorial/__init__.py`` make a root factory
|
and remove the ``add_route`` statements from the
|
:term:`configurator`:
|
|
.. literalinclude:: traversal_siteroot/tutorial/__init__.py
|
:linenos:
|
|
#. We have ``traversal_siteroot/tutorial/resources.py`` with a class for
|
the root of our site and a factory that returns it:
|
|
.. literalinclude:: traversal_siteroot/tutorial/resources.py
|
:linenos:
|
|
#. Our views in ``traversal_siteroot/tutorial/views.py`` are now
|
quite different...no ``route_name``:
|
|
.. literalinclude:: traversal_siteroot/tutorial/views.py
|
:linenos:
|
|
#. A template in ``traversal_siteroot/tutorial/home.pt``:
|
|
.. literalinclude:: traversal_siteroot/tutorial/home.pt
|
:language: html
|
:linenos:
|
|
|
#. Simplified tests in ``traversal_siteroot/tutorial/tests.py``:
|
|
.. literalinclude:: traversal_siteroot/tutorial/tests.py
|
:linenos:
|
|
#. Now run the tests:
|
|
.. code-block:: bash
|
|
|
(env27)$ nosetests tutorial
|
.
|
----------------------------------------------------------------------
|
Ran 4 tests in 0.141s
|
|
OK
|
|
#. Run your Pyramid application with:
|
|
.. code-block:: bash
|
|
(env27)$ pserve development.ini --reload
|
|
#. Open ``http://localhost:6543/`` in your browser.
|
|
Analysis
|
========
|
|
Our ``__init__.py`` has a small but important change: we create the
|
configuration with a *root factory*. Our root factory is a simple
|
function that performs some work and returns the root object in the
|
:ref:`resource tree <pyramid:the_resource_tree>`.
|
|
In the resource tree, Pyramid can match URLs to objects and subobjects,
|
finishing in a view as the operation to perform. Traversing through
|
containers is done using Python's normal ``__getitem__`` dictionary
|
protocol.
|
|
Pyramid provides services beyond simple Python dictionaries. These
|
:ref:`location <pyramid:location_aware>`
|
services need a little bit more protocol than just ``__getitem__``.
|
Namely, objects need to provide an attribute/callable for
|
``__name__`` and ``__parent__``.
|
|
In this step, our tree has one object: the root. It is an instance of
|
``SiteFolder``. Since it is the root, it doesn't need a ``__name__``
|
(aka ``id``) nor a ``__parent__`` (reference to the container an object
|
is in.)
|
|
Our ``home`` view is passed, by Pyramid, the instance of this folder as
|
``context``. The view can then grab attributes and other data from the
|
object that is the focus of the URL.
|
|
Now, on to the most visible part: no more routes! Previously we wrote
|
URL "replacement patterns" which mapped to a route. The route extracted
|
data from the patterns and made this data available to views that were
|
mapped to that route.
|
|
Instead, segments in URLs become object identifiers in Python.
|
|
Extra Credit
|
============
|
|
#. Is the root factory called once on startup, or on every request? Do
|
a small change that answers this. What is the impact of the answer
|
on this?
|
|
.. seealso::
|
:ref:`pyramid:traversal_chapter`,
|
:ref:`pyramid:location_aware`,
|
:ref:`pyramid:the_resource_tree`,
|
:ref:`much_ado_about_traversal_chapter`
|
