FEAT: Add if_exists parameter to ExcelWriter

Author: mirober

doc/source/whatsnew/v1.3.0.rst

@@ -125,6 +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`)
 - :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,6 +666,16 @@ 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).
+
+            * 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.
+
+        .. versionadded:: 1.3.0
 
     Attributes
     ----------
@@ -834,6 +844,7 @@ def __init__(
         datetime_format=None,
         mode: str = "w",
         storage_options: StorageOptions = None,
+        if_exists: Optional[str] = None,
         **engine_kwargs,
     ):
         # validate that this engine can handle the extension
@@ -951,8 +962,7 @@ def close(self):
 
 @doc(storage_options=_shared_docs["storage_options"])
 def inspect_excel_format(
-    content_or_path: FilePathOrBuffer,
-    storage_options: StorageOptions = None,
+    content_or_path: FilePathOrBuffer, storage_options: StorageOptions = None,
 ) -> str:
     """
     Inspect the path or content of an excel file and get its format.

pandas/io/excel/_odswriter.py

@@ -28,14 +28,15 @@ def __init__(
         engine: Optional[str] = None,
         mode: str = "w",
         storage_options: StorageOptions = None,
+        if_exists: Optional[str] = None,
         **engine_kwargs,
     ):
         from odf.opendocument import OpenDocumentSpreadsheet
 
         engine_kwargs["engine"] = engine
 
-        if mode == "a":
-            raise ValueError("Append mode is not supported with odf!")
+        if mode == "a" or if_exists:
+            raise ValueError("Append mode and if_exists are not supported with odf!")
 
         super().__init__(
             path, mode=mode, storage_options=storage_options, **engine_kwargs

pandas/io/excel/_openpyxl.py

@@ -37,6 +37,7 @@ def __init__(
         engine=None,
         mode: str = "w",
         storage_options: StorageOptions = None,
+        if_exists: Optional[str] = None,
         **engine_kwargs,
     ):
         # Use the openpyxl module as the Excel writer.
@@ -53,12 +54,26 @@ def __init__(
 
             self.book = load_workbook(self.handles.handle)
             self.handles.handle.seek(0)
+            self.sheets = {name: self.book[name] for name in self.book.sheetnames}
+
+            if if_exists is None:
+                self.if_exists = "new_sheet"
+            elif if_exists in {"new_sheet", "overwrite_sheet", "overwrite_cells"}:
+                self.if_exists = if_exists
+            else:
+                raise ValueError(f"'{if_exists}' is not valid for if_exists")
         else:
             # Create workbook object with default optimized_write=True.
             self.book = Workbook()
 
             if self.book.worksheets:
                 self.book.remove(self.book.worksheets[0])
+            if if_exists is None:
+                self.if_exists = None
+            else:
+                raise ValueError(
+                    "The 'if_exists' parameter is only valid with mode='a' (append)"
+                )
 
     def save(self):
         """
@@ -412,7 +427,18 @@ def write_cells(
         _style_cache: Dict[str, Dict[str, Serialisable]] = {}
 
         if sheet_name in self.sheets:
-            wks = self.sheets[sheet_name]
+            if self.if_exists == "new_sheet":
+                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":
+                wks = self.sheets[sheet_name]
+                wks.delete_cols(1, wks.max_column)
+            elif self.if_exists == "overwrite_cells" or self.if_exists is None:
+                wks = self.sheets[sheet_name]
+            else:
+                raise ValueError(f"'{self.if_exists}' is not valid for if_exists")
         else:
             wks = self.book.create_sheet()
             wks.title = sheet_name

pandas/io/excel/_xlsxwriter.py

@@ -1,6 +1,7 @@
 from typing import (
     Dict,
     List,
+    Optional,
     Tuple,
 )
 
@@ -175,13 +176,16 @@ def __init__(
         datetime_format=None,
         mode: str = "w",
         storage_options: StorageOptions = None,
+        if_exists: Optional[str] = None,
         **engine_kwargs,
     ):
         # Use the xlsxwriter module as the Excel writer.
         from xlsxwriter import Workbook
 
-        if mode == "a":
-            raise ValueError("Append mode is not supported with xlsxwriter!")
+        if mode == "a" or if_exists:
+            raise ValueError(
+                "Append mode and if_exists are not supported with xlsxwriter!"
+            )
 
         super().__init__(
             path,

pandas/io/excel/_xlwt.py

@@ -1,6 +1,7 @@
 from typing import (
     TYPE_CHECKING,
     Dict,
+    Optional,
 )
 
 import pandas._libs.json as json
@@ -24,15 +25,16 @@ def __init__(
         encoding=None,
         mode: str = "w",
         storage_options: StorageOptions = None,
+        if_exists: Optional[str] = None,
         **engine_kwargs,
     ):
         # Use the xlwt module as the Excel writer.
         import xlwt
 
         engine_kwargs["engine"] = engine
 
-        if mode == "a":
-            raise ValueError("Append mode is not supported with xlwt!")
+        if mode == "a" or if_exists:
+            raise ValueError("Append mode and if_exists are not supported with xlwt!")
 
         super().__init__(
             path, mode=mode, storage_options=storage_options, **engine_kwargs

pandas/tests/io/excel/test_openpyxl.py

@@ -109,6 +109,39 @@ def test_write_append_mode(ext, mode, expected):
             assert wb2.worksheets[index]["A1"].value == cell_value
 
 
+@pytest.mark.parametrize(
+    "if_exists,num_sheets,expected",
+    [
+        ("new_sheet", 2, ["apple", "banana"]),
+        ("overwrite_sheet", 1, ["pear"]),
+        ("overwrite_cells", 1, ["pear", "banana"]),
+    ],
+)
+def test_if_exists_append_modes(ext, if_exists, num_sheets, expected):
+    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)
+        with pd.ExcelWriter(
+            f, engine="openpyxl", mode="a", if_exists=if_exists
+        ) as writer:
+            df2.to_excel(writer, sheet_name="foo", index=False)
+
+        wb = openpyxl.load_workbook(f)
+        assert len(wb.sheetnames) == num_sheets
+        assert wb.sheetnames[0] == "foo"
+        result = pd.read_excel(wb, "foo", engine="openpyxl")
+        assert list(result["fruit"]) == expected
+        if len(wb.sheetnames) == 2:
+            # atm the name given for the second sheet will be "foo1"
+            # but we don't want the test to fail if openpyxl changes this
+            result = pd.read_excel(wb, wb.sheetnames[1], engine="openpyxl")
+            assert result.equals(df2)
+        wb.close()
+
+
 def test_to_excel_with_openpyxl_engine(ext):
     # GH 29854
     with tm.ensure_clean(ext) as filename:

pandas/tests/io/excel/test_xlsxwriter.py

@@ -56,7 +56,7 @@ def test_column_format(ext):
 
 
 def test_write_append_mode_raises(ext):
-    msg = "Append mode is not supported with xlsxwriter!"
+    msg = "Append mode and if_exists are not supported with xlsxwriter!"
 
     with tm.ensure_clean(ext) as f:
         with pytest.raises(ValueError, match=msg):