DEPR: positional arguments of read/to_state (#48128)

* DEPR: positional arguments of read/to_state

* pr number

* isort

* use keyword arguments in tests and fix typo

Author: twoertwein

doc/source/whatsnew/v1.5.0.rst

@@ -850,6 +850,7 @@ Other Deprecations
 - Deprecated producing a single element when iterating over a :class:`DataFrameGroupBy` or a :class:`SeriesGroupBy` that has been grouped by a list of length 1; A tuple of length one will be returned instead (:issue:`42795`)
 - Fixed up warning message of deprecation of :meth:`MultiIndex.lesort_depth` as public method, as the message previously referred to :meth:`MultiIndex.is_lexsorted` instead (:issue:`38701`)
 - Deprecated the ``sort_columns`` argument in :meth:`DataFrame.plot` and :meth:`Series.plot` (:issue:`47563`).
+- Deprecated positional arguments for all but the first argument of :meth:`DataFrame.to_stata` and :func:`read_stata`, use keyword arguments instead (:issue:`48128`).
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_150.performance:

pandas/core/frame.py

@@ -2576,6 +2576,7 @@ def _from_arrays(
         compression_options=_shared_docs["compression_options"] % "path",
     )
     @deprecate_kwarg(old_arg_name="fname", new_arg_name="path")
+    @deprecate_nonkeyword_arguments(version=None, allowed_args=["self", "path"])
     def to_stata(
         self,
         path: FilePath | WriteBuffer[bytes],

pandas/io/stata.py

@@ -49,6 +49,7 @@
 )
 from pandas.util._decorators import (
     Appender,
+    deprecate_nonkeyword_arguments,
     doc,
 )
 
@@ -1980,6 +1981,7 @@ def value_labels(self) -> dict[str, dict[float, str]]:
 
 
 @Appender(_read_stata_doc)
+@deprecate_nonkeyword_arguments(version=None, allowed_args=["filepath_or_buffer"])
 def read_stata(
     filepath_or_buffer: FilePath | ReadBuffer[bytes],
     convert_dates: bool = True,

pandas/tests/io/test_stata.py

@@ -285,7 +285,7 @@ def test_read_write_dta5(self):
         original.index.name = "index"
 
         with tm.ensure_clean() as path:
-            original.to_stata(path, None)
+            original.to_stata(path, convert_dates=None)
             written_and_read_again = self.read_dta(path)
             tm.assert_frame_equal(written_and_read_again.set_index("index"), original)
 
@@ -297,7 +297,7 @@ def test_write_dta6(self, datapath):
         original["quarter"] = original["quarter"].astype(np.int32)
 
         with tm.ensure_clean() as path:
-            original.to_stata(path, None)
+            original.to_stata(path, convert_dates=None)
             written_and_read_again = self.read_dta(path)
             tm.assert_frame_equal(
                 written_and_read_again.set_index("index"),
@@ -317,7 +317,7 @@ def test_read_write_dta10(self, version):
         original["integer"] = original["integer"].astype(np.int32)
 
         with tm.ensure_clean() as path:
-            original.to_stata(path, {"datetime": "tc"}, version=version)
+            original.to_stata(path, convert_dates={"datetime": "tc"}, version=version)
             written_and_read_again = self.read_dta(path)
             # original.index is np.int32, read index is np.int64
             tm.assert_frame_equal(
@@ -377,7 +377,7 @@ def test_read_write_dta11(self):
 
         with tm.ensure_clean() as path:
             with tm.assert_produces_warning(InvalidColumnName):
-                original.to_stata(path, None)
+                original.to_stata(path, convert_dates=None)
 
             written_and_read_again = self.read_dta(path)
             tm.assert_frame_equal(written_and_read_again.set_index("index"), formatted)
@@ -412,7 +412,7 @@ def test_read_write_dta12(self, version):
         with tm.ensure_clean() as path:
             with warnings.catch_warnings(record=True) as w:
                 warnings.simplefilter("always", InvalidColumnName)
-                original.to_stata(path, None, version=version)
+                original.to_stata(path, convert_dates=None, version=version)
                 # should get a warning for that format.
                 assert len(w) == 1
 
@@ -453,7 +453,7 @@ def test_read_write_reread_dta14(self, file, parsed_114, version, datapath):
         tm.assert_frame_equal(parsed_114, parsed)
 
         with tm.ensure_clean() as path:
-            parsed_114.to_stata(path, {"date_td": "td"}, version=version)
+            parsed_114.to_stata(path, convert_dates={"date_td": "td"}, version=version)
             written_and_read_again = self.read_dta(path)
             tm.assert_frame_equal(written_and_read_again.set_index("index"), parsed_114)
 
@@ -573,7 +573,7 @@ def test_dates_invalid_column(self):
         original.index.name = "index"
         with tm.ensure_clean() as path:
             with tm.assert_produces_warning(InvalidColumnName):
-                original.to_stata(path, {0: "tc"})
+                original.to_stata(path, convert_dates={0: "tc"})
 
             written_and_read_again = self.read_dta(path)
             modified = original.copy()
@@ -623,7 +623,7 @@ def test_date_export_formats(self):
         expected = DataFrame([expected_values], columns=columns)
         expected.index.name = "index"
         with tm.ensure_clean() as path:
-            original.to_stata(path, conversions)
+            original.to_stata(path, convert_dates=conversions)
             written_and_read_again = self.read_dta(path)
             tm.assert_frame_equal(written_and_read_again.set_index("index"), expected)