ENH: add if_sheet_exists='overlay' to ExcelWriter

pandas/io/excel/_base.py

@@ -681,14 +681,18 @@ class ExcelWriter(metaclass=abc.ABCMeta):
         be parsed by ``fsspec``, e.g., starting "s3://", "gcs://".
 
         .. versionadded:: 1.2.0
-    if_sheet_exists : {'error', 'new', 'replace'}, default 'error'
+    if_sheet_exists : {'error', 'new', 'replace', 'overlay'}, default 'error'
         How to behave when trying to write to a sheet that already
         exists (append mode only).
 
         * error: raise a ValueError.
         * new: Create a new sheet, with a name determined by the engine.
         * replace: Delete the contents of the sheet before writing to it.
 
+        .. versionadded:: 1.4.0
+        * overlay: Write contents to the existing sheet without removing the old
+        contents.
+
         .. versionadded:: 1.3.0
     engine_kwargs : dict, optional
         Keyword arguments to be passed into the engine.
@@ -755,6 +759,28 @@ class ExcelWriter(metaclass=abc.ABCMeta):
     >>> with ExcelWriter("path_to_file.xlsx", mode="a", engine="openpyxl") as writer:
     ...     df.to_excel(writer, sheet_name="Sheet3")
 
+    Here, the `if_sheet_exists` parameter can be set to replace a sheet if it
+    already exists:
+
+    >>> with ExcelWriter(
+    ...     "path_to_file.xlsx",
+    ...     mode="a",
+    ...     engine="openpyxl",
+    ...     if_sheet_exists="replace",
+    ... ) as writer:
+    ...     df.to_excel(writer, sheet_name="Sheet1")
+
+    You can also write multiple DataFrames to a single sheet. Note that the
+    ``if_sheet_exists`` parameter needs to be set to ``overlay``:
+
+    >>> with ExcelWriter("path_to_file.xlsx",
+    ...     mode="a",
+    ...     engine="openpyxl",
+    ...     if_sheet_exists="overlay",
+    ... ) as writer:
+    ...     df1.to_excel(writer, sheet_name="Sheet1")
+    ...     df2.to_excel(writer, sheet_name="Sheet1", startcol=3)
+
     You can store Excel file in RAM:
 
     >>> import io
@@ -940,10 +966,10 @@ def __init__(
 
         self.mode = mode
 
-        if if_sheet_exists not in [None, "error", "new", "replace"]:
+        if if_sheet_exists not in [None, "error", "new", "replace", "overlay"]:
             raise ValueError(
                 f"'{if_sheet_exists}' is not valid for if_sheet_exists. "
-                "Valid options are 'error', 'new' and 'replace'."
+                "Valid options are 'error', 'new', 'replace' and 'overlay'."
             )
         if if_sheet_exists and "r+" not in mode:
             raise ValueError("if_sheet_exists is only valid in append mode (mode='a')")

pandas/io/excel/_openpyxl.py

@@ -437,10 +437,12 @@ def write_cells(
                         f"Sheet '{sheet_name}' already exists and "
                         f"if_sheet_exists is set to 'error'."
                     )
+                elif self.if_sheet_exists == "overlay":
+                    wks = self.sheets[sheet_name]
                 else:
                     raise ValueError(
                         f"'{self.if_sheet_exists}' is not valid for if_sheet_exists. "
-                        "Valid options are 'error', 'new' and 'replace'."
+                        "Valid options are 'error', 'new', 'replace' and 'overlay'."
                     )
             else:
                 wks = self.sheets[sheet_name]

pandas/tests/io/excel/test_openpyxl.py

@@ -139,6 +139,7 @@ def test_write_append_mode(ext, mode, expected):
     [
         ("new", 2, ["apple", "banana"]),
         ("replace", 1, ["pear"]),
+        ("overlay", 1, ["pear", "banana"]),
     ],
 )
 def test_if_sheet_exists_append_modes(ext, if_sheet_exists, num_sheets, expected):
@@ -170,7 +171,7 @@ def test_if_sheet_exists_append_modes(ext, if_sheet_exists, num_sheets, expected
         (
             "invalid",
             "'invalid' is not valid for if_sheet_exists. Valid options "
-            "are 'error', 'new' and 'replace'.",
+            "are 'error', 'new', 'replace' and 'overlay'.",
         ),
         (
             "error",