################## 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 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 ` 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 `. You may also :doc:`write healthchecks ` to make sure everything goes fine in live environments. ************ What's next? ************ Let's :doc:`install django-downloadview `. .. rubric:: Notes & references .. target-notes:: .. _`nginx`: http://nginx.org .. _`X-Accel`: http://wiki.nginx.org/X-accel