##############
Download views
##############

This section contains narrative overview about class-based views provided by
django-downloadview.

By default, all of those views would stream the file to the client.
But keep in mind that you can setup :doc:`/optimizations/index` to delegate
actual streaming to a reverse proxy.


*************
DownloadMixin
*************

The :py:class:`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.


****************
BaseDownloadView
****************

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

The only thing it does is to implement
:py:meth:`get <django_downloadview.views.BaseDownloadView.get>`: it triggers
:py:meth:`DownloadMixin's render_to_response
<django_downloadview.views.DownloadMixin.render_to_response>`.


******************
ObjectDownloadView
******************

The :py:class:`django_downloadview.views.ObjectDownloadView` class-based view
allows you to **serve files given a model with some file fields** such as
FileField or ImageField.

Use this view anywhere you could use Django's builtin ObjectDetailView.

Some options allow you to store file metadata (size, content-type, ...) in the
model, as deserialized fields.


*******************
StorageDownloadView
*******************

The :py:class:`django_downloadview.views.StorageDownloadView` class-based view
allows you to **serve files given a storage and a path**.

Use this view when you manage files in a storage (which is a good practice),
unrelated to a model.


****************
PathDownloadView
****************

The :py:class:`django_downloadview.views.PathDownloadView` class-based view
allows you to **serve files given an absolute path on local filesystem**.

Two main use cases:

* as a shortcut. This dead-simple view is straight to call, so you can use it
  to simplify code in more complex views, provided you have an absolute path to
  a local file.

* override. Extend :py:class:`django_downloadview.views.PathDownloadView` and
  override :py:meth:`django_downloadview.views.PathDownloadView:get_path`.


****************
HTTPDownloadView
****************

The :py:class:`django_downloadview.views.HTTPDownloadView` class-based view
allows you to **serve files given an URL**. That URL is supposed to be
downloadable from the Django server.

Use it when you want to setup a proxy to remote files:

* the Django view filters input and computes target URL.
* if you setup optimizations, Django itself doesn't proxies the file,
* but, as a fallback, Django uses `requests`_ to proxy the file.

Extend :py:class:`django_downloadview.views.HTTPDownloadView` then
override :py:meth:`django_downloadview.views.HTTPDownloadView:get_url`.


*******************
VirtualDownloadView
*******************

The :py:class:`django_downloadview.views.VirtualDownloadView` class-based view
allows you to **serve files that don't live on disk**.

Use it when you want to stream a file which content is dynamically generated
or which lives in memory.


.. rubric:: References

.. target-notes::

.. _`requests`: https://pypi.python.org/pypi/requests