z3c.traverser 2.0

CHANGES

可插拔遍历器

遍历器是Zope将URI路径转换为应用程序对象的机制。它们提供了一个极端灵活的机制来根据应用程序的策略做出决策。不幸的是，默认的遍历器实现不够灵活，无法处理也希望参与遍历决策过程的任意扩展（通过适配器）的对象。

可插入遍历器允许开发者，特别是第三方开发者，在不更改原始遍历器实现的情况下向对象添加新的遍历器。

>>> from z3c.traverser.traverser import PluggableTraverser

假设我们有一个对象

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

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

>>> content = Content()

我们希望遍历到。由于遍历器是呈现特定类型的，它们被实现为视图，因此必须使用请求启动

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

现在我们可以尝试查找变量

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

但是失败了。为什么？因为我们还没有注册一个知道如何查找属性的插件遍历器。这个包已经提供了一个这样的遍历器，所以我们只需要注册它

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

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

现在我们可以尝试查找属性，我们得到值

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

然而，错误的变量名仍然会返回一个NotFound错误

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

每个遍历器还应该确保传递的名称不是一个视图。（这允许我们在视图前不指定@@。）所以让我们注册一个

>>> 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')

现在我们可以查找视图了

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

附加命名空间

主体

principal 命名空间允许在 URL 中区分用户名。这对于基于主体的缓存很有用。命名空间本身不会改变任何东西。它只是检查主体是否是登录的用户。

>>> 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')

如果我们有错误的主体，我们将得到一个 Unauthorized 异常。

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

否则不是

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

遍历视图插件

此包允许遍历视图小部件和视图管理器。它还提供了描述在此文件中的对象的绝对 URL 视图，有关遍历器，请参阅 BROWSER.rst。

>>> from z3c.traverser.viewlet import browser

让我们定义一些测试类。

>>> 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')

您现在可以使用此接口创建视图小部件。

>>> 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

我们必须设置名称，这通常在 zcml 中完成。

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

让我们创建一个简单的视图小部件。请注意，我们需要一个 __name__ 属性才能使视图小部件可遍历。通常您不必关心这一点，因为 zcml 指令在注册时设置名称。

>>> 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')

我们现在应该能够获取视图小部件和管理的绝对 URL。我们必须为测试注册适配器。

>>> 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'

视图插件遍历

通过命名空间进行视图小部件的遍历。

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

我们已经注册了一个测试页面，其中包含我们的视图小部件。视图小部件本身仅渲染一个链接到其位置的链接（这只是用于测试）。

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

让我们跟随链接直接遍历视图小部件。

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

如果一个视图管理器嵌套在另一个视图小部件中会发生什么？为了测试这一点，我们将创建另一个管理器和另一个视图小部件

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

让我们跟随链接直接遍历视图小部件。

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

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

从遍历堆栈中提取信息

此包允许定义虚拟遍历路径，以便从遍历堆栈中收集任意信息，而不是例如查询字符串。

与通常定义自定义遍历器的常用方式相比，此实现不需要逐步执行整个遍历过程。所需遍历信息直接从遍历堆栈中获取，并消耗使用的堆栈部分。这样，就不必仅为了遍历而定义代理类。

此实现不适用于 tales，因为它需要请求的遍历堆栈。

对于遍历堆栈中的每个名称，都会查找一个名为 ITraversalStackConsumer 的命名多适配器，如果找到，则从堆栈中删除该项目，并将适配器添加到请求注解中。

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

如果没有定义适配器，则遍历堆栈保持不变。为了展示此行为，我们定义了一些示例类。

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

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

存在一个方便的函数，它返回一个迭代器，该迭代器遍历适配器名称和适配器的元组。如果需要，还会消耗请求的遍历堆栈。

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

在此处手动设置遍历堆栈以进行测试。

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

因此，如果没有找到 ITraversalStackConsumer 适配器，则堆栈保持不变。

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

存在一个针对消费者实现的基本类，它实现了 ITraversalStackConsumer 接口。

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

让我们定义一个自定义消费者。

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

现在我们将找到新注册的消费者，并且堆栈中的“some”部分被消耗。

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

每个消费者至少必须消耗一个元素，这始终是适配器注册的名称。

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

让我们提供一个其他适配器，以演示适配器始终具有遍历堆栈的相反顺序。这实际上是 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']

消费者类的 arguments 属性定义了从堆栈中消耗/需要的参数数量。让我们创建一个键值消费者，该消费者应从堆栈中提取键值对。

>>> 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'

当然，我们可以使用相同类型的多个消费者。

>>> 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')]

如果我们有太少的参数，则抛出 NotFound 异常。

>>> 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'

为了实际使用堆栈消费者检索信息，还有一个方便的函数，该函数将消费者存储在请求注解中。这通常应在 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'>]

而不是与注解纠缠，可以直接将请求适配到 ITraversalStackInfo。

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

>>> len(ti)
2

如果没有遍历堆栈信息，适配器始终返回一个空的 TraversalStackInfoObject。

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

从遍历堆栈中提取信息

这是一个简单的示例，以展示此包的用法。请查看测试目录，了解应该如何设置。

>>> 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('https://127.0.0.1/@@stackinfo.html')

因此，基本上我们没有任何堆栈信息。

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

让我们尝试将 foo 设置为 bar。

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

两个消费者。

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

无效的 URL

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