rolling out new feature: make response from a query set using pyexcel v0.1.5

chfw · chfw · commit 3a7b62df44f5 · 2015-04-29T18:48:28.000+01:00
diff --git a/db.sqlite3 b/db.sqlite3
diff --git a/django_excel/__init__.py b/django_excel/__init__.py
@@ -1,3 +1,15 @@
+"""
+    django_excel
+    ~~~~~~~~~~~~~~~~~~~
+
+    A django middleware that provides one application programming interface
+    to read and write data in different excel file formats
+
+    :copyright: (c) 2015 by Onni Software Ltd.
+    :license: New BSD License
+"""
+
+
 from django.core.files.uploadhandler import MemoryFileUploadHandler, TemporaryFileUploadHandler
 from django.core.files.uploadedfile import InMemoryUploadedFile, TemporaryUploadedFile
 from django.http import HttpResponse
@@ -11,10 +23,10 @@ def _get_file_extension(self):
         return extension
         
     def load_single_sheet(self, sheet_name=None, **keywords):
-        return pe.load_from_memory(self._get_file_extension(), self.file.read(), sheet_name, **keywords)
+        return pe.get_sheet(file_type=self._get_file_extension(), content=self.file.read(), sheet_name=sheet_name, **keywords)
 
-    def load_book(self):
-        return pe.load_book_from_memory(self._get_file_extension(), self.file.read())
+    def load_book(self, **keywords):
+        return pe.get_book(file_type=self._get_file_extension(), content=self.file.read(), **keywords)
 
     def save_to_database(self, model=None,
                          sheet_name=None, name_columns_by_row=0, name_rows_by_column=-1, **keywords):
@@ -23,12 +35,12 @@ def save_to_database(self, model=None,
                                        name_rows_by_column=name_rows_by_column,
                                        **keywords)
         if sheet:
-            sheet.save_to_django_model(model)
+            sheet.save_to_django_model(model, **keywords)
 
     def save_book_to_database(self, models=None, **keywords):
         book = self.load_book(**keywords)
         if book:
-            book.save_to_django_models(models)
+            book.save_to_django_models(models, **keywords)
 
 
 class ExcelInMemoryUploadedFile(ExcelMixin, InMemoryUploadedFile):
@@ -72,6 +84,7 @@ def new_file(self, file_name, *args, **kwargs):
     make_response_from_dict,
     make_response_from_records,
     make_response_from_book_dict,
+    make_response_from_query_sets
 )
 
 def make_response_from_a_table(model, file_type, status=200, **keywords):
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -49,16 +49,16 @@
 
 # General information about the project.
 project = u'django-excel'
-copyright = u'2015, C. W.'
+copyright = u'2015, Onni Software Ltd.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.0.1'
+version = '0.0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.0.1'
+release = '0.0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/source/custom-export.png b/doc/source/custom-export.png
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -99,7 +99,7 @@ Then run the test application::
 Handle excel file upload and download
 ++++++++++++++++++++++++++++++++++++++
 
-This example shows how to process uploaded excel file and how to make data download as an excel file. Open your browser and visit http://localhost:8000/upload, you shall see this upload form:
+This example shows how to process uploaded excel file and how to make data download as an excel file. Open your browser and visit http://localhost:8000/polls/upload, you shall see this upload form:
 
 .. image :: upload-form.png
 
@@ -125,7 +125,7 @@ Please open the file `polls/views.py <https://github.com/chfw/django-excel/blob/
 
 **UploadFileForm** is html widget for file upload form in the html page. Then look down at **filehandle**. It is an instance of either ExcelInMemoryUploadedFile or TemporaryUploadedExcelFile, which inherit ExcelMixin and hence have a list of conversion methods to call, such as get_sheet, get_array, etc.
 
-For the response, :meth:`~django_excel.make_response` converts :class:`~pyexcel.Sheet` instance obtained via :meth:`~django_excel.ExcelMixin.get_sheet` into a csv file for download.
+For the response, :meth:`~django_excel.make_response` converts :class:`pyexcel.Sheet` instance obtained via :meth:`~django_excel.ExcelMixin.get_sheet` into a csv file for download.
 
 Please feel free to change those functions according to :ref:`the mapping table <data-types-and-its-conversion-funcs>`.
 
@@ -173,7 +173,7 @@ into the following data models::
 .. note::
    Except the added "slug" field, **Question** and **Choice** are copied from Django tutoial part 1.
 
-Please visit this link http://localhost:8000/import/, you shall see this upload form:
+Please visit this link http://localhost:8000/polls/import/, you shall see this upload form:
 
 .. image:: import-page.png
 
@@ -236,7 +236,7 @@ The custom formatting function is needed when the data from the excel sheet need
 Handle data export
 ++++++++++++++++++++++++++++++
 
-This section shows how to export the data in your models as an excel file. After you have completed the previous section, you can visit http://localhost:8000/export/book and you shall get a file download dialog:
+This section shows how to export the data in your models as an excel file. After you have completed the previous section, you can visit http://localhost:8000/polls/export/book and you shall get a file download dialog:
 
 .. image:: download-dialog.png
 
@@ -253,7 +253,24 @@ Now let's examine the code behind this in `polls/views.py <https://github.com/ch
         elif atype == "book":
             return excel.make_response_from_tables([Question, Choice], 'xls')
         
-:meth:`~django_excel.make_response_from_tables` does all what is needed: read out the data, convert them into xls and give it the browser. And what you need to do is to give a list of models to be exported and a file type. As you have noticed, you can visit http://localhost:8000/exportsheet and will get **Question** exported as a single sheet file.
+:meth:`~django_excel.make_response_from_tables` does all what is needed: read out the data, convert them into xls and give it the browser. And what you need to do is to give a list of models to be exported and a file type. As you have noticed, you can visit http://localhost:8000/polls/export/sheet and will get **Question** exported as a single sheet file.
+
+Handle custom data export
++++++++++++++++++++++++++++++++
+
+It is also quite common to download a portion of the data in a database table, for example the result of a search query. With version 0.0.2, you can pass on a query sets to to :meth:`~django_excel.make_response_from_query_sets` and generate an excel sheet from it::
+
+    def export_data(request, atype):
+	    ...
+        elif atype == "custom":
+            question = Question.objects.get(slug='ide')
+            query_sets = Choice.objects.filter(question=question)
+            column_names = ['choice_text', 'id', 'votes']
+            return excel.make_response_from_query_sets(query_sets, column_names, 'xls')
+
+You can visit http://localhost:8000/polls/export/custom and will get the query set exported as a single sheet file as:
+
+.. image:: custom-export.png
 
 .. _data-types-and-its-conversion-funcs:
 
@@ -262,18 +279,19 @@ All supported data types
 
 Here is table of functions for all supported data types:
 
-=========================== ======================================================== ==================================================
+=========================== ======================================================== ===================================================
 data structure              from file to data structures                             from data structures to response
-=========================== ======================================================== ==================================================
+=========================== ======================================================== ===================================================
 dict                        :meth:`~django_excel.ExcelMixin.get_dict`                :meth:`~django_excel.make_response_from_dict`
 records                     :meth:`~django_excel.ExcelMixin.get_records`             :meth:`~django_excel.make_response_from_records`
 a list of lists             :meth:`~django_excel.ExcelMixin.get_array`               :meth:`~django_excel.make_response_from_array`
 dict of a list of lists     :meth:`~django_excel.ExcelMixin.get_book_dict`           :meth:`~django_excel.make_response_from_book_dict`
-:class:`~pyexcel.Sheet`     :meth:`~django_excel.ExcelMixin.get_sheet`               :meth:`~django_excel.make_response`
-:class:`~pyexcel.Book`      :meth:`~django_excel.ExcelMixin.get_book`                :meth:`~django_excel.make_response`
+:class:`pyexcel.Sheet`      :meth:`~django_excel.ExcelMixin.get_sheet`               :meth:`~django_excel.make_response`
+:class:`pyexcel.Book`       :meth:`~django_excel.ExcelMixin.get_book`                :meth:`~django_excel.make_response`
 database table              :meth:`~django_excel.ExcelMixin.save_to_database`        :meth:`~django_excel.make_response_from_a_table` 
-a list of database tables   :meth:`~django_excel.ExcelMixin.save_book_to_database`   :meth:`~django_excel.make_response_from_tables` 
-=========================== ======================================================== ==================================================
+a list of database tables   :meth:`~django_excel.ExcelMixin.save_book_to_database`   :meth:`~django_excel.make_response_from_tables`
+a database query sets                                                                :meth:`~django_excel.make_response_from_query_sets`
+=========================== ======================================================== ===================================================
 
 See more examples of the data structures in :ref:`pyexcel documentation<pyexcel:a-list-of-data-structures>`
 
@@ -291,7 +309,7 @@ API Reference
       :param sheet_name: For an excel book, there could be multiple sheets. If it is left
                          unspecified, the sheet at index 0 is loaded. For 'csv', 'tsv' file,
                          *sheet_name* should be None anyway.
-      :param keywords: additional keywords to pyexcel library
+      :param keywords: additional keywords to :meth:`pyexcel.get_sheet`
       :returns: A sheet object
 
    .. method:: get_array(sheet_name=None, **keywords)
@@ -324,27 +342,19 @@ API Reference
       :param keywords: additional keywords to pyexcel library
       :returns: a two dimensional array, a list of lists
 
-   .. method:: save_to_database(table=None, **keywords)
-
-      :param table: a database table or a tuple which have this sequence (table, table_init_func, mapdict, name_columns_by_row, name_rows_by_column)
+   .. method:: save_to_database(model=None, initializer=None, mapdict=None, **keywords)
 
-                     ==================== =================================================================================
-                     Field                Description
-                     ==================== =================================================================================
-                     table_init_funcs     it is needed when your table had custom __init__ function
-                     mapdict              model column names
-                     name_columns_by_row  use a row to name columns. if you use name_rows_by_column, please set this to -1
-                     name_rows_by_column  uses a column to name rows.
-                     ==================== =================================================================================
+      :param model: a django model
+      :param initializer: a custom table initialization function if you have one
+      :param mapdict: the explicit table column names if your excel data do not have the exact column names
+      :param keywords: additional keywords to :meth:`pyexcel.Sheet.save_to_django_model`
 
-      :param keywords: additional keywords to pyexcel library
-
-
-   .. method:: save_book_to_database(tables=None, **keywords)
-
-      :param tables: a list of database tables or tuples which have this sequence (table, table_init_func, mapdict, name_columns_by_row, name_rows_by_column), see :meth:`~ExcelMixin.save_to_database`
-      :param keywords: additional keywords to pyexcel library
+   .. method:: save_book_to_database(models=None, initializers=None, mapdicts=None, **keywords)
 
+      :param models: a list of django models
+      :param initializers: a list of model initialization functions.
+      :param mapdicts: a list of explicit table column names if your excel data sheets do not have the exact column names
+      :param keywords: additional keywords to :meth:`pyexcel.Book.save_to_django_models`
 
 Response methods
 -----------------
@@ -353,7 +363,7 @@ Response methods
 
    .. method:: make_response(pyexcel_instance, file_type, status=200)
 
-      :param pyexcel_instance: pyexcel.Sheet or pyexcel.Book
+      :param pyexcel_instance: :class:`pyexcel.Sheet` or :class:`pyexcel.Book`
       :param file_type: one of the following strings:
                         
                         * 'csv'
@@ -393,9 +403,19 @@ Response methods
       :param status: same as :meth:`~django_excel.make_response`
 
    .. autofunction:: make_response_from_a_table(model, file_type status=200)
-   .. autofunction:: make_response_from_tables(models, file_type status=200)
 
 
+   .. method:: make_response_from_query_sets(query_sets, column_names, file_type status=200)
+
+      Produce a single sheet Excel book of *file_type* from your custom database queries
+
+      :param query_sets: a query set
+      :param column_names: a nominated column names. It could not be None, otherwise no data is returned.
+      :param file_type: same as :meth:`~django_excel.make_response`
+      :param status: same as :meth:`~django_excel.make_response`
+
+   .. autofunction:: make_response_from_tables(models, file_type status=200)
+
 Indices and tables
 --------------------
 
diff --git a/polls/views.py b/polls/views.py
@@ -50,7 +50,12 @@ def export_data(request, atype):
         return excel.make_response_from_a_table(Question, 'xls')
     elif atype == "book":
         return excel.make_response_from_tables([Question, Choice], 'xls')
-    
+    elif atype == "custom":
+        question = Question.objects.get(slug='ide')
+        query_sets = Choice.objects.filter(question=question)
+        column_names = ['choice_text', 'id', 'votes']
+        return excel.make_response_from_query_sets(query_sets, column_names, 'xls')
+
 def import_data(request):
     if request.method == "POST":
         form = UploadFileForm(request.POST, request.FILES)
@@ -60,9 +65,11 @@ def choice_func(row):
             return row
         if form.is_valid():
             request.FILES['file'].save_book_to_database(
-                models=[
-                    (Question, ['question_text', 'pub_date', 'slug'], None, 0),
-                    (Choice, ['question', 'choice_text', 'votes'], choice_func, 0) 
+                models=[Question, Choice],
+                initializers=[None, choice_func],
+                mapdicts=[
+                    ['question_text', 'pub_date', 'slug'],
+                    ['question', 'choice_text', 'votes']
                  ]
                 )
             return HttpResponse("OK", status=200)
@@ -85,8 +92,8 @@ def import_dataa(request):
         form = UploadFileForm(request.POST, request.FILES)
         if form.is_valid():
             request.FILES['file'].save_to_database(
-                model=(Question,
-                       ['question_text', 'pub_date']))
+                model=Question,
+                mapdict=['question_text', 'pub_date'])
             return HttpResponse("OK")
         else:
             return HttpResponseBadRequest()
diff --git a/setup.py b/setup.py
@@ -9,25 +9,26 @@
     README_txt = readme.read()
 
 dependencies = [
-    'pyexcel>=0.1.3',
+    'pyexcel>=0.1.5',
+    'pyexcel-webio>=0.0.2',
     'Django>=1.7.1'
 ]
 
 setup(
     name='django-excel',
     author="C. W.",
-    version='0.0.1',
+    version='0.0.2',
     author_email="wangc_2011@hotmail.com",
     url="https://github.com/chfw/django-excel",
-    description='A django library to read, manipulate and write data in different excel formats: csv, ods, xls, xlsx and xlsm.',
+    description='A django middleware that provides one application programming interface to read and write data in different excel file formats',
     install_requires=dependencies,
     packages=find_packages(exclude=['ez_setup', 'examples', 'tests', 'mysite', 'polls', 'migrations']),
     include_package_data=True,
     long_description=README_txt,
     zip_safe=False,
     tests_require=['nose'],
     keywords=['API', 'Django', 'Excel'],
-    license='GNU GPLv3 or BSD',
+    license='New BSD',
     classifiers=[
         'Development Status :: 3 - Alpha',
         'Environment :: Web Environment',
diff --git a/testResponse.py b/testResponse.py
@@ -55,7 +55,7 @@ def test_download(self):
             print(file_type)
             response = self.client.get("/polls/download/"+file_type)
             assert response['Content-Type'] == FILE_TYPE_MIME_TABLE[file_type]
-            sheet = pe.load_from_memory(file_type, response.content)
+            sheet = pe.get_sheet(file_type=file_type, content=response.content)
             sheet.format(int)
             array = sheet.to_array()
             assert array == self.data
@@ -106,7 +106,7 @@ def test_exchange(self):
                     response = self.client.post('/polls/exchange/'+file_type,
                                                 data={"file": fp})
                     assert response['Content-Type'] == FILE_TYPE_MIME_TABLE[file_type]
-                    sheet = pe.load_from_memory(file_type, response.content)
+                    sheet = pe.get_sheet(file_type=file_type, content=response.content)
                     sheet.format(int)
                     array = sheet.to_array()
                     assert array == self.data
@@ -125,7 +125,7 @@ def testBook(self):
         assert response.status_code == 200
         response2 = self.client.get('/polls/export/book')
         assert response2.status_code == 200
-        book = pe.load_book_from_memory('xls', response2.content)
+        book = pe.get_book(file_type='xls', content=response2.content)
         content = dedent("""
         Sheet Name: question
         +----+---------------------------+----------------------------------------------+----------+
@@ -161,7 +161,7 @@ def testSheet(self):
         assert response.status_code == 200
         response2 = self.client.get('/polls/export/sheet')
         assert response2.status_code == 200
-        sheet = pe.load_from_memory('xls', response2.content)
+        sheet = pe.get_sheet(file_type='xls', content=response2.content)
         content = dedent("""
         Sheet Name: question
         +----+---------------------------+----------------------------------------------+----------+
@@ -173,6 +173,28 @@ def testSheet(self):
         +----+---------------------------+----------------------------------------------+----------+""").strip('\n')
         assert str(sheet) == content
 
+    def testCustomExport(self):
+        fp = open(self.testfile, "rb")
+        response = self.client.post('/polls/import/', data={"file": fp})
+        assert response.status_code == 200
+        response2 = self.client.get('/polls/export/custom')
+        assert response2.status_code == 200
+        sheet = pe.get_sheet(file_type='xls', content=response2.content)
+        content = dedent("""
+        Sheet Name: pyexcel_sheet1
+        +---------------+----+-------+
+        | choice_text   | id | votes |
+        +---------------+----+-------+
+        | Eclipse       | 4  | 0     |
+        +---------------+----+-------+
+        | Visual Studio | 5  | 0     |
+        +---------------+----+-------+
+        | PyCharm       | 6  | 0     |
+        +---------------+----+-------+
+        | IntelliJ      | 7  | 0     |
+        +---------------+----+-------+""").strip('\n')
+        assert str(sheet) == content
+
 
 @override_settings(FILE_UPLOAD_MAX_MEMORY_SIZE=1)
 class ExcelResponseUsingFileTestCase(ExcelResponseTestCase):
