Metadata-Version: 1.1
Name: eea.cache
Version: 7.0
Summary: Tools and config for memcache related caching
Home-page: http://eea.github.com/docs/eea.cache
Author: Alin Voinea (Eau de Web)
Author-email: alin@eaudeweb.ro
License: GPL
Download-URL: http://pypi.python.org/pypi/eea.cache
Description: =========
        EEA Cache
        =========
        .. image:: http://ci.eionet.europa.eu/job/eea.cache-www/badge/icon
          :target: http://ci.eionet.europa.eu/job/eea.cache-www/lastBuild
        .. image:: http://ci.eionet.europa.eu/job/eea.cache-plone4/badge/icon
          :target: http://ci.eionet.europa.eu/job/eea.cache-plone4/lastBuild
        
        Introduction
        ============
        
        This package combines the features from lovely.memcached and plone.memoize.ram.
        It provides a decorator and utility for Memcaches at EEA.
        The decorator allows you set dependencies known by eea.cache
        
        .. note ::
        
          This add-on doesn't do anything by itself. It needs to be integrated by a
          developer within your own products. For reference you can check
          the `eea.app.visualization`_ package.
        
        Contents
        ========
        
        .. contents::
        
        Main features
        =============
        
        1. Extends and overrides plone.memoize cache adapters to work with memcache
        2. Provides an extended @cache decorator that supports:
        
           * cache lifetime override per method
           * dependencies string in order to bulk invalidate cache
           * auto-invalidation of cache when ObjectModifiedEvent is triggered
        
        3. Possibility to manually invalidate cache via URL.
        
        Install
        =======
        
        * Add eea.cache to your eggs and zcml section in your buildout and re-run buildout::
        
            eggs =
              ...
              eea.cache
        
            zcml =
              ...
              eea.cache
              eea.cache-overrides
        
        * You can download a sample buildout from https://github.com/eea/eea.cache/tree/master/buildouts/plone4
        * Install eea.cache within Site Setup > Add-ons
        * Start memcache::
        
          $ bin/memcached start
        
        Dependencies
        ============
        
        * `python-memcached`_
        * `plone.memoize`_
        * `plone.uuid`_
        
        
        Source code
        ===========
        
        Latest source code (Zope 2 compatible):
          * `Plone Collective on Github <https://github.com/collective/eea.cache>`_
          * `EEA on Github <https://github.com/eea/eea.cache>`_
        
        
        Cache decorator
        ===============
        
        ::
        
            >>> def key(method, self):
            ...     return method.__name__
        
            >>> from eea.cache import cache
            >>> @cache(key, dependencies=["frontpage"])
            ... def myMethod(num):
            ...     return num*num
        
        Lets clear any running memcache::
        
            >>> from eea.cache.event import InvalidateCacheEvent
            >>> from zope.event import notify
            >>> notify(InvalidateCacheEvent(raw=True, dependencies=['frontpage']))
        
        Our myMethod will now be cached with the key returned from the method 'key' and
        with dependency 'frontpage'::
        
            >>> myMethod(2)
            4
            >>> myMethod(3)
            4
        
            >>> notify(InvalidateCacheEvent(raw=True, dependencies=['frontpage']))
            >>> myMethod(3)
            9
        
        Cache lifetime
        ==============
        By default your content is cached in memcache for one hour (3600 seconds). You
        can change this by adding an **int** property within: ZMI > portal_properties >
        site_properties called **memcached_defaultLifetime** and set it's value to
        **86400** (one day) for example.
        
        
        Cache lifetime override per key
        -------------------------------
        
        Starting with eea.cache 5.1 you can also pass a lifetime key with the duration
        in seconds which will override the defaultLifetime either given from the
        portal property or the default one from lovely.memcached of 3600 seconds::
        
            ex: in order to cache the result only for 4 minutes
            >>> @cache(key, dependencies=["frontpage"], lifetime=240)
            ... def myMethod(num):
            ...     return num*num
        
        
        Invalidate cache
        ================
        If you use cache decorator for BrowserView methods or directly on Zope objects
        methods cache will be **automatically invalidated** when object is modified
        (ObjectModifiedEvent is triggered)::
        
            >>> from Products.Five.browser import BrowserView
        
            >>> class XXX(BrowserView):
            ...     @cache(key)
            ...     def title(self):
            ...         return self.context.title_or_id()
        
        You can disable auto invalidation by providing the auto_invalidate param to @cache
        decorator::
        
            >>> @cache(key, auto_invalidate=False)
            ... def title(self):
            ...     return self.context.title_or_id()
        
        memcache.invalidate
        -------------------
        In order to manually invalidate memcached cache per object this package
        provides a browser view called **memcache.invalidate**.
        It will invalidate all memcached methods associated with current object's UID::
        
            http://localhost:2020/Plone/front-page/memcache.invalidate
        
        You can also manually invalidate related items and back references::
        
            http://localhost:2020/Plone/front-page/memcache.invalidate/relatedItems
        
            http://localhost:2020/Plone/front-page/memcache.invalidate/backRefs
        
        By default this method can be called by users with these roles:
        
        * Editor
        * CommonEditor
        * Owner
        * Manager
        
        cache.invalidate
        ----------------
        In order to manually invalidate cache (memcached and varnish) per object this
        package provides a browser view called **cache.invalidate**.
        It will call memcache.invalidate and also notify Purge event for varnish::
        
            http://localhost:2020/Plone/front-page/cache.invalidate
        
        You can also manually invalidate related items and back references::
        
            http://localhost:2020/Plone/front-page/cache.invalidate/relatedItems
        
            http://localhost:2020/Plone/front-page/cache.invalidate/backRefs
        
        By default this method can be called by users with these roles:
        
        * Editor
        * CommonEditor
        * Owner
        * Manager
        
        
        Copyright and license
        =====================
        The Initial Owner of the Original Code is European Environment Agency (EEA).
        All Rights Reserved.
        
        The eea.cache (the Original Code) is free software;
        you can redistribute it and/or modify it under the terms of the GNU
        General Public License as published by the Free Software Foundation;
        either version 2 of the License, or (at your option) any later
        version.
        
        More details under docs/License.txt
        
        
        Funding and project management
        ==============================
        
        EEA_ - European Environment Agency (EU)
        
        .. _EEA: http://www.eea.europa.eu/
        .. _`EEA Cache`: http://eea.github.com/docs/eea.cache
        .. _`plone.recipe.zope2instance`: http://pypi.python.org/pypi/plone.recipe.zope2instance
        .. _`eea.app.visualization`: http://eea.github.com/docs/eea.app.visualization
        .. _`plone.memoize`: http://pypi.python.org/pypi/plone.memoize
        .. _`plone.uuid`: http://pypi.python.org/pypi/plone.uuid
        .. _`python-memcached`: http://pypi.python.org/pypi/python-memcached
        
        Changelog
        =========
        
        7.0 - (2014-08-27)
        ------------------
        * Upgrade step: Within "Plone > Site setup > Add-ons" install EEA Cache
          [voineali refs #20678]
        * Pre-upgrade-step: Also add eea.cache within buildout zcml directive before
          eea.cache-overrides
          [voineali refs #20678]
        * Feature: Added a browser view called **cache.invalidate** that allows
          editors to manually invalidate cache (including varnish and memcache). It
          also supports invalidation for related-items and back-references
          [voineali refs #20678]
        * Feature: Added a browser view called **memcache.invalidate** that allows
          users to manually invalidate memcache. It also supports
          invalidation of relatedItems and back-references memcache
          [voineali refs #20678]
        * Change: Auto-invalidate all cache associated with current object's UID when
          ObjectModifiedEvent is triggered
          [voineali refs #20678]
        
        6.3 - (2014-01-21)
        ------------------
        * Bug fix: removed wrongly added blockquotes within README.rst
          [ichim-david refs #18064]
        * Feature: adding Sphinx-generated documentation in Page Template format
          [batradav refs #9502]
        
        6.2 - (2013-10-04)
        ------------------
        * Change: updated zope imports with the versions that require minimum Plone 4.1
          for eea.cache
          [ichimdav refs #15651]
        
        6.1 - (2013-06-17)
        ------------------
        * Cleanup: Use logger.debug instead of logger.info for debug messages
          [avoinea]
        
        6.0 - (2013-05-20)
        ------------------
        * Feature: Removed lovely.memcached dependency
          [voineali refs #14343]
        
        5.1 - (2013-02-04)
        ------------------
        * Feature: added information for contributors
          [ciobabog refs #13892]
        * Feature: added ability to pass a lifetime key to the cache decorator in
          order to cache it for a determined period different from the default lifetime
          [ichimdav #13677]
        * Upgrade step: (optional)
          Within ZMI > portal_properties > site_properties add an **int** property
          called **memcached_defaultLifetime** and set it's value to
          **86400** (one day) or any value that fits your needs.
        * Feature: Ability to set memcached default lifetime, which by now was hardcoded
          to one hour (3600 seconds)
          [voineali refs #13677]
        
        5.0 - (2012-10-08)
        ------------------
        * Change: Updated README and egg's metadata
          [voineali refs #5434]
        
        4.3 - (2012-07-13)
        ------------------
        * Bug fix: fixed markup of HISTORY.txt file
          [ciobabog refs #5231]
        
        4.2 - (2012-02-06)
        ------------------
         * no changes
        
        4.0 - (2011-11-07)
        ------------------
        * Feature: Plone 4.x compatible release
          [ghicaale #4309]
        
        0.3 - (2010-11-22)
        ------------------
        * Bug fix: fixed tests namespace in order to be used within hudson
          [voineali #3821]
        
        0.2 - (2010-11-10)
        ------------------
        * Bug fix: added fake memcache client in order to fix broken doctests
          [voineali]
        
        0.1 - (2009-11-10)
        ------------------
        * Initial release
        
        
Keywords: eea cache memcache
Platform: UNKNOWN
Classifier: Framework :: Zope2
Classifier: Framework :: Zope3
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 4.0
Classifier: Framework :: Plone :: 4.1
Classifier: Framework :: Plone :: 4.2
Classifier: Programming Language :: Zope
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: License :: OSI Approved :: Mozilla Public License 1.0 (MPL)
