Metadata-Version: 2.1
Name: eea.cache
Version: 9.5
Summary: Tools and config for memcache related caching
Home-page: https://github.com/collective/eea.cache
Author: European Environment Agency: IDM2 A-Team
Author-email: eea-edw-a-team-alerts@googlegroups.com
License: GPL
Download-URL: https://pypi.python.org/pypi/eea.cache
Keywords: EEA cache memcache Add-ons Plone Zope
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: Addon
Classifier: Framework :: Plone :: 4.3
Classifier: Framework :: Plone :: 5.2
Classifier: Framework :: Plone :: 6.0
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Description-Content-Type: text/x-rst
Provides-Extra: test

=========
EEA Cache
=========
.. image:: https://ci.eionet.europa.eu/buildStatus/icon?job=eea/eea.cache/develop&subject=develop
  :target: https://ci.eionet.europa.eu/job/eea/job/eea.cache/job/develop/display/redirect
  :alt: Develop
.. image:: https://ci.eionet.europa.eu/buildStatus/icon?job=eea/eea.cache/master&subject=master
  :target: https://ci.eionet.europa.eu/job/eea/job/eea.cache/job/master/display/redirect
  :alt: Master
.. image:: https://img.shields.io/github/v/release/eea/eea.cache
  :target: https://pypi.org/project/eea.cache/
  :alt: Release

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`_
* `pylibmc`_ (optional, for better performance)
* `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 InvalidateMemCacheEvent
    >>> from zope.event import notify
    >>> notify(InvalidateMemCacheEvent(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(InvalidateMemCacheEvent(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

varnish.invalidate
-------------------
In order to manually invalidate memcached cache per object this package
provides a browser view called **varnish.invalidate**.
It will invalidate all memcached methods associated with current object's UID::

    http://localhost:2020/Plone/front-page/varnish.invalidate

You can also manually invalidate related items and back references::

    http://localhost:2020/Plone/front-page/varnish.invalidate/relatedItems

    http://localhost:2020/Plone/front-page/varnish.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 varnish.invalidate::

    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

cache.settings
--------------
There is also a Cache Tab per object where you can manually select which cache
to invalidate. By default, you can invalidate memcache and varnish. You also
have the possibility to invalidate memcache and/or varnish for related items
and also fo back references.

This form can be extended with more options. For a more detailed
example see `eea.pdf`_

**configure.zcml**::

  <adapter
    zcml:condition="installed eea.cache"
    factory=".behavior.ExtraBehavior"
    />

  <adapter
    zcml:condition="installed eea.cache"
    factory=".behavior.ExtraSettings"
    name="eea.pdf.cache.extender"
    />

**behavior.py**::

  # Model
  class IExtraSettings(model.Schema):
      """ Extra settings
      """
      pdf = schema.Bool(
          title=_(u"PDF"),
          description=_(u"Invalidate latest generated PDF file"),
          required=False,
          default=False
      )


  # Behaviour
  class ExtraBehavior(object):
      implements(IExtraSettings)
      adapts(IPDFAware)

      def __init__(self, context):
          self.context = context

      @property
      def pdf(self):
          """ PDF
          """
          return False

      @pdf.setter
      def pdf(self, value):
          """ Invalidate last generated PDF?
          """
          if not value:
              return

          removePdfFiles()

  # Form
  class ExtraSettings(extensible.FormExtender):
      adapts(IPDFAware, ILayer, SettingsForm)

      def __init__(self, context, request, form):
          self.context = context
          self.request = request
          self.form = form

      def update(self):
          """ Extend form
          """
          self.add(IExtraSettings, prefix="extra")
          self.move('pdf', after='varnish', prefix='extra')


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: https://www.eea.europa.eu/
.. _`EEA Cache`: https://eea.github.io/docs/eea.cache
.. _`plone.recipe.zope2instance`: https://pypi.python.org/pypi/plone.recipe.zope2instance
.. _`eea.app.visualization`: https://eea.github.io/docs/eea.app.visualization
.. _`plone.memoize`: https://pypi.python.org/pypi/plone.memoize
.. _`pylibmc`: https://pypi.python.org/pypi/pylibmc
.. _`plone.uuid`: https://pypi.python.org/pypi/plone.uuid
.. _`python-memcached`: https://pypi.python.org/pypi/python-memcached
.. _`eea.pdf`: https://eea.github.io/docs/eea.pdf

Changelog
=========

9.5 - (2021-12-16)
---------------------------
* Change: Plone 6 / pip install ready. Drop includeDependencies
  [avoinea]

9.4 - (2020-03-10)
---------------------------
* Bug fix: avoid error when cache key contains utf-8 characters
  [ichim-dvaid refs #113458]

9.3 - (2020-03-04)
---------------------------
* Bug fix: Removed hard dependency on plone.app.caching: missing VARNISH.__name__
  [avoinea]

9.2 - (2019-12-13)
---------------------------
* Bug fix: Fix the uninstall profile
  [avoinea]

9.1 - (2019-11-21)
--------------------------
* Feature: Made all Dexterity content cache aware
  [avoinea refs #110155]
* Feature: Added support for Python 3 and Plone 5.2
  [alecghica refs #110155]

9.0 - (2019-06-06)
--------------------------
* Change: Cache decorator no longer caches empty results
  [ichim-david refs #104467]
* Feature: Cache decorator now has cache_empty parameter if it's set will
  still cache empty results
  [ichim-david refs #104467]

8.5 - (2019-01-28)
--------------------------
* Jenkins: Add sonarqube step
  [avoinea refs #101552]
* Change: updated URLs pointing to eea.europa.eu with https://
  [alecghica refs #95849]

8.4 - (2018-06-13)
--------------------------
* Bug fix: lambda takes no arguments (1 given)
  [avoinea]

8.3 - (2018-06-06)
--------------------------
* Bug fix: Fix relatedItems cache invalidation
  [avoinea refs #95891]

8.2 - (2018-05-24)
-----------------------
* Bug fix: Speed-up cache invalidation for backward-references
  [avoinea refs #95020]
* Feature: replaced invalidate_cache method with a method that use eea.cache
  [alecghica refs #95020]
* Feature: "Refresh this page" method redirect you back to the original context
  [alecghica refs #95020]
* Feature: cache.settings if called in a context of a default view it will
  also invalidate its parent
  [alecghica refs #95020]
* Bug fix: fixed case under all invalidate methods when a broken relations
  is present and None is found instead of an object
  [alecghica refs #95020]

8.1 - (2017-12-12)
------------------
* Change: Replace eeacms/zptlint with eeacms/plone-test:4 zptlint
  [avoinea refs #90415]

8.0 - (2017-11-07)
------------------
* Change: Remove Sphinx generated documentation
  [petchesi-iulian refs #88212]

7.9 - (2017-05-22)
------------------
* Change: fixed PyLint warnings and errors
  [valipod refs #84949]

7.8 - (2017-05-15)
------------------
* Change: fixed PyLint warnings and errors
  [eduard-fironda refs #84949]

7.7 - (2017-04-24)
------------------
* Change: updated package information
  [eduard-fironda]

7.6 - (2016-05-19)
------------------
* Bug fix: Fix pylint warnings
  [chiridra refs #71940]

7.5 - (2015-08-18)
------------------
* Change: Auto-include zcml within plone context in order to make this package
  work without having to add it within buildout zcml directive.
  [avoinea]
* Feature: Implemented support for pylibmc
  [razvanchitu refs #27571]

7.4 - (2015-03-17)
------------------
* Change: Switched to curl in the jenkins build install script
  [olimpiurob refs #22402]
* Change: Changed fetch url for jenkins build install script to the install
  script from the main EEA CPB repository
  [olimpiurob refs #22402]

7.3 - (2014-12-23)
------------------
* Bug fix: fixed libevent download made by the buildout
  [ghicaale refs #21453]

7.2 - (2014-11-20)
------------------
* Change: Added InvalidateEverything event to be able to invalidate memcache and
  varnish instead of adding subscribers on ObjectModifiedEvent
  [voineali refs #21852, #21850, #21851]
* Change: Migrate cache invalidation form to plone.z3cform in order to easily
  extend it outside this package
  [voineali refs #21630]

7.1 - (2014-10-01)
------------------
* Feature: invalidate Memcache now appear on cache form as one of the options.
  [ghicaale refs #21143]
* Feature: created handler to invalidate only Varnish.
  [ghicaale refs #21143]
* Feature: improved result messages.
  [ghicaale refs #21143]

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


