Refs #80 - Improved documentation about 'DownnloadMixin.attachment' attribute.

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 </files>`, 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 </files>`, 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:

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
+    #: <django_downloadview.response.DownloadResponse.attachment>`.
     attachment = True
 
     #: Client-side filename, if only file is returned as attachment.

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
 ************************************

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
 **********************************