{
    "info": {
        "author": "Alexander Schepanovski",
        "author_email": "suor.web@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 5 - Production/Stable",
            "Environment :: Web Environment",
            "Framework :: Django",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: BSD License",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2",
            "Programming Language :: Python :: 2.6",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.3",
            "Topic :: Internet :: WWW/HTTP",
            "Topic :: Software Development :: Libraries :: Python Modules"
        ],
        "description": "Cacheops\n========\n\nA slick app that supports automatic or manual queryset caching and automatic\ngranular event-driven invalidation.\n\nIt uses `redis <http://redis.io/>`_ as backend for ORM cache and redis or\nfilesystem for simple time-invalidated one.\n\nAnd there is more to it:\n\n- decorators to cache any user function as queryset or by time\n- extensions for django and jinja2 templates to cache template fragments as querysets or by time\n- concurrent file cache with a decorator\n- a couple of hacks to make django faster\n\n\nRequirements\n------------\n\nPython 2.6, 2.7 or 3.3, Django 1.2+ and Redis 2.6+.\n\n\nInstallation\n------------\n\nUsing pip::\n\n    $ pip install django-cacheops\n\nOr you can get latest one from github::\n\n    $ git clone git://github.com/Suor/django-cacheops.git\n    $ ln -s `pwd`/django-cacheops/cacheops/ /somewhere/on/python/path/\n\n\nSetup\n-----\n\nAdd ``cacheops`` to your ``INSTALLED_APPS`` before any apps that use it.\n\nSetup redis connection and enable caching for desired models:\n\n.. code:: python\n\n    CACHEOPS_REDIS = {\n        'host': 'localhost', # redis-server is on same machine\n        'port': 6379,        # default redis port\n        'db': 1,             # SELECT non-default redis database\n                             # using separate redis db or redis instance\n                             # is highly recommended\n        'socket_timeout': 3,\n    }\n\n    CACHEOPS = {\n        # Automatically cache any User.objects.get() calls for 15 minutes\n        # This includes request.user or post.author access,\n        # where Post.author is a foreign key to auth.User\n        'auth.user': ('get', 60*15),\n\n        # Automatically cache all gets, queryset fetches and counts\n        # to other django.contrib.auth models for an hour\n        'auth.*': ('all', 60*60),\n\n        # Enable manual caching on all news models with default timeout of an hour\n        # Use News.objects.cache().get(...)\n        #  or Tags.objects.filter(...).order_by(...).cache()\n        # to cache particular ORM request.\n        # Invalidation is still automatic\n        'news.*': ('just_enable', 60*60),\n\n        # Automatically cache count requests for all other models for 15 min\n        '*.*': ('count', 60*15),\n    }\n\n\nAdditionally, you can tell cacheops to degrade gracefully on redis fail with:\n\n.. code:: python\n\n    CACHEOPS_DEGRADE_ON_FAILURE=True\n\n\nUsage\n-----\n\n| **Automatic caching.**\n\nIt's automatic you just need to set it up.\n\n| **Manual caching.**\n\nYou can force any queryset to use cache by calling it's ``.cache()`` method:\n\n.. code:: python\n\n    Article.objects.filter(tag=2).cache()\n\n\nHere you can specify which ops should be cached for queryset, for example, this code:\n\n.. code:: python\n\n    qs = Article.objects.filter(tag=2).cache(ops=['count'])\n    paginator = Paginator(objects, ipp)\n    articles = list(pager.page(page_num)) # hits database\n\n\nwill cache ``.count()`` call in Paginator but not later in articles fetch.\nThere are three possible actions - ``get``, ``fetch`` and ``count``. You can\npass any subset of this ops to ``.cache()`` method even empty to turn off caching.\nThere are, however, a shortcut for it:\n\n.. code:: python\n\n    qs = Article.objects.filter(visible=True).nocache()\n    qs1 = qs.filter(tag=2)       # hits database\n    qs2 = qs.filter(category=3)  # hits it once more\n\n\nIt is useful when you want to disable automatic caching on particular queryset.\n\n| **Function caching.**\n\nYou can cache and invalidate result of a function the same way as a queryset.\nCache of next function will be invalidated on any ``Article`` change, addition\nor deletion:\n\n.. code:: python\n\n    from cacheops import cached_as\n\n    @cached_as(Article)\n    def article_stats():\n        return {\n            'tags': list( Article.objects.values('tag').annotate(count=Count('id')) )\n            'categories': list( Article.objects.values('category').annotate(count=Count('id')) )\n        }\n\n\nNote that we are using list on both querysets here, it's because we don't want\nto cache queryset objects but their results.\n\nAlso note that cache key does not depend on arguments of a function, so it's result\nshould not, either. This is done to enable caching of view functions. Instead\nyou should use a local function:\n\n.. code:: python\n\n    def articles_block(category, count=5):\n\n        @cached_as(Article.objects.filter(category=category), extra=count)\n        def _articles_block():\n            qs = Article.objects.filter(category=category)\n            articles = list(qs.filter(photo=True)[:count])\n\n            if len(articles) < count:\n                articles += list(qs[:count-len(articles)])\n\n            return articles\n\n        return _articles_block()\n\n\nUsing local function gives additional advantage: we can filter queryset used\nin ``@cached_as()`` to make invalidation more granular. We also add an\n``extra`` to make different keys for calls with same ``category`` but different\n``count``.\n\n\nInvalidation\n------------\n\nCacheops uses both time and event-driven invalidation. The event-driven one\nlistens on model signals and invalidates appropriate caches on ``Model.save()``\nand ``.delete()``.\n\nInvalidation tries to be granular which means it won't invalidate a queryset\nthat cannot be influenced by added/updated/deleted object judging by query\nconditions. Most time this will do what you want, if it's not you can use one\nof the following:\n\n.. code:: python\n\n    from cacheops import invalidate_obj, invalidate_model\n\n    invalidate_obj(some_article)  # invalidates queries affected by some_article\n    invalidate_model(Article)     # invalidates all queries for model\n\n\nAnd last there is ``invalidate`` command::\n\n    ./manage.py invalidate articles.Article.34  # same as invalidate_obj\n    ./manage.py invalidate articles.Article     # same as invalidate_model\n    ./manage.py invalidate articles   # invalidate all models in articles\n\nAnd the one that FLUSHES cacheops redis database::\n\n    ./manage.py invalidate all\n\nDon't use that if you share redis database for both cache and something else.\n\n\nMultiple database support\n-------------------------\n\nBy default cacheops considers query result is same for same query, not depending on database queried. That could be changed with ``db_agnostic`` cache profile option:\n\n.. code:: python\n\n    CACHEOPS = {\n        'some.model': ('get', TIMEOUT, {'db_agnostic': False}),\n        # ...\n    }\n\n\nSimple time-invalidated cache\n-----------------------------\n\nTo cache result of a function call for some time use:\n\n.. code:: python\n\n    from cacheops import cached\n\n    @cached(timeout=number_of_seconds)\n    def top_articles(category):\n        return ... # Some costly queries\n\n\n``@cached()`` will generate separate entry for each combination of decorated function and its\narguments. Also you can use ``extra`` same way as in ``@cached_as()``, most useful for nested functions:\n\n.. code:: python\n\n    @property\n    def articles_json(self):\n        @cached(timeout=10*60, extra=self.category)\n        def _articles_json():\n            ...\n            return json.dumps(...)\n\n        return _articles_json()\n\n\nYou can manually invalidate cached function result this way:\n\n.. code:: python\n\n    top_articles.invalidate(some_category)\n\n\nCacheops also provides get/set primitives for simple cache:\n\n.. code:: python\n\n    from cacheops import cache\n\n    cache.set(cache_key, data, timeout=None)\n    cache.get(cache_key)\n    cache.delete(cache_key)\n\n\n``cache.get`` will raise ``CacheMiss`` if nothing is stored for given key:\n\n.. code:: python\n\n    from cacheops import cache, CacheMiss\n\n    try:\n        result = cache.get(key)\n    except CacheMiss:\n        ... # deal with it\n\n\nFile Cache\n----------\n\nFile based cache can be used the same way as simple time-invalidated one:\n\n.. code:: python\n\n    from cacheops import file_cache\n\n    @file_cache.cached(timeout=number_of_seconds)\n    def top_articles(category):\n        return ... # Some costly queries\n\n    # later, on appropriate event\n    top_articles.invalidate(some_category)\n\n    # primitives\n    file_cache.set(cache_key, data, timeout=None)\n    file_cache.get(cache_key)\n    file_cache.delete(cache_key)\n\n\nIt have several improvements upon django built-in file cache, both about high load. First, it is safe against concurrent writes. Second, it's invalidation is done as separate task, you'll need to call this from crontab for that to work::\n\n    /path/manage.py cleanfilecache\n\n\nDjango templates integration\n----------------------------\n\nCacheops provides tags to cache template fragments for Django 1.4+. They mimic ``@cached_as`` and ``@cached`` decorators, however they require explicit naming of each fragment:\n\n.. code:: django\n\n    {% load cacheops %}\n\n    {% cached_as <queryset> <timeout> <fragment_name> [<extra1> <extra2> ...] %}\n        ... some template code ...\n    {% endcached_as %}\n\n    {% cached <timeout> <fragment_name> [<extra1> <extra2> ...] %}\n        ... some template code ...\n    {% endcached %}\n\nYou can use ``0`` for timeout in ``@cached_as`` to use it's default value for model.\n\n\nJinja2 extension\n----------------\n\nAdd ``cacheops.jinja2.cache`` to your extensions and use:\n\n.. code:: jinja\n\n    {% cached_as <queryset> [, timeout=<timeout>] [, extra=<key addition>] %}\n        ... some template code ...\n    {% endcached_as %}\n\nor\n\n.. code:: jinja\n\n    {% cached [timeout=<timeout>] [, extra=<key addition>] %}\n        ...\n    {% endcached %}\n\nTags work the same way as corresponding decorators.\n\n\nCAVEATS\n-------\n\n1. Conditions other than ``__exact`` or ``__in`` don't provide more granularity for\n   invalidation.\n2. Conditions on related models don't provide it either.\n3. Update of \"selected_related\" object does not invalidate cache for queryset.\n4. Mass updates don't trigger invalidation.\n5. ORDER BY and LIMIT/OFFSET don't affect invalidation.\n6. Doesn't work with RawQuerySet.\n7. Conditions on subqueries don't affect invalidation.\n8. Doesn't work right with multi-table inheritance.\n9. Aggregates is not implemented yet.\n10. Timeout in queryset and ``@cached_as()`` cannot be larger than default.\n\nHere 1, 3, 5, 10 are part of design compromise, trying to solve them will make\nthings complicated and slow. 2 and 7 can be implemented if needed, but it's\nprobably counter-productive since one can just break queries into simple ones,\nwhich cache better. 4 is a deliberate choice, making it \"right\" will flush\ncache too much when update conditions are orthogonal to most queries conditions.\n6 can be cached as ``SomeModel.objects.all()`` but ``@cached_as()`` someway covers that\nand is more flexible. 8 is postponed until it will gain more interest or a champion willing to\nimplement it emerge.\n\n\nPerformance tips\n----------------\n\nHere come some performance tips to make cacheops and Django ORM faster.\n\n1. When you use cache you pickle and unpickle lots of django model instances, which could be slow. You can optimize django models serialization with `django-pickling <http://github.com/Suor/django-pickling>`_.\n\n2. Constructing querysets is rather slow in django, mainly because most of ``QuerySet`` methods clone self, then change it and return a clone. Original queryset is usually thrown away. Cacheops adds ``.inplace()`` method, which makes queryset mutating, preventing useless cloning::\n\n    items = Item.objects.inplace().filter(category=12).order_by('-date')[:20]\n\n   You can revert queryset to cloning state using ``.cloning()`` call.\n\n3. More to 2, there is a `bug in django 1.4- <https://code.djangoproject.com/ticket/16759>`_,\n   which sometimes make queryset cloning very slow. You can use any patch from this ticket to fix it.\n\n4. Use template fragment caching when possible, it's way more fast because you don't need to generate anything. Also pickling/unpickling a string is much faster than list of model instances.\n\n5. Run separate redis instance for cache with disabled `persistence <http://redis.io/topics/persistence>`_. You can manually call `SAVE <http://redis.io/topics/persistence>`_ or `BGSAVE <http://redis.io/commands/bgsave>`_ to stay hot upon server restart.\n\n6. If you filter queryset on many different or complex conditions cache could degrade performance (comparing to uncached db calls) in consequence of frequent cache misses. Disable cache in such cases entirely or on some heuristics which detect if this request would be probably hit. E.g. enable cache if only some primary fields are used in filter.\n\n   Caching querysets with large amount of filters also slows down all subsequent invalidation on that model. You can disable caching if more than some amount of fields is used in filter simultaneously.\n\n\nWriting a test\n--------------\n\nWriting a test for an issue you are having can speed up it's resolution a lot. Here is how you do that. I am supposing you have some application code causing it.\n\n1. Make a fork.\n2. Install all from `test_requirements.txt`.\n3. Ensure you can run tests with `./run_tests.py`.\n4. Copy relevant models code to https://github.com/Suor/django-cacheops/blob/master/tests/models.py\n5. Go to https://github.com/Suor/django-cacheops/blob/master/tests/tests.py and paste code causing exception to `IssueTests.test_{issue_number}`.\n6. Execute `./run_tests.py IssueTests.test_{issue_number}` and see it failing.\n7. Cut down model and test code until error disappears and make a step back.\n8. Commit changes and make a pull request.\n\n\nTODO\n----\n\n- autodiscover ways to stringify things, make a better error message/docs\n- better invalidate_model()\n- add local cache (cleared at the and of request?)\n- support transactions\n- a way to turn off or postpone invalidation\n- faster .get() handling for simple cases such as get by pk/id, with simple key calculation\n- integrate with prefetch_related()\n- fast mode: store cache in local memory, but check in with redis if it's valid\n- shard cache between multiple redises\n- disable cache if select_for_update() called (or if _for_write set?)\n- lazy methods on querysets (calculate cache key from methods called)",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://github.com/Suor/django-cacheops",
        "keywords": null,
        "license": "BSD",
        "maintainer": null,
        "maintainer_email": null,
        "name": "django-cacheops-with-stats",
        "package_url": "https://pypi.org/project/django-cacheops-with-stats/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/django-cacheops-with-stats/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "http://github.com/Suor/django-cacheops"
        },
        "release_url": "https://pypi.org/project/django-cacheops-with-stats/1.3.1/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "A slick ORM cache with automatic granular event-driven invalidation for Django.",
        "version": "1.3.1"
    },
    "last_serial": 1439794,
    "releases": {
        "1.3.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5527913aef6983aa29b9f8071122b062",
                    "sha256": "4fcb4796fcc5fa6c5907fe617b86ff1a18035323cdae4b945f97d5c5d56eaa80"
                },
                "downloads": -1,
                "filename": "django-cacheops-with-stats-1.3.1.tar.gz",
                "has_sig": false,
                "md5_digest": "5527913aef6983aa29b9f8071122b062",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 24144,
                "upload_time": "2015-02-26T18:55:53",
                "url": "https://files.pythonhosted.org/packages/20/bc/cb9ebc610208fb463b1457612b6e3983a02a6ae9fa11c3b38c58b6d3af6a/django-cacheops-with-stats-1.3.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "5527913aef6983aa29b9f8071122b062",
                "sha256": "4fcb4796fcc5fa6c5907fe617b86ff1a18035323cdae4b945f97d5c5d56eaa80"
            },
            "downloads": -1,
            "filename": "django-cacheops-with-stats-1.3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "5527913aef6983aa29b9f8071122b062",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 24144,
            "upload_time": "2015-02-26T18:55:53",
            "url": "https://files.pythonhosted.org/packages/20/bc/cb9ebc610208fb463b1457612b6e3983a02a6ae9fa11c3b38c58b6d3af6a/django-cacheops-with-stats-1.3.1.tar.gz"
        }
    ]
}