# Calm Cache for Django
`django-calm-cache` keeps your cache calm while your site is being hammered by
bucket loads of traffic.
this project is forked from [pitcrews:django-calm-cache](https://bitbucket.org/pitcrews/django-calm-cache/).
Thanks for all the contributors.
But the origin project can't be used in new verion of django.
And it seems the author didn't update the package in pypi.
So I forked and update the django3-calm-cache repository
## Key Features
* [Mint caching](http://djangosnippets.org/snippets/155/) to avoid the
[dog pile](http://en.wikipedia.org/wiki/Cache_stampede) effect
* Timeout jitter to reduce the number of entries expiring simultaneously
* Works alongside any other Django cache backend
* `MemcachedCache` and `PyLibMCCache` Django backends are extended to support
data compression provided by [python-memcached](ftp://ftp.tummy.com/pub/python-memcached/)
and [pylibmc](http://sendapatch.se/projects/pylibmc/) respectively
* `PyLibMCCache` is extended to support binary protocol
* `cache_response` decorator that could be applied to any Django view and
conditionally cache responses just like Django standard `CacheMiddleware`
and `cache_page` do, but more configurable, explicit and extensible
## Installation
:::shell
pip3 install django3-calm-cache
### Cache Backends
Update the cache settings in your `settings.py`:
:::python
CACHES = {
'default': {
'BACKEND' : 'calm_cache.backends.CalmCache',
'LOCATION': 'locmem-cache',
'KEY_FUNCTION': 'calm_cache.contrib.sha1_key_func',
'OPTIONS': {
'MINT_PERIOD': '10', # Allow stale results for this many seconds. Default: 0 (Off)
'GRACE_PERIOD': '120', # Serve stale value once during this period. Default: 0 (Off)
'JITTER': '10', # Upper bound on the random jitter in seconds. Default: 0 (Off)
},
},
'locmem-cache': {
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
'LOCATION': 'foo',
},
'zipped-memcached': {
'BACKEND': 'calm_cache.backends.MemcachedCache',
'LOCATION': '127.0.0.1:11211',
'OPTIONS': {
'MIN_COMPRESS_LEN': 1024, # Compress values of this size or larger, bytes. Default: 0 (Disabled)
},
},
'zipped-bin-pylibmc': {
'BACKEND': 'calm_cache.backends.PyLibMCCache',
'LOCATION': '127.0.0.1:11211',
'OPTIONS': {
'MIN_COMPRESS_LEN': 1024, # Compress values of this size or larger, bytes. Default: 0 (Disabled)
'BINARY': True, # Enable binary protocol for this backend. Default: False (Disabled)
},
},
}
Now relax knowing your site's caching won't fall over at the first sign of sustained traffic.
#### CalmCache Configuration
`LOCATION` parameter defines the name of another, "real", Django cache backend
which will be used to actually store values
`CalmCache` backend accepts the following options:
* `MINT_PERIOD`: the time period that starts right after the user-supplied
or default timeout (`TIMEOUT` setting) ends.
First request during this period receives get() miss (`None` or default) and
refreshes the value while all other requests are returning cached (stale)
value until it is either updated or expired. Seconds. Default: `0`
* `GRACE_PERIOD`: the time period starting after mint delay.
During grace period stale value is returned only once and is removed after that.
Seconds. Default: `0`
* `JITTER`: defines the range for `[0 ... JITTER]` random value
that is added to client supplied and "real" cache timeouts. Seconds. Default: `0`
#### CalmCache Guidelines
Actual stored key names are composed of `CalmCache.make_key()`
and underlying cache's `make_key()` methods' outputs, and therefore are stacked:
real_cache_prefix:calm_cache_prefix:user_supplied_key
Minting is designed to cope with highly concurrent requests and good value
of `MINT_PERIOD` would be comparable to the stored object regeneration time.
Grace period starts after mint delay and first request that comes during this time
is satisfied with stale value. The value cached under the given key
is invalidated immediately and next requesting client will refresh and
store a new value. This technique improves hit ratio for infrequently accessed
data when occasional staleness is affordable.
Add random variability to the expiry of cache objects as they may be generated
at the same time, which mitigates expiry synchronisation
The maximum real cache TTL is caclulated as
timeout + MINT_PERIOD + GRACE_PERIOD + JITTER
Setting `MINT_PERIOD`, `GRACE_PERIOD` or `JITTER` to `0` or not setting them
at all turns off relevant logic in the code.
#### CalmCache Limitations
* `CalmCache` currently only supports cache methods `add`, `set`, `get`, `delete`,
`has_key` and `clear`
### Response Cache
Example usage:
:::python
from calm_cache.decorators import cache_response
@cache_response(15, key_prefix='my_view', codes=(200, 404))
def my_view(request, slug=None):
return HttpResponse()
`cache_response`'s constructor arguments, relevant Django settings and
defaults:
* `cache_timeout`: integer, default TTL for cached entries. Required
* `cache`: Django cache backend name. If not specified, default cache
backend will be used
* `key_prefix`: this string is always prepending resulting keys.
Default: `''`. Django setting: `CCRC_KEY_PREFIX`
* `methods`: a list/tuple with request methods that could be cached.
Default: `('GET', )`. Django setting: `CCRC_CACHE_REQ_METHDODS`
* `codes`: a list/tuple with cacheable response codes.
Default: `(200, )`. Django setting: `CCRC_CACHE_RSP_CODES`
* `nocache_req`: a dictionary with request headers as keys and
regular expressions as values (strings or compiled), so that when request
has a header with value matching the expression,
the response is never cached. The headers should be put in WSGI format,
i.e. `'HTTP_X_FORWARDED_FOR'`. Default: `{}`.
* `nocache_rsp`: a list of response headers that prevents response
from being cached. Default: `('Set-Cookie', 'Vary')`.
Django setting: `CCRC_NOCACHE_RSP_HEADERS`
* `anonymous_only`: boolean selecting whether only anonymous requests
should be served from the cache/responses cached.
Default: `True`. Django setting: `CCRC_ANONYMOUS_REQ_ONLY`
* `cache_cookies`: boolean, if False, requests with cookies will
not be cached, otherwise cookies are ignored. Default: `False`.
Django setting: `CCRC_CACHE_REQ_COOKIES`
* `excluded_cookies`: if `cache_cookies` is False, cookies found in
this list are ignored (considered as not set).
If `cache_cookies` is True, response will not be cached if
one of cookies listed is found in the request. Default: `()`.
Django setting: `CCRC_EXCLUDED_REQ_COOKIES`
* `include_scheme`: boolean selecting whether request scheme (http
or https) should be used for the key. Default: `True`.
Django setting: `CCRC_KEY_SCHEME`
* `include_host`: boolean selecting whether requested Host: should
be used for the key. Default: `True`. Django setting: `CCRC_KEY_HOST`
* `hitmiss_header`: a tuple with three elements: header name,
value for cache hit and another for cache miss.
If set to `None`, the header is never added
Default: `('X-Cache', 'Hit', 'Miss')'`. Django setting: `CCRC_HITMISS_HEADER`
* `key_function`: optional callable that should be used instead of
built-in key function.
Has to accept request as its only argument and return either
a string with the key or `None` if the request should not be cached.
#### ResponseCache Features and Guidelines
* Unlike `CacheMiddleware`, `cache_response` does not analyse `Cache-Control`
header and does not change cache TTL. The header is cached along
with the response just like any other header
* Default settings for `cache_reponse` are chosen to be the safest, but in
order to achieve better cache performance careful configuretion is required
* By default, reponses with `Set-Cookie` and `Vary` headers are never cached,
requests that have `Cookie` header are not cached either
* Responses that have CSRF token(s) are never cached
* Requests that have authenticated user associated with them are not cached
by default
* URL and Hostname are used to build the cache key, which could be a problem
for certain caching engines due to their limitation to key characters and length.
You are advised to use some hashing `KEY_FUNCTION` in your caching backend, like,
for example, provided `calm_cache.contrib.sha1_key_func`
## Legals
License: BSD 3-clause
Copyright (c) 2014, Fairfax Media Limited
All rights reserved.
Raw data
{
"_id": null,
"home_page": "https://github.com/ramwin/django-calm-cache",
"name": "django3-calm-cache",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "django cache memcache memcached minting pylibmc libmemcached",
"author": "Xiang Wang",
"author_email": "ramwin@qq.com",
"download_url": "https://files.pythonhosted.org/packages/77/06/9b0b6de0ee91ebeff87c146c72bd68957a8615d9efe5c8ca8133cff2b86a/django3_calm_cache-1.0.2.tar.gz",
"platform": "Platform Independent",
"description": "# Calm Cache for Django\n\n`django-calm-cache` keeps your cache calm while your site is being hammered by\nbucket loads of traffic.\n\nthis project is forked from [pitcrews:django-calm-cache](https://bitbucket.org/pitcrews/django-calm-cache/). \nThanks for all the contributors. \nBut the origin project can't be used in new verion of django. \nAnd it seems the author didn't update the package in pypi. \nSo I forked and update the django3-calm-cache repository\n\n## Key Features\n\n * [Mint caching](http://djangosnippets.org/snippets/155/) to avoid the\n [dog pile](http://en.wikipedia.org/wiki/Cache_stampede) effect\n * Timeout jitter to reduce the number of entries expiring simultaneously\n * Works alongside any other Django cache backend\n * `MemcachedCache` and `PyLibMCCache` Django backends are extended to support\n data compression provided by [python-memcached](ftp://ftp.tummy.com/pub/python-memcached/)\n and [pylibmc](http://sendapatch.se/projects/pylibmc/) respectively\n * `PyLibMCCache` is extended to support binary protocol\n * `cache_response` decorator that could be applied to any Django view and\n conditionally cache responses just like Django standard `CacheMiddleware`\n and `cache_page` do, but more configurable, explicit and extensible\n\n## Installation\n\n :::shell\n pip3 install django3-calm-cache\n\n\n### Cache Backends\n\nUpdate the cache settings in your `settings.py`:\n\n :::python\n CACHES = {\n 'default': {\n 'BACKEND' : 'calm_cache.backends.CalmCache',\n 'LOCATION': 'locmem-cache',\n 'KEY_FUNCTION': 'calm_cache.contrib.sha1_key_func',\n 'OPTIONS': {\n 'MINT_PERIOD': '10', # Allow stale results for this many seconds. Default: 0 (Off)\n 'GRACE_PERIOD': '120', # Serve stale value once during this period. Default: 0 (Off)\n 'JITTER': '10', # Upper bound on the random jitter in seconds. Default: 0 (Off)\n },\n },\n 'locmem-cache': {\n 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',\n 'LOCATION': 'foo',\n },\n 'zipped-memcached': {\n 'BACKEND': 'calm_cache.backends.MemcachedCache',\n 'LOCATION': '127.0.0.1:11211',\n 'OPTIONS': {\n 'MIN_COMPRESS_LEN': 1024, # Compress values of this size or larger, bytes. Default: 0 (Disabled)\n },\n },\n 'zipped-bin-pylibmc': {\n 'BACKEND': 'calm_cache.backends.PyLibMCCache',\n 'LOCATION': '127.0.0.1:11211',\n 'OPTIONS': {\n 'MIN_COMPRESS_LEN': 1024, # Compress values of this size or larger, bytes. Default: 0 (Disabled)\n 'BINARY': True, # Enable binary protocol for this backend. Default: False (Disabled)\n },\n },\n }\n\nNow relax knowing your site's caching won't fall over at the first sign of sustained traffic.\n\n#### CalmCache Configuration\n\n\n`LOCATION` parameter defines the name of another, \"real\", Django cache backend\nwhich will be used to actually store values\n\n`CalmCache` backend accepts the following options:\n\n * `MINT_PERIOD`: the time period that starts right after the user-supplied\n or default timeout (`TIMEOUT` setting) ends.\n First request during this period receives get() miss (`None` or default) and\n refreshes the value while all other requests are returning cached (stale)\n value until it is either updated or expired. Seconds. Default: `0`\n * `GRACE_PERIOD`: the time period starting after mint delay.\n During grace period stale value is returned only once and is removed after that.\n Seconds. Default: `0`\n * `JITTER`: defines the range for `[0 ... JITTER]` random value\n that is added to client supplied and \"real\" cache timeouts. Seconds. Default: `0`\n\n\n#### CalmCache Guidelines\n\nActual stored key names are composed of `CalmCache.make_key()`\nand underlying cache's `make_key()` methods' outputs, and therefore are stacked:\n\n real_cache_prefix:calm_cache_prefix:user_supplied_key\n\n\nMinting is designed to cope with highly concurrent requests and good value\nof `MINT_PERIOD` would be comparable to the stored object regeneration time.\n\nGrace period starts after mint delay and first request that comes during this time\nis satisfied with stale value. The value cached under the given key\nis invalidated immediately and next requesting client will refresh and\nstore a new value. This technique improves hit ratio for infrequently accessed\ndata when occasional staleness is affordable.\n\nAdd random variability to the expiry of cache objects as they may be generated\nat the same time, which mitigates expiry synchronisation\n\nThe maximum real cache TTL is caclulated as\n\n timeout + MINT_PERIOD + GRACE_PERIOD + JITTER\n\n\nSetting `MINT_PERIOD`, `GRACE_PERIOD` or `JITTER` to `0` or not setting them\nat all turns off relevant logic in the code.\n\n\n#### CalmCache Limitations\n\n * `CalmCache` currently only supports cache methods `add`, `set`, `get`, `delete`,\n `has_key` and `clear`\n\n\n### Response Cache\n\nExample usage:\n\n :::python\n from calm_cache.decorators import cache_response\n\n @cache_response(15, key_prefix='my_view', codes=(200, 404))\n def my_view(request, slug=None):\n return HttpResponse()\n\n`cache_response`'s constructor arguments, relevant Django settings and\ndefaults:\n\n * `cache_timeout`: integer, default TTL for cached entries. Required\n * `cache`: Django cache backend name. If not specified, default cache\n backend will be used\n * `key_prefix`: this string is always prepending resulting keys.\n Default: `''`. Django setting: `CCRC_KEY_PREFIX`\n * `methods`: a list/tuple with request methods that could be cached.\n Default: `('GET', )`. Django setting: `CCRC_CACHE_REQ_METHDODS`\n * `codes`: a list/tuple with cacheable response codes.\n Default: `(200, )`. Django setting: `CCRC_CACHE_RSP_CODES`\n * `nocache_req`: a dictionary with request headers as keys and\n regular expressions as values (strings or compiled), so that when request\n has a header with value matching the expression,\n the response is never cached. The headers should be put in WSGI format,\n i.e. `'HTTP_X_FORWARDED_FOR'`. Default: `{}`.\n * `nocache_rsp`: a list of response headers that prevents response\n from being cached. Default: `('Set-Cookie', 'Vary')`.\n Django setting: `CCRC_NOCACHE_RSP_HEADERS`\n * `anonymous_only`: boolean selecting whether only anonymous requests\n should be served from the cache/responses cached.\n Default: `True`. Django setting: `CCRC_ANONYMOUS_REQ_ONLY`\n * `cache_cookies`: boolean, if False, requests with cookies will\n not be cached, otherwise cookies are ignored. Default: `False`.\n Django setting: `CCRC_CACHE_REQ_COOKIES`\n * `excluded_cookies`: if `cache_cookies` is False, cookies found in\n this list are ignored (considered as not set).\n If `cache_cookies` is True, response will not be cached if\n one of cookies listed is found in the request. Default: `()`.\n Django setting: `CCRC_EXCLUDED_REQ_COOKIES`\n * `include_scheme`: boolean selecting whether request scheme (http\n or https) should be used for the key. Default: `True`.\n Django setting: `CCRC_KEY_SCHEME`\n * `include_host`: boolean selecting whether requested Host: should\n be used for the key. Default: `True`. Django setting: `CCRC_KEY_HOST`\n * `hitmiss_header`: a tuple with three elements: header name,\n value for cache hit and another for cache miss.\n If set to `None`, the header is never added\n Default: `('X-Cache', 'Hit', 'Miss')'`. Django setting: `CCRC_HITMISS_HEADER`\n * `key_function`: optional callable that should be used instead of\n built-in key function.\n Has to accept request as its only argument and return either\n a string with the key or `None` if the request should not be cached.\n\n\n#### ResponseCache Features and Guidelines\n\n * Unlike `CacheMiddleware`, `cache_response` does not analyse `Cache-Control`\n header and does not change cache TTL. The header is cached along\n with the response just like any other header\n * Default settings for `cache_reponse` are chosen to be the safest, but in\n order to achieve better cache performance careful configuretion is required\n * By default, reponses with `Set-Cookie` and `Vary` headers are never cached,\n requests that have `Cookie` header are not cached either\n * Responses that have CSRF token(s) are never cached\n * Requests that have authenticated user associated with them are not cached\n by default\n * URL and Hostname are used to build the cache key, which could be a problem\n for certain caching engines due to their limitation to key characters and length.\n You are advised to use some hashing `KEY_FUNCTION` in your caching backend, like,\n for example, provided `calm_cache.contrib.sha1_key_func`\n\n\n## Legals\n\nLicense: BSD 3-clause\n\nCopyright (c) 2014, Fairfax Media Limited\nAll rights reserved.\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "A set of useful tools that enhance the standard Django cache experience",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/ramwin/django-calm-cache"
},
"split_keywords": [
"django",
"cache",
"memcache",
"memcached",
"minting",
"pylibmc",
"libmemcached"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dba3e8037fcfa221c5d4df6fd73654234d83bc7c4a2650ea68d8aa3816b30ec5",
"md5": "29c7d4abda22350a97f9c86897b61479",
"sha256": "50de0dff412fe717467c6e803c514e03e8a57bf70f377a786418a91906469d3d"
},
"downloads": -1,
"filename": "django3_calm_cache-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29c7d4abda22350a97f9c86897b61479",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12891,
"upload_time": "2024-11-18T16:35:25",
"upload_time_iso_8601": "2024-11-18T16:35:25.467267Z",
"url": "https://files.pythonhosted.org/packages/db/a3/e8037fcfa221c5d4df6fd73654234d83bc7c4a2650ea68d8aa3816b30ec5/django3_calm_cache-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "77069b0b6de0ee91ebeff87c146c72bd68957a8615d9efe5c8ca8133cff2b86a",
"md5": "798e9f27e93ef977503fa65d889128c3",
"sha256": "6ff873b0a4d08cfac3f21e7c80459d87638b9ac00436f96996ae6fc9a5078167"
},
"downloads": -1,
"filename": "django3_calm_cache-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "798e9f27e93ef977503fa65d889128c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13478,
"upload_time": "2024-11-18T16:35:27",
"upload_time_iso_8601": "2024-11-18T16:35:27.487740Z",
"url": "https://files.pythonhosted.org/packages/77/06/9b0b6de0ee91ebeff87c146c72bd68957a8615d9efe5c8ca8133cff2b86a/django3_calm_cache-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-18 16:35:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ramwin",
"github_project": "django-calm-cache",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "django3-calm-cache"
}
JSON
