{ "info": { "author": "Martin Aspeli", "author_email": "optilude@gmail.com", "bugtrack_url": null, "classifiers": [ "Framework :: Plone", "Programming Language :: Python", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "collective.beaker - Beaker integration for Zope 2 and Plone.\n============================================================\n\nThis package provides a means to configure the `Beaker\n`_ session management and caching framework for\nuse within a Zope 2 (and Plone) environment.\n\nOrdinarily, Beaker is configured using WSGI middleware. However, Zope 2 does\nnot (yet) run WSGI by default (unless you use ``repoze.zope2``). This package\nprovides an alternative configuration syntax, based in zope.conf.\n\nInstallation\n------------\n\nTo use this package, you need to install it. Typically, you would do this\nvia the ``install_requires`` line in your own package's ``setup.py``::\n\n install_requires=[\n ...\n 'collective.beaker',\n ],\n\nYou can also install it using the ``eggs`` line in buildout.cfg, e.g.::\n\n [instance]\n ...\n eggs =\n ...\n collective.beaker\n\nIf you are on Zope 2.10 (e.g. for Plone 3), you will also need to install the\n`ZPublisherEventsBackport\n`_ package. You can\nget that as a dependency by depending in the ``[Zope2.10]`` extra, e.g.::\n\n [instance]\n ...\n eggs =\n ...\n collective.beaker [Zope2.10]\n\nIf you are in Zope 2.12 or later, the relevant events are included by default,\nand you should *not* depend on ``ZPublisherEventsBackport`` or the\n``[Zope2.10]`` extra.\n\nConfiguring Beaker\n------------------\n\nTo configure Beaker, add a section to your ``zope.conf`` like this::\n\n \n cache.type file\n cache.data_dir /tmp/cache/data\n cache.lock_dir /tmp/cache/lock\n cache.regions short, long\n cache.short.expire 60\n cache.long.expire 3600\n \n session.type file\n session.data_dir /tmp/sessions/data\n session.lock_dir /tmp/sessions/lock\n session.key beaker.session\n session.secret secret\n \n\nIf you are using buildout and ``plone.recipe.zope2instance`` to generate your\n``zope.conf``, you can use the following option::\n\n [instance]\n ...\n zope-conf-additional =\n \n cache.type file\n cache.data_dir ${buildout:directory}/var/cache/data\n cache.lock_dir ${buildout:directory}/var/cache/lock\n cache.regions short, long\n cache.short.expire 60\n cache.long.expire 3600\n \n session.type file\n session.data_dir ${buildout:directory}/var/sessions/data\n session.lock_dir ${buildout:directory}/var/sessions/lock\n session.key beaker.session\n session.secret secret\n \n\nHere, we have also used a buildout substitution to put the cache and session\ndirectories inside the buildout directory.\n\nYou also need to load the configuration for the ``collective.beaker`` package.\nThis can be done with a ZCML line like this::\n\n \n\nThis could be in your own ``configure.zcml``, or in a ZCML slug. If you are\nusing buildout and ``plone.recipe.zope2instance``, you can install a slug\nby adding a ``zcml`` line like::\n\n [instance]\n ...\n zcml =\n collective.beaker\n\nThe settings within the ```` section are passed\ndirectly to Beaker. See the `Beaker configuration documentation\n`_ for more details about the\navailable options.\n\nPlease note that:\n\n* All cache settings must be prefixed with ``cache.``\n* All session settings must be prefixed with ``session.``\n\nFor the session settings, the following defaults apply:\n\n* ``invalidate_corrupt=True``, so corrupt sessions are invalidated\n* ``type=None`` and ``data_dir=None``, thus defaulting to an in-memory\n session\n* ``key=beaker.session.id`` - this is the cookie key\n* ``timeout=None``, so sessions don't time out\n* ``secret=None``, so session cookies are not encrypted\n* ``log_file=None``, so there is no logging\n\nUsing sessions\n--------------\n\nTo obtain a Beaker session from a request, use the following pattern::\n\n >>> from collective.beaker.interfaces import ISession\n >>> session = ISession(request)\n\nSee the `Beaker session documentation\n`_ for details on the resultant\nsession object. You can more or less treat it as a dictionary with string\nkeys::\n\n >>> session['username'] = currentUserName\n\nIf you modify the session, you need to manually save it::\n\n >>> session.save()\n\nAlternatively, you can set the ``session.auto`` configuration key to ``on``,\nand sessions will be automatically saved on each request.\n\nIf you want to delete the session, use::\n\n >>> session.delete()\n\nNote that Beaker does not automatically expire/remove sessions, so you may\nneed to do this yourself.\n\nIf you want to invalidate the session and create a new one, use::\n\n >>> session.invalidate()\n\nNote that the session is configured when each request is begun, based on the\nsession settings read from ``zope.conf``. It is possible to override these\nby registering a utility providing ``ISessionConfig`` from this package. The\nutility must implement the dict API (you can use a regular dict, or a\npersistent mapping object, for example). This allows, for example, a site-\nlocal utility to provide per-site session data.\n\nUsing caching\n-------------\n\nThe Beaker documentation illustrates how to create a cache manager as a \nglobal variable. The ``CacheManager`` instance provides decorators and\nfunctions to use the cache. You can still use this pattern, but this will\nnot use any of the configuration managed by ``collective.beaker`` in zope.conf\n\nYou can, however, use cache regions, as well as the explicit caching API. At\nruntime (but *not* in module scope) you can obtain a Beaker ``CacheManager``\nthat is configured as per ``zope.conf`` like so::\n\n >>> from zope.component import getUtility\n >>> from collective.beaker.interfaces import ICacheManager\n \n >>> cacheManager = getUtility(ICacheManager)\n\nYou can now use this programmatically as per the Beaker documentation, e.g.::\n\n >>> myCache = cacheManager.get_cache('mynamespace', expire=1800)\n\nRefer to the `Beaker caching documentation\n`_ for details.\n\nYou can also use caching region decorators, e.g. with::\n\n >>> from beaker.cache import cache_region\n >>> @cache_region('short')\n ... def my_function():\n ... ...\n\nProvided that the 'short' region is configured (as in the ``zope.conf``\nexample above), this will lazily look up the region settings and use those\nfor caching.\n\nTo invalidate the cache, you could call::\n\n >>> from beaker.cache import region_invalidate\n >>> region_invalidate(my_function, 'short')\n\nAgain, refer to the Beaker documentation for details.\n\nTesting\n-------\n\nIf you are writing integration tests for code that uses beaker sessions or\ncaches, you need to ensure that beaker is configured before you call the\nrelevant code. Otherwise, you are liable to get component lookup errors\non ``ISessionConfig`` or ``ICacheManager`` layers. This is because integration\ntests written with ``ZopeTestCase``/``PloneTestCase`` do not read your\n``zope.conf`` and so the ``collective.beaker`` configuration code does not\nhave any configuration data when it is loaded.\n\nYou can deal with this in one of two ways:\n\n* Register your own ``ISessionConfig`` and/or ``ICacheManager`` utilities.\n See ``interfaces.py`` for details.\n* Provide \"fake\" ZConfig settings before ZCML processing takes place.\n\nYou can use the test layer in ``collective.beaker.testing.BeakerConfigLayer``\nto do the latter. You need to make sure that this layer is mixed in before\nany layer that executes ZCML processing. For example::\n\n from colective.beaker.testing import BeakerConfigLayer\n from Products.PloneTestCase.layer import PloneSiteLayer\n from Products.PloneTestCase.ptc import PloneTestCase\n \n class MyLayer(BeakerConfigLayer, PloneSiteLayer):\n pass\n \n class TestCase(PloneTestCase):\n \n layer = MyLayer\n \nYou can of course add your own ``setUp`` and ``tearDown`` methods to the\nlayer. The important thing is that the ``BeakerConfigLayer`` comes before\nthe ``PloneSiteLayer``, which will configure the site.\n\nThis setup will use default settings (see ``testing.py`` for the exact\nvalues), but you can manipulate these on a per-setting basis. For example::\n\n from zope.component import getUtility\n from collective.beaker.interfaces import ISessionConfig\n \n config = getUtility(ISessionConfig)\n config['secret'] = 'password'\n\nBear in mind that this is normally a global utility, so any changes will\ncross test boundaries unless you also tear down your settings properly. Thus,\nit is probably more appropriate to do this setup in a layer than in an\nindividual test.\n\nWhen writing tests that use Beaker sessions, if you are not performing\nfunctional testing using something like ``zope.testbrowser``, you may also\nneed to simulate the request start/end events that ``collective.beaker``\nlistens to in order to configure the session.\n\nFor example::\n\n from collective.beaker.session import initializeSession, closeSession\n \n ...\n \n class TestCase(PloneTestCase):\n \n layer = MyLayer\n \n def test_something(self):\n request = self.app.REQUEST\n initializeSession(request)\n \n # perform your test here\n \n closeSession(request)\n\nIn a unit test, it is probably easier to just provide a mock ``ISession``\nadapter for the request. There is a mock session implementation in this\npackage which can help you with that::\n \n import unittest\n import zope.component.testing\n \n from zope.component import provideAdapter\n from collective.beaker.testing import testingSession\n \n from collective.beaker.interfaces import ISession\n from zope.publisher.browser import TestRequest\n \n \n class MyUnitTestCase(unittest.TestCase):\n \n def setUp(self):\n provideAdapter(testingSession)\n ...\n \n def tearDown(self):\n zope.component.testing.tearDown()\n \n def test_something(self):\n request = TestRequest()\n session = ISession(request)\n ...\n\nLike the \"real\" session, the test session is tied to the request, so you\nshould get the same object back each time you look up the adapter on the\nrequest. You can also check the following properties to see how the session\nhas been used:\n\n* ``_saved`` is True if ``save()`` has been called once.\n* ``_invalidated`` is True if ``invalidate()`` has been called once.\n* ``_deleted`` is True if ``delete()`` has been called once.\n\nFinally, ``accessed()`` will return True and the ``last_accessed`` attribute\nwill be set to the current date/time when common dictionary operations are\nused.\n\nChangelog for collective.beaker\n===============================\n\n1.0b3 (2011-05-11)\n------------------\n - fixed spelling issue in setup.py\n [ajung]\n\n1.0b2 (2010-01-23)\n------------------\n\n - Fix support for signed cookies (the ``secret`` parameter) in sessions.\n [optilude]\n\n - Provide better testing tools and more resilient test setup.\n [optilude]\n\n - Make the ZCML directive more resilient to configurations where there is\n no product_config. This can happen in test setup, for example.\n [optilude]\n\n1.0b1 (2009-12-10)\n------------------\n\n - Initial release\n [optilude]", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://pypi.python.org/pypi/collective.beaker", "keywords": "beaker zope plone caching sessions", "license": "BSD", "maintainer": null, "maintainer_email": null, "name": "collective.beaker", "package_url": "https://pypi.org/project/collective.beaker/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/collective.beaker/", "project_urls": { "Download": "UNKNOWN", "Homepage": "http://pypi.python.org/pypi/collective.beaker" }, "release_url": "https://pypi.org/project/collective.beaker/1.0b3/", "requires_dist": null, "requires_python": null, "summary": "Beaker integration for Zope and Plone", "version": "1.0b3" }, "last_serial": 787655, "releases": { "1.0b1": [ { "comment_text": "", "digests": { "md5": "5d7e3f556d614150acf35d785b6d629e", "sha256": "bb815e47d796cc378390849c93555a6f35b4d4d33ee5b82557683adc39fc460d" }, "downloads": -1, "filename": "collective.beaker-1.0b1.tar.gz", "has_sig": false, "md5_digest": "5d7e3f556d614150acf35d785b6d629e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10286, "upload_time": "2009-12-11T06:47:29", "url": "https://files.pythonhosted.org/packages/c3/42/5dd148024a012e57b8432445a610a8b7372fe18baa1607bda52a9eec6ac7/collective.beaker-1.0b1.tar.gz" } ], "1.0b2": [ { "comment_text": "", "digests": { "md5": "3dc7a00ab13c58f9014e0a60b1d3ef31", "sha256": "3b24411cce3df8697962cd2be010bc00d35130bf84d4b602617e5a23e9930182" }, "downloads": -1, "filename": "collective.beaker-1.0b2.tar.gz", "has_sig": false, "md5_digest": "3dc7a00ab13c58f9014e0a60b1d3ef31", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14020, "upload_time": "2010-01-23T15:57:24", "url": "https://files.pythonhosted.org/packages/03/b4/04967a0ea25425c507988cc29c645dd935e4e3ef5243ec5bdc5598671f77/collective.beaker-1.0b2.tar.gz" } ], "1.0b3": [ { "comment_text": "", "digests": { "md5": "ba0134e1552a4d5a265879c9141795da", "sha256": "34ab90c8792b46b8e62e5be94107645df812dcfb30867780e87e16937a5c6b4e" }, "downloads": -1, "filename": "collective.beaker-1.0b3.tar.gz", "has_sig": false, "md5_digest": "ba0134e1552a4d5a265879c9141795da", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13380, "upload_time": "2011-05-11T13:08:58", "url": "https://files.pythonhosted.org/packages/1e/1f/876804152a13cfeca47e01b6b13a6026f39139bd19fbe3f085196813c00f/collective.beaker-1.0b3.tar.gz" } ], "1.0b3dev-r239026": [ { "comment_text": "", "digests": { "md5": "f059d35d170429ba058a9ff03b0f751d", "sha256": "200458cdcc1a5cdae669f00cc0834eee2793f8c62c41b84bdd4e57aeaed70fef" }, "downloads": -1, "filename": "collective.beaker-1.0b3dev-r239026.tar.gz", "has_sig": false, "md5_digest": "f059d35d170429ba058a9ff03b0f751d", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13396, "upload_time": "2011-05-11T13:08:04", "url": "https://files.pythonhosted.org/packages/a5/ba/66d0fa7c70f6292d4a5e8065b07dcb7e26e81a4409324cf797a2dfe050c3/collective.beaker-1.0b3dev-r239026.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "ba0134e1552a4d5a265879c9141795da", "sha256": "34ab90c8792b46b8e62e5be94107645df812dcfb30867780e87e16937a5c6b4e" }, "downloads": -1, "filename": "collective.beaker-1.0b3.tar.gz", "has_sig": false, "md5_digest": "ba0134e1552a4d5a265879c9141795da", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13380, "upload_time": "2011-05-11T13:08:58", "url": "https://files.pythonhosted.org/packages/1e/1f/876804152a13cfeca47e01b6b13a6026f39139bd19fbe3f085196813c00f/collective.beaker-1.0b3.tar.gz" } ] }