From f67757baaa7ee748a4a2b49518953b34743e0ca6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20Bryon?= Date: Thu, 11 Apr 2013 15:42:28 +0200 Subject: [PATCH] Reviewed documentation. --- README | 25 ++++++++++++++++++++----- docs/about/alternatives.txt | 35 ++++++++++++++++++++++------------- 2 files changed, 42 insertions(+), 18 deletions(-) diff --git a/README b/README index 754786b..9cfc2cb 100644 --- a/README +++ b/README @@ -3,10 +3,19 @@ django-downloadview ################### Django-DownloadView provides generic views to make Django serve files. -It supports delegation to the actual streaming to reverse proxies, via -mechanisms such as Nginx's X-Accel. -Example, in some urls.py: +It can serve files from models, storages, local filesystem, arbitrary URL... +and even generated files. + +For increased performances, it can delegate the actual streaming to a reverse +proxy, via mechanisms such as Nginx's X-Accel. + + +******* +Example +******* + +In some :file:`urls.py`, serve files managed in a model: .. code-block:: python @@ -14,7 +23,6 @@ Example, in some urls.py: from django_downloadview import ObjectDownloadView from demoproject.download.models import Document # A model with a FileField - # ObjectDownloadView inherits from django.views.generic.BaseDetailView. download = ObjectDownloadView.as_view(model=Document, file_field='file') @@ -22,13 +30,20 @@ Example, in some urls.py: url('^download/(?P[A-Za-z0-9_-]+)/$', download, name='download'), ) +More examples in the :doc:`demo project `! + + +***** +Views +***** + Several views are provided to cover frequent use cases: * ``ObjectDownloadView`` to serve some file field of a model. * ``StorageDownloadView`` to serve files in a storage, without models. * ``PathDownloadView`` to serve files located on local filesystem, without storage. -* ``HTTPDownloadView`` to proxy some remote URL. +* ``HTTPDownloadView`` to proxy some arbitrary URL. * ``VirtualDownloadView`` to serve in-memory or generated files. See :doc:`views` for details. diff --git a/docs/about/alternatives.txt b/docs/about/alternatives.txt index 96715bb..4eb8f90 100644 --- a/docs/about/alternatives.txt +++ b/docs/about/alternatives.txt @@ -30,20 +30,30 @@ django-sendfile `django-sendfile`_ is a wrapper around web-server specific methods for sending files to web clients. -API is made of a single ``sendfile()`` function. +API is made of a single ``sendfile()`` function, which returns a download +response. The download response type depends on the chosen backend, which could +be Django, Lighttpd's X-Sendfile, Nginx's X-Accel... -Views call the ``sendfile`` function. They don't care about the backend. -There, django-downloadview's class-based views return some DownloadResponse. +It seems that django-senfile main focus is simplicity: you call the +``sendfile()`` method inside your views. -Optimizations are supported via backends. Backends are configured in settings. -There, django-downloadview uses middlewares instead. +Django-downloadview main focus is reusability: you configure (or override) +class-based views depending on the use case. -It seems that django-senfile main focus is simplicity, whereas -django-downloadview main focus is reusability. You may choose -django-downloadview if you need integration with class-based views. +As of 2012-04-11, ``django-sendfile`` (version 0.3.2) seems quite popular and +may be a good alternative **provided you serve files that live in local +filesystem**, because the ``sendfile()`` method only accepts filenames relative +to local filesystem (i.e. using ``os.path.exists``). -As of 2012-12-10, ``django-sendfile`` seems quite popular and may be a good -alternative. +Django-downloadview (since version 1.1) handles file wrappers, and thus allows +you to serve files from more locations: + +* models, +* storages, +* local filesystem, +* remote URL (using `requests`_), +* in-memory (or generated) files (such as StringIO), +* ... and your custom ones with little efforts. ******************** @@ -65,15 +75,14 @@ static files via your frontend server after authorizing the user against As of 2012-12-10, this project seems inactive. -********** -References -********** +.. rubric:: References .. target-notes:: .. _`Django has a builtin static file view`: https://docs.djangoproject.com/en/1.4/ref/contrib/staticfiles/#static-file-development-view .. _`django-sendfile`: http://pypi.python.org/pypi/django-sendfile +.. _`requests`: https://pypi.python.org/pypi/requests .. _`django-private-files`: http://pypi.python.org/pypi/django-private-files .. _`django-protected-files`: https://github.com/lincolnloop/django-protected-files