Rename parameter to if_sheet_exists

Author: mirober

doc/source/whatsnew/v1.3.0.rst

@@ -125,7 +125,7 @@ Other enhancements
 - :func:`to_numeric` now supports downcasting of nullable ``ExtensionDtype`` objects (:issue:`33013`)
 - Add support for dict-like names in :class:`MultiIndex.set_names` and :class:`MultiIndex.rename` (:issue:`20421`)
 - :func:`pandas.read_excel` can now auto detect .xlsb files (:issue:`35416`)
-- :class:`pandas.ExcelWriter` now accepts an ``if_exists`` parameter to control the behaviour of append mode when writing to existing sheets (:issue:`40230`)
+- :class:`pandas.ExcelWriter` now accepts an ``if_sheet_exists`` parameter to control the behaviour of append mode when writing to existing sheets (:issue:`40230`)
 - :meth:`.Rolling.sum`, :meth:`.Expanding.sum`, :meth:`.Rolling.mean`, :meth:`.Expanding.mean`, :meth:`.Rolling.median`, :meth:`.Expanding.median`, :meth:`.Rolling.max`, :meth:`.Expanding.max`, :meth:`.Rolling.min`, and :meth:`.Expanding.min` now support ``Numba`` execution with the ``engine`` keyword (:issue:`38895`)
 - :meth:`DataFrame.apply` can now accept NumPy unary operators as strings, e.g. ``df.apply("sqrt")``, which was already the case for :meth:`Series.apply` (:issue:`39116`)
 - :meth:`DataFrame.apply` can now accept non-callable DataFrame properties as strings, e.g. ``df.apply("size")``, which was already the case for :meth:`Series.apply` (:issue:`39116`)

pandas/io/excel/_base.py

@@ -666,14 +666,15 @@ class ExcelWriter(metaclass=abc.ABCMeta):
         be parsed by ``fsspec``, e.g., starting "s3://", "gcs://".
 
         .. versionadded:: 1.2.0
-    if_exists : {'new_sheet', 'overwrite_sheet', 'overwrite_cells'}, default 'new_sheet'
-            How to behave when trying to write to a sheet that already
-            exists (append mode only).
+    if_sheet_exists : {'avoid', 'replace', 'overwrite', 'fail'}, default 'avoid'
+        How to behave when trying to write to a sheet that already
+        exists (append mode only).
 
-            * new_sheet: Create a new sheet with a different name.
-            * overwrite_sheet: Delete the contents of the sheet, then write to it.
-            * overwrite_cells: Write directly to the named sheet
-              without deleting the previous contents.
+        * avoid: Create a new sheet with a different name.
+        * replace: Delete the contents of the sheet before writing to it.
+        * overwrite: Write directly to the named sheet
+          without deleting the previous contents.
+        * fail: raise a ValueError.
 
         .. versionadded:: 1.3.0
 
@@ -844,7 +845,7 @@ def __init__(
         datetime_format=None,
         mode: str = "w",
         storage_options: StorageOptions = None,
-        if_exists: Optional[str] = None,
+        if_sheet_exists: Optional[str] = None,
         **engine_kwargs,
     ):
         # validate that this engine can handle the extension
@@ -879,17 +880,18 @@ def __init__(
 
         self.mode = mode
 
-        if if_exists and "r+" not in mode:
-            raise ValueError("if_exists is only valid in append mode (mode='a')")
-        if if_exists is not None and if_exists not in {
-            "new_sheet",
-            "overwrite_sheet",
-            "overwrite_cells",
+        if if_sheet_exists and "r+" not in mode:
+            raise ValueError("if_sheet_exists is only valid in append mode (mode='a')")
+        if if_sheet_exists is not None and if_sheet_exists not in {
+            "avoid",
+            "replace",
+            "overwrite",
+            "fail",
         }:
-            raise ValueError(f"'{if_exists}' is not valid for if_exists")
-        if if_exists is None and "r+" in mode:
-            if_exists = "new_sheet"
-        self.if_exists = if_exists
+            raise ValueError(f"'{if_sheet_exists}' is not valid for if_sheet_exists")
+        if if_sheet_exists is None and "r+" in mode:
+            if_sheet_exists = "avoid"
+        self.if_sheet_exists = if_sheet_exists
 
     def __fspath__(self):
         return getattr(self.handles.handle, "name", "")

pandas/io/excel/_openpyxl.py

@@ -37,7 +37,7 @@ def __init__(
         engine=None,
         mode: str = "w",
         storage_options: StorageOptions = None,
-        if_exists: Optional[str] = None,
+        if_sheet_exists: Optional[str] = None,
         **engine_kwargs,
     ):
         # Use the openpyxl module as the Excel writer.
@@ -47,7 +47,7 @@ def __init__(
             path,
             mode=mode,
             storage_options=storage_options,
-            if_exists=if_exists,
+            if_sheet_exists=if_sheet_exists,
             **engine_kwargs,
         )
 
@@ -420,18 +420,22 @@ def write_cells(
 
         if sheet_name in self.sheets:
             if "r+" in self.mode:
-                if self.if_exists == "new_sheet":
+                if self.if_sheet_exists == "avoid":
                     wks = self.book.create_sheet()
                     # openpyxl will create a name for the new sheet by appending digits
                     wks.title = sheet_name
                     self.sheets[wks.title] = wks
-                elif self.if_exists == "overwrite_sheet":
+                elif self.if_sheet_exists == "replace":
                     wks = self.sheets[sheet_name]
                     wks.delete_cols(1, wks.max_column)
-                elif self.if_exists == "overwrite_cells" or self.if_exists is None:
+                elif self.if_sheet_exists == "overwrite":
                     wks = self.sheets[sheet_name]
+                elif self.if_sheet_exists == "fail":
+                    raise ValueError(f"Sheet '{sheet_name}' already exists.")
                 else:
-                    raise ValueError(f"'{self.if_exists}' is not valid for if_exists")
+                    raise ValueError(
+                        f"'{self.if_sheet_exists}' is not valid for if_sheet_exists"
+                    )
             else:
                 wks = self.sheets[sheet_name]
         else:

pandas/tests/io/excel/test_openpyxl.py

@@ -111,23 +111,23 @@ def test_write_append_mode(ext, mode, expected):
 
 
 @pytest.mark.parametrize(
-    "if_exists,num_sheets,expected",
+    "if_sheet_exists,num_sheets,expected",
     [
-        ("new_sheet", 2, ["apple", "banana"]),
-        ("overwrite_sheet", 1, ["pear"]),
-        ("overwrite_cells", 1, ["pear", "banana"]),
+        ("avoid", 2, ["apple", "banana"]),
+        (None, 2, ["apple", "banana"]),
+        ("replace", 1, ["pear"]),
+        ("overwrite", 1, ["pear", "banana"]),
     ],
 )
-def test_if_exists_append_modes(ext, if_exists, num_sheets, expected):
+def test_if_sheet_exists_append_modes(ext, if_sheet_exists, num_sheets, expected):
     # GH 40230
     df1 = DataFrame({"fruit": ["apple", "banana"]})
     df2 = DataFrame({"fruit": ["pear"]})
 
     with tm.ensure_clean(ext) as f:
-        with pd.ExcelWriter(f, engine="openpyxl", mode="w") as writer:
-            df1.to_excel(writer, sheet_name="foo", index=False)
+        df1.to_excel(f, engine="openpyxl", sheet_name="foo", index=False)
         with pd.ExcelWriter(
-            f, engine="openpyxl", mode="a", if_exists=if_exists
+            f, engine="openpyxl", mode="a", if_sheet_exists=if_sheet_exists
         ) as writer:
             df2.to_excel(writer, sheet_name="foo", index=False)
 
@@ -144,16 +144,27 @@ def test_if_exists_append_modes(ext, if_exists, num_sheets, expected):
         wb.close()
 
 
-def test_if_exists_raises(ext):
-    if_exists_msg = "if_exists is only valid in append mode (mode='a')"
-    invalid_msg = "'invalid' is not valid for if_exists"
+def test_if_sheet_exists_raises(ext):
+    mode_msg = "if_sheet_exists is only valid in append mode (mode='a')"
+    invalid_msg = "'invalid' is not valid for if_sheet_exists"
+    fail_msg = "Sheet 'foo' already exists."
+    df = DataFrame({"fruit": ["pear"]})
 
     with tm.ensure_clean(ext) as f:
-        with pytest.raises(ValueError, match=re.escape(if_exists_msg)):
-            ExcelWriter(f, engine="openpyxl", mode="w", if_exists="new_sheet")
+        with pytest.raises(ValueError, match=re.escape(mode_msg)):
+            ExcelWriter(f, engine="openpyxl", mode="w", if_sheet_exists="new_sheet")
+
     with tm.ensure_clean(ext) as f:
         with pytest.raises(ValueError, match=invalid_msg):
-            ExcelWriter(f, engine="openpyxl", mode="a", if_exists="invalid")
+            ExcelWriter(f, engine="openpyxl", mode="a", if_sheet_exists="invalid")
+
+    with tm.ensure_clean(ext) as f:
+        with pytest.raises(ValueError, match=fail_msg):
+            df.to_excel(f, "foo", engine="openpyxl")
+            with pd.ExcelWriter(
+                f, engine="openpyxl", mode="a", if_sheet_exists="fail"
+            ) as writer:
+                df.to_excel(writer, sheet_name="foo")
 
 
 def test_to_excel_with_openpyxl_engine(ext):