DEPR: convert_dtypes boolean keywords

Deprecate the infer_objects, convert_string, convert_integer,
convert_boolean, and convert_floating keywords in
DataFrame.convert_dtypes and Series.convert_dtypes.

closes #62022

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jbrockmendel

doc/source/whatsnew/v3.1.0.rst

@@ -122,6 +122,7 @@ Deprecations
   :meth:`DataFrame.var`, :meth:`DataFrame.sem`, :meth:`DataFrame.sum`,
   :meth:`DataFrame.prod` (and their :class:`Series` equivalents); this will raise in
   a future version of pandas (:issue:`53098`)
+- Deprecated the ``infer_objects``, ``convert_string``, ``convert_integer``, ``convert_boolean``, and ``convert_floating`` keywords in :meth:`DataFrame.convert_dtypes` and :meth:`Series.convert_dtypes` (:issue:`62022`)
 - Deprecated the inference of ``datetime64`` dtype from data containing ``datetime.date`` objects when used in comparisons or :meth:`Index.equals` with :class:`DatetimeIndex`. Use :func:`pandas.to_datetime` to explicitly convert to ``datetime64`` instead (:issue:`65056`)
 -
 

pandas/core/generic.py

@@ -6776,11 +6776,11 @@ def infer_objects(self, copy: bool | lib.NoDefault = lib.no_default) -> Self:
     @final
     def convert_dtypes(
         self,
-        infer_objects: bool = True,
-        convert_string: bool = True,
-        convert_integer: bool = True,
-        convert_boolean: bool = True,
-        convert_floating: bool = True,
+        infer_objects: bool | lib.NoDefault = lib.no_default,
+        convert_string: bool | lib.NoDefault = lib.no_default,
+        convert_integer: bool | lib.NoDefault = lib.no_default,
+        convert_boolean: bool | lib.NoDefault = lib.no_default,
+        convert_floating: bool | lib.NoDefault = lib.no_default,
         dtype_backend: DtypeBackend = "numpy_nullable",
     ) -> Self:
         """
@@ -6794,16 +6794,41 @@ def convert_dtypes(
         ----------
         infer_objects : bool, default True
             Whether object dtypes should be converted to the best possible types.
+
+            .. deprecated:: 3.1.0
+                The ``infer_objects`` keyword is deprecated and will be removed
+                in a future version.
+
         convert_string : bool, default True
             Whether object dtypes should be converted to ``StringDtype()``.
+
+            .. deprecated:: 3.1.0
+                The ``convert_string`` keyword is deprecated and will be removed
+                in a future version.
+
         convert_integer : bool, default True
             Whether, if possible, conversion can be done to integer extension types.
+
+            .. deprecated:: 3.1.0
+                The ``convert_integer`` keyword is deprecated and will be removed
+                in a future version.
+
         convert_boolean : bool, defaults True
             Whether object dtypes should be converted to ``BooleanDtypes()``.
+
+            .. deprecated:: 3.1.0
+                The ``convert_boolean`` keyword is deprecated and will be removed
+                in a future version.
+
         convert_floating : bool, defaults True
             Whether, if possible, conversion can be done to floating extension types.
             If `convert_integer` is also True, preference will be give to integer
             dtypes if the floats can be faithfully casted to integers.
+
+            .. deprecated:: 3.1.0
+                The ``convert_floating`` keyword is deprecated and will be removed
+                in a future version.
+
         dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
             Back-end data type applied to the resultant :class:`DataFrame` or
             :class:`Series` (still experimental). Behaviour is as follows:
@@ -6916,6 +6941,38 @@ def convert_dtypes(
         dtype: string
         """
         check_dtype_backend(dtype_backend)
+        deprecated_args = {
+            "infer_objects": infer_objects,
+            "convert_string": convert_string,
+            "convert_integer": convert_integer,
+            "convert_boolean": convert_boolean,
+            "convert_floating": convert_floating,
+        }
+        for arg_name, arg_val in deprecated_args.items():
+            if arg_val is not lib.no_default:
+                warnings.warn(
+                    f"The {arg_name} keyword in {type(self).__name__}."
+                    f"convert_dtypes is deprecated and will be removed in a "
+                    f"future version.",
+                    Pandas4Warning,
+                    stacklevel=find_stack_level(),
+                )
+
+        # Resolve no_default to the current default values (True)
+        infer_objects = infer_objects if infer_objects is not lib.no_default else True
+        convert_string = (
+            convert_string if convert_string is not lib.no_default else True
+        )
+        convert_integer = (
+            convert_integer if convert_integer is not lib.no_default else True
+        )
+        convert_boolean = (
+            convert_boolean if convert_boolean is not lib.no_default else True
+        )
+        convert_floating = (
+            convert_floating if convert_floating is not lib.no_default else True
+        )
+
         new_mgr = self._mgr.convert_dtypes(
             infer_objects=infer_objects,
             convert_string=convert_string,

pandas/core/groupby/groupby.py

@@ -2711,13 +2711,7 @@ def size(self) -> DataFrame | Series:
             result = self._obj_1d_constructor(result)
 
         if dtype_backend is not None:
-            result = result.convert_dtypes(
-                infer_objects=False,
-                convert_string=False,
-                convert_boolean=False,
-                convert_floating=False,
-                dtype_backend=dtype_backend,
-            )
+            result = result.convert_dtypes(dtype_backend=dtype_backend)
 
         if not self.as_index:
             result = result.rename("size").reset_index()

pandas/io/json/_json.py

@@ -1047,9 +1047,7 @@ def _read_ujson(self) -> DataFrame | Series:
             obj = self._get_object_parser(self.data)
         if self.dtype_backend is not lib.no_default:
             with option_context("future.distinguish_nan_and_na", False):
-                return obj.convert_dtypes(
-                    infer_objects=False, dtype_backend=self.dtype_backend
-                )
+                return obj.convert_dtypes(dtype_backend=self.dtype_backend)
         else:
             return obj
 
@@ -1134,9 +1132,7 @@ def __next__(self) -> DataFrame | Series:
 
         if self.dtype_backend is not lib.no_default:
             with option_context("future.distinguish_nan_and_na", False):
-                return obj.convert_dtypes(
-                    infer_objects=False, dtype_backend=self.dtype_backend
-                )
+                return obj.convert_dtypes(dtype_backend=self.dtype_backend)
         else:
             return obj
 

pandas/tests/copy_view/test_astype.py

@@ -3,6 +3,8 @@
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 from pandas import (
     DataFrame,
     Series,
@@ -199,12 +201,13 @@ def test_astype_arrow_timestamp():
 def test_convert_dtypes_infer_objects():
     ser = Series(["a", "b", "c"])
     ser_orig = ser.copy()
-    result = ser.convert_dtypes(
-        convert_integer=False,
-        convert_boolean=False,
-        convert_floating=False,
-        convert_string=False,
-    )
+    with tm.assert_produces_warning(Pandas4Warning):
+        result = ser.convert_dtypes(
+            convert_integer=False,
+            convert_boolean=False,
+            convert_floating=False,
+            convert_string=False,
+        )
 
     assert tm.shares_memory(get_array(ser), get_array(result))
     result.iloc[0] = "x"

pandas/tests/frame/methods/test_convert_dtypes.py

@@ -3,6 +3,7 @@
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
 import pandas.util._test_decorators as td
 
 import pandas as pd
@@ -23,7 +24,8 @@ def test_convert_dtypes(self, convert_integer, expected, string_storage):
             }
         )
         with pd.option_context("string_storage", string_storage):
-            result = df.convert_dtypes(True, True, convert_integer, False)
+            with tm.assert_produces_warning(Pandas4Warning):
+                result = df.convert_dtypes(True, True, convert_integer, False)
         expected = pd.DataFrame(
             {
                 "a": pd.Series([1, 2, 3], dtype=expected),
@@ -168,13 +170,14 @@ def test_pyarrow_backend_no_conversion(self):
         pytest.importorskip("pyarrow")
         df = pd.DataFrame({"a": [1, 2], "b": 1.5, "c": True, "d": "x"})
         expected = df.copy()
-        result = df.convert_dtypes(
-            convert_floating=False,
-            convert_integer=False,
-            convert_boolean=False,
-            convert_string=False,
-            dtype_backend="pyarrow",
-        )
+        with tm.assert_produces_warning(Pandas4Warning):
+            result = df.convert_dtypes(
+                convert_floating=False,
+                convert_integer=False,
+                convert_boolean=False,
+                convert_string=False,
+                dtype_backend="pyarrow",
+            )
         tm.assert_frame_equal(result, expected)
 
     def test_convert_dtypes_pyarrow_to_np_nullable(self):
@@ -196,7 +199,8 @@ def test_convert_dtypes_pyarrow_timestamp(self):
     def test_convert_dtypes_avoid_block_splitting(self):
         # GH#55341
         df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6], "c": "a"})
-        result = df.convert_dtypes(convert_integer=False)
+        with tm.assert_produces_warning(Pandas4Warning):
+            result = df.convert_dtypes(convert_integer=False)
         expected = pd.DataFrame(
             {
                 "a": [1, 2, 3],
@@ -253,3 +257,20 @@ def test_convert_dtypes_mixed_column_after_slice(self):
             }
         )
         tm.assert_frame_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "kwarg",
+        [
+            "infer_objects",
+            "convert_string",
+            "convert_integer",
+            "convert_boolean",
+            "convert_floating",
+        ],
+    )
+    def test_convert_dtypes_deprecated_kwargs(self, kwarg):
+        # GH#62022
+        df = pd.DataFrame({"a": [1, 2, 3]})
+        msg = f"The {kwarg} keyword in DataFrame.convert_dtypes"
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            df.convert_dtypes(**{kwarg: True})

pandas/tests/groupby/aggregate/test_cython.py

@@ -5,6 +5,8 @@
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 from pandas.core.dtypes.common import (
     is_float_dtype,
     is_integer_dtype,
@@ -326,7 +328,8 @@ def test_cython_agg_nullable_int(op_name):
         convert_integer = False
     else:
         convert_integer = True
-    expected = expected.convert_dtypes(convert_integer=convert_integer)
+    with tm.assert_produces_warning(Pandas4Warning):
+        expected = expected.convert_dtypes(convert_integer=convert_integer)
     tm.assert_series_equal(result, expected)
 
 

pandas/tests/series/methods/test_convert_dtypes.py

@@ -4,6 +4,7 @@
 import pytest
 
 from pandas._libs import lib
+from pandas.errors import Pandas4Warning
 import pandas.util._test_decorators as td
 
 import pandas as pd
@@ -200,7 +201,8 @@ def test_convert_dtypes(
         else:
             series = pd.Series(data)
 
-        result = series.convert_dtypes(*params)
+        with tm.assert_produces_warning(Pandas4Warning):
+            result = series.convert_dtypes(*params)
 
         param_names = [
             "infer_objects",
@@ -283,7 +285,8 @@ def test_convert_byte_string_dtype(self):
     def test_convert_dtype_object_with_na(self, infer_objects, dtype):
         # GH#48791
         ser = pd.Series([1, pd.NA])
-        result = ser.convert_dtypes(infer_objects=infer_objects)
+        with tm.assert_produces_warning(Pandas4Warning):
+            result = ser.convert_dtypes(infer_objects=infer_objects)
         expected = pd.Series([1, pd.NA], dtype=dtype)
         tm.assert_series_equal(result, expected)
 
@@ -293,7 +296,8 @@ def test_convert_dtype_object_with_na(self, infer_objects, dtype):
     def test_convert_dtype_object_with_na_float(self, infer_objects, dtype):
         # GH#48791
         ser = pd.Series([1.5, pd.NA])
-        result = ser.convert_dtypes(infer_objects=infer_objects)
+        with tm.assert_produces_warning(Pandas4Warning):
+            result = ser.convert_dtypes(infer_objects=infer_objects)
         expected = pd.Series([1.5, pd.NA], dtype=dtype)
         tm.assert_series_equal(result, expected)