From 7875999fe222b1843865dee0d41ebe2f072c563d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20Bryon?= Date: Mon, 3 Mar 2014 07:49:30 +0100 Subject: [PATCH] Refs #80 - Improved documentation about 'DownnloadMixin.attachment' attribute. --- django_downloadview/response.py | 61 ++++++++++++++----------------- django_downloadview/views/base.py | 15 ++++++++ docs/views/custom.txt | 17 +++++++++ docs/views/object.txt | 23 ------------ 4 files changed, 59 insertions(+), 57 deletions(-) diff --git a/django_downloadview/response.py b/django_downloadview/response.py index c22775f..efa9c1f 100644 --- a/django_downloadview/response.py +++ b/django_downloadview/response.py @@ -91,39 +91,7 @@ class DownloadResponse(StreamingHttpResponse): where :attr:`~django.http.StreamingHttpResponse.streaming_content` is a file wrapper. - Constructor differs a bit from :class:`~django.http.response.HttpResponse`: - - ``file_instance`` - A :doc:`file wrapper instance `, such as - :class:`~django.core.files.base.File`. - - ``attachement`` - Boolean. Whether to return the file as attachment or not. - Affects ``Content-Disposition`` header. - - ``basename`` - Unicode. Client-side name of the file to stream. - Only used if ``attachment`` is ``True``. - Affects ``Content-Disposition`` header. - - ``status`` - HTTP status code. - - ``content_type`` - Value for ``Content-Type`` header. - If ``None``, then mime-type and encoding will be populated by the - response (default implementation uses mimetypes, based on file - name). - - ``file_mimetype`` - Value for file's mimetype. If ``None`` (the default), then the file's - mimetype will be guessed via Python's :mod:`mimetypes`. See - :meth:`get_mime_type`. - - ``file_encoding`` - Value for file's encoding. If ``None`` (the default), then the file's - encoding will be guessed via Python's :mod:`mimetypes`. See - :meth:`get_encoding`. + Constructor differs a bit from :class:`~django.http.response.HttpResponse`. Here are some highlights to understand internal mechanisms and motivations: @@ -152,17 +120,42 @@ class DownloadResponse(StreamingHttpResponse): def __init__(self, file_instance, attachment=True, basename=None, status=200, content_type=None, file_mimetype=None, file_encoding=None): - """Constructor.""" + """Constructor. + + :param content_type: Value for ``Content-Type`` header. + If ``None``, then mime-type and encoding will be + populated by the response (default implementation + uses :mod:`mimetypes`, based on file name). + + """ + #: A :doc:`file wrapper instance `, such as + #: :class:`~django.core.files.base.File`. self.file = file_instance super(DownloadResponse, self).__init__(streaming_content=self.file, status=status, content_type=content_type) + + #: Client-side name of the file to stream. + #: Only used if ``attachment`` is ``True``. + #: Affects ``Content-Disposition`` header. self.basename = basename + + #: Whether to return the file as attachment or not. + #: Affects ``Content-Disposition`` header. self.attachment = attachment if not content_type: del self['Content-Type'] # Will be set later. + + #: Value for file's mimetype. + #: If ``None`` (the default), then the file's mimetype will be guessed + #: via Python's :mod:`mimetypes`. See :meth:`get_mime_type`. self.file_mimetype = file_mimetype + + #: Value for file's encoding. If ``None`` (the default), then the + #: file's encoding will be guessed via Python's :mod:`mimetypes`. See + #: :meth:`get_encoding`. self.file_encoding = file_encoding + # Apply default headers. for header, value in self.default_headers.items(): if not header in self: diff --git a/django_downloadview/views/base.py b/django_downloadview/views/base.py index 58fb04f..a8b9c82 100644 --- a/django_downloadview/views/base.py +++ b/django_downloadview/views/base.py @@ -28,6 +28,21 @@ class DownloadMixin(object): response_class = DownloadResponse #: Whether to return the response as attachment or not. + #: + #: When ``True`` (the default), the view returns file "as attachment", + #: which usually triggers a "Save the file as ..." prompt. + #: + #: When ``False``, the view returns file "inline", as if it was an element + #: of the current page. + #: + #: .. note:: + #: + #: The actual behaviour client-side depends on the browser and its + #: configuration. + #: + #: In fact, affects the "Content-Disposition" header via :attr:`response's + #: attachment attribute + #: `. attachment = True #: Client-side filename, if only file is returned as attachment. diff --git a/docs/views/custom.txt b/docs/views/custom.txt index 5ecda28..65eba35 100644 --- a/docs/views/custom.txt +++ b/docs/views/custom.txt @@ -4,6 +4,7 @@ Make your own view .. currentmodule:: django_downloadview.views.base + ************* DownloadMixin ************* @@ -41,6 +42,22 @@ The only thing it does is to implement :member-order: bysource +*********************************************** +Serving a file inline rather than as attachment +*********************************************** + +Use :attr:`~DownloadMixin.attachment` to make a view serve a file inline rather +than as attachment, i.e. to display the file as if it was an internal part of a +page rather than triggering "Save file as..." prompt. + +See details in :attr:`attachment API documentation +<~DownloadMixin.attachment>`. + +.. literalinclude:: /../demo/demoproject/object/views.py + :language: python + :lines: 1-5, 20-23 + + ************************************ Handling http not modified responses ************************************ diff --git a/docs/views/object.txt b/docs/views/object.txt index 0b71cbe..4cc3752 100644 --- a/docs/views/object.txt +++ b/docs/views/object.txt @@ -62,29 +62,6 @@ Then here is the code to serve "another_file" instead of the default "file": :lines: 1-5, 10-12 -*********************************************** -Serving a file inline rather than as attachment -*********************************************** - -You can setup :attr:`~django_downloadview.views.base.DownloadMixin.attachment` -to make a view serve a file inline rather than as attachment: - -* ``attachment`` is ``False``: inline file, which content is displayed inside - the browser, as if it was an element of the current page. - -* ``attachment`` is ``True`` (default): attached file, which usually triggers a - download, i.e. the user is prompted to "save the file as ...". - -.. literalinclude:: /../demo/demoproject/object/views.py - :language: python - :lines: 1-5, 20-23 - -.. note:: - - The actual behaviour client-side depends on browsers and their - configuration. - - ********************************** Mapping file attributes to model's **********************************