collective.beaker 1.0b3

安装

要使用此包，您需要安装它。通常，您会通过您自己包的setup.py中的install_requires行来这样做。

install_requires=[
      ...
      'collective.beaker',
  ],

您还可以使用buildout.cfg中的eggs行来安装它，例如。

[instance]
...
eggs =
    ...
    collective.beaker

如果您在使用Zope 2.10（例如，用于Plone 3），您还需要安装ZPublisherEventsBackport包。您可以通过在[Zope2.10]额外依赖项中依赖它来获取该包，例如。

[instance]
...
eggs =
    ...
    collective.beaker [Zope2.10]

如果您在Zope 2.12或更高版本中，相关事件默认情况下已包含，因此您不应依赖ZPublisherEventsBackport或[Zope2.10]额外依赖项。

配置Beaker

要配置Beaker，请向您的 zope.conf 文件中添加一个部分，如下所示：

<product-config beaker>
    cache.type              file
    cache.data_dir          /tmp/cache/data
    cache.lock_dir          /tmp/cache/lock
    cache.regions           short, long
    cache.short.expire      60
    cache.long.expire       3600

    session.type            file
    session.data_dir        /tmp/sessions/data
    session.lock_dir        /tmp/sessions/lock
    session.key             beaker.session
    session.secret          secret
</product-config>

如果您使用buildout和 plone.recipe.zope2instance 生成您的 zope.conf，可以使用以下选项：

[instance]
...
zope-conf-additional =
    <product-config beaker>
        cache.type              file
        cache.data_dir          ${buildout:directory}/var/cache/data
        cache.lock_dir          ${buildout:directory}/var/cache/lock
        cache.regions           short, long
        cache.short.expire      60
        cache.long.expire       3600

        session.type            file
        session.data_dir        ${buildout:directory}/var/sessions/data
        session.lock_dir        ${buildout:directory}/var/sessions/lock
        session.key             beaker.session
        session.secret          secret
    </product-config>

在这里，我们还使用了buildout替换，将缓存和会话目录放在buildout目录内。

您还需要加载 collective.beaker 包的配置。可以通过如下ZCML行来实现：

<include package="collective.beaker" />

这可以放在您自己的 configure.zcml 中，或者在一个ZCML片段中。如果您使用buildout和 plone.recipe.zope2instance，可以通过添加以下 zcml 行来安装片段：

[instance]
...
zcml =
    collective.beaker

<product-config beaker> 部分内的设置将被直接传递给Beaker。有关可用选项的详细信息，请参阅Beaker配置文档。

请注意：

• 所有缓存设置都必须以前缀 cache. 开头。

• 所有会话设置都必须以前缀 session. 开头。

对于会话设置，以下为默认值：

• invalidate_corrupt=True，因此损坏的会话将被无效化

• type=None 和 data_dir=None，因此默认为内存会话

• key=beaker.session.id - 这是cookie密钥

• timeout=None，因此会话不会超时

• secret=None，因此会话cookie不会被加密

• log_file=None，因此没有日志记录

使用会话

要从请求中获取Beaker会话，请使用以下模式：

>>> from collective.beaker.interfaces import ISession
>>> session = ISession(request)

有关结果会话对象的详细信息，请参阅Beaker会话文档。您可以将其大致视为具有字符串键的字典。

>>> session['username'] = currentUserName

如果您修改了会话，您需要手动保存它

>>> session.save()

或者，您可以将 session.auto 配置键设置为 on，这样会话将在每次请求时自动保存。

如果您想删除会话，请使用

>>> session.delete()

请注意，Beaker不会自动使会话过期/删除，因此您可能需要自己这样做。

如果您想使会话无效并创建一个新的，请使用

>>> session.invalidate()

请注意，会话是在每个请求开始时根据从 zope.conf 读取的会话设置进行配置的。您可以通过注册提供 ISessionConfig 的实用程序来覆盖这些设置。该实用程序必须实现字典API（您可以使用常规字典或持久映射对象，例如）。这允许，例如，站点本地实用程序提供每个站点的会话数据。

使用缓存

Beaker文档说明了如何创建一个作为全局变量的缓存管理器。 CacheManager 实例提供了使用缓存的装饰器和函数。您仍然可以使用这种模式，但这将不会使用 collective.beaker 在zope.conf中管理的任何配置。

然而，您可以使用缓存区域以及显式的缓存API。在运行时（但 不是 在模块作用域内），您可以通过以下方式获得配置为 zope.conf 的Beaker CacheManager：

>>> from zope.component import getUtility
>>> from collective.beaker.interfaces import ICacheManager

>>> cacheManager = getUtility(ICacheManager)

您现在可以根据Beaker文档使用它，例如：

>>> myCache = cacheManager.get_cache('mynamespace', expire=1800)

有关详细信息，请参阅Beaker缓存文档。

您还可以使用缓存区域装饰器，例如：

>>> from beaker.cache import cache_region
>>> @cache_region('short')
... def my_function():
...     ...

前提是已配置“短”区域（如上例中的 zope.conf），这将懒惰地查找区域设置并用于缓存。

要使缓存失效，您可以调用：

>>> from beaker.cache import region_invalidate
>>> region_invalidate(my_function, 'short')

有关详细信息，请参阅 Beaker 文档。

测试

如果您正在编写使用 beaker 会话或缓存的代码的集成测试，您需要在调用相关代码之前确保 beaker 已配置。否则，您可能会在 ISessionConfig 或 ICacheManager 层上遇到组件查找错误。这是因为使用 ZopeTestCase/PloneTestCase 编写的集成测试不会读取您的 zope.conf，因此当它被加载时，collective.beaker 配置代码没有任何配置数据。

您可以通过以下两种方式之一来处理这种情况：

• 注册自己的 ISessionConfig 和/或 ICacheManager 实用程序。有关详细信息，请参阅 interfaces.py。

• 在 ZCML 处理之前提供“假” ZConfig 设置。

您可以使用 collective.beaker.testing.BeakerConfigLayer 中的测试层来完成后者。您需要确保在执行 ZCML 处理的任何层之前混合此层。例如：

from colective.beaker.testing import BeakerConfigLayer
from Products.PloneTestCase.layer import PloneSiteLayer
from Products.PloneTestCase.ptc import PloneTestCase

class MyLayer(BeakerConfigLayer, PloneSiteLayer):
    pass

class TestCase(PloneTestCase):

    layer = MyLayer

当然，您可以在层中添加自己的 setUp 和 tearDown 方法。重要的是 BeakerConfigLayer 在 PloneSiteLayer 之前，后者将配置站点。

此设置将使用默认设置（有关确切值，请参阅 testing.py），但您可以根据每个设置进行操作。例如：

from zope.component import getUtility
from collective.beaker.interfaces import ISessionConfig

config = getUtility(ISessionConfig)
config['secret'] = 'password'

请注意，这通常是一个全局实用程序，因此除非您还适当地拆除了设置，否则任何更改都将跨越测试边界。因此，在层中而不是在单个测试中进行此设置可能更合适。

当编写使用 Beaker 会话的测试时，如果您不是使用像 zope.testbrowser 这样的东西进行功能测试，您可能还需要模拟 collective.beaker 监听的请求开始/结束事件以配置会话。

例如：

from collective.beaker.session import initializeSession, closeSession

...

class TestCase(PloneTestCase):

    layer = MyLayer

    def test_something(self):
        request = self.app.REQUEST
        initializeSession(request)

        # perform your test here

        closeSession(request)

在单元测试中，可能只需为请求提供模拟的 ISession 适配器即可。此包中有一个模拟会话实现，可以帮助您完成此操作。

import unittest
import zope.component.testing

from zope.component import provideAdapter
from collective.beaker.testing import testingSession

from collective.beaker.interfaces import ISession
from zope.publisher.browser import TestRequest


class MyUnitTestCase(unittest.TestCase):

    def setUp(self):
        provideAdapter(testingSession)
        ...

    def tearDown(self):
        zope.component.testing.tearDown()

    def test_something(self):
        request = TestRequest()
        session = ISession(request)
        ...

与“真实”会话一样，测试会话与请求相关联，因此每次在请求上查找适配器时，您都应该得到相同的对象。您还可以检查以下属性以查看会话的使用情况：

• _saved 为 True 时表示已调用一次 save()。

• _invalidated 为 True 时表示已调用一次 invalidate()。

• _deleted 为 True 时表示已调用一次 delete()。

最后，当使用常规字典操作时，accessed() 将返回 True，并将 last_accessed 属性设置为当前日期/时间。

1.0b3 (2011-05-11)

• 修复 setup.py 中的拼写错误 [ajung]

1.0b2 (2010-01-23)

• 修复会话中对签名cookie（secret 参数）的支持。[optilude]

• 提供更好的测试工具和更健壮的测试设置。[optilude]

• 使 ZCML 指令在存在产品配置（例如在测试设置中）时更健壮。[optilude]

1.0b1 (2009-12-10)

• 首次发布 [optilude]