Metadata-Version: 2.1
Name: django-cachekiller
Version: 0.8.0
Summary: Static file CDN cache buster for fast site updates.
Home-page: https://github.com/meeb/django-cachekiller
Author: https://github.com/meeb
Author-email: meeb@meeb.org
License: MIT
Keywords: django,cache,buster,cdn,cachebuster
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
License-File: LICENSE

# django-cachekiller

`django-cachekiller` is a small add-on for Django that adds the `cdnstatic`
template tag which adds a 'cache busting' dynamic query string appended to the
file paths. This tag functions identically to the standard `{% static ... %}`
template tag. This is designed to work with CDNs that cache by complete URI
including the query string so when you push a change the CDNs are automatically
refreshed without having to wait for TTLs to expire. Internally we use this with
`django-distill`, a static site generator for Django to work with static sites
with heavy caching on images behind CloudFlare, cachefly and other CDNs:

https://github.com/meeb/django-distill

Under the hood, this module just chains the request to the existing `static` tag
to be widely compatible.

# Installation

Install from pip:

```bash
$ pip install django-cachekiller
```

Add `django_cachekiller` to your `INSTALLED_APPS` in your `settings.py`:

```python
INSTALLED_APPS = [
    # ... other apps here ...
    'django_cachekiller',
]
```

That's it.

# Usage

Load the new module at the top of your templates:

```html
{% load cdnstaticfiles %}
```

Then use the new tag in the template exactly as you would use the `static` tag:

```html
{% cdnstatic 'some/image.jpg' %}
```
This renders as (assuming `settings.STATIC_URL` is set to `/static/`):

```html
/static/some/image.jpg?tag=[random tag]
```

`[random tag]` is either the truncated mercurial or git commit reference if it
is available, otherwise it will be the current date in `YYYYMMDDHHMMSS` format.
If there are existing query string parameters then the `tag` is intelligently
appended. The `cdnstatic` tag will not break the existing URL.

Additionally, if you need to just access the `[random tag]` for some other use
without the automatic URL rewriting you can use the following:

```html
<a href="/someurl.html?tag={% cdntag %}">link</a>
```

This can be used in conjunction with other URL wrapping tags for combatability
where chaining tags is difficult, for example:

```html
<link rel="stylesheet" href="{% sass_src 'file.scss' %}?tag={% cdntag %}">
```

# Contributing

All properly formatted and sensible pull requests, issues and comments are
welcome.


