z3c.traverser 2.0

CHANGES

Pluggable Traversers

Traversers are Zope’s mechanism to convert URI paths to an object of the application. They provide an extremly flexible mechanism to make decisions based on the policies of the application. Unfortunately the default traverser implementation is not flexible enough to deal with arbitrary extensions (via adapters) of objects that also wish to participate in the traversal decision process.

The pluggable traverser allows developers, especially third-party developers, to add new traversers to an object without altering the original traversal implementation.

>>> from z3c.traverser.traverser import PluggableTraverser

Let’s say that we have an object

>>> from zope.interface import Interface, implementer
>>> class IContent(Interface):
...     pass

>>> @implementer(IContent)
... class Content(object):
...     var = True

>>> content = Content()

that we wish to traverse to. Since traversers are presentation-type specific, they are implemented as views and must thus be initiated using a request:

>>> from zope.publisher.base import TestRequest
>>> request = TestRequest('')
>>> traverser = PluggableTraverser(content, request)

We can now try to lookup the variable:

>>> traverser.publishTraverse(request, 'var')
Traceback (most recent call last):
...
NotFound: Object: <Content object at ...>, name: 'var'

But it failed. Why? Because we have not registered a plugin traverser yet that knows how to lookup attributes. This package provides such a traverser already, so we just have to register it:

>>> from zope.component import provideSubscriptionAdapter
>>> from zope.publisher.interfaces import IPublisherRequest
>>> from z3c.traverser.traverser import AttributeTraverserPlugin

>>> provideSubscriptionAdapter(AttributeTraverserPlugin,
...                            (IContent, IPublisherRequest))

If we now try to lookup the attribute, we the value:

>>> traverser.publishTraverse(request, 'var')
True

However, an incorrect variable name will still return a NotFound error:

>>> traverser.publishTraverse(request, 'bad')
Traceback (most recent call last):
...
NotFound: Object: <Content object at ...>, name: 'bad'

Every traverser should also make sure that the passed in name is not a view. (This allows us to not specify the @@ in front of a view.) So let’s register one:

>>> class View(object):
...     def __init__(self, context, request):
...         pass

>>> from zope.component import provideAdapter
>>> from zope.publisher.interfaces import IPublisherRequest
>>> provideAdapter(View,
...                adapts=(IContent, IPublisherRequest),
...                provides=Interface,
...                name='view.html')

Now we can lookup the view as well:

>>> traverser.publishTraverse(request, 'view.html')
<View object at ...>

Additional Namespaces

Principal

The principal namespace allows to differentiate between usernames in the url. This is usefull for caching on a per principal basis. The namespace itself doesn’t change anything. It just checks if the principal is the one that is logged in.

>>> from z3c.traverser import namespace
>>> from zope.publisher.browser import TestRequest
>>> class Request(TestRequest):
...     principal = None
...
...     def shiftNameToApplication(self):
...         pass

>>> class Principal(object):
...     def __init__(self, id):
...         self.id = id

>>> pid = 'something'
>>> r = Request()
>>> r.principal = Principal('anonymous')

If we have the wrong principal we get an Unauthorized exception.

>>> ns = namespace.principal(object(), r)
>>> ns.traverse('another', None) # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
Unauthorized: ++principal++another

Otherwise not

>>> ns.traverse('anonymous', None)
<object object at ...>

Traversing Viewlets

This package allows to traverse viewlets and viewletmanagers. It also provides absolute url views for those objects which are described in this file, for traversers see BROWSER.rst.

>>> from z3c.traverser.viewlet import browser

Let us define some test classes.

>>> import zope.component
>>> from zope.viewlet import manager
>>> from zope.viewlet import interfaces
>>> from zope.publisher.interfaces.browser import IDefaultBrowserLayer
>>> import zope.interface
>>> class ILeftColumn(interfaces.IViewletManager):
...     """Viewlet manager located in the left column."""
>>> LeftColumn = manager.ViewletManager('left', ILeftColumn)
>>> zope.component.provideAdapter(
...     LeftColumn,
...     (zope.interface.Interface,
...     IDefaultBrowserLayer, zope.interface.Interface),
...     interfaces.IViewletManager, name='left')

You can then create a viewlet manager using this interface now:

>>> from zope.viewlet import viewlet
>>> from zope.container.contained import Contained

>>> class Content(Contained):
...     pass
>>> root['content'] = Content()
>>> content = root['content']
>>> from zope.publisher.browser import TestRequest
>>> request = TestRequest()
>>> from zope.publisher.interfaces.browser import IBrowserView
>>> from zope.publisher.browser import BrowserView
>>> class View(BrowserView):
...     pass

We have to set the name, this is normally done in zcml.

>>> view = View(content, request)
>>> view.__name__ = 'test.html'
>>> leftColumn = LeftColumn(content, request, view)

Let us create a simple viewlet. Note that we need a __name__ attribute in order to make the viewlet traversable. Normally you don’t have to take care of this, because the zcml directive sets the name upon registration.

>>> class MyViewlet(viewlet.ViewletBase):
...     __name__ = 'myViewlet'
...     def render(self):
...         return u'<div>My Viewlet</div>'
>>> from zope.security.checker import NamesChecker, defineChecker
>>> viewletChecker = NamesChecker(('update', 'render'))
>>> defineChecker(MyViewlet, viewletChecker)

>>> zope.component.provideAdapter(
...     MyViewlet,
...     (zope.interface.Interface, IDefaultBrowserLayer,
...     IBrowserView, ILeftColumn),
...     interfaces.IViewlet, name='myViewlet')

We should now be able to get the absolute url of the viewlet and the manager. We have to register the adapter for the test.

>>> from zope.traversing.browser.interfaces import IAbsoluteURL
>>> from zope.traversing.browser import absoluteurl

>>> zope.component.provideAdapter(
...     browser.ViewletAbsoluteURL,
...     (interfaces.IViewlet, IDefaultBrowserLayer),
...     IAbsoluteURL)
>>> zope.component.provideAdapter(
...     browser.ViewletManagerAbsoluteURL,
...     (interfaces.IViewletManager, IDefaultBrowserLayer),
...     IAbsoluteURL, name="absolute_url")
>>> zope.component.provideAdapter(
...     browser.ViewletManagerAbsoluteURL,
...     (interfaces.IViewletManager, IDefaultBrowserLayer),
...     IAbsoluteURL)
>>> myViewlet = MyViewlet(content, request, view, leftColumn)
>>> absoluteurl.absoluteURL(leftColumn, request)
'http://127.0.0.1/content/test.html/++manager++left'
>>> absoluteurl.absoluteURL(myViewlet, request)
'.../content/test.html/++manager++left/++viewlet++myViewlet'

Viewlet Traversing

Traversing to viewlets is done via namespaces.

>>> from webtest.app import TestApp
>>> browser = TestApp(wsgi_app)
>>> res = browser.get('http://localhost/@@test.html')

We have a test page registered that contains our viewlet. The viewlet itself just renders a link to its location (this is just for testing).

>>> print(res.html)
<html>
  <body>
     <div><div><a
     href="http://localhost/test.html/++manager++IMyManager/++viewlet++MyViewlet">My
     Viewlet</a></div></div>
  </body>
</html>

Let’s follow the link to traverse the viewlet directly.

>>> res = res.click('My Viewlet')
>>> res.request.url
'http://localhost/test.html/++manager++IMyManager/++viewlet++MyViewlet'
>>> print(res.body.decode())
<div><a href="http://localhost/test.html/++manager++IMyManager/++viewlet++MyViewlet">My Viewlet</a></div>

What happens if a viewlet managers is nested into another viewlet? To test this we will create another manager and another viewlet:

>>> res = browser.get('http://localhost/@@nested.html')
>>> print(res.html)
<html>
  <body>
    <div><div><a href="http://localhost/nested.html/++manager++IOuterManager/++viewlet++OuterViewlet/++manager++IInnerManager/++viewlet++InnerViewlet/++manager++IMostInnerManager/++viewlet++MostInnerViewlet">Most inner viewlet</a></div></div>
  </body>
</html>

Let’s follow the link to traverse the viewlet directly.

>>> res = res.click('Most inner viewlet')
>>> res.request.url
'http://localhost/nested.html/++manager++IOuterManager/++viewlet++OuterViewlet/++manager++IInnerManager/++viewlet++InnerViewlet/++manager++IMostInnerManager/++viewlet++MostInnerViewlet'

>>> print(res.body.decode())
<div><a href="http://localhost/nested.html/++manager++IOuterManager/++viewlet++OuterViewlet/++manager++IInnerManager/++viewlet++InnerViewlet/++manager++IMostInnerManager/++viewlet++MostInnerViewlet">Most inner viewlet</a></div>

Extracting Information from the Traversal Stack

This package allows to define virtual traversal paths for collecting arbitrary information from the traversal stack instead of, for example, query strings.

In contrast to the common way of defining custom Traversers, this implementation does not require to go through the whole traversal process step by step. The traversal information needed is taken from the traversalstack directly and the used parts of the stack are consumed. This way one don’t have to define proxy classes just for traversal.

This implementation does not work in tales because it requires the traversalstack of the request.

For each name in the traversal stack a named multiadapter is looked up for ITraversalStackConsumer, if found the item gets removed from the stack and the adapter is added to the request annotation.

>>> from z3c.traverser.stackinfo import traversing
>>> from z3c.traverser.stackinfo import interfaces

If there are no adapters defined, the traversalstack is kept as is. To show this behaviour we define some sample classes.

>>> from zope import interface
>>> class IContent(interface.Interface):
...     pass

>>> from zope.site.folder import Folder
>>> @interface.implementer(IContent)
... class Content(Folder):
...     pass

There is a convinience function which returns an iterator which iterates over tuples of adapterName, adapter. Additionally the traversal stack of the request is consumed if needed.

>>> from zope.publisher.browser import TestRequest
>>> from zope.publisher.interfaces.browser import IBrowserRequest
>>> request = TestRequest()

We set the traversal stack manually for testing here.

>>> request.setTraversalStack(['index.html', 'path', 'some'])
>>> content = Content()

So if no ITraversalStackConsumer adapters are found the stack is left untouched.

>>> list(traversing.getStackConsumers(content, request))
[]
>>> request.getTraversalStack()
['index.html', 'path', 'some']

There is a base class for consumer implementations which implements the ITraversalStackConsumer interface.

>>> from z3c.traverser.stackinfo import consumer
>>> from zope.interface.verify import verifyObject
>>> o = consumer.BaseConsumer(None, None)
>>> verifyObject(interfaces.ITraversalStackConsumer,o)
True

Let us define a custom consumer.

>>> from zope import component
>>> class DummyConsumer(consumer.BaseConsumer):
...     component.adapts(IContent, IBrowserRequest)
>>> component.provideAdapter(DummyConsumer, name='some')

Now we will find the newly registered consumer and the ‘some’ part of the stack is consumed.

>>> consumers = list(traversing.getStackConsumers(content, request))
>>> consumers
[('some', <DummyConsumer named 'some'>)]
>>> request.getTraversalStack()
['index.html', 'path']

Each consumer at least has to consume one element, which is always the name under which the adapter was registered under.

>>> name, cons = consumers[0]
>>> cons.__name__
'some'

Let us provide another adapter, to demonstrate that the adpaters always have the reverse order of the traversal stack. This is actually the order in the url.

>>> component.provideAdapter(DummyConsumer, name='other')
>>> stack = ['index.html', 'path', 'some', 'other']
>>> request.setTraversalStack(stack)
>>> consumers = list(traversing.getStackConsumers(content, request))
>>> consumers
[('other', <DummyConsumer named 'other'>),
 ('some', <DummyConsumer named 'some'>)]

>>> [c.__name__ for name, c in consumers]
['other', 'some']

The arguments attribute of the consumer class defines how many arguments are consumed/needed from the stack. Let us create a KeyValue consumer, that should extract key value pairs from the stack.

>>> class KeyValueConsumer(DummyConsumer):
...     arguments=('key', 'value')
>>> component.provideAdapter(KeyValueConsumer, name='kv')
>>> stack = ['index.html', 'value', 'key', 'kv']
>>> request.setTraversalStack(stack)
>>> consumers = list(traversing.getStackConsumers(content, request))
>>> consumers
[('kv', <KeyValueConsumer named 'kv'>)]
>>> request.getTraversalStack()
['index.html']
>>> name, cons = consumers[0]
>>> cons.key
'key'
>>> cons.value
'value'

We can of course use multiple consumers of the same type.

>>> stack = ['index.html', 'v2', 'k2', 'kv', 'v1', 'k1', 'kv']
>>> request.setTraversalStack(stack)
>>> consumers = list(traversing.getStackConsumers(content, request))
>>> [(c.__name__, c.key, c.value) for name, c in consumers]
[('kv', 'k1', 'v1'), ('kv', 'k2', 'v2')]

If we have too less arguments a NotFound exception.

>>> stack = ['k2', 'kv', 'v1', 'k1', 'kv']
>>> request.setTraversalStack(stack)
>>> consumers = list(traversing.getStackConsumers(content, request))
Traceback (most recent call last):
  ...
NotFound: Object: <Content object at ...>, name: 'kv'

In order to actually use the stack consumers to retrieve information, there is another convinience function which stores the consumers in the requests annotations. This should noramlly be called on BeforeTraverseEvents.

>>> stack = ['index.html', 'v2', 'k2', 'kv', 'v1', 'k1', 'kv']
>>> request.setTraversalStack(stack)
>>> traversing.applyStackConsumers(content, request)
>>> request.annotations[traversing.CONSUMERS_ANNOTATION_KEY]
[<KeyValueConsumer named 'kv'>,
 <KeyValueConsumer named 'kv'>]

Instead of messing with the annotations one just can adapt the request to ITraversalStackInfo.

>>> component.provideAdapter(consumer.requestTraversalStackInfo)
>>> ti = interfaces.ITraversalStackInfo(request)
>>> ti
(<KeyValueConsumer named 'kv'>, <KeyValueConsumer named 'kv'>)

>>> len(ti)
2

The adapter always returs an empty TraversalStackInfoObject if there is no traversalstack information.

>>> request = TestRequest()
>>> ti = interfaces.ITraversalStackInfo(request)
>>> len(ti)
0

Extracting Information from the Traversal Stack

This is a simple example to demonstrate the usage of this package. Please take a look into the testing directory to see how things should be set up.

>>> from webtest.app import TestApp
>>> browser = TestApp(wsgi_app,
...     extra_environ={'wsgi.handleErrors': False,
...                    'paste.throw_errors': True,
...                    'x-wsgiorg.throw_errors': True})
>>> res = browser.get('http://localhost/@@stackinfo.html')

So basically we have no stack info.

>>> print(res.body.decode())
Stack Info from object at http://localhost/stackinfo.html:

Let us try to set foo to bar.

>>> res = browser.get('http://localhost/kv/foo/bar/@@stackinfo.html')
>>> print(res.body.decode())
Stack Info from object at http://localhost/stackinfo.html:
consumer kv:
key = 'foo'
value = 'bar'

Two consumers.

>>> res = browser.get(
...     'http://localhost/kv/foo/bar/kv/time/late/@@stackinfo.html')
>>> print(res.body.decode())
Stack Info from object at http://localhost/stackinfo.html:
consumer kv:
key = 'foo'
value = 'bar'
consumer kv:
key = 'time'
value = 'late'

Invalid url:

>>> browser.get('http://localhost/kv/foo/bar/kv/@@stackinfo.html') \
...     # doctes: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
NotFound: Object: <...Folder object at ...>, name: 'kv'