2: 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, or routes
  • the more object-oriented approach of traversal 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.

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

...is nothing more than:

>>> root['aFolder']['subFolder'].search()

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

  1. We are going to use the previous step as our starting point:

    $ cd ..; cp -r layout siteroot; cd siteroot
$ $VENV/bin/python setup.py develop

  2. In siteroot/tutorial/__init__.py, make a root factory that points to a function in a module we are about to create:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    from pyramid.config import Configurator

from .resources import bootstrap


def main(global_config, **settings):
    config = Configurator(settings=settings,
                          root_factory=bootstrap)
    config.include('pyramid_jinja2')
    config.scan('.views')
    return config.make_wsgi_app()

  3. We add a new file siteroot/tutorial/resources.py with a class for the root of our site, and a factory that returns it:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    class Root(dict):
    __name__ = ''
    __parent__ = None
    def __init__(self, title):
        self.title = title


def bootstrap(request):
    root = Root('My Site')

    return root

  4. Our views in siteroot/tutorial/views.py are now very different:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    from pyramid.view import view_config


class TutorialViews:
    def __init__(self, context, request):
        self.context = context
        self.request = request

    @view_config(renderer='templates/home.jinja2')
    def home(self):
        page_title = 'Quick Tutorial: Home'
        return dict(page_title=page_title)

    @view_config(name='hello', renderer='templates/hello.jinja2')
    def hello(self):
        page_title = 'Quick Tutorial: Hello'
        return dict(page_title=page_title)

  5. Rename the template siteroot/tutorial/templates/site.jinja2 to siteroot/tutorial/templates/home.jinja2 and modify it:

    1
2
3
4
5
6
7
8
    {% extends "templates/layout.jinja2" %}
{% block content %}

  <p>Welcome to {{ context.title }}. Visit
    <a href="{{ request.resource_url(context, 'hello') }}">hello</a>
  </p>

{% endblock content %}

  6. Add a template in siteroot/tutorial/templates/hello.jinja2:

    1
2
3
4
5
6
7
8
    {% extends "templates/layout.jinja2" %}
{% block content %}

<p>Welcome to {{ context.title }}. Visit 
<a href="{{ request.resource_url(context) }}">home</a></p>


{% endblock content %}

  7. Modify the simple tests in siteroot/tutorial/tests.py:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
    import unittest

from pyramid.testing import DummyRequest
from pyramid.testing import DummyResource


class TutorialViewsUnitTests(unittest.TestCase):
    def test_home(self):
        from .views import TutorialViews

        request = DummyRequest()
        title = 'Dummy Context'
        context = DummyResource(title=title)
        inst = TutorialViews(context, request)
        result = inst.home()
        self.assertIn('Home', result['page_title'])


class TutorialFunctionalTests(unittest.TestCase):
    def setUp(self):
        from tutorial import main
        app = main({})
        from webtest import TestApp
        self.testapp = TestApp(app)

    def test_hello(self):
        result = self.testapp.get('/hello', status=200)
        self.assertIn(b'Quick Tutorial: Hello', result.body)

  8. Now run the tests:

    $ $VENV/bin/nosetests tutorial
..
----------------------------------------------------------------------
Ran 2 tests in 0.134s

OK

  9. Run your Pyramid application with:

    $ $VENV/bin/pserve development.ini --reload

  10. Open http://localhost:6543/hello 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 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 location 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 our Root class. The next URL hop is hello. Our root instance does not have an item in its dictionary named hello, so Pyramid looks for a view with a name=hello, finding our view method.

Our home view is passed by Pyramid, with 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

  1. 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?

See also

Traversal, Location-Aware Resources, The Resource Tree, Much Ado About Traversal