Use case

As a developer, you are asked to add download features to websites:

• download PDF documents as attachment,
• export data as CSV files,
• generate archives (tar.gz)...

Sometimes you can simply make sure that those files are on server's disk, then serve them as static files.

But sometimes you can't, because the files are generated dynamically, or you have to perform some backend operations such as user authentication.

Using Django, you can write views that return files as attachment, with very little code. But that's always the same "copy-paste-adapt" pattern. In order to keep it DRY, you'd appreciate an API.

Last but not least, streaming files with Django (and with Python in general) isn't the most efficient way to go. Http servers and reverse proxies (nginx, lighttpd, ...) are far more efficient. Luckily, many servers allow proxied services (i.e. Django) to delegate the actual streaming process. This feature is generally known as "x-sendfile". As an example, see Lighttpd's X-Sendfile documentation.

Django-downloadview simplifies the implementation of download views with Django, with pluggable x-sendfile support.

Example

Given some Django model with a FileField:

# In some models.py...
from django.db import models

class Document(models.Model):
    """A sample model with a FileField."""
    slug = models.SlugField(verbose_name='slug')
    file = models.FileField(verbose_name='file', upload_to='document')

You can easily create a view that returns the file contents as attachment:

# In some urls.py...
from django.conf.urls import patterns, url
from django_downloadview import ObjectDownloadView
from document.models import Document  # The model we created upward.

download_document = ObjectDownloadView.as_view(model=Document)

urlpatterns = patterns('',
    url(r'^document/(?P<slug>[a-zA-Z0-9_-]+)/$', download_document),
)

Pretty straightforward isn't it?

Of course, there are several ways to get download views. ObjectDownloadView supports more options (basically, all options inherited from DetailView, more some options related to the download).

Optimizations

You have the download view, let's optimize the streaming. Depending on your use case, you can enable global optimization with a middleware, or setup per-view optimizations via decorators. Read the documentation about optimizations for details.

As of version 1.0, django-downloadview has built-in support of Nginx's X-Accel only. But contributions are welcome ;)

Made for overrides

We tried to make django-downloadview simple to use, and simple to adapt:

• for most cases, using the built-in views is quick and enough;
• for special cases, class-based views and utilities should be easy to extend and override.

Do you feel some use case cannot easily be implemented? Let us know!.

Future

After the 1.0 release, two big user stories were identified, which could require some API refactoring.

References

• Online documentation
• Have a look at alternatives and related projects.
• django-downloadview on PyPI
• Issues and feature requests
• Main code repository