DEPR: Positional arguments in to_hdf except path_or_buf (#54491)

* Adding deprecation, updating unit tests and documentation.

* Fixing failing unit test.

* Moving contribution to whatsnew/v2.2.0

* Update v2.1.0.rst

doc/source/user_guide/io.rst

@@ -4220,7 +4220,7 @@ similar to how ``read_csv`` and ``to_csv`` work.
 .. ipython:: python
 
    df_tl = pd.DataFrame({"A": list(range(5)), "B": list(range(5))})
-   df_tl.to_hdf("store_tl.h5", "table", append=True)
+   df_tl.to_hdf("store_tl.h5", key="table", append=True)
    pd.read_hdf("store_tl.h5", "table", where=["index>2"])
 
 .. ipython:: python
@@ -4243,12 +4243,12 @@ HDFStore will by default not drop rows that are all missing. This behavior can b
    )
    df_with_missing
 
-   df_with_missing.to_hdf("file.h5", "df_with_missing", format="table", mode="w")
+   df_with_missing.to_hdf("file.h5", key="df_with_missing", format="table", mode="w")
 
    pd.read_hdf("file.h5", "df_with_missing")
 
    df_with_missing.to_hdf(
-       "file.h5", "df_with_missing", format="table", mode="w", dropna=True
+       "file.h5", key="df_with_missing", format="table", mode="w", dropna=True
    )
    pd.read_hdf("file.h5", "df_with_missing")
 
@@ -4278,7 +4278,7 @@ This format is specified by default when using ``put`` or ``to_hdf`` or by ``for
    .. ipython:: python
       :okexcept:
 
-      pd.DataFrame(np.random.randn(10, 2)).to_hdf("test_fixed.h5", "df")
+      pd.DataFrame(np.random.randn(10, 2)).to_hdf("test_fixed.h5", key="df")
       pd.read_hdf("test_fixed.h5", "df", where="index>5")
 
    .. ipython:: python
@@ -6321,23 +6321,23 @@ The following test functions will be used below to compare the performance of se
 
 
    def test_hdf_fixed_write(df):
-       df.to_hdf("test_fixed.hdf", "test", mode="w")
+       df.to_hdf("test_fixed.hdf", key="test", mode="w")
 
 
    def test_hdf_fixed_read():
        pd.read_hdf("test_fixed.hdf", "test")
 
 
    def test_hdf_fixed_write_compress(df):
-       df.to_hdf("test_fixed_compress.hdf", "test", mode="w", complib="blosc")
+       df.to_hdf("test_fixed_compress.hdf", key="test", mode="w", complib="blosc")
 
 
    def test_hdf_fixed_read_compress():
        pd.read_hdf("test_fixed_compress.hdf", "test")
 
 
    def test_hdf_table_write(df):
-       df.to_hdf("test_table.hdf", "test", mode="w", format="table")
+       df.to_hdf("test_table.hdf", key="test", mode="w", format="table")
 
 
    def test_hdf_table_read():
@@ -6346,7 +6346,7 @@ The following test functions will be used below to compare the performance of se
 
    def test_hdf_table_write_compress(df):
        df.to_hdf(
-           "test_table_compress.hdf", "test", mode="w", complib="blosc", format="table"
+           "test_table_compress.hdf", key="test", mode="w", complib="blosc", format="table"
        )
 
 

doc/source/whatsnew/v0.11.0.rst

@@ -347,7 +347,7 @@ Enhancements
       .. ipython:: python
 
           df = pd.DataFrame({'A': range(5), 'B': range(5)})
-          df.to_hdf('store.h5', 'table', append=True)
+          df.to_hdf('store.h5', key='table', append=True)
           pd.read_hdf('store.h5', 'table', where=['index > 2'])
 
       .. ipython:: python

doc/source/whatsnew/v0.13.0.rst

@@ -385,7 +385,7 @@ HDFStore API changes
      dfq = pd.DataFrame(np.random.randn(10, 4),
                         columns=list('ABCD'),
                         index=pd.date_range('20130101', periods=10))
-     dfq.to_hdf(path, 'dfq', format='table', data_columns=True)
+     dfq.to_hdf(path, key='dfq', format='table', data_columns=True)
 
   Use boolean expressions, with in-line function evaluation.
 
@@ -415,9 +415,9 @@ HDFStore API changes
 
      path = 'test.h5'
      df = pd.DataFrame(np.random.randn(10, 2))
-     df.to_hdf(path, 'df_table', format='table')
-     df.to_hdf(path, 'df_table2', append=True)
-     df.to_hdf(path, 'df_fixed')
+     df.to_hdf(path, key='df_table', format='table')
+     df.to_hdf(path, key='df_table2', append=True)
+     df.to_hdf(path, key='df_fixed')
      with pd.HDFStore(path) as store:
          print(store)
 

doc/source/whatsnew/v0.17.0.rst

@@ -793,7 +793,7 @@ Previous behavior:
 
    In [27]:
    df_with_missing.to_hdf('file.h5',
-                          'df_with_missing',
+                          key='df_with_missing',
                           format='table',
                           mode='w')
 
@@ -809,7 +809,7 @@ New behavior:
 
 .. ipython:: python
 
-   df_with_missing.to_hdf("file.h5", "df_with_missing", format="table", mode="w")
+   df_with_missing.to_hdf("file.h5", key="df_with_missing", format="table", mode="w")
 
    pd.read_hdf("file.h5", "df_with_missing")
 

doc/source/whatsnew/v0.20.0.rst

@@ -1059,7 +1059,7 @@ usually resulting in an invalid comparison, returning an empty result frame. The
 .. ipython:: python
 
    df = pd.DataFrame({'unparsed_date': ['2014-01-01', '2014-01-01']})
-   df.to_hdf('store.h5', 'key', format='table', data_columns=True)
+   df.to_hdf('store.h5', key='key', format='table', data_columns=True)
    df.dtypes
 
 Previous behavior:

doc/source/whatsnew/v2.2.0.rst

@@ -92,6 +92,7 @@ Other API changes
 
 Deprecations
 ~~~~~~~~~~~~
+- Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_hdf` except ``path_or_buf``. (:issue:`54229`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_pickle` except ``path``. (:issue:`54229`)
 -
 

pandas/core/generic.py

@@ -2642,6 +2642,9 @@ def to_json(
         )
 
     @final
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "path_or_buf"], name="to_hdf"
+    )
     def to_hdf(
         self,
         path_or_buf: FilePath | HDFStore,

pandas/tests/io/pytables/test_append.py

@@ -643,7 +643,7 @@ def test_append_hierarchical(tmp_path, setup_path, multiindex_dataframe_random_d
         tm.assert_frame_equal(result, expected)
 
     path = tmp_path / "test.hdf"
-    df.to_hdf(path, "df", format="table")
+    df.to_hdf(path, key="df", format="table")
     result = read_hdf(path, "df", columns=["A", "B"])
     expected = df.reindex(columns=["A", "B"])
     tm.assert_frame_equal(result, expected)

pandas/tests/io/pytables/test_categorical.py

@@ -152,7 +152,7 @@ def test_categorical_conversion(tmp_path, setup_path):
     # We are expecting an empty DataFrame matching types of df
     expected = df.iloc[[], :]
     path = tmp_path / setup_path
-    df.to_hdf(path, "df", format="table", data_columns=True)
+    df.to_hdf(path, key="df", format="table", data_columns=True)
     result = read_hdf(path, "df", where="obsids=B")
     tm.assert_frame_equal(result, expected)
 
@@ -163,7 +163,7 @@ def test_categorical_conversion(tmp_path, setup_path):
     # We are expecting an empty DataFrame matching types of df
     expected = df.iloc[[], :]
     path = tmp_path / setup_path
-    df.to_hdf(path, "df", format="table", data_columns=True)
+    df.to_hdf(path, key="df", format="table", data_columns=True)
     result = read_hdf(path, "df", where="obsids=B")
     tm.assert_frame_equal(result, expected)
 
@@ -185,7 +185,7 @@ def test_categorical_nan_only_columns(tmp_path, setup_path):
     df["d"] = df.b.astype("category")
     expected = df
     path = tmp_path / setup_path
-    df.to_hdf(path, "df", format="table", data_columns=True)
+    df.to_hdf(path, key="df", format="table", data_columns=True)
     result = read_hdf(path, "df")
     tm.assert_frame_equal(result, expected)
 
@@ -209,6 +209,6 @@ def test_convert_value(
     expected.col = expected.col.cat.set_categories(categorical_values)
 
     path = tmp_path / setup_path
-    df.to_hdf(path, "df", format="table", min_itemsize=max_widths)
+    df.to_hdf(path, key="df", format="table", min_itemsize=max_widths)
     result = read_hdf(path, where=where)
     tm.assert_frame_equal(result, expected)

pandas/tests/io/pytables/test_complex.py

@@ -20,7 +20,7 @@ def test_complex_fixed(tmp_path, setup_path):
     )
 
     path = tmp_path / setup_path
-    df.to_hdf(path, "df")
+    df.to_hdf(path, key="df")
     reread = read_hdf(path, "df")
     tm.assert_frame_equal(df, reread)
 
@@ -30,7 +30,7 @@ def test_complex_fixed(tmp_path, setup_path):
         columns=list("ABCDE"),
     )
     path = tmp_path / setup_path
-    df.to_hdf(path, "df")
+    df.to_hdf(path, key="df")
     reread = read_hdf(path, "df")
     tm.assert_frame_equal(df, reread)
 
@@ -43,8 +43,8 @@ def test_complex_table(tmp_path, setup_path):
     )
 
     path = tmp_path / setup_path
-    df.to_hdf(path, "df", format="table")
-    reread = read_hdf(path, "df")
+    df.to_hdf(path, key="df", format="table")
+    reread = read_hdf(path, key="df")
     tm.assert_frame_equal(df, reread)
 
     df = DataFrame(
@@ -54,7 +54,7 @@ def test_complex_table(tmp_path, setup_path):
     )
 
     path = tmp_path / setup_path
-    df.to_hdf(path, "df", format="table", mode="w")
+    df.to_hdf(path, key="df", format="table", mode="w")
     reread = read_hdf(path, "df")
     tm.assert_frame_equal(df, reread)
 
@@ -77,7 +77,7 @@ def test_complex_mixed_fixed(tmp_path, setup_path):
         index=list("abcd"),
     )
     path = tmp_path / setup_path
-    df.to_hdf(path, "df")
+    df.to_hdf(path, key="df")
     reread = read_hdf(path, "df")
     tm.assert_frame_equal(df, reread)
 
@@ -106,7 +106,7 @@ def test_complex_mixed_table(tmp_path, setup_path):
         tm.assert_frame_equal(df.loc[df.A > 2], result)
 
     path = tmp_path / setup_path
-    df.to_hdf(path, "df", format="table")
+    df.to_hdf(path, key="df", format="table")
     reread = read_hdf(path, "df")
     tm.assert_frame_equal(df, reread)
 
@@ -120,7 +120,7 @@ def test_complex_across_dimensions_fixed(tmp_path, setup_path):
     comps = [tm.assert_series_equal, tm.assert_frame_equal]
     for obj, comp in zip(objs, comps):
         path = tmp_path / setup_path
-        obj.to_hdf(path, "obj", format="fixed")
+        obj.to_hdf(path, key="obj", format="fixed")
         reread = read_hdf(path, "obj")
         comp(obj, reread)
 
@@ -131,7 +131,7 @@ def test_complex_across_dimensions(tmp_path, setup_path):
     df = DataFrame({"A": s, "B": s})
 
     path = tmp_path / setup_path
-    df.to_hdf(path, "obj", format="table")
+    df.to_hdf(path, key="obj", format="table")
     reread = read_hdf(path, "obj")
     tm.assert_frame_equal(df, reread)
 
@@ -172,10 +172,10 @@ def test_complex_series_error(tmp_path, setup_path):
 
     path = tmp_path / setup_path
     with pytest.raises(TypeError, match=msg):
-        s.to_hdf(path, "obj", format="t")
+        s.to_hdf(path, key="obj", format="t")
 
     path = tmp_path / setup_path
-    s.to_hdf(path, "obj", format="t", index=False)
+    s.to_hdf(path, key="obj", format="t", index=False)
     reread = read_hdf(path, "obj")
     tm.assert_series_equal(s, reread)
 

pandas/tests/io/pytables/test_errors.py

@@ -115,7 +115,7 @@ def test_invalid_terms(tmp_path, setup_path):
         columns=list("ABCD"),
         index=date_range("20130101", periods=10),
     )
-    dfq.to_hdf(path, "dfq", format="table", data_columns=True)
+    dfq.to_hdf(path, key="dfq", format="table", data_columns=True)
 
     # check ok
     read_hdf(path, "dfq", where="index>Timestamp('20130104') & columns=['A', 'B']")
@@ -128,7 +128,7 @@ def test_invalid_terms(tmp_path, setup_path):
         columns=list("ABCD"),
         index=date_range("20130101", periods=10),
     )
-    dfq.to_hdf(path, "dfq", format="table")
+    dfq.to_hdf(path, key="dfq", format="table")
 
     msg = (
         r"The passed where expression: A>0 or C>0\n\s*"
@@ -169,7 +169,7 @@ def test_invalid_complib(setup_path):
     with tm.ensure_clean(setup_path) as path:
         msg = r"complib only supports \[.*\] compression."
         with pytest.raises(ValueError, match=msg):
-            df.to_hdf(path, "df", complib="foolib")
+            df.to_hdf(path, key="df", complib="foolib")
 
 
 @pytest.mark.parametrize(
@@ -185,7 +185,7 @@ def test_to_hdf_multiindex_extension_dtype(idx, tmp_path, setup_path):
     df = DataFrame(0, index=mi, columns=["a"])
     path = tmp_path / setup_path
     with pytest.raises(NotImplementedError, match="Saving a MultiIndex"):
-        df.to_hdf(path, "df")
+        df.to_hdf(path, key="df")
 
 
 def test_unsuppored_hdf_file_error(datapath):
@@ -212,7 +212,7 @@ def test_read_hdf_errors(setup_path, tmp_path):
     with pytest.raises(OSError, match=msg):
         read_hdf(path, "key")
 
-    df.to_hdf(path, "df")
+    df.to_hdf(path, key="df")
     store = HDFStore(path, mode="r")
     store.close()