From 23a0cecd906071c205f53bdc333939fd04e35c45 Mon Sep 17 00:00:00 2001 From: Aaron Barber Date: Mon, 22 May 2017 16:31:59 -0700 Subject: [PATCH 1/5] GH10559: Minor improvement: Change to_excel sheet name modify io/excel.py and relevant docs (io.rst) to use sheet_name for read_excel but allow sheetname to still be used for backwards compatibility. add test_excel to verify that sheet_name and sheetname args produce the same result. --- doc/source/io.rst | 16 ++++++++-------- pandas/io/excel.py | 16 ++++++++++------ pandas/tests/io/test_excel.py | 12 ++++++++++++ 3 files changed, 30 insertions(+), 14 deletions(-) diff --git a/doc/source/io.rst b/doc/source/io.rst index 9692766505d7a..bca23dd18a0e3 100644 --- a/doc/source/io.rst +++ b/doc/source/io.rst @@ -2561,12 +2561,12 @@ Reading Excel Files ''''''''''''''''''' In the most basic use-case, ``read_excel`` takes a path to an Excel -file, and the ``sheetname`` indicating which sheet to parse. +file, and the ``sheet_name`` indicating which sheet to parse. .. code-block:: python # Returns a DataFrame - read_excel('path_to_file.xls', sheetname='Sheet1') + read_excel('path_to_file.xls', sheet_name='Sheet1') .. _io.excel.excelfile_class: @@ -2634,12 +2634,12 @@ of sheet names can simply be passed to ``read_excel`` with no loss in performanc Specifying Sheets +++++++++++++++++ -.. note :: The second argument is ``sheetname``, not to be confused with ``ExcelFile.sheet_names`` +.. note :: The second argument is ``sheet_name``, not to be confused with ``ExcelFile.sheet_names`` .. note :: An ExcelFile's attribute ``sheet_names`` provides access to a list of sheets. -- The arguments ``sheetname`` allows specifying the sheet or sheets to read. -- The default value for ``sheetname`` is 0, indicating to read the first sheet +- The arguments ``sheet_name`` allows specifying the sheet or sheets to read. +- The default value for ``sheet_name`` is 0, indicating to read the first sheet - Pass a string to refer to the name of a particular sheet in the workbook. - Pass an integer to refer to the index of a sheet. Indices follow Python convention, beginning at 0. @@ -2670,18 +2670,18 @@ Using None to get all sheets: .. code-block:: python # Returns a dictionary of DataFrames - read_excel('path_to_file.xls',sheetname=None) + read_excel('path_to_file.xls',sheet_name=None) Using a list to get multiple sheets: .. code-block:: python # Returns the 1st and 4th sheet, as a dictionary of DataFrames. - read_excel('path_to_file.xls',sheetname=['Sheet1',3]) + read_excel('path_to_file.xls',sheet_name=['Sheet1',3]) .. versionadded:: 0.16 -``read_excel`` can read more than one sheet, by setting ``sheetname`` to either +``read_excel`` can read more than one sheet, by setting ``sheet_name`` to either a list of sheet names, a list of sheet positions, or ``None`` to read all sheets. .. versionadded:: 0.13 diff --git a/pandas/io/excel.py b/pandas/io/excel.py index fba3d7559aeaf..35c9bcdc37892 100644 --- a/pandas/io/excel.py +++ b/pandas/io/excel.py @@ -48,7 +48,7 @@ The string could be a URL. Valid URL schemes include http, ftp, s3, and file. For file URLs, a host is expected. For instance, a local file could be file://localhost/path/to/workbook.xlsx -sheetname : string, int, mixed list of strings/ints, or None, default 0 +sheet_name : string, int, mixed list of strings/ints, or None, default 0 Strings are used for sheet names, Integers are used in zero-indexed sheet positions. @@ -144,7 +144,7 @@ Returns ------- parsed : DataFrame or Dict of DataFrames - DataFrame from the passed in Excel file. See notes in sheetname + DataFrame from the passed in Excel file. See notes in sheet_name argument for more information on when a Dict of Dataframes is returned. """ @@ -190,7 +190,7 @@ def get_writer(engine_name): @Appender(_read_excel_doc) -def read_excel(io, sheetname=0, header=0, skiprows=None, skip_footer=0, +def read_excel(io, sheet_name=0, header=0, skiprows=None, skip_footer=0, index_col=None, names=None, parse_cols=None, parse_dates=False, date_parser=None, na_values=None, thousands=None, convert_float=True, has_index_names=None, converters=None, @@ -200,8 +200,12 @@ def read_excel(io, sheetname=0, header=0, skiprows=None, skip_footer=0, if not isinstance(io, ExcelFile): io = ExcelFile(io, engine=engine) + # maintain backwards compatibility by converting sheetname to sheet_name + if 'sheetname' in kwds: + sheet_name = kwds.pop('sheetname') + return io._parse_excel( - sheetname=sheetname, header=header, skiprows=skiprows, names=names, + sheetname=sheet_name, header=header, skiprows=skiprows, names=names, index_col=index_col, parse_cols=parse_cols, parse_dates=parse_dates, date_parser=date_parser, na_values=na_values, thousands=thousands, convert_float=convert_float, has_index_names=has_index_names, @@ -266,7 +270,7 @@ def __init__(self, io, **kwds): def __fspath__(self): return self._io - def parse(self, sheetname=0, header=0, skiprows=None, skip_footer=0, + def parse(self, sheet_name=0, header=0, skiprows=None, skip_footer=0, names=None, index_col=None, parse_cols=None, parse_dates=False, date_parser=None, na_values=None, thousands=None, convert_float=True, has_index_names=None, @@ -279,7 +283,7 @@ def parse(self, sheetname=0, header=0, skiprows=None, skip_footer=0, docstring for more info on accepted parameters """ - return self._parse_excel(sheetname=sheetname, header=header, + return self._parse_excel(sheetname=sheet_name, header=header, skiprows=skiprows, names=names, index_col=index_col, has_index_names=has_index_names, diff --git a/pandas/tests/io/test_excel.py b/pandas/tests/io/test_excel.py index bbf4f1107ac9e..0956b00803371 100644 --- a/pandas/tests/io/test_excel.py +++ b/pandas/tests/io/test_excel.py @@ -544,6 +544,18 @@ def test_date_conversion_overflow(self): result = self.get_exceldf('testdateoverflow') tm.assert_frame_equal(result, expected) + # GH10559: Minor improvement: Change to_excel "sheet_name" to "sheetname" + # GH10969: DOC: Consistent variable names (sheetname vs sheet_name, issue 10559) + # GH12604: CLN GH10559 Rename sheetname variable to sheet_name for consistency + def test_sheet_name_and_sheetname(self): + dfref = self.get_csv_refdf('test1') + df1 = self.get_exceldf('test1', sheet_name='Sheet1') # doc + df2 = self.get_exceldf('test1', sheetname='Sheet2') # bkwrds compat + + tm.assert_frame_equal(df1, dfref, check_names=False) + tm.assert_frame_equal(df2, dfref, check_names=False) + + class XlrdTests(ReadingTestsBase): """ From 5a59cd0179d7925ca70a98ed8fecf664bf32daf8 Mon Sep 17 00:00:00 2001 From: Aaron Barber Date: Mon, 22 May 2017 21:13:58 -0700 Subject: [PATCH 2/5] GH10559: Minor improvement: Change to_excel sheet name added @deprecate_kwarg to read_excel as arg changes from sheetname to sheet_name. moved test comments into function, add assert_produces_warning. --- pandas/io/excel.py | 9 +++++---- pandas/tests/io/test_excel.py | 11 +++++------ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/pandas/io/excel.py b/pandas/io/excel.py index 35c9bcdc37892..5bcfda55887f4 100644 --- a/pandas/io/excel.py +++ b/pandas/io/excel.py @@ -30,7 +30,7 @@ import pandas.compat.openpyxl_compat as openpyxl_compat from warnings import warn from distutils.version import LooseVersion -from pandas.util._decorators import Appender +from pandas.util._decorators import Appender, deprecate_kwarg from textwrap import fill __all__ = ["read_excel", "ExcelWriter", "ExcelFile"] @@ -189,6 +189,7 @@ def get_writer(engine_name): raise ValueError("No Excel writer '%s'" % engine_name) +@deprecate_kwarg('sheetname', 'sheet_name') @Appender(_read_excel_doc) def read_excel(io, sheet_name=0, header=0, skiprows=None, skip_footer=0, index_col=None, names=None, parse_cols=None, parse_dates=False, @@ -200,9 +201,9 @@ def read_excel(io, sheet_name=0, header=0, skiprows=None, skip_footer=0, if not isinstance(io, ExcelFile): io = ExcelFile(io, engine=engine) - # maintain backwards compatibility by converting sheetname to sheet_name - if 'sheetname' in kwds: - sheet_name = kwds.pop('sheetname') +# maintain backwards compatibility by converting sheetname to sheet_name +# if 'sheetname' in kwds: +# sheet_name = kwds.pop('sheetname') return io._parse_excel( sheetname=sheet_name, header=header, skiprows=skiprows, names=names, diff --git a/pandas/tests/io/test_excel.py b/pandas/tests/io/test_excel.py index 0956b00803371..834936164a0c7 100644 --- a/pandas/tests/io/test_excel.py +++ b/pandas/tests/io/test_excel.py @@ -544,19 +544,18 @@ def test_date_conversion_overflow(self): result = self.get_exceldf('testdateoverflow') tm.assert_frame_equal(result, expected) - # GH10559: Minor improvement: Change to_excel "sheet_name" to "sheetname" - # GH10969: DOC: Consistent variable names (sheetname vs sheet_name, issue 10559) - # GH12604: CLN GH10559 Rename sheetname variable to sheet_name for consistency def test_sheet_name_and_sheetname(self): + # GH10559: Minor improvement: Change to_excel "sheet_name" to "sheetname" + # GH10969: DOC: Consistent variable names (sheetname vs sheet_name, issue 10559) + # GH12604: CLN GH10559 Rename sheetname variable to sheet_name for consistency dfref = self.get_csv_refdf('test1') df1 = self.get_exceldf('test1', sheet_name='Sheet1') # doc - df2 = self.get_exceldf('test1', sheetname='Sheet2') # bkwrds compat + with tm.assert_produces_warning(FutureWarning, check_stacklevel=False): + df2 = self.get_exceldf('test1', sheetname='Sheet2') # bkwrds compat tm.assert_frame_equal(df1, dfref, check_names=False) tm.assert_frame_equal(df2, dfref, check_names=False) - - class XlrdTests(ReadingTestsBase): """ This is the base class for the xlrd tests, and 3 different file formats From 4171dd628a608f40c1c70cdc1175bad2f0fac8db Mon Sep 17 00:00:00 2001 From: Aaron Barber Date: Mon, 22 May 2017 21:40:56 -0700 Subject: [PATCH 3/5] GH10559: Minor improvement: Change to_excel sheet name remove manual arg change, use @deprecate_kwarg to read_excel as arg changes from sheetname to sheet_name. --- pandas/io/excel.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/pandas/io/excel.py b/pandas/io/excel.py index 5bcfda55887f4..a81ee503c76ca 100644 --- a/pandas/io/excel.py +++ b/pandas/io/excel.py @@ -201,10 +201,6 @@ def read_excel(io, sheet_name=0, header=0, skiprows=None, skip_footer=0, if not isinstance(io, ExcelFile): io = ExcelFile(io, engine=engine) -# maintain backwards compatibility by converting sheetname to sheet_name -# if 'sheetname' in kwds: -# sheet_name = kwds.pop('sheetname') - return io._parse_excel( sheetname=sheet_name, header=header, skiprows=skiprows, names=names, index_col=index_col, parse_cols=parse_cols, parse_dates=parse_dates, From 91438b8c8381d99a3544afa73559c78d84aa2cf5 Mon Sep 17 00:00:00 2001 From: Aaron Barber Date: Mon, 22 May 2017 22:54:41 -0700 Subject: [PATCH 4/5] GH10559: Minor improvement: Change to_excel sheet name shorten lines under 79 char. --- pandas/tests/io/test_excel.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pandas/tests/io/test_excel.py b/pandas/tests/io/test_excel.py index 834936164a0c7..0a79d4e8fd81b 100644 --- a/pandas/tests/io/test_excel.py +++ b/pandas/tests/io/test_excel.py @@ -545,17 +545,18 @@ def test_date_conversion_overflow(self): tm.assert_frame_equal(result, expected) def test_sheet_name_and_sheetname(self): - # GH10559: Minor improvement: Change to_excel "sheet_name" to "sheetname" - # GH10969: DOC: Consistent variable names (sheetname vs sheet_name, issue 10559) - # GH12604: CLN GH10559 Rename sheetname variable to sheet_name for consistency + # GH10559: Minor improvement: Change "sheet_name" to "sheetname" + # GH10969: DOC: Consistent var names (sheetname vs sheet_name) + # GH12604: CLN GH10559 Rename sheetname variable to sheet_name dfref = self.get_csv_refdf('test1') df1 = self.get_exceldf('test1', sheet_name='Sheet1') # doc with tm.assert_produces_warning(FutureWarning, check_stacklevel=False): - df2 = self.get_exceldf('test1', sheetname='Sheet2') # bkwrds compat + df2 = self.get_exceldf('test1', sheetname='Sheet2') # bkwrd compat tm.assert_frame_equal(df1, dfref, check_names=False) tm.assert_frame_equal(df2, dfref, check_names=False) + class XlrdTests(ReadingTestsBase): """ This is the base class for the xlrd tests, and 3 different file formats From 4c6da132e9f0a1c4c42a03aa12effa167aeab218 Mon Sep 17 00:00:00 2001 From: Aaron Barber Date: Tue, 23 May 2017 09:35:50 -0700 Subject: [PATCH 5/5] GH10559: Minor improvement: Change to_excel sheet name update whats new 0.21.0 Deprecations section noting sheetname deprecated in favor of sheet_name. add sheetname deprecation in read_excel() docstring. --- doc/source/whatsnew/v0.21.0.txt | 2 +- pandas/io/excel.py | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/source/whatsnew/v0.21.0.txt b/doc/source/whatsnew/v0.21.0.txt index 3734dc15be2e9..b6c9495765b2f 100644 --- a/doc/source/whatsnew/v0.21.0.txt +++ b/doc/source/whatsnew/v0.21.0.txt @@ -57,7 +57,7 @@ Other API Changes Deprecations ~~~~~~~~~~~~ - +- :func:`read_excel()` has deprecated ``sheetname`` in favor of ``sheet_name`` for consistency with to_excel() (:issue:`10559`). .. _whatsnew_0210.prior_deprecations: diff --git a/pandas/io/excel.py b/pandas/io/excel.py index a81ee503c76ca..81a36b21b3617 100644 --- a/pandas/io/excel.py +++ b/pandas/io/excel.py @@ -69,6 +69,10 @@ * [0,1,"Sheet5"] -> 1st, 2nd & 5th sheet as a dictionary of DataFrames * None -> All sheets as a dictionary of DataFrames +sheetname : string, int, mixed list of strings/ints, or None, default 0 + .. deprecated:: 0.21.0 + Use `sheet_name` instead + header : int, list of ints, default 0 Row (0-indexed) to use for the column labels of the parsed DataFrame. If a list of integers is passed those row positions will