Merge pull request #1463 from xlwings/table-update-fix

aligned the table.update method with the standard behavior of writing…

docs/reports.rst

@@ -101,7 +101,7 @@ will generate this report:
 Excel Tables
 ------------
 
-Using Excel tables is the recommended way to format tables as the styling can be applied dynamically across columns and rows. You can also use themes and apply alternating colors to rows/columns. Go to ``Insert`` > ``Table`` and make sure that you activate ``My table has headers`` before clicking on ``OK``. Add the placeholder as usual on the top-left of your Excel table:
+Using Excel tables is the recommended way to format tables as the styling can be applied dynamically across columns and rows. You can also use themes and apply alternating colors to rows/columns. On top of that, they are the easiest way to make the source of a chart dynamic. Go to ``Insert`` > ``Table`` and make sure that you activate ``My table has headers`` before clicking on ``OK``. Add the placeholder as usual on the top-left of your Excel table:
 
 .. figure:: images/excel_table_template.png
     :scale: 60%
@@ -115,14 +115,14 @@ Running the following script::
     df = pd.DataFrame(data=nrows * [ncols * ['test']],
                       columns=['col ' + str(i) for i in range(ncols)])
 
-    create_report('template.xlsx', 'output.xlsx', df=df)
+    create_report('template.xlsx', 'output.xlsx', df=df.set_index('col 0'))
 
 Will produce the following report:
 
 .. figure:: images/excel_table_report.png
     :scale: 60%
 
 .. note::
-    * When using Excel tables, DataFrame indices are excluded by default. If you would like to include them, make sure to reset the index before providing the DataFrame to the ``create_report`` function: ``df.reset_index()``.
+    * If you would like to exclude the DataFrame index, make sure to set the index to the first column e.g.: ``df.set_index('column_name')``.
     * At the moment, you can only assign pandas DataFrames to tables.
-    * For Excel table support, you need at least version 0.21.0
+    * For Excel table support, you need at least version 0.21.0 and the index behavior was changed in 0.21.3

docs/whatsnew.rst

@@ -1,6 +1,11 @@
 What's New
 ==========
 
+v0.21.3 (Nov 22, 2020)
+----------------------
+
+* :guilabel:`PRO` **Breaking Change**: The :meth:`Table.update <xlwings.main.Table.update>` method has been changed to treat the DataFrame's index consistently whether or not it's being written to an Excel table: by default, the index is now transferred to Excel in both cases.
+
 v0.21.2 (Nov 15, 2020)
 ----------------------
 

xlwings/main.py

@@ -2342,7 +2342,7 @@ class Table:
     >>> sht.tables[0]  # or sht.tables['TableName']
     <Table 'Table 1' in <Sheet [Book1]Sheet1>>
 
-    .. versionchanged:: 0.21.0
+    .. versionadded:: 0.21.0
     """
     def __init__(self, *args, **options):
         impl = options.pop('impl', None)
@@ -2500,12 +2500,14 @@ def update(self, data):
 
         Updates the Excel table with the provided data. Currently restricted to DataFrames.
 
+        .. versionchanged:: 0.21.3
+
         Arguments
         ---------
 
         data : pandas DataFrame
-            Currently restricted to pandas DataFrames. Note that the DataFrame index is not
-            sent to Excel. If you do want to include it, make sure to do ``df.reset_index()``.
+            Currently restricted to pandas DataFrames. If you want to hide the index,
+            set the first column as the index, e.g. ``df.set_index('column_name')``.
 
         Returns
         -------
@@ -2527,7 +2529,9 @@ def update(self, data):
             df = pd.DataFrame(data=nrows * [ncols * ['test']],
                               columns=['col ' + str(i) for i in range(ncols)])
 
-            # Insert a new table if it doesn't exist yet, otherwise update the existing one
+            # Hide the index, then insert a new table if it doesn't exist yet,
+            # otherwise update the existing one
+            df = df.set_index('col 0')
             if table_name in [table.name for table in sheet.tables]:
                 sheet.tables[table_name].update(df)
             else:

xlwings/pro/tables.py

@@ -14,8 +14,8 @@ def update(self, data):
             self.range[:, len(self.range.columns) - col_diff:].delete()
         if self.data_body_range:
             self.data_body_range.delete()
-        self.range[1:, :].options(index=False, header=False).value = data
-        self.header_row_range.value = list(data.columns)
+        self.header_row_range.value = list(data.index.names) + list(data.columns)
+        self.range[1:, :].options(index=True, header=False).value = data
         return self
     else:
         raise TypeError(type_error_msg)