django-downloadview¶

Simple example¶

Given a model with a FileField:

from django.db import models


class Document(models.Model):
    slug = models.SlugField()
    file = models.FileField(upload_to='object')

Setup a view to stream the file attribute:

from django_downloadview import ObjectDownloadView

from demoproject.object.models import Document


default_file_view = ObjectDownloadView.as_view(model=Document)

ObjectDownloadView inherits from BaseDetailView, i.e. it expects either slug or pk:

from django.conf.urls import patterns, url

from demoproject.object import views


urlpatterns = patterns(
    '',
    url(r'^default-file/(?P<slug>[a-zA-Z0-9_-]+)/$',
        views.default_file_view,
        name='default_file'),
)

Base options¶

ObjectDownloadView inherits from DownloadMixin, which has various options such as basename or attachment.

Serving specific file field¶

If your model holds several file fields, or if the file field name is not “file”, you can use ObjectDownloadView.file_field to specify the field to use.

Here is a model where there are two file fields:

from django.db import models


class Document(models.Model):
    slug = models.SlugField()
    file = models.FileField(upload_to='object')
    another_file = models.FileField(upload_to='object-other')

Then here is the code to serve “another_file” instead of the default “file”:

from django_downloadview import ObjectDownloadView

from demoproject.object.models import Document


another_file_view = ObjectDownloadView.as_view(
    model=Document,
    file_field='another_file')

Mapping file attributes to model’s¶

Sometimes, you use Django model to store file’s metadata. Some of this metadata can be used when you serve the file.

As an example, let’s consider the client-side basename lives in model and not in storage:

from django.db import models


class Document(models.Model):
    slug = models.SlugField()
    file = models.FileField(upload_to='object')
    basename = models.CharField(max_length=100)

Then you can configure the ObjectDownloadView.basename_field option:

from django_downloadview import ObjectDownloadView

from demoproject.object.models import Document


deserialized_basename_view = ObjectDownloadView.as_view(
    model=Document,
    basename_field='basename')

See details below for a full list of options.

API reference¶

class django_downloadview.views.object.ObjectDownloadView(**kwargs)¶

Bases: django.views.generic.detail.SingleObjectMixin, django_downloadview.views.base.BaseDownloadView

Serve file fields from models.

This class extends SingleObjectMixin, so you can use its arguments to target the instance to operate on: slug, slug_kwarg, model, queryset...

In addition to SingleObjectMixin arguments, you can set arguments related to the file to be downloaded:

• file_field;
• basename_field;
• encoding_field;
• mime_type_field;
• charset_field;
• modification_time_field;
• size_field.

file_field is the main one. Other arguments are provided for convenience, in case your model holds some (deserialized) metadata about the file, such as its basename, its modification time, its MIME type... These fields may be particularly handy if your file storage is not the local filesystem.

file_field = 'file'¶

Name of the model’s attribute which contains the file to be streamed. Typically the name of a FileField.

basename_field = None¶

Optional name of the model’s attribute which contains the basename.

encoding_field = None¶

Optional name of the model’s attribute which contains the encoding.

mime_type_field = None¶

Optional name of the model’s attribute which contains the MIME type.

charset_field = None¶

Optional name of the model’s attribute which contains the charset.

modification_time_field = None¶

Optional name of the model’s attribute which contains the modification

size_field = None¶

Optional name of the model’s attribute which contains the size.

get_file()¶

Return FieldFile instance.

The file wrapper is model’s field specified as file_field. It is typically a FieldFile or subclass.

Raises FileNotFound if instance’s field is empty.

Additional attributes are set on the file wrapper if encoding, mime_type, charset, modification_time or size are configured.

get_basename()¶

Return client-side filename.

get(request, *args, **kwargs)¶

Simple example¶

Given a storage:

from django.core.files.storage import FileSystemStorage


storage = FileSystemStorage()

Setup a view to stream files in storage:

from django_downloadview import StorageDownloadView


static_path = StorageDownloadView.as_view(storage=storage)

The view accepts a path argument you can setup either in as_view or via URLconfs:

from django.conf.urls import patterns, url

from demoproject.storage import views


urlpatterns = patterns(
    '',
    url(r'^static-path/(?P<path>[a-zA-Z0-9_-]+\.[a-zA-Z0-9]{1,4})$',
        views.static_path,
        name='static_path'),
)

Base options¶

StorageDownloadView inherits from DownloadMixin, which has various options such as basename or attachment.

Computing path dynamically¶

Override the StorageDownloadView.get_path() method to adapt path resolution to your needs.

As an example, here is the same view as above, but the path is converted to uppercase:

from django_downloadview import StorageDownloadView


class DynamicStorageDownloadView(StorageDownloadView):
    """Serve file of storage by path.upper()."""
    def get_path(self):
        """Return uppercase path."""
        return super(DynamicStorageDownloadView, self).get_path().upper()


dynamic_path = DynamicStorageDownloadView.as_view(storage=storage)

API reference¶

class django_downloadview.views.storage.StorageDownloadView(**kwargs)¶

Bases: django_downloadview.views.path.PathDownloadView

Serve a file using storage and filename.

storage = <django.core.files.storage.DefaultStorage object at 0x3de8890>¶

Storage the file to serve belongs to.

path = None¶

Path to the file to serve relative to storage.

get_path()¶

Return path of the file to serve, relative to storage.

Default implementation simply returns view’s path attribute.

Override this method if you want custom implementation.

get_file()¶

Return StorageFile instance.

Simple example¶

Setup a view to stream files given path:

import os

from django_downloadview import PathDownloadView


# Let's initialize some fixtures.
app_dir = os.path.dirname(os.path.abspath(__file__))
project_dir = os.path.dirname(app_dir)
fixtures_dir = os.path.join(project_dir, 'fixtures')
#: Path to a text file that says 'Hello world!'.
hello_world_path = os.path.join(fixtures_dir, 'hello-world.txt')

#: Serve ``fixtures/hello-world.txt`` file.
static_path = PathDownloadView.as_view(path=hello_world_path)

Base options¶

PathDownloadView inherits from DownloadMixin, which has various options such as basename or attachment.

Computing path dynamically¶

Override the PathDownloadView.get_path() method to adapt path resolution to your needs:

import os

from django_downloadview import PathDownloadView


# Let's initialize some fixtures.
app_dir = os.path.dirname(os.path.abspath(__file__))
project_dir = os.path.dirname(app_dir)
fixtures_dir = os.path.join(project_dir, 'fixtures')


class DynamicPathDownloadView(PathDownloadView):
    """Serve file in ``settings.MEDIA_ROOT``.

    .. warning::

       Make sure to prevent "../" in path via URL patterns.

    .. note::

       This particular setup would be easier to perform with
       :class:`StorageDownloadView`

    """
    def get_path(self):
        """Return path inside fixtures directory."""
        # Get path from URL resolvers or as_view kwarg.
        relative_path = super(DynamicPathDownloadView, self).get_path()
        # Make it absolute.
        absolute_path = os.path.join(fixtures_dir, relative_path)
        return absolute_path


dynamic_path = DynamicPathDownloadView.as_view()

The view accepts a path argument you can setup either in as_view or via URLconfs:

from django.conf.urls import patterns, url

from demoproject.path import views


urlpatterns = patterns(
    '',
    url(r'^dynamic-path/(?P<path>[a-zA-Z0-9_-]+\.[a-zA-Z0-9]{1,4})$',
        views.dynamic_path,
        name='dynamic_path'),
)

API reference¶

class django_downloadview.views.path.PathDownloadView(**kwargs)¶

Bases: django_downloadview.views.base.BaseDownloadView

Serve a file using filename.

path = None¶

Server-side name (including path) of the file to serve.

Filename is supposed to be an absolute filename of a file located on the local filesystem.

path_url_kwarg = 'path'¶

Name of the URL argument that contains path.

get_path()¶

Return actual path of the file to serve.

Default implementation simply returns view’s path.

Override this method if you want custom implementation. As an example, path could be relative and your custom get_path() implementation makes it absolute.

get_file()¶

Use path to return wrapper around file to serve.

Simple example¶

Setup a view to stream files given URL:

from django_downloadview import HTTPDownloadView


class SimpleURLDownloadView(HTTPDownloadView):
    def get_url(self):
        """Return URL of hello-world.txt file on GitHub."""
        return 'https://raw.github.com/benoitbryon/django-downloadview' \
               '/b7f660c5e3f37d918b106b02c5af7a887acc0111' \
               '/demo/demoproject/download/fixtures/hello-world.txt'


simple_url = SimpleURLDownloadView.as_view()

Base options¶

HTTPDownloadView inherits from DownloadMixin, which has various options such as basename or attachment.

API reference¶

class django_downloadview.views.http.HTTPDownloadView(**kwargs)¶

Bases: django_downloadview.views.base.BaseDownloadView

Proxy files that live on remote servers.

url = u''¶

URL to download (the one we are proxying).

request_kwargs = {}¶

Additional keyword arguments for request handler.

get_request_factory()¶

Return request factory to perform actual HTTP request.

Default implementation returns requests.get() callable.

get_request_kwargs()¶

Return keyword arguments for use with get_request_factory().

Default implementation returns request_kwargs.

get_url()¶

Return remote file URL (the one we are proxying).

Default implementation returns url.

get_file()¶

Return wrapper which has an url attribute.

Base options¶

VirtualDownloadView inherits from DownloadMixin, which has various options such as basename or attachment.

Serve text (string or unicode) or bytes¶

Let’s consider you build text dynamically, as a bytes or string or unicode object. Serve it with Django’s builtin ContentFile wrapper:

from django.core.files.base import ContentFile

from django_downloadview import VirtualDownloadView


class TextDownloadView(VirtualDownloadView):
    def get_file(self):
        """Return :class:`django.core.files.base.ContentFile` object."""
        return ContentFile(b"Hello world!\n", name='hello-world.txt')

Serve StringIO¶

StringIO object lives in memory. Let’s wrap it in some download view via VirtualFile:

from six import StringIO

from django_downloadview import VirtualDownloadView
from django_downloadview import VirtualFile


class StringIODownloadView(VirtualDownloadView):
    def get_file(self):
        """Return wrapper on ``StringIO`` object."""
        file_obj = StringIO(u"Hello world!\n")
        return VirtualFile(file_obj, name='hello-world.txt')

Stream generated content¶

Let’s consider you have a generator function (yield) or an iterator object (__iter__()):

def generate_hello():
    yield u'Hello '
    yield u'world!'
    yield u'\n'

Stream generated content using VirtualDownloadView, VirtualFile and StringIteratorIO:

from django_downloadview import VirtualDownloadView
from django_downloadview import VirtualFile
from django_downloadview import StringIteratorIO


class GeneratedDownloadView(VirtualDownloadView):
    def get_file(self):
        """Return wrapper on ``StringIteratorIO`` object."""
        file_obj = StringIteratorIO(generate_hello())
        return VirtualFile(file_obj, name='hello-world.txt')

API reference¶

class django_downloadview.views.virtual.VirtualDownloadView(**kwargs)¶

Bases: django_downloadview.views.base.BaseDownloadView

Serve not-on-disk or generated-on-the-fly file.

Override the get_file() method to customize file wrapper.

was_modified_since(file_instance, since)¶

Delegate to file wrapper’s was_modified_since, or return True.

This is the implementation of an edge case: when files are generated on the fly, we cannot guess whether they have been modified or not. If the file wrapper implements was_modified_since() method, then we trust it. Otherwise it is safer to suppose that the file has been modified.

This behaviour prevents file size to be computed on the Django side. Because computing file size means iterating over all the file contents, and we want to avoid that whenever possible. As an example, it could reduce all the benefits of working with dynamic file generators... which is a major feature of virtual files.

DownloadMixin¶

The django_downloadview.views.DownloadMixin class is not a view. It is a base class which you can inherit of to create custom download views.

DownloadMixin is a base of BaseDownloadView, which itself is a base of all other django_downloadview’s builtin views.

class django_downloadview.views.base.DownloadMixin¶

Bases: object

Placeholders and base implementation to create file download views.

Note

This class does not inherit from django.views.generic.base.View.

The get_file() method is a placeholder subclasses must implement. Base implementation raises NotImplementedError.

Other methods provide a base implementation that use the file wrapper returned by get_file().

response_class¶

Response class, to be used in render_to_response().

alias of DownloadResponse

attachment = True¶

Whether to return the response as attachment or not.

When True (the default), the view returns file “as attachment”, which usually triggers a “Save the file as ...” prompt.

When False, the view returns file “inline”, as if it was an element of the current page.

Note

The actual behaviour client-side depends on the browser and its configuration.

In fact, affects the “Content-Disposition” header via response's attachment attribute.

basename = None¶

Client-side filename, if only file is returned as attachment.

mimetype = None¶

File’s mime type. If None (the default), then the file’s mime type will be guessed via mimetypes.

encoding = None¶

File’s encoding. If None (the default), then the file’s encoding will be guessed via mimetypes.

get_file()¶

Return a file wrapper instance.

Raises FileNotFound if file does not exist.

get_basename()¶

Return basename.

Override this method if you need more dynamic basename.

get_mimetype()¶

Return mimetype.

Override this method if you need more dynamic mime type.

get_encoding()¶

Return encoding.

Override this method if you need more dynamic encoding.

was_modified_since(file_instance, since)¶

Return True if file_instance was modified after since.

Uses file wrapper’s was_modified_since if available, with value of since as positional argument.

Else, fallbacks to default implementation, which uses django.views.static.was_modified_since().

Django’s was_modified_since function needs a datetime and a size. It is passed modified_time and size attributes from file wrapper. If file wrapper does not support these attributes (AttributeError or NotImplementedError is raised), then the file is considered as modified and True is returned.

not_modified_response(*response_args, **response_kwargs)¶

Return django.http.HttpResponseNotModified instance.

download_response(*response_args, **response_kwargs)¶

Return DownloadResponse.

file_not_found_response()¶

Raise Http404.

render_to_response(*response_args, **response_kwargs)¶

Return “download” response (if everything is ok).

Return file_not_found_response() if file does not exist.

Respects the “HTTP_IF_MODIFIED_SINCE” header if any. In that case, uses was_modified_since() and not_modified_response().

Else, uses download_response() to return a download response.

BaseDownloadView¶

The django_downloadview.views.BaseDownloadView class is a base class to create download views. It inherits DownloadMixin and django.views.generic.base.View.

The only thing it does is to implement get: it triggers DownloadMixin's render_to_response.

class django_downloadview.views.base.BaseDownloadView(**kwargs)¶

Bases: django_downloadview.views.base.DownloadMixin, django.views.generic.base.View

A base DownloadMixin that implements get().

get(request, *args, **kwargs)¶

Handle GET requests: stream a file.

Serving a file inline rather than as attachment¶

Use attachment to make a view serve a file inline rather than as attachment, i.e. to display the file as if it was an internal part of a page rather than triggering “Save file as...” prompt.

See details in attachment API documentation.

from django_downloadview import ObjectDownloadView

from demoproject.object.models import Document


#: Serve ``file`` attribute of ``Document`` model, inline (not as attachment).
inline_file_view = ObjectDownloadView.as_view(
    model=Document,
    attachment=False)

Handling http not modified responses¶

Sometimes, you know the latest date and time the content was generated at, and you know a new request would generate exactly the same content. In such a case, you should implement was_modified_since() in your view.

As an example, the download views above always generate “Hello world!”... so, if the client already downloaded it, we can safely return some HTTP “304 Not Modified” response:

from django.core.files.base import ContentFile
from django_downloadview import VirtualDownloadView

class TextDownloadView(VirtualDownloadView):
    def get_file(self):
        """Return :class:`django.core.files.base.ContentFile` object."""
        return ContentFile(u"Hello world!", name='hello-world.txt')

    def was_modified_since(self, file_instance, since):
        return False  # Never modified, always u"Hello world!".

Django’s static file view¶

django.contrib.staticfiles provides a view to serve files [1]. It is simple and quite naive by design: it is meant for development, not for production. See Django ticket #2131 [2]: advanced file streaming is left to third-party applications.

django-downloadview is such a third-party application.

django-sendfile¶

django-sendfile [3] is a wrapper around web-server specific methods for sending files to web clients.

django-senfile‘s main focus is simplicity: API is made of a single sendfile() function you call inside your views:

from sendfile import sendfile

def hello_world(request):
     """Send 'hello-world.pdf' file as a response."""
     return sendfile(request, '/path/to/hello-world.pdf')

The download response type depends on the chosen backend, which could be Django, Lighttpd’s X-Sendfile, Nginx’s X-Accel... depending your settings:

SENDFILE_BACKEND = 'sendfile.backends.nginx'  # sendfile() will return
                                              # X-Accel responses.
# Additional settings for sendfile's nginx backend.
SENDFILE_ROOT = '/path/to'
SENDFILE_URL = '/proxied-download'

Here are main differences between the two projects:

• django-sendfile supports only files that live on local filesystem (i.e. where os.path.exists returns True). Whereas django-downloadview allows you to serve or proxy files stored in various locations, including remote ones.
• django-sendfile uses a single global configuration (i.e. settings.SENDFILE_ROOT), thus optimizations are limited to a single root folder. Whereas django-downloadview‘s DownloadDispatcherMiddleware supports multiple configurations.

References

1.6 (2014-03-03)¶

Python 3 support, development environment refactoring.

• Feature #46: introduced support for Python>=3.3.
• Feature #80: added documentation about “how to serve a file inline VS how to serve a file as attachment”. Improved documentation of views’ base options inherited from DownloadMixin.
• Feature #74: the Makefile in project’s repository no longer creates a virtualenv. Developers setup the environment as they like, i.e. using virtualenv, virtualenvwrapper or whatever. Tests are run with tox.

1.5 (2013-11-29)¶

X-Sendfile support and helpers to migrate for django-sendfile.

• Feature #2 - Introduced support of Lighttpd’s x-Sendfile.
• Feature #36 - Introduced support of Apache’s mod_xsendfile.
• Feature #41 - django_downloadview.sendfile is a port of django-sendfile‘s sendfile function. The documentation contains notes about migrating from django-sendfile to django-downloadview.

1.4 (2013-11-24)¶

Bugfixes and documentation features.

• Bugfix #43 - ObjectDownloadView returns HTTP 404 if model instance’s file field is empty (was HTTP 500).
• Bugfix #7 - Special characters in file names (Content-Disposition header) are urlencoded. An US-ASCII fallback is also provided.
• Feature #10 - django-downloadview is registered on djangopackages.com.
• Feature #65 - INSTALL documentation shows “known good set” (KGS) of versions, i.e. versions that have been used in test environment.

1.3 (2013-11-08)¶

Big refactoring around middleware configuration, API readability and documentation.

• Bugfix #57 - PathDownloadView opens files in binary mode (was text mode).

• Bugfix #48 - Fixed basename assertion in assert_download_response: checks Content-Disposition header.

• Bugfix #49 - Fixed content assertion in assert_download_response: checks only response’s streaming_content attribute.

• Bugfix #60 - VirtualFile.__iter__ uses force_bytes() to support both “text-mode” and “binary-mode” content. See https://code.djangoproject.com/ticket/21321

• Feature #50 - Introduced django_downloadview.DownloadDispatcherMiddleware that iterates over a list of configurable download middlewares. Allows to plug several download middlewares with different configurations.

  This middleware is mostly dedicated to internal usage. It is used by SmartDownloadMiddleware described below.

• Feature #42 - Documentation shows how to stream generated content (yield). Introduced django_downloadview.StringIteratorIO.

• Refactoring #51 - Dropped support of Python 2.6

• Refactoring #25 - Introduced django_downloadview.SmartDownloadMiddleware which allows to setup multiple optimization rules for one backend.

  Deprecates the following settings related to previous single-and-global middleware:

  • NGINX_DOWNLOAD_MIDDLEWARE_MEDIA_ROOT
  • NGINX_DOWNLOAD_MIDDLEWARE_MEDIA_URL
  • NGINX_DOWNLOAD_MIDDLEWARE_EXPIRES
  • NGINX_DOWNLOAD_MIDDLEWARE_WITH_BUFFERING
  • NGINX_DOWNLOAD_MIDDLEWARE_LIMIT_RATE

• Refactoring #52 - ObjectDownloadView now inherits from SingleObjectMixin and BaseDownloadView (was DownloadMixin and BaseDetailView). Simplified DownloadMixin.render_to_response() signature.

• Refactoring #40 - Documentation includes examples from demo project.

• Refactoring #39 - Documentation focuses on usage, rather than API. Improved narrative documentation.

• Refactoring #53 - Added base classes in django_downloadview.middlewares, such as ProxiedDownloadMiddleware.

• Refactoring #54 - Expose most Python API directly in django_downloadview package. Simplifies import statements in client applications. Splitted nginx module in a package.

• Added unit tests, improved code coverage.

1.2 (2013-05-28)¶

Bugfixes and documentation improvements.

• Bugfix #26 - Prevented computation of virtual file’s size, unless the file wrapper implements was_modified_since() method.
• Bugfix #34 - Improved support of files that do not implement modification time.
• Bugfix #35 - Fixed README conversion from reStructuredText to HTML (PyPI).

1.1 (2013-04-11)¶

Various improvements. Contains backward incompatible changes.

• Added HTTPDownloadView to proxy to arbitrary URL.
• Added VirtualDownloadView to support files living in memory.
• Using StreamingHttpResponse introduced with Django 1.5. Makes Django 1.5 a requirement!
• Added django_downloadview.test.assert_download_response utility.
• Download views and response now use file wrappers. Most logic around file attributes, formerly in views, moved to wrappers.
• Replaced DownloadView by PathDownloadView and StorageDownloadView. Use the right one depending on the use case.

1.0 (2012-12-04)¶

• Introduced optimizations for Nginx X-Accel: a middleware and a decorator
• Introduced generic views: DownloadView and ObjectDownloadView
• Initialized project

Notes & references