{
    "info": {
        "author": "Wichert Akkerman",
        "author_email": "zope-dev@zope.org",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 5 - Production/Stable",
            "Environment :: Web Environment",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: Zope Public License",
            "Programming Language :: Python :: 2",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: 3.8",
            "Programming Language :: Python :: Implementation :: CPython",
            "Programming Language :: Python :: Implementation :: PyPy",
            "Topic :: Software Development :: Libraries :: Python Modules"
        ],
        "description": "Introduction\n============\n\nCaching of web pages is a complicated process: there are many possible\npolicies to choose from, and the right policy can depend on factors such as\nwho is making the request, the URL is being retrieved and resource\nnegotiation settings such as accepted languages and encodings,\n\nHardcoding caching logic in an application is not desirable, especially for\nreusable code. It is also not possible to allow an administrator to manually\nconfigure the caching headers for every resource in an application. This\npackages tries to address this problem by providing a cache ruleset\nframework: it allows implementors to specify a ruleset for every component.\nAdministrators can then define a policy which dictates the correct caching\nbehaviour for each ruleset.\n\nDepending on your environment there are different options for turning\nthe ruleset into HTTP caching headers.\n\n* If you are using Plone_ 3 and CacheFu_ you can use `five.caching`_ to\n  integrate with CacheSetup.\n* If you are using Zope 2.12 or later, you can use `plone.caching`_ to\n  integrate with the publisher events and `plone.cachepurging`_ if you require\n  support for ``PURGE`` requests.\n* If you are using Plone 4, you can also use `plone.app.caching`_, which\n  provides UI and default behaviour for `plone.caching`_ and\n  `plone.cachepurging`_.\n* In a WSGI environment you could set the ruleset in `environ` or a response\n  header and add a piece of middleware which acts on those hints.\n\nUsage\n=====\n\nYou can register rulesets using either ZCML or directly in python. If you\nuse ZCML you can use the ``<cache:ruleset />`` directive::\n\n  <configure\n      xmlns=\"http://namespaces.zope.org/zope\"\n      xmlns:browser=\"http://namespaces.zope.org/browser\"\n      xmlns:cache=\"http://namespaces.zope.org/cache\"/>\n\n    <include package=\"z3c.caching\" file=\"meta.zcml\" />\n\n    <cache:rulesetType\n        name=\"plone.contentTypes\"\n        title=\"Plone content types\"\n        description=\"Non-folderish content types\"\n        />\n\n    <cache:ruleset\n        for=\".frontpage.FrontpageView\"\n        ruleset=\"plone.contentTypes\"\n        />\n\n    <browser:page\n        for=\"..interfaces.IFrontpage\"\n        class=\".frontpage.FrontpageView\"\n        name=\"frontpage_view\"\n        template=\"templates/frontpage_view.pt\"\n        permission=\"zope2.View\" />\n\n  </configure>\n\nThis example sets up a browser view called ``frontpage_view`` and\nassociates it with the ``plone.contentTypes`` ruleset.\n\n**NOTE:** Ruleset names should be *dotted names*. That is, they should consist\nonly of upper or lowercase letters, digits, underscores and/or periods (dots).\nThe idea is that this forms a namespace similar to namespaces created by\npackages and modules in Python.\n\nYou can specify either a class or an interface in the ``for`` attribute. As\nwith an adapter registration, a more specific registration can be used to\noverride a more generic one.\n\nAbove, we also add some metadata about the type of ruleset using the\n``<cache:rulesetType />`` directive. This is principally useful for UI support\nand can be often be skipped.\n\nIf you prefer to use python directly you can do so::\n\n   from z3c.caching.registry import register\n   from frontpage import FrontpageView\n\n   register(FrontpageView, \"plone.contentTypes\")\n\nTo find the ruleset for an object use the ``lookup()`` method::\n\n   from z3c.caching.registry import lookup\n   cacheRule = lookup(FrontpageView)\n\nTo declare the ruleset type metadata, use the ``declareType`` method::\n\n   from z3c.caching.registry import declareType\n   declareType = declareType(name=\"plone.contentTypes\", \\\n                             title=u\"Plone content types\", \\\n                             description=u\"Non-folderish content types\")\n\nIf you want to get a list of all declared types, use the ``enumerateTypes()``\nmethod::\n\n    from z3c.caching.registry import enumerate\n    for type_ in enumerateTypes():\n        ...\n\nThe ``type_`` object provides ``IRulesetType`` and has attributes for\n``name``, ``title`` and ``description``.\n\nStrict mode\n-----------\n\nBy default, you are not required to declare the type of a ruleset before using\nit. This is convenient, but increases the risk of typos or a proliferation of\nrulesets that are semantically equivalent. If you want to guard against this\ncase, you can put the ruleset into explicit mode, like this::\n\n    from z3c.caching.registry import setExplicitMode\n    setExplicitMode(True)\n\nInformation about cacheable resources\n=====================================\n\nThis package is intentionally simple, and depends only on a small set of core\nZope Toolkit packages. However, real-world caching often requires specific\ninformation about published (and potentially cacheable) resources, such as\nwhen the underlying resource was last modified, and which URLs to purge if\nthe caching proxy needs to be purged.\n\n``z3c.caching`` aims to be a \"safe\" and minimalist dependency for packages\nwhich want to declare how they can be cached. Hence, whilst the implementation\nof such things as setting cache control response headers and supporting\npurging of a caching reverse proxy are left up to other packages,\n``z3c.caching`` provides a few interfaces which \"caching-aware\" packages can\nimplement, for higher level frameworks (such as `plone.caching`_ and\n`plone.cachepurging`_) to rely on. This avoids a direct dependency between\nsuch packages and those higher level frameworks.\n\nThese interfaces are described below. A few helper components are also\nprovided. To configure them, you can include ``z3c.caching``'s ZCML\nconfiguration::\n\n    <include package=\"z3c.caching\" />\n\nLast modified date/time\n-----------------------\n\nThe ``ILastModified`` adapter interface can be used to describe the last\nmodified date of a given published object::\n\n    class ILastModified(Interface):\n        \"\"\"An abstraction to help obtain a last-modified date for a published\n        resource.\n\n        Should be registered as an unnamed adapter from a published object\n        (e.g. a view).\n        \"\"\"\n\n        def __call__():\n            \"\"\"Return the last-modified date, as a Python datetime object.\n\n            The datetime returned must be timezone aware and should normally\n            be in the local timezone.\n\n            May return None if the last modified date cannot be determined.\n            \"\"\"\n\nOne implementation for this interface is provided by default: When looked up\nfor a Zope browser view, it will delegate to an ``ILastModified`` adapter on\nthe view's context. Higher level packages may choose to implement this adapter\nfor other types of publishable resources, and/or different types of view\ncontext.\n\nCache purging\n-------------\n\nHigh-traffic sites often put a caching proxy such as `Squid`_ or `Varnish`_\nin front of the web application server to offload the caching of resources.\nSuch proxies can be controlled via response headers (perhaps set via caching\noperations looked up based on ``z3c.caching`` rulesets). Most caching proxies\nalso support so-called ``PURGE`` requests, where the web application sends a\nrequest directly to the caching proxy asking it to purge (presumably old)\ncopies it may hold of a resource (e.g. because that resource has changed).\n\nThis package does not implement any communication with caching proxies. If\nyou need that in a Zope 2 context, consider `plone.cachepurging`_. However,\na few components are included to help packages declare their behaviour in\nrelation to a caching proxy that supports purging.\n\nFirstly, ``z3.caching`` defines a ``Purge`` event, described the interface\n``z3c.caching.interfaces.IPurgeEvent``::\n\n    class IPurgeEvent(IObjectEvent):\n        \"\"\"Event which can be fired to purge a particular object.\n\n        This event is not fired anywhere in this package. Instead, higher level\n        frameworks are expected to fire this event when an object may need to be\n        purged.\n\n        It is safe to fire the event multiple times for the same object. A given\n        object will only be purged once.\n        \"\"\"\n\nIf an object has been changed so that it may need to be purged, you can fire\nthe event, like so::\n\n    from z3c.caching.purge import Purge\n    from zope.event import notify\n\n    notify(Purge(context))\n\nA higher level framework such as `plone.cachepurging`_ can listen to this\nevent to queue purge requests for the object.\n\nOf course, the most common reason to purge an object's cached representations\nis that it has been modified or removed. ``z3c.caching`` provides event\nhandlers for the standard ``IObjectModifiedEvent``, ``IObjectMovedEvent`` and\n``IObjectRemovedEvent`` events, which re-broadcasts a ``Purge`` event for\nthe modified/moved/removed object.\n\nTo opt into these event handlers, simply mark your content object with the\n``IPurgeable`` interface, e.g.::\n\n    from z3c.caching.interfaces import IPurgeable\n\n    class MyContent(Persistent):\n        implements(IPurgeable)\n\n        ...\n\nYou can also do this declaratively in ZCML, even for classes not under your\ncontrol::\n\n    <class class=\".content.MyContent\">\n        <implements interface=\"z3c.caching.interfaces.IPurgeable\" />\n    </class>\n\nThese helpers can signal to a framework like `plone.cachepurging`_ that the\nobject needs to be purged, but this is not enough to know how to construct\nthe ``PURGE`` request. The caching proxy also needs to be told which path or\npaths to purge. This is the job of the ``IPurgePaths`` adapter interface::\n\n    class IPurgePaths(Interface):\n        \"\"\"Return paths to send as PURGE requests for a given object.\n\n        The purging hook will look up named adapters from the objects sent to\n        the purge queue (usually by an IPurgeEvent being fired) to this interface.\n        The name is not significant, but is used to allow multiple implementations\n        whilst still permitting per-type overrides. The names should therefore\n        normally be unique, prefixed with the dotted name of the package to which\n        they belong.\n        \"\"\"\n\n        def getRelativePaths():\n            \"\"\"Return a list of paths that should be purged. The paths should be\n            relative to the virtual hosting root, i.e. they should start with a\n            '/'.\n\n            These paths will be rewritten to incorporate virtual hosting if\n            necessary.\n            \"\"\"\n\n        def getAbsolutePaths():\n            \"\"\"Return a list of paths that should be purged. The paths should be\n            relative to the  domain root, i.e. they should start with a '/'.\n\n            These paths will *not* be rewritten to incorporate virtual hosting.\n            \"\"\"\n\nThe difference between the \"relative\" and \"absolute\" paths only comes into\neffect if virtual hosting is used. In most cases, you want to implement\n``getRelativePaths()`` to return a path that is relative to the current\nvirtual hosting root. In Zope 2, you can get this via the\n``absolute_url_path()`` function on any traversable item. Alternatively,\nyou can look up an ``IAbsoluteURL`` adapter and discard the domain portion.\n\n``getAbsolutePaths()`` is mainly useful for paths that are \"special\" to the\ncaching proxy. For example, you could configure Varnish to purge the entire\ncache when sending a request to ``/_purge_all``, and then implement\n``getAbsolutePaths()`` to return an iterable with that string in it.\n\nHere is the default implementation from `plone.cachepurging`_, which purges\nthe default path of an object derived from Zope 2's ``OFS.Traversable``::\n\n    class TraversablePurgePaths(object):\n        \"\"\"Default purge for OFS.Traversable-style objects\n        \"\"\"\n\n        implements(IPurgePaths)\n        adapts(ITraversable)\n\n        def __init__(self, context):\n            self.context = context\n\n        def getRelativePaths(self):\n            return [self.context.absolute_url_path()]\n\n        def getAbsolutePaths(self):\n            return []    \n\nIn ZCML, this is registered as::\n\n    <adapter factory=\".paths.TraversablePurgePaths\" name=\"default\" />\n\nThe Plone-specific `plone.app.caching` implements further adapters (with \nother, unique names) for things like the default view method alias (``/view``)\nand downloadable paths for Archetypes image and file fields.\n\n.. _Plone: http://plone.org/\n.. _CacheFu: http://plone.org/products/cachefu\n.. _five.caching: http://pypi.python.org/pypi/five.caching\n.. _plone.caching: http://pypi.python.org/pypi/plone.caching\n.. _plone.cachepurging: http://pypi.python.org/pypi/plone.cachepurging\n.. _plone.app.caching: http://pypi.python.org/pypi/plone.app.caching\n.. _Squid: http://squid-cache.org\n.. _Varnish: http://varnish-cache.org\n\n\nChangelog\n=========\n\n\n2.2 (2019-10-16)\n----------------\n\n- Fix DeprecationWarnings: import moves from ``zope.component`` to ``zope.interface``.\n  Depend on zope.interface >= 3.8.0.\n  [jensens]\n\n- Add support for Python 3.8a3.\n  [icemac]\n\n2.1 (2018-11-06)\n----------------\n\n- Changed ruleset of IRuleset to TextLine to work with\n  `zope.configuration >= 4.2`. See\n  `Products.CMFPlone#2591 <https://github.com/plone/Products.CMFPlone/issues/2591>`_.\n  [pbauer]\n\n\n2.0 (2018-03-22)\n----------------\n\n* Added support for Python 3.5, 3.6, 3.7, PyPy2 and PyPy3.\n  [icemac]\n\n\n2.0a1 - April 22, 2010\n----------------------\n\n* Added `Purge`` event and ``IPurgeable` and ``IPurgePaths`` interfaces.\n  Although this package doesn't provide any purging support, it is convenient\n  to keep the interfaces necessary for other packages to describe their cache\n  purging behaviour here. This allows a relatively harmless dependency on\n  z3c.caching, even in generic code, as distinct from a higher-level,\n  application server specific framework.\n  [optilude]\n\n* Added concept of an explicitly declare ruleset type. Optional by default,\n  but can be made required by setting `explicit` to `True`.\n  [optilude]\n\n* Added ``ILastModified`` implementation for a view which delegates to the\n  view's context.\n  [optilude]\n\n* Added ``enumerateTypes()`` method to the registry, used to list all currently\n  used cache rule ids.\n  [optilude]\n\n* Made the registry use the ZCA more directly.\n  [matthewwilkes]\n\n\n1.0b1 - October 15, 2008\n------------------------\n\n* Initial release\n  [wichert]\n\n\n\n\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/zopefoundation/z3c.caching",
        "keywords": "zope caching",
        "license": "ZPL",
        "maintainer": "",
        "maintainer_email": "",
        "name": "z3c.caching",
        "package_url": "https://pypi.org/project/z3c.caching/",
        "platform": "",
        "project_url": "https://pypi.org/project/z3c.caching/",
        "project_urls": {
            "Homepage": "https://github.com/zopefoundation/z3c.caching"
        },
        "release_url": "https://pypi.org/project/z3c.caching/2.2/",
        "requires_dist": [
            "setuptools",
            "zope.interface (>=3.8.0)",
            "zope.component",
            "zope.event",
            "zope.lifecycleevent",
            "zope.browser",
            "zope.configuration ; extra == 'zcml'"
        ],
        "requires_python": "",
        "summary": "Caching infrastructure for web apps",
        "version": "2.2"
    },
    "last_serial": 5981437,
    "releases": {
        "1.0b1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cc36a2b679be468ad82f80d50185d545",
                    "sha256": "740051c31a040bced37cb11519ee256bb54eb8de3fd1c3ff5200e55c820bd396"
                },
                "downloads": -1,
                "filename": "z3c.caching-1.0b1.zip",
                "has_sig": false,
                "md5_digest": "cc36a2b679be468ad82f80d50185d545",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 11341,
                "upload_time": "2008-10-15T11:06:57",
                "url": "https://files.pythonhosted.org/packages/75/96/df000cfe249d05f9f158560265e8f8e589b52c56c64be570505cb0494db2/z3c.caching-1.0b1.zip"
            }
        ],
        "2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "0fe900690cec4dcb7ca471224a93248c",
                    "sha256": "948813aaf7ad1b72a20aac5929e71109c753aa7c1fa2c143ba512f0448dcca10"
                },
                "downloads": -1,
                "filename": "z3c.caching-2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "0fe900690cec4dcb7ca471224a93248c",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20203,
                "upload_time": "2018-03-22T13:06:49",
                "url": "https://files.pythonhosted.org/packages/b8/f1/3df95f0b404909797d741a6fc1da338d600556415473d9fc6030ad15cb5b/z3c.caching-2.0.tar.gz"
            }
        ],
        "2.0a1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "17f250b5084c2324a7d15c6810ee628e",
                    "sha256": "ff75ba246d59227bd5d90f038dded04ac82bad4af43954994c8109d9dfb66931"
                },
                "downloads": -1,
                "filename": "z3c.caching-2.0a1.tar.gz",
                "has_sig": false,
                "md5_digest": "17f250b5084c2324a7d15c6810ee628e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 19893,
                "upload_time": "2010-04-22T11:25:31",
                "url": "https://files.pythonhosted.org/packages/fc/eb/b2e37787e674637f30fa63ca867db2568d75ad8b52c8318b7dafe3d633d0/z3c.caching-2.0a1.tar.gz"
            }
        ],
        "2.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8b0f989cb1e7c689fbe3490e94d62999",
                    "sha256": "e4e5b7d5fad8f4ebb2ff04a7f4307d8f35caadd16fb9271b03bd166d8079f8ea"
                },
                "downloads": -1,
                "filename": "z3c.caching-2.1-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "8b0f989cb1e7c689fbe3490e94d62999",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 25232,
                "upload_time": "2018-11-06T06:51:36",
                "url": "https://files.pythonhosted.org/packages/a9/9c/c861f3970004d04ac4a8baf127f3d1a0e63dd24a65761ab4f46b93871cee/z3c.caching-2.1-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "4bfd8130958390fa05666a956c26a4c0",
                    "sha256": "ef7d0735e3fe101b72bd25afa8137fb020c276c4e8b4a17f8270b43d537e74f1"
                },
                "downloads": -1,
                "filename": "z3c.caching-2.1.tar.gz",
                "has_sig": false,
                "md5_digest": "4bfd8130958390fa05666a956c26a4c0",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20455,
                "upload_time": "2018-11-06T06:51:38",
                "url": "https://files.pythonhosted.org/packages/c1/88/5b55255a45dafcb4cf2dcd837578b18632c785ba87201dd8d88d2bfccede/z3c.caching-2.1.tar.gz"
            }
        ],
        "2.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "24513d2a14709e8c6097e0c59f8ffeac",
                    "sha256": "ced307be6e2d37546f0cfd1bfb834c79ec08983dd17041e9dd342159e9379927"
                },
                "downloads": -1,
                "filename": "z3c.caching-2.2-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "24513d2a14709e8c6097e0c59f8ffeac",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 20465,
                "upload_time": "2019-10-16T06:13:44",
                "url": "https://files.pythonhosted.org/packages/69/1a/bff6e4a74ce2c5bdd6d723dba1edf40361129a8b7469891717fd9a69df33/z3c.caching-2.2-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "e809e88293145a4352bba2a2a64563df",
                    "sha256": "e6f9903faca77c7fc571ea35e31ce511dcb4652b1f383241aa2b2a7f559b6d4a"
                },
                "downloads": -1,
                "filename": "z3c.caching-2.2.tar.gz",
                "has_sig": false,
                "md5_digest": "e809e88293145a4352bba2a2a64563df",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20849,
                "upload_time": "2019-10-16T06:13:47",
                "url": "https://files.pythonhosted.org/packages/0c/21/2ff1e3033a3293ed3eb7b56a9a765035be99ce430fb3be7120b3e89dc358/z3c.caching-2.2.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "24513d2a14709e8c6097e0c59f8ffeac",
                "sha256": "ced307be6e2d37546f0cfd1bfb834c79ec08983dd17041e9dd342159e9379927"
            },
            "downloads": -1,
            "filename": "z3c.caching-2.2-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "24513d2a14709e8c6097e0c59f8ffeac",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 20465,
            "upload_time": "2019-10-16T06:13:44",
            "url": "https://files.pythonhosted.org/packages/69/1a/bff6e4a74ce2c5bdd6d723dba1edf40361129a8b7469891717fd9a69df33/z3c.caching-2.2-py2.py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "e809e88293145a4352bba2a2a64563df",
                "sha256": "e6f9903faca77c7fc571ea35e31ce511dcb4652b1f383241aa2b2a7f559b6d4a"
            },
            "downloads": -1,
            "filename": "z3c.caching-2.2.tar.gz",
            "has_sig": false,
            "md5_digest": "e809e88293145a4352bba2a2a64563df",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 20849,
            "upload_time": "2019-10-16T06:13:47",
            "url": "https://files.pythonhosted.org/packages/0c/21/2ff1e3033a3293ed3eb7b56a9a765035be99ce430fb3be7120b3e89dc358/z3c.caching-2.2.tar.gz"
        }
    ]
}