Merge pull request #106 from maurizi/mvm/doc/document-filename-parame…

…ters

Document filename parameters

README.rst

@@ -18,7 +18,7 @@ This tool was created out of repeatedly needing to do the following in django:
 
 For more detailed documentation, please read `this blog post. <http://www.azavea.com/blogs/labs/2014/03/exporting-django-querysets-to-csv/>`_
 
-installation
+Installation
 ------------
 
 Run::
@@ -27,7 +27,7 @@ Run::
 
 Supports Python 2.7 and 3.5, Django >= 1.8.
 
-usage
+Usage
 -----
 Perform all filtering and field authorization in your view using ``.filter()`` and ``.values()``.
 Then, use ``render_to_csv_response`` to turn a queryset into a response with a CSV attachment.
@@ -47,11 +47,10 @@ If you need to write the CSV to a file you can use ``write_csv`` instead::
   with open('foo.csv', 'wb') as csv_file:
     write_csv(qs, csv_file)
 
-foreign keys
+Foreign keys
 ------------
 
-Foreign keys are supported natively using ``ValuesQuerySet`` in Django. Simply use the ``__`` technique as 
-you would in the Django ORM when you pass args to the ``.values()`` method.
+Foreign keys are supported natively using ``ValuesQuerySet`` in Django. Simply use the ``__`` technique as you would in the Django ORM when you pass args to the ``.values()`` method.
 
 models.py::
 
@@ -72,18 +71,20 @@ views.py::
       people = Person.objects.values('name', 'favorite_food__name')
       return render_to_csv_response(people)
 
-keyword arguments
+Keyword arguments
 -----------------
 
-This module exports two functions that write CSVs, ``render_to_csv_response`` and ``write_csv``. Both of these functions require their own positional arguments. In addition, they both take the following optional keyword arguments:
+This module exports two functions that write CSVs, ``render_to_csv_response`` and ``write_csv``. Both of these functions require their own positional arguments as documented above. In addition, they both take the following optional keyword arguments:
 
 - ``field_header_map`` - (default: ``None``) A dictionary mapping names of model fields to column header names. If specified, the csv writer will use these column headers. Otherwise, it will use defer to other parameters for rendering column names.
 - ``field_serializer_map`` - (default: ``{}``) A dictionary mapping names of model fields to functions that serialize them to text. For example, ``{'created': (lambda x: x.strftime('%Y/%m/%d')) }`` will serialize a datetime field called ``created``.
 - ``use_verbose_names`` - (default: ``True``) A boolean determining whether to use the django field's ``verbose_name``, or to use it's regular field name as a column header. Note that if a given field is found in the ``field_header_map``, this value will take precendence.
 - ``field_order`` - (default: ``None``) A list of fields to determine the sort order. This list need not be complete: any fields not specified will follow those in the list with the order they would have otherwise used.
 
-In addition to the above arguments, ``render_to_csv_response`` takes the following optional keyword argument:
+In addition to the above arguments, ``render_to_csv_response`` takes the following optional keyword arguments:
 
+- ``filename`` - (default: ``None``) A string used to set a filename in the ``Content-Disposition`` header as part of the returned ``HttpResponse``. If this is not passed, a filename will be automatically generated based on the table name of the QuerySet.
+- ``append_datestamp`` - (default: ``False``) A boolean determining whether to append a timestamp as part of the filename set in the ``Content-Disposition`` header.
 - ``streaming`` - (default: ``True``) A boolean determining whether to use ``StreamingHttpResponse`` instead of the normal ``HttpResponse``.
 
 The remaining keyword arguments are *passed through* to the csv writer. For example, you can export a CSV with a different delimiter.
@@ -99,7 +100,7 @@ views.py::
 For more details on possible arguments, see the documentation on `DictWriter <https://docs.python.org/2/library/csv.html#csv.DictWriter>`_.
 
 
-development and contributions
+Development and contributions
 -----------------------------
 
 Please read the included ``CONTRIBUTING.rst`` file.

djqscsv/djqscsv.py

@@ -14,7 +14,7 @@
 # the rest will be passed along to the csv writer
 DJQSCSV_KWARGS = {
     'field_header_map', 'field_serializer_map', 'use_verbose_names',
-    'field_order', 'streaming'}
+    'field_order'}
 
 
 class CSVException(Exception):
@@ -31,7 +31,7 @@ def write(self, value):
 
 
 def render_to_csv_response(queryset, filename=None, append_datestamp=False,
-                           **kwargs):
+                           streaming=True, **kwargs):
     """
     provides the boilerplate for making a CSV http response.
     takes a filename or generates one from the queryset's model.
@@ -46,7 +46,7 @@ def render_to_csv_response(queryset, filename=None, append_datestamp=False,
 
     response_args = {'content_type': 'text/csv'}
 
-    if not kwargs.get('streaming', True):
+    if not streaming:
         response = HttpResponse(**response_args)
         write_csv(queryset, response, **kwargs)
     else: