ENH: 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
@@ -868,6 +879,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",
+        }:
+            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
+
     def __fspath__(self):
         return getattr(self.handles.handle, "name", "")
 

pandas/io/excel/_openpyxl.py

@@ -37,13 +37,18 @@ 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.
         from openpyxl.workbook import Workbook
 
         super().__init__(
-            path, mode=mode, storage_options=storage_options, **engine_kwargs
+            path,
+            mode=mode,
+            storage_options=storage_options,
+            if_exists=if_exists,
+            **engine_kwargs,
         )
 
         # ExcelWriter replaced "a" by "r+" to allow us to first read the excel file from
@@ -53,6 +58,8 @@ 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}
+
         else:
             # Create workbook object with default optimized_write=True.
             self.book = Workbook()
@@ -412,7 +419,21 @@ def write_cells(
         _style_cache: Dict[str, Dict[str, Serialisable]] = {}
 
         if sheet_name in self.sheets:
-            wks = self.sheets[sheet_name]
+            if "r+" in self.mode:
+                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.sheets[sheet_name]
         else:
             wks = self.book.create_sheet()
             wks.title = sheet_name

pandas/tests/io/excel/test_openpyxl.py

@@ -1,4 +1,5 @@
 from pathlib import Path
+import re
 
 import numpy as np
 import pytest
@@ -109,6 +110,52 @@ 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):
+    # 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)
+        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_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"
+
+    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 tm.ensure_clean(ext) as f:
+        with pytest.raises(ValueError, match=invalid_msg):
+            ExcelWriter(f, engine="openpyxl", mode="a", if_exists="invalid")
+
+
 def test_to_excel_with_openpyxl_engine(ext):
     # GH 29854
     with tm.ensure_clean(ext) as filename: