DEPR: deprecated nonkeyword arguments in to_markdown (pandas-dev#54605)

* deprecated nonkeyword arguments

* added parameter keywords

doc/source/whatsnew/v2.2.0.rst

@@ -95,6 +95,7 @@ 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_json` except ``path_or_buf``. (:issue:`54229`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_latex` except ``buf``. (:issue:`54229`)
+- Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_markdown` except ``buf``. (:issue:`54229`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_pickle` except ``path``. (:issue:`54229`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_string` except ``buf``. (:issue:`54229`)
 -

pandas/core/frame.py

@@ -2800,6 +2800,9 @@ def to_feather(self, path: FilePath | WriteBuffer[bytes], **kwargs) -> None:
 
         to_feather(self, path, **kwargs)
 
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "buf"], name="to_markdown"
+    )
     @doc(
         Series.to_markdown,
         klass=_shared_doc_kwargs["klass"],

pandas/core/series.py

@@ -1871,7 +1871,7 @@ def to_markdown(
         {examples}
         """
         return self.to_frame().to_markdown(
-            buf, mode, index, storage_options=storage_options, **kwargs
+            buf, mode=mode, index=index, storage_options=storage_options, **kwargs
         )
 
     # ----------------------------------------------------------------------

pandas/tests/io/formats/test_to_markdown.py

@@ -1,8 +1,12 @@
-from io import StringIO
+from io import (
+    BytesIO,
+    StringIO,
+)
 
 import pytest
 
 import pandas as pd
+import pandas._testing as tm
 
 pytest.importorskip("tabulate")
 
@@ -88,3 +92,15 @@ def test_showindex_disallowed_in_kwargs():
     df = pd.DataFrame([1, 2, 3])
     with pytest.raises(ValueError, match="Pass 'index' instead of 'showindex"):
         df.to_markdown(index=True, showindex=True)
+
+
+def test_markdown_pos_args_deprecatation():
+    # GH-54229
+    df = pd.DataFrame({"a": [1, 2, 3]})
+    msg = (
+        r"Starting with pandas version 3.0 all arguments of to_markdown except for the "
+        r"argument 'buf' will be keyword-only."
+    )
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        buffer = BytesIO()
+        df.to_markdown(buffer, "grid")