##################
Overview, concepts
##################

Given:

* you manage files with Django (permissions, filters, generation, ...)

* files are stored somewhere or generated somehow (local filesystem, remote
  storage, memory...)

As a developer, you want to serve files quick and efficiently.

Here is an overview of `django-downloadview`'s answer...


************************************
Generic views cover commons patterns
************************************

Choose the generic view depending on the file you want to serve:

* :doc:`/views/object`: file field in a model;
* :doc:`/views/storage`: file in a storage;
* :doc:`/views/path`: absolute filename on local filesystem;
* :doc:`/views/http`: file at URL (the resource is proxied);
* :doc:`/views/virtual`: bytes, text, file-like objects, generated files...


*************************************************
Generic views and mixins allow easy customization
*************************************************

If your use case is a bit specific, you can easily extend the views above or
:doc:`create your own based on mixins </views/custom>`.


*****************************
Views return DownloadResponse
*****************************

Views return :py:class:`~django_downloadview.response.DownloadResponse`. It is
a special :py:class:`django.http.StreamingHttpResponse` where content is
encapsulated in a file wrapper.

Learn more in :doc:`responses`.


***********************************
DownloadResponse carry file wrapper
***********************************

Views instanciate a :doc:`file wrapper </files>` and use it to initialize
responses.

**File wrappers describe files**: they carry files properties such as name,
size, encoding...

**File wrappers implement loading and iterating over file content**. Whenever
possible, file wrappers do not embed file data, in order to save memory.

Learn more about available file wrappers in :doc:`files`.


*****************************************************************
Middlewares convert DownloadResponse into ProxiedDownloadResponse
*****************************************************************

Before WSGI application use file wrapper and actually use file contents,
middlewares or decorators) are given the opportunity to capture
:class:`~django_downloadview.response.DownloadResponse` instances.

Let's take this opportunity to optimize file loading and streaming!

A good optimization it to delegate streaming to a reverse proxy, such as
`nginx`_ via `X-Accel`_ internal redirects. This way, Django doesn't load file
content in memory.

`django_downloadview` provides middlewares that convert
:class:`~django_downloadview.response.DownloadResponse` into
:class:`~django_downloadview.response.ProxiedDownloadResponse`.

Learn more in :doc:`optimizations/index`.


***************
Testing matters
***************

`django-downloadview` also helps you :doc:`test the views you customized
<testing>`.

You may also :doc:`write healthchecks </healthchecks>` to make sure everything
goes fine in live environments.


************
What's next?
************

Let's :doc:`install django-downloadview <install>`.


.. rubric:: Notes & references

.. target-notes::

.. _`nginx`: http://nginx.org
.. _`X-Accel`: http://wiki.nginx.org/X-accel
