Pass through Engine kwargs in ExcelWriter

pandas/io/excel/_base.py

@@ -700,7 +700,14 @@ class ExcelWriter(metaclass=abc.ABCMeta):
 
         .. versionadded:: 1.3.0
     engine_kwargs : dict, optional
-        Keyword arguments to be passed into the engine.
+        Keyword arguments to be passed into the engine. These will be passed to
+        the following functions of the respective engines:
+
+        * odswriter: ``odf.opendocument.OpenDocumentSpreadsheet(**engine_kwargs)``
+        * xlsxwriter: ``xlsxwriter.Workbook(file, **engine_kwargs)``
+        * xlwt: ``xlwt.Workbook(encoding, **engine_kwargs)``
+        * openpyxl (write mode): ``openpyxl.Workbook(**engine_kwargs)``
+        * openpyxl (append mode): ``openpyxl.load_workbook(file, **engine_kwargs)``
 
         .. versionadded:: 1.3.0
     **kwargs : dict, optional
@@ -780,6 +787,26 @@ class ExcelWriter(metaclass=abc.ABCMeta):
     ...     with zf.open("filename.xlsx", "w") as buffer:
     ...         with pd.ExcelWriter(buffer) as writer:
     ...             df.to_excel(writer)
+
+    You can specify additional arguments to the underlying engine:
+
+    >>> with pd.ExcelWriter(
+    ...     "path_to_file.xlsx",
+    ...     engine="xlsxwriter",
+    ...     engine_kwargs={"options": {"nan_inf_to_errors": True}}
+    ... ) as writer:
+    ...     df.to_excel(writer)
+
+    In append mode, ``engine_kwargs`` are passed through to
+    openpyxl's ``load_workbook``:
+
+    >>> with pd.ExcelWriter(
+    ...     "path_to_file.xlsx",
+    ...     engine="openpyxl",
+    ...     mode="a",
+    ...     engine_kwargs={"keep_vba": True}
+    ... ) as writer:
+    ...     df.to_excel(writer, sheet_name="Sheet2")
     """
 
     # Defining an ExcelWriter implementation (see abstract methods for more...)

pandas/io/excel/_odswriter.py

@@ -11,7 +11,10 @@
 from pandas._typing import StorageOptions
 
 from pandas.io.excel._base import ExcelWriter
-from pandas.io.excel._util import validate_freeze_panes
+from pandas.io.excel._util import (
+    combine_kwargs,
+    validate_freeze_panes,
+)
 from pandas.io.formats.excel import ExcelCell
 
 
@@ -44,7 +47,9 @@ def __init__(
             engine_kwargs=engine_kwargs,
         )
 
-        self.book = OpenDocumentSpreadsheet()
+        engine_kwargs = combine_kwargs(engine_kwargs, kwargs)
+
+        self.book = OpenDocumentSpreadsheet(**engine_kwargs)
         self._style_dict: dict[str, str] = {}
 
     def save(self) -> None:

pandas/io/excel/_openpyxl.py

@@ -62,13 +62,13 @@ def __init__(
         if "r+" in self.mode:  # Load from existing workbook
             from openpyxl import load_workbook
 
-            self.book = load_workbook(self.handles.handle)
+            self.book = load_workbook(self.handles.handle, **engine_kwargs)
             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()
+            self.book = Workbook(**engine_kwargs)
 
             if self.book.worksheets:
                 self.book.remove(self.book.worksheets[0])

pandas/io/excel/_xlwt.py

@@ -53,7 +53,7 @@ def __init__(
 
         if encoding is None:
             encoding = "ascii"
-        self.book = xlwt.Workbook(encoding=encoding)
+        self.book = xlwt.Workbook(encoding=encoding, **engine_kwargs)
         self.fm_datetime = xlwt.easyxf(num_format_str=self.datetime_format)
         self.fm_date = xlwt.easyxf(num_format_str=self.date_format)
 

pandas/tests/io/excel/test_odswriter.py

@@ -19,23 +19,40 @@ def test_write_append_mode_raises(ext):
             ExcelWriter(f, engine="odf", mode="a")
 
 
-@pytest.mark.parametrize("nan_inf_to_errors", [True, False])
-def test_kwargs(ext, nan_inf_to_errors):
+def test_kwargs(ext):
     # GH 42286
-    # odswriter doesn't utilize kwargs, nothing to check except that it works
-    kwargs = {"options": {"nan_inf_to_errors": nan_inf_to_errors}}
+    # GH 43445
+    # test for error: OpenDocumentSpreadsheet does not accept any arguments
+    kwargs = {"kwarg": 1}
     with tm.ensure_clean(ext) as f:
         msg = re.escape("Use of **kwargs is deprecated")
-        with tm.assert_produces_warning(FutureWarning, match=msg):
-            with ExcelWriter(f, engine="odf", **kwargs) as _:
-                pass
-
-
-@pytest.mark.parametrize("nan_inf_to_errors", [True, False])
-def test_engine_kwargs(ext, nan_inf_to_errors):
+        error = re.escape(
+            "OpenDocumentSpreadsheet() got an unexpected keyword argument 'kwarg'"
+        )
+        with pytest.raises(
+            TypeError,
+            match=error,
+        ):
+            with tm.assert_produces_warning(FutureWarning, match=msg):
+                with ExcelWriter(f, engine="odf", **kwargs) as _:
+                    pass
+
+
+@pytest.mark.parametrize("engine_kwargs", [None, {"kwarg": 1}])
+def test_engine_kwargs(ext, engine_kwargs):
     # GH 42286
-    # odswriter doesn't utilize engine_kwargs, nothing to check except that it works
-    engine_kwargs = {"options": {"nan_inf_to_errors": nan_inf_to_errors}}
+    # GH 43445
+    # test for error: OpenDocumentSpreadsheet does not accept any arguments
     with tm.ensure_clean(ext) as f:
-        with ExcelWriter(f, engine="odf", engine_kwargs=engine_kwargs) as _:
-            pass
+        if engine_kwargs is not None:
+            error = re.escape(
+                "OpenDocumentSpreadsheet() got an unexpected keyword argument 'kwarg'"
+            )
+            with pytest.raises(
+                TypeError,
+                match=error,
+            ):
+                ExcelWriter(f, engine="odf", engine_kwargs=engine_kwargs)
+        else:
+            with ExcelWriter(f, engine="odf", engine_kwargs=engine_kwargs) as _:
+                pass

pandas/tests/io/excel/test_openpyxl.py

@@ -85,30 +85,81 @@ def test_write_cells_merge_styled(ext):
         assert xcell_a2.font == openpyxl_sty_merged
 
 
-@pytest.mark.parametrize("write_only", [True, False])
-def test_kwargs(ext, write_only):
-    # GH 42286
-    # openpyxl doesn't utilize kwargs, only test that supplying a kwarg works
-    kwargs = {"write_only": write_only}
+@pytest.mark.parametrize("iso_dates", [True, False])
+def test_kwargs(ext, iso_dates):
+    # GH 42286 GH 43445
+    kwargs = {"iso_dates": iso_dates}
     with tm.ensure_clean(ext) as f:
         msg = re.escape("Use of **kwargs is deprecated")
         with tm.assert_produces_warning(FutureWarning, match=msg):
             with ExcelWriter(f, engine="openpyxl", **kwargs) as writer:
+                assert writer.book.iso_dates == iso_dates
                 # ExcelWriter won't allow us to close without writing something
                 DataFrame().to_excel(writer)
 
 
-@pytest.mark.parametrize("write_only", [True, False])
-def test_engine_kwargs(ext, write_only):
-    # GH 42286
-    # openpyxl doesn't utilize kwargs, only test that supplying a engine_kwarg works
-    engine_kwargs = {"write_only": write_only}
+@pytest.mark.parametrize("iso_dates", [True, False])
+def test_engine_kwargs_write(ext, iso_dates):
+    # GH 42286 GH 43445
+    engine_kwargs = {"iso_dates": iso_dates}
     with tm.ensure_clean(ext) as f:
         with ExcelWriter(f, engine="openpyxl", engine_kwargs=engine_kwargs) as writer:
+            assert writer.book.iso_dates == iso_dates
             # ExcelWriter won't allow us to close without writing something
             DataFrame().to_excel(writer)
 
 
+@pytest.mark.parametrize(
+    "engine_kwargs", [{"data_only": True}, {"keep_vba": True}, {"keep_links": False}]
+)
+def test_engine_kwargs_append(ext, engine_kwargs):
+    # GH 43445
+    # only read_only=True will give something easy that can be verified (maybe
+    # keep_links or data_only could also work, but that'd be more complicated)
+    # arguments are passed through to load_workbook()
+    with tm.ensure_clean(ext) as f:
+        DataFrame(["hello", "world"]).to_excel(f)
+        with ExcelWriter(
+            f, engine="openpyxl", mode="a", engine_kwargs=engine_kwargs
+        ) as writer:
+            DataFrame(["goodbye", "world"]).to_excel(writer, sheet_name="Sheet2")
+
+
+@pytest.mark.parametrize("data_only,B2", [(True, 0), (False, "=1+1")])
+def test_engine_kwargs_append_keep_links(ext, data_only, B2):
+    # GH 43445
+    # tests whether the keep_links engine_kwarg actually works well for
+    # openpyxl's load_workbook
+    # not sure if we have to test for this though, since it also relies a bit on
+    # functionality of openpyxl
+    with tm.ensure_clean(ext) as f:
+        DataFrame(["=1+1"]).to_excel(f)
+        with ExcelWriter(
+            f, engine="openpyxl", mode="a", engine_kwargs={"data_only": data_only}
+        ) as writer:
+            assert writer.sheets["Sheet1"]["B2"].value == B2
+            # ExcelWriter needs us to writer something to close properly?
+            DataFrame().to_excel(writer, sheet_name="Sheet2")
+
+
+def test_engine_kwargs_append_invalid(ext):
+    # GH 43445
+    # test whether an invalid engine kwargs actually raises
+    with tm.ensure_clean(ext) as f:
+        DataFrame(["hello", "world"]).to_excel(f)
+        with pytest.raises(
+            TypeError,
+            match=re.escape(
+                "load_workbook() got an unexpected keyword argument 'apple_banana'"
+            ),
+        ):
+            with ExcelWriter(
+                f, engine="openpyxl", mode="a", engine_kwargs={"apple_banana": "fruit"}
+            ) as writer:
+                # not sure if we have to do something here?
+                DataFrame(["good"]).to_excel(writer, sheet_name="Sheet2")
+
+
 @pytest.mark.parametrize(
     "mode,expected", [("w", ["baz"]), ("a", ["foo", "bar", "baz"])]
 )

pandas/tests/io/excel/test_xlwt.py

@@ -101,25 +101,27 @@ def test_option_xls_writer_deprecated(ext):
         options.io.excel.xls.writer = "xlwt"
 
 
-@pytest.mark.parametrize("write_only", [True, False])
-def test_kwargs(ext, write_only):
+@pytest.mark.parametrize("style_compression", [0, 2])
+def test_kwargs(ext, style_compression):
     # GH 42286
-    # xlwt doesn't utilize kwargs, only test that supplying a kwarg works
-    kwargs = {"write_only": write_only}
+    kwargs = {"style_compression": style_compression}
     with tm.ensure_clean(ext) as f:
         msg = re.escape("Use of **kwargs is deprecated")
         with tm.assert_produces_warning(FutureWarning, match=msg):
-            with ExcelWriter(f, engine="openpyxl", **kwargs) as writer:
+            with ExcelWriter(f, engine="xlwt", **kwargs) as writer:
+                assert (
+                    writer.book._Workbook__styles.style_compression == style_compression
+                )
                 # xlwt won't allow us to close without writing something
                 DataFrame().to_excel(writer)
 
 
-@pytest.mark.parametrize("write_only", [True, False])
-def test_engine_kwargs(ext, write_only):
+@pytest.mark.parametrize("style_compression", [0, 2])
+def test_engine_kwargs(ext, style_compression):
     # GH 42286
-    # xlwt doesn't utilize kwargs, only test that supplying a engine_kwarg works
-    engine_kwargs = {"write_only": write_only}
+    engine_kwargs = {"style_compression": style_compression}
     with tm.ensure_clean(ext) as f:
-        with ExcelWriter(f, engine="openpyxl", engine_kwargs=engine_kwargs) as writer:
+        with ExcelWriter(f, engine="xlwt", engine_kwargs=engine_kwargs) as writer:
+            assert writer.book._Workbook__styles.style_compression == style_compression
             # xlwt won't allow us to close without writing something
             DataFrame().to_excel(writer)