DEPR: deprecate set_eng_float_format (#64717)

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

Author: jbrockmendel

doc/source/user_guide/options.rst

@@ -307,17 +307,13 @@ Number formatting
 ------------------
 
 pandas also allows you to set how numbers are displayed in the console.
-This option is not set through the ``set_options`` API.
-
-Use the ``set_eng_float_format`` function
-to alter the floating-point formatting of pandas objects to produce a particular
-format.
+Use ``display.precision`` to control the number of decimal places:
 
 .. ipython:: python
 
    import numpy as np
 
-   pd.set_eng_float_format(accuracy=3, use_eng_prefix=True)
+   pd.set_option("display.precision", 2)
    s = pd.Series(np.random.randn(5), index=["a", "b", "c", "d", "e"])
    s / 1.0e3
    s / 1.0e6

doc/source/whatsnew/v3.1.0.rst

@@ -99,6 +99,7 @@ Other API changes
 Deprecations
 ~~~~~~~~~~~~
 - Deprecated :attr:`Timestamp.dayofweek`, :attr:`Timestamp.dayofyear`, :attr:`Timestamp.daysinmonth` in favor of :attr:`Timestamp.day_of_week`, :attr:`Timestamp.day_of_year`, :attr:`Timestamp.days_in_month`, respectively. The same deprecation applies to the corresponding attributes on :class:`Period`, :class:`DatetimeIndex`, :class:`PeriodIndex`, and :attr:`Series.dt` (:issue:`46768`)
+- Deprecated :func:`set_eng_float_format`. Use ``pd.set_option("display.precision", N)`` to control decimal precision, or pass a custom callable to ``pd.set_option("display.float_format", func)`` (:issue:`64460`)
 - Deprecated :meth:`.DataFrameGroupBy.agg` and :meth:`.Resampler.agg` unpacking a scalar when the provided ``func`` returns a Series or array of length 1; in the future this will result in the Series or array being in the result. Users should unpack the scalar in ``func`` itself (:issue:`64014`)
 - Deprecated :meth:`ExcelFile.parse`, use :func:`read_excel` instead (:issue:`58247`)
 - Deprecated ``engine="fastparquet"`` and ``engine="auto"`` in :func:`read_parquet` and :meth:`DataFrame.to_parquet`. The ``fastparquet`` library has been retired; use ``engine="pyarrow"`` or do not pass ``engine`` to use the default. (:issue:`64597`)

pandas/io/formats/format.py

@@ -25,6 +25,7 @@
     Any,
     cast,
 )
+import warnings
 
 import numpy as np
 
@@ -41,7 +42,9 @@
     Timestamp,
 )
 from pandas._libs.tslibs.nattype import NaTType
+from pandas.errors import Pandas4Warning
 from pandas.util._decorators import set_module
+from pandas.util._exceptions import find_stack_level
 
 from pandas.core.dtypes.common import (
     is_complex_dtype,
@@ -1945,6 +1948,11 @@ def set_eng_float_format(accuracy: int = 3, use_eng_prefix: bool = False) -> Non
     """
     Format float representation in DataFrame with SI notation.
 
+    .. deprecated:: 3.1.0
+        Use ``pd.set_option("display.precision", N)`` to control decimal
+        precision, or pass a custom callable to
+        ``pd.set_option("display.float_format", func)``.
+
     Sets the floating-point display format for ``DataFrame`` objects using engineering
     notation (SI units), allowing easier readability of values across wide ranges.
 
@@ -1968,44 +1976,26 @@ def set_eng_float_format(accuracy: int = 3, use_eng_prefix: bool = False) -> Non
 
     Examples
     --------
-    >>> df = pd.DataFrame([1e-9, 1e-3, 1, 1e3, 1e6])
-    >>> df
-                  0
-    0  1.000000e-09
-    1  1.000000e-03
-    2  1.000000e+00
-    3  1.000000e+03
-    4  1.000000e+06
-
-    >>> pd.set_eng_float_format(accuracy=1)
-    >>> df
-             0
-    0  1.0E-09
-    1  1.0E-03
-    2  1.0E+00
-    3  1.0E+03
-    4  1.0E+06
-
-    >>> pd.set_eng_float_format(use_eng_prefix=True)
-    >>> df
-            0
-    0  1.000n
-    1  1.000m
-    2   1.000
-    3  1.000k
-    4  1.000M
-
-    >>> pd.set_eng_float_format(accuracy=1, use_eng_prefix=True)
-    >>> df
-          0
-    0  1.0n
-    1  1.0m
-    2   1.0
-    3  1.0k
-    4  1.0M
-
-    >>> pd.set_option("display.float_format", None)  # unset option
+    Use ``pd.set_option("display.precision", N)`` to control decimal
+    precision instead:
+
+    >>> with pd.option_context("display.precision", 3):
+    ...     print(pd.DataFrame([1e-9, 1e-3, 1, 1e3, 1e6]))
+               0
+    0  1.000e-09
+    1  1.000e-03
+    2  1.000e+00
+    3  1.000e+03
+    4  1.000e+06
     """
+    warnings.warn(
+        "set_eng_float_format is deprecated and will be removed in a future "
+        "version. Use pd.set_option('display.precision', N) to control decimal "
+        "precision, or pass a custom callable to "
+        "pd.set_option('display.float_format', func).",
+        Pandas4Warning,
+        stacklevel=find_stack_level(),
+    )
     set_option("display.float_format", EngFormatter(accuracy, use_eng_prefix))
 
 

pandas/tests/io/formats/test_eng_formatting.py

@@ -1,11 +1,15 @@
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 from pandas import (
     DataFrame,
     reset_option,
     set_eng_float_format,
+    set_option,
 )
+import pandas._testing as tm
 
 from pandas.io.formats.format import EngFormatter
 
@@ -21,19 +25,23 @@ def test_eng_float_formatter2(self, float_frame):
         df = float_frame
         df.loc[5] = 0
 
-        set_eng_float_format()
+        msg = "set_eng_float_format is deprecated"
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            set_eng_float_format()
         repr(df)
 
-        set_eng_float_format(use_eng_prefix=True)
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            set_eng_float_format(use_eng_prefix=True)
         repr(df)
 
-        set_eng_float_format(accuracy=0)
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            set_eng_float_format(accuracy=0)
         repr(df)
 
     def test_eng_float_formatter(self):
         df = DataFrame({"A": [1.41, 141.0, 14100, 1410000.0]})
 
-        set_eng_float_format()
+        set_option("display.float_format", EngFormatter(accuracy=3))
         result = df.to_string()
         expected = (
             "             A\n"
@@ -44,12 +52,15 @@ def test_eng_float_formatter(self):
         )
         assert result == expected
 
-        set_eng_float_format(use_eng_prefix=True)
+        set_option(
+            "display.float_format",
+            EngFormatter(accuracy=3, use_eng_prefix=True),
+        )
         result = df.to_string()
         expected = "         A\n0    1.410\n1  141.000\n2  14.100k\n3   1.410M"
         assert result == expected
 
-        set_eng_float_format(accuracy=0)
+        set_option("display.float_format", EngFormatter(accuracy=0))
         result = df.to_string()
         expected = "         A\n0    1E+00\n1  141E+00\n2   14E+03\n3    1E+06"
         assert result == expected
@@ -242,7 +253,7 @@ def test_nan(self):
             }
         )
         pt = df.pivot_table(values="a", index="b", columns="c")
-        set_eng_float_format(accuracy=1)
+        set_option("display.float_format", EngFormatter(accuracy=1))
         result = pt.to_string()
         assert "NaN" in result