Metadata-Version: 1.1
Name: django-ultracache
Version: 0.3.3
Summary: Drop-in replacement for Django's template fragment caching. Provides automatic cache invalidation.
Home-page: http://github.com/praekelt/django-ultracache
Author: Praekelt Consulting
Author-email: dev@praekelt.com
License: BSD
Description: Django Ultracache
        =================
        **Drop-in replacement for Django's template fragment caching. Provides automatic Django cache invalidation and reverse caching proxy purging.**
        
        .. figure:: https://travis-ci.org/praekelt/django-ultracache.svg?branch=develop
           :align: center
           :alt: Travis
        
        .. contents:: Contents
            :depth: 5
        
        Installation
        ------------
        
        #. Install or add ``django-ultracache`` to your Python path.
        
        #. Add ``ultracache`` to your ``INSTALLED_APPS`` setting.
        
        #. Ensure ``django.core.context_processors.request`` is in ``TEMPLATE_CONTEXT_PROCESSORS`` setting.
        
        Usage
        -----
        
        ``django-ultracache`` provides a template tag ``{% ultracache %}`` that functions like Django's
        standard cache template tag, with these exceptions.
        
        #. It takes the sites framework into consideration, allowing different caching per site.
        
        #. It allows undefined variables to be passed as arguments, thus simplifying the template.
        
        #. Crucially, it is aware of model objects that are subjected to its caching. When an object is modified
           all affected cache key are automatically expired. This allows the user to set longer expiry times without having
           to worry about stale content.
        
        #. The cache invalidation can be extended to issue purge commands to Varnish, Nginx or other reverse caching proxies.
        
        Simplest use case::
        
            {% load ultracache_tags %}
            {% ultracache 3600 'my_identifier' object 123 undefined 'string' %}
                {{ object.title }}
            {% endultracache %}
        
        The tag can be nested. ``ultracache`` is aware of all model objects that are subjected to its caching.
        In this example cache keys ``outer`` and ``inner_one`` are expired when object one is changed but
        cache key ``inner_two`` remains unaffected::
        
            {% load ultracache_tags %}
            {% ultracache 1200 'outer' %}
                {% ultracache 1200 'inner_one' %}
                    title = {{ one.title }}
                {% endultracache %}
                {% ultracache 1200 'inner_two' %}
                    title = {{ two.title }}
                {% endultracache %}
            {% endultracache %}
        
        ``django-ultracache`` also provides a decorator ``cached_get`` to cache your views. The parameters
        follow the same rules as the ``ultracache`` template tag except they must all resolve. ``request.get_full_path()`` is
        always implicitly added to the cache key::
        
            from ultracache.decorators import cached_get
        
        
            class CachedView(TemplateView):
                template_name = "ultracache/cached_view.html"
        
                @cached_get(300, "request.is_secure()", 456)
                def get(self, *args, **kwargs):
                    return super(CachedView, self).get(*args, **kwargs)
        
        The ``cached_get`` decorator can be used in an URL pattern::
        
            from ultracache.decorators import cached_get
        
            url(
                r"^cached-view/$",
                cached_get(3600)(TemplateView.as_view(
                    template_name="myproduct/template.html"
                )),
                name="cached-view"
            )
        
        Do not indiscriminately use the ``cached_get`` decorator. It only ever operates on GET requests
        but cannot know if the code being wrapped retrieves data from eg. the session. In such a case
        it will cache things it is not supposed to cache.
        
        You can create custom reverse caching proxy purgers. See ``purgers.py`` for examples::
        
            ULTRACACHE = {
                'purge': {'method': 'myproduct.purgers.squid'}
            }
        
        Automatic invalidation defaults to true. To disable automatic invalidation set::
        
            ULTRACACHE = {
                'invalidate': False
            }
        
        How does it work?
        -----------------
        
        ``django-ultracache`` monkey patches ``django.template.base.Variable._resolve_lookup`` to make a record of
        model objects as they are resolved. The ``ultracache`` template tag inspects the list of objects contained
        within it and keeps a registry in Django's caching backend. A ``post_save`` signal handler monitors objects
        for changes and expires the appropriate cache keys.
        
        Tips
        ----
        
        #. If you arre running a cluster of Django nodes then ensure that they use a shared caching backend.
        
        #. Expose objects in your templates. Instead of passing ``object_title`` to a template rather have the
           template dereference ``object.title``.
        
        Authors
        =======
        
        Praekelt Consulting
        -------------------
        * Hedley Roos
        
        Changelog
        =========
        
        0.3.3
        -----
        #. Handle case where one cached view renders another cached view inside it, thus potentially sharing the same cache key.
        
        0.3.2
        -----
        #. The `ultracache` template tag now only caches HEAD and GET requests.
        
        0.3.1
        -----
        #. Trivial release to work around Pypi errors of the day.
        
        0.3
        ---
        #. Replace `cache.get` in for loop with `cache.get_many`.
        
        0.2
        ---
        #. Do not automatically add `request.get_full_path()` if any of `request.get_full_path()`, `request.path` or `request.path_info` is an argument for `cached_get`.
        
        0.1.6
        -----
        #. Also cache response headers.
        
        0.1.5
        -----
        #. Explicitly check for GET and HEAD request method and cache only those requests.
        
        0.1.4
        -----
        #. Rewrite decorator to be function based instead of class based so it is easier to use in urls.py.
        
        0.1.3
        -----
        #. `cached_get` decorator now does not cache if request contains messages.
        
        0.1.2
        -----
        #. Fix HTTPResponse caching bug.
        
        0.1.1
        -----
        #. Handle case where a view returns an HTTPResponse object.
        
        0.1
        ---
        #. Initial release.
        
        
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
