Metadata-Version: 1.1
Name: django-ultracache
Version: 2.0.0
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-Content-Type: UNKNOWN
Description: Django Ultracache
        =================
        **Cache views, template fragments and arbitrary Python code. Monitor Django object changes to perform automatic fine-grained cache invalidation from Django level, through proxies, to the browser.**
        
        .. figure:: https://travis-ci.org/praekelt/django-ultracache.svg?branch=develop
           :align: center
           :alt: Travis
        
        .. contents:: Contents
            :depth: 5
        
        Overview
        --------
        
        Cache views, template fragments and arbitrary Python code. Once cached we
        either avoid database queries and expensive computations, depending on the use
        case. In all cases affected caches are automatically expired when objects "red"
        or "blue" are modified, without us having to add "red" or "blue" to the cache.
        
        View::
        
            from ultracache.decorators import cached_get, ultracache
        
            @ultracache(300)
            class MyView(TemplateView):
                template_name = "my_view.html"
        
                def get_context_data(self, **kwargs):
                    context = super().get_context_data(**kwargs)
                    # Note we never use red
                    red = Color.objects.get(slug="red")
                    # For our example color_slug is blue
                    context["color"] = Color.objects.get(slug=kwargs["color_slug"])
                    return context
        
        Template::
        
            {# variable "color" is the object "blue" #}
            {% load ultracache_tags %}
            {% ultracache 300 "color-info" color.pk %}
                {# expensive properties #}
                {{ color.compute_valid_hex_codes }}
                {{ color.name_in_all_languages }}
            {% endultracache %}
        
        Python::
        
            from ultracache.utils import Ultracache
        
            ...
        
            color_slug = request.GET["color_slug"]
            uc = Ultracache(300, "another-identifier", color_slug)
            if uc:
                codes = uc.cached
            else:
                color = Color.objects.get(slug=color_slug)
                codes = color.compute_valid_hex_codes()
                uc.cache(codes)
            print(codes)
        
        Installation
        ------------
        
        #. Install or add ``django-ultracache`` to your Python path.
        
        #. Add ``ultracache`` to your ``INSTALLED_APPS`` setting.
        
        #. Ensure ``django.template.context_processors.request`` is in the context processors setting.
        
        Features
        --------
        
        #. Caches template fragments, views, Django Rest Framework viewsets.
        
        #. It takes the sites framework into consideration, allowing different caching per site.
        
        #. 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.
        
        Usage
        -----
        
        The ``cached_get`` and ``ultracache`` view decorators
        *****************************************************
        
        ``django-ultracache`` also provides decorators ``cached_get`` and
        ``ultracache`` 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. The
        ``ultracache`` decorator is newer and cleaner, so use that where possible::
        
            from ultracache.decorators import cached_get, ultracache
        
        
            class CachedView(TemplateView):
                template_name = "cached_view.html"
        
                @cached_get(300, "request.is_secure()", 456)
                def get(self, *args, **kwargs):
                    return super(CachedView, self).get(*args, **kwargs)
        
            @ultracache(300, "request.is_secure()", 456)
            class AnotherCachedView(TemplateView):
                template_name = "cached_view.html"
        
        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 decorators. They only ever operate on GET
        requests but cannot know if the code being wrapped retrieves data from eg. the
        session. In such a case they will cache things they are not supposed to cache.
        
        If your view is used by more than one URL pattern then it is highly recommended
        to apply the ``cached_get`` decorator in the URL pattern. Applying it directly
        to the ``get`` method may lead to cache collisions, especially if
        ``get_template_names`` is overridden.
        
        The ``ultracache`` template tag
        *******************************
        
        ``django-ultracache`` provides a template tag ``{% ultracache %}`` that
        functions much like Django's standard cache template tag; however, it takes the
        sites framework into consideration, allowing different caching per site, and it
        handles undefined variables.
        
        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 %}
        
        Specifying a good cache key
        ***************************
        
        The cache key decides whether a piece of code or template is going to be evaluated further. The
        cache key must therefore accurately and minimally describe what is being subjected to caching.
        
        todo
        
        Django Rest Framework viewset caching
        *************************************
        
        Cache ``list`` and ``retrieve`` actions on viewsets::
        
            # Cache all viewsets
            ULTRACACHE = {
                "drf": {"viewsets": {"*": {}}}
        
            }
        
            # Cache a specific viewset by name
            ULTRACACHE = {
                "drf": {"viewsets": {"my.app.MyViewset": {}}}
        
            }
        
            # Cache a specific viewset by class
            ULTRACACHE = {
                "drf": {"viewsets": {MyViewset: {}}}
        
            }
        
            # Timeouts default to 300 seconds
            ULTRACACHE = {
                "drf": {"viewsets": {"*": {"timeout": 1200}}}
        
            }
        
            # Evaluate code to append to the cache key. This example caches differently
            # depending on whether the user is logged in or not.
            ULTRACACHE = {
                "drf": {"viewsets": {"*": {"evaluate": "request.user.is_anonymous"}}}
        
            }
        
            # Evaluate code to append to the cache key via a callable.
            def mycallable(viewset, request):
                if viewset.__class__.__name__ == "foo":
                    return request.user.id
        
            ULTRACACHE = {
                "drf": {"viewsets": {"*": {"evaluate": mycallable}}}
        
            }
        
        Purgers
        *******
        
        You can create custom reverse caching proxy purgers. See ``purgers.py`` for examples::
        
            ULTRACACHE = {
                "purge": {"method": "myproduct.purgers.squid"}
            }
        
        The most useful purger is ``broadcast``. As the name implies it broadcasts purge
        instructions to a queue. Note that you need celery running and configured to
        write to a RabbitMQ instance for this to work correctly.
        
        The purge instructions are consumed by the ``cache-purge-consumer.py`` script.
        The script reads a purge instruction from the queue and then sends a purge
        instruction to an associated reverse caching proxy. To run the script::
        
            virtualenv ve
            ./ve/bin/pip install -e .
            ./ve/bin/python bin/cache-purge-consumer.py -c config.yaml
        
        The config file has these options:
        
        #. rabbit-url
           Specify RabbitMQ connection parameters in the AMQP URL format
           ``amqp://username:password@host:port/<virtual_host>[?query-string]``.
           *Optional. Defaults to ``amqp://guest:guest@127.0.0.1:5672/%2F``. Note the
           URL encoding for the path.*
        
        #. host
           A reverse caching proxy may be responsible for many domains (hosts), and
           ultracache will keep track of the host that is involved in a purge request;
           however, if you have a use case that does not supply a hostname, eg. doing a
           PURGE request via curl, then forcing a hostname solves the use case.
           *Optional.*
        
        #. proxy-address
           The IP address or hostname of the reverse caching proxy.
           *Optional. Defaults to 127.0.0.1.*
        
        #. logfile
           Set to a file to log all purge instructions. Specify ``stdout`` to log to
           standard out.
           *Optional.*
        
        Other settings
        **************
        
        Automatic invalidation defaults to true. To disable automatic invalidation set::
        
            ULTRACACHE = {
                "invalidate": False
            }
        
        ``django-ultracache`` maintains a registry in Django's caching backend (see
        `How does it work`). This registry can"t be allowed to grow unchecked, thus a
        limit is imposed on the registry size. It would be inefficient to impose a size
        limit on the entire registry so a maximum size is set per cached value. It
        defaults to 1000000 bytes::
        
            ULTRACACHE = {
                "max-registry-value-size": 10000
            }
        
        It is highly recommended to use a backend that supports compression because a
        larger size improves cache coherency.
        
        If you make use of a reverse caching proxy then you need the original set of
        request headers (or a relevant subset) to purge paths from the proxy correctly.
        The problem with the modern web is the sheer amount of request headers present
        on every request would lead to a large number of entries having to be stored by
        ``django-ultracache`` in Django's caching backend. Your proxy probably has a
        custom hash computation rule that considers only the request path (always
        implied) and Django's sessionid cookie, so define a setting to also consider only
        the cookie on the Django side::
        
            ULTRACACHE = {
                "consider-headers": ["cookie"]
            }
        
        If you only need to consider some cookies then set::
        
            ULTRACACHE = {
                "consider-cookies": ["sessionid", "some-other-cookie"]
            }
        
        How does it work?
        -----------------
        
        ``django-ultracache`` monkey patches
        ``django.template.base.Variable._resolve_lookup`` and
        ``django.db.models.Model.__getattribute__`` to make a record of model objects
        as they are resolved. The ``ultracache`` template tag, ``ultracache`` decorator
        and ``ultracache`` context manager inspect the list of objects contained
        within them and keep 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 are running a cluster of Django nodes then ensure that they use a shared caching backend.
        
        Authors
        =======
        
        Praekelt Consulting
        -------------------
        * Hedley Roos
        
        Changelog
        =========
        
        2.0.0
        -----
        #. Remove dependency on the sites framework everywhere. The sites framework is still automatically
           considered if an installed app.
        #. Do not store metadata in the request anymore but in a list on thread locals.
        #. Introduce class utils.Ultracache to subject arbitrary pieces of Python code to caching.
        #. Drop Django 1 support.
        
        1.11.12
        -------
        #. Simpler class based decorator.
        #. Add Django 2.1 and Python 3.6 tests.
        
        1.11.11
        -------
        #. Add a test for tasks.
        
        1.11.10
        -------
        #. Ensure a working error message if pika is not found.
        #. `cached_get` now considers any object accessed in get_context_data and not just objects accessed in the view template.
        #. The original request headers are now sent to the purgers along with the path. This enables fine-grained proxy invalidation.
        #. Django 2.0 and Python 3 compatibility. Django 1.9 support has been dropped.
        
        1.11.9
        ------
        #. Simplify the DRF caching implementation. It also now considers objects touched by sub-serializers.
        
        1.11.8
        ------
        #. The DRF settings now accept dotted names.
        #. The DRF setting now accepts a callable whose result forms part of the cache key.
        
        1.11.7
        ------
        #. Use pickle to cache DRF data because DRF uses a Decimal type that isn't recognized by Python's json library.
        
        1.11.6
        ------
        #. Adjust the DRF decorator so it can be used in more places.
        
        1.11.5
        ------
        #. Django Rest Framework caching does not cache the entire response anymore, only the data and headers.
        
        1.11.4
        ------
        #. Move the twisted work to `django-ultracache-twisted`.
        #. Clearly raise exception if libraries are not found.
        
        1.11.3
        ------
        #. Move the twisted directory one lower.
        
        1.11.2
        ------
        #. Package the product properly so all directories are included.
        
        1.11.1
        ------
        #. More defensive code to ensure we don't interfere during migrations in a test run.
        
        1.11.0
        ------
        #. Introduce `rabbitmq-url` setting for use by `broadcast_purge` task.
        #. Django 1.11 support.
        #. Deprecate Django 1.6 support.
        
        1.10.2
        ------
        #. Remove logic that depends on SITE_ID so site can also be inferred from the request.
        
        1.10.1
        ------
        #. Add caching for Django Rest Framework viewsets.
        #. Django 1.10 compatibility.
        
        1.9.1
        -----
        #. Add missing import only surfacing in certain code paths.
        #. `Invalidate` setting was not being loaded properly. Fixed.
        #. Handle content types RuntimeError when content types have not been migrated yet.
        
        1.9.0
        -----
        #. Move to tox for tests.
        #. Django 1.9 compatibility.
        
        0.3.8
        -----
        #. Honor the `raw` parameter send along by loaddata. It prevents redundant post_save handling.
        
        0.3.7
        -----
        #. Revert the adding of the template name. It introduces a performance penalty in a WSGI environment.
        #. Further reduce the number of writes to the cache.
        
        0.3.6
        -----
        #. Add template name (if possible) to the caching key.
        #. Reduce number of calls to set_many.
        
        0.3.5
        -----
        #. Keep the metadata cache size in check to prevent possibly infinite growth.
        
        0.3.4
        -----
        #. Prevent redundant sets.
        #. Work around an apparent Python bug related to `di[k].append(v)` vs `di[k] = di[k] + [v]`. The latter is safe.
        
        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
