From 3cdb8b36b963a45543451f4f97e7aaf99d736795 Mon Sep 17 00:00:00 2001 From: robmarkcole Date: Sat, 10 Mar 2018 15:50:17 +0000 Subject: [PATCH 1/7] Fix to_excel parameters --- pandas/core/generic.py | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a893b2ba1a189..261632d5b17e4 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1591,52 +1591,57 @@ def _repr_latex_(self): # I/O Methods _shared_docs['to_excel'] = """ - Write %(klass)s to an excel sheet + Write %(klass)s to an excel sheet. %(versionadded_to_excel)s - Parameters ---------- excel_writer : string or ExcelWriter object - File path or existing ExcelWriter + File path or existing ExcelWriter. sheet_name : string, default 'Sheet1' - Name of sheet which will contain DataFrame + Name of sheet which will contain DataFrame. na_rep : string, default '' - Missing data representation + Missing data representation. float_format : string, default None - Format string for floating point numbers + Format string for floating point numbers. columns : sequence, optional - Columns to write + Columns to write. header : boolean or list of string, default True Write out the column names. If a list of strings is given it is - assumed to be aliases for the column names + assumed to be aliases for the column names. index : boolean, default True - Write row names (index) + Write row names (index). index_label : string or sequence, default None Column label for index column(s) if desired. If None is given, and `header` and `index` are True, then the index names are used. A sequence should be given if the DataFrame uses MultiIndex. - startrow : - upper left cell row to dump data frame - startcol : - upper left cell column to dump data frame + startrow : integer, default 0 + Upper left cell row to dump data frame. + startcol : integer, default 0 + Upper left cell column to dump data frame. engine : string, default None - write engine to use - you can also set this via the options + Write engine to use - you can also set this via the options ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and ``io.excel.xlsm.writer``. merge_cells : boolean, default True Write MultiIndex and Hierarchical Rows as merged cells. - encoding: string, default None - encoding of the resulting excel file. Only necessary for xlwt, + encoding : string, default 'ascii' + Encoding of the resulting excel file. Only necessary for xlwt, other writers support unicode natively. inf_rep : string, default 'inf' Representation for infinity (there is no native representation for - infinity in Excel) + infinity in Excel). + verbose : boolean, default True + Display more information in the error logs. freeze_panes : tuple of integer (length 2), default None Specifies the one-based bottommost row and rightmost column that - is to be frozen + is to be frozen. .. versionadded:: 0.20.0 + Returns + ------- + Nothing returned. + Notes ----- If passing an existing ExcelWriter object, then the sheet will be added From 0e9f733e91143e20b17b7f27f9c4f4ec105c8b68 Mon Sep 17 00:00:00 2001 From: robmarkcole Date: Sat, 10 Mar 2018 20:26:43 +0000 Subject: [PATCH 2/7] Extend example, add Also --- pandas/core/generic.py | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 261632d5b17e4..297056d31f1e4 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1592,7 +1592,11 @@ def _repr_latex_(self): _shared_docs['to_excel'] = """ Write %(klass)s to an excel sheet. - %(versionadded_to_excel)s + + To write a %(klass)s to an excel .xlsx file it is necessary to first create + an ExcelWriter object with a target file name, and specify a sheet in the + file to write to. + Parameters ---------- excel_writer : string or ExcelWriter object @@ -1636,22 +1640,32 @@ def _repr_latex_(self): Specifies the one-based bottommost row and rightmost column that is to be frozen. - .. versionadded:: 0.20.0 + .. versionadded:: 0.20.0. Returns ------- Nothing returned. - Notes - ----- + See Also + -------- + pd.read_excel + + Examples + -------- + + >>> df1 = pd.DataFrame([['a', 'b'], ['c', 'd']], + ... index=['row 1', 'row 2'], + ... columns=['col 1', 'col 2']) + >>> writer = pd.ExcelWriter('output.xlsx', engine='xlsxwriter') + >>> df1.to_excel(writer, sheet_name='Sheet1') + >>> writer.save() + If passing an existing ExcelWriter object, then the sheet will be added to the existing workbook. This can be used to save different DataFrames to one workbook: - >>> writer = pd.ExcelWriter('output.xlsx') - >>> df1.to_excel(writer,'Sheet1') + >>> df2 = df1.copy() >>> df2.to_excel(writer,'Sheet2') - >>> writer.save() For compatibility with to_csv, to_excel serializes lists and dicts to strings before writing. From 8eb83308df2dba3bd5babf1929f554ca8f7b35b2 Mon Sep 17 00:00:00 2001 From: robmarkcole Date: Sat, 10 Mar 2018 20:57:45 +0000 Subject: [PATCH 3/7] Extend summary --- pandas/core/generic.py | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 297056d31f1e4..54b6a4a66d40b 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1595,7 +1595,11 @@ def _repr_latex_(self): To write a %(klass)s to an excel .xlsx file it is necessary to first create an ExcelWriter object with a target file name, and specify a sheet in the - file to write to. + file to write to. Multiple sheets may be written to by + specifying unique sheet_name. With all data written to the file it is + necessary to save the changes. Note that creating an ExcelWriter object + with a file name that already exists will result in the contents of the + existing file being erased. Parameters ---------- @@ -1664,8 +1668,11 @@ def _repr_latex_(self): to the existing workbook. This can be used to save different DataFrames to one workbook: + >>> writer2 = pd.ExcelWriter('output2.xlsx', engine='xlsxwriter') + >>> df1.to_excel(writer2, sheet_name='Sheet1') >>> df2 = df1.copy() - >>> df2.to_excel(writer,'Sheet2') + >>> df2.to_excel(writer2, sheet_name='Sheet2') + >>> writer2.save() For compatibility with to_csv, to_excel serializes lists and dicts to strings before writing. From 48116e253ad048e96f66e362166c8b620f81d844 Mon Sep 17 00:00:00 2001 From: robmarkcole Date: Tue, 13 Mar 2018 21:09:39 +0000 Subject: [PATCH 4/7] Address reviewer comments --- pandas/core/generic.py | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 54b6a4a66d40b..e5674166ae587 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1611,7 +1611,7 @@ def _repr_latex_(self): Missing data representation. float_format : string, default None Format string for floating point numbers. - columns : sequence, optional + columns : sequence or list of string, optional Columns to write. header : boolean or list of string, default True Write out the column names. If a list of strings is given it is @@ -1627,12 +1627,12 @@ def _repr_latex_(self): startcol : integer, default 0 Upper left cell column to dump data frame. engine : string, default None - Write engine to use - you can also set this via the options - ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and + Write engine to use, 'openpyxl' or 'xlsxwriter'. You can also set this + via the options ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and ``io.excel.xlsm.writer``. merge_cells : boolean, default True Write MultiIndex and Hierarchical Rows as merged cells. - encoding : string, default 'ascii' + encoding : string, default None Encoding of the resulting excel file. Only necessary for xlwt, other writers support unicode natively. inf_rep : string, default 'inf' @@ -1646,13 +1646,9 @@ def _repr_latex_(self): .. versionadded:: 0.20.0. - Returns - ------- - Nothing returned. - See Also -------- - pd.read_excel + pandas.read_excel Examples -------- @@ -1674,6 +1670,9 @@ def _repr_latex_(self): >>> df2.to_excel(writer2, sheet_name='Sheet2') >>> writer2.save() + Limit floats to a fixed precision using float_format. For example + float_format="%.2f" will format 0.1234 to 0.12. + For compatibility with to_csv, to_excel serializes lists and dicts to strings before writing. """ From 69921c6a28e0b8bcbdcd8be142bb241f514cb519 Mon Sep 17 00:00:00 2001 From: robmarkcole Date: Wed, 14 Mar 2018 10:18:52 +0000 Subject: [PATCH 5/7] Address second round of comments --- pandas/core/generic.py | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index e5674166ae587..8cd4deac9c833 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1594,9 +1594,9 @@ def _repr_latex_(self): Write %(klass)s to an excel sheet. To write a %(klass)s to an excel .xlsx file it is necessary to first create - an ExcelWriter object with a target file name, and specify a sheet in the + an `ExcelWriter` object with a target file name, and specify a sheet in the file to write to. Multiple sheets may be written to by - specifying unique sheet_name. With all data written to the file it is + specifying unique `sheet_name`. With all data written to the file it is necessary to save the changes. Note that creating an ExcelWriter object with a file name that already exists will result in the contents of the existing file being erased. @@ -1653,28 +1653,30 @@ def _repr_latex_(self): Examples -------- + Create, write to and save a workbook: + >>> df1 = pd.DataFrame([['a', 'b'], ['c', 'd']], ... index=['row 1', 'row 2'], ... columns=['col 1', 'col 2']) - >>> writer = pd.ExcelWriter('output.xlsx', engine='xlsxwriter') - >>> df1.to_excel(writer, sheet_name='Sheet1') - >>> writer.save() + >>> df1.to_excel("output.xlsx", sheet_name='Sheet1') - If passing an existing ExcelWriter object, then the sheet will be added - to the existing workbook. This can be used to save different - DataFrames to one workbook: + If you wish to write to more than one sheet in the workbook, it is + necessary to specify an ExcelWriter object: - >>> writer2 = pd.ExcelWriter('output2.xlsx', engine='xlsxwriter') - >>> df1.to_excel(writer2, sheet_name='Sheet1') + >>> writer = pd.ExcelWriter('output2.xlsx', engine='xlsxwriter') + >>> df1.to_excel(writer, sheet_name='Sheet1') >>> df2 = df1.copy() - >>> df2.to_excel(writer2, sheet_name='Sheet2') - >>> writer2.save() + >>> df2.to_excel(writer, sheet_name='Sheet2') + >>> writer.save() + + Note that once a workbook has been saved it is not possible write further + data without rewriting the whole workbook. Limit floats to a fixed precision using float_format. For example float_format="%.2f" will format 0.1234 to 0.12. - For compatibility with to_csv, to_excel serializes lists and dicts to - strings before writing. + For compatibility with `to_csv `__ , + to_excel serializes lists and dicts to strings before writing. """ def to_json(self, path_or_buf=None, orient=None, date_format=None, From 6755281e7d0073b7697b8c88a57f1428065fdd97 Mon Sep 17 00:00:00 2001 From: robmarkcole Date: Wed, 4 Apr 2018 05:32:39 +0100 Subject: [PATCH 6/7] Address comments Address comments of @jorisvandenbossche --- pandas/core/generic.py | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 8cd4deac9c833..1893ef6544ec2 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1593,9 +1593,10 @@ def _repr_latex_(self): _shared_docs['to_excel'] = """ Write %(klass)s to an excel sheet. - To write a %(klass)s to an excel .xlsx file it is necessary to first create - an `ExcelWriter` object with a target file name, and specify a sheet in the - file to write to. Multiple sheets may be written to by + To write a single %(klass)s to an excel .xlsx file it is only necessary to + specify a target file name. To write to multiple sheets it is necessary to + create an `ExcelWriter` object with a target file name, and specify a sheet + in the file to write to. Multiple sheets may be written to by specifying unique `sheet_name`. With all data written to the file it is necessary to save the changes. Note that creating an ExcelWriter object with a file name that already exists will result in the contents of the @@ -1649,6 +1650,7 @@ def _repr_latex_(self): See Also -------- pandas.read_excel + pandas.ExcelWriter Examples -------- @@ -1658,7 +1660,11 @@ def _repr_latex_(self): >>> df1 = pd.DataFrame([['a', 'b'], ['c', 'd']], ... index=['row 1', 'row 2'], ... columns=['col 1', 'col 2']) - >>> df1.to_excel("output.xlsx", sheet_name='Sheet1') + >>> df1.to_excel("output.xlsx") + + To specify the sheet name: + + >>> df1.to_excel("output.xlsx", sheet_name='Sheet_name_1') If you wish to write to more than one sheet in the workbook, it is necessary to specify an ExcelWriter object: @@ -1673,9 +1679,9 @@ def _repr_latex_(self): data without rewriting the whole workbook. Limit floats to a fixed precision using float_format. For example - float_format="%.2f" will format 0.1234 to 0.12. + float_format="%%.2f" will format 0.1234 to 0.12. - For compatibility with `to_csv `__ , + For compatibility with :meth:`~DataFrame.to_csv`, to_excel serializes lists and dicts to strings before writing. """ From b2a64960c3438f872d1d33437c7dd326be8e88ee Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 24 Jul 2018 11:01:34 -0500 Subject: [PATCH 7/7] Updated * Added notes * Moved float_format section * Removed "default None" --- pandas/core/generic.py | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 18e65bd96b64f..fa4572dd7b979 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1855,8 +1855,9 @@ def _repr_latex_(self): Name of sheet which will contain DataFrame. na_rep : string, default '' Missing data representation. - float_format : string, default None - Format string for floating point numbers. + float_format : string, optional + Format string for floating point numbers. For example + ``float_format="%%.2f"`` will format 0.1234 to 0.12. columns : sequence or list of string, optional Columns to write. header : boolean or list of string, default True @@ -1864,21 +1865,21 @@ def _repr_latex_(self): assumed to be aliases for the column names. index : boolean, default True Write row names (index). - index_label : string or sequence, default None - Column label for index column(s) if desired. If None is given, and + index_label : string or sequence, optional + Column label for index column(s) if desired. If not specified, and `header` and `index` are True, then the index names are used. A sequence should be given if the DataFrame uses MultiIndex. startrow : integer, default 0 Upper left cell row to dump data frame. startcol : integer, default 0 Upper left cell column to dump data frame. - engine : string, default None + engine : string, optional Write engine to use, 'openpyxl' or 'xlsxwriter'. You can also set this via the options ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and ``io.excel.xlsm.writer``. merge_cells : boolean, default True Write MultiIndex and Hierarchical Rows as merged cells. - encoding : string, default None + encoding : string, optional Encoding of the resulting excel file. Only necessary for xlwt, other writers support unicode natively. inf_rep : string, default 'inf' @@ -1886,12 +1887,20 @@ def _repr_latex_(self): infinity in Excel). verbose : boolean, default True Display more information in the error logs. - freeze_panes : tuple of integer (length 2), default None + freeze_panes : tuple of integer (length 2), optional Specifies the one-based bottommost row and rightmost column that is to be frozen. .. versionadded:: 0.20.0. + Notes + ----- + For compatibility with :meth:`~DataFrame.to_csv`, + to_excel serializes lists and dicts to strings before writing. + + Once a workbook has been saved it is not possible write further data + without rewriting the whole workbook. + See Also -------- pandas.read_excel @@ -1919,15 +1928,6 @@ def _repr_latex_(self): >>> df2 = df1.copy() >>> df2.to_excel(writer, sheet_name='Sheet2') >>> writer.save() - - Note that once a workbook has been saved it is not possible write further - data without rewriting the whole workbook. - - Limit floats to a fixed precision using float_format. For example - float_format="%%.2f" will format 0.1234 to 0.12. - - For compatibility with :meth:`~DataFrame.to_csv`, - to_excel serializes lists and dicts to strings before writing. """ def to_json(self, path_or_buf=None, orient=None, date_format=None,