mirror of
https://github.com/jazzband/django-downloadview.git
synced 2026-03-16 22:40:25 +00:00
109 lines
3.2 KiB
Text
109 lines
3.2 KiB
Text
##################
|
|
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
|