WARN: Clarify future warnings for read_csv (#44651)

* WARN: Clarify future warnings for read_csv

* Adjust test

* Use namedtuple

* Fix tests

Author: phofl

pandas/io/parsers/readers.py

@@ -7,7 +7,10 @@
 import csv
 import sys
 from textwrap import fill
-from typing import Any
+from typing import (
+    Any,
+    NamedTuple,
+)
 import warnings
 
 import numpy as np
@@ -446,10 +449,18 @@
     "low_memory",
 }
 
-_deprecated_defaults: dict[str, Any] = {
-    "error_bad_lines": None,
-    "warn_bad_lines": None,
-    "squeeze": None,
+
+class _DeprecationConfig(NamedTuple):
+    default_value: Any
+    msg: str | None
+
+
+_deprecated_defaults: dict[str, _DeprecationConfig] = {
+    "error_bad_lines": _DeprecationConfig(None, "Use on_bad_lines in the future."),
+    "warn_bad_lines": _DeprecationConfig(None, "Use on_bad_lines in the future."),
+    "squeeze": _DeprecationConfig(
+        None, 'Append .squeeze("columns") to the call to squeeze.'
+    ),
 }
 
 
@@ -926,15 +937,22 @@ def _get_options_with_defaults(self, engine):
                 if engine != "c" and value != default:
                     if "python" in engine and argname not in _python_unsupported:
                         pass
-                    elif value == _deprecated_defaults.get(argname, default):
+                    elif (
+                        value
+                        == _deprecated_defaults.get(
+                            argname, _DeprecationConfig(default, None)
+                        ).default_value
+                    ):
                         pass
                     else:
                         raise ValueError(
                             f"The {repr(argname)} option is not supported with the "
                             f"{repr(engine)} engine"
                         )
             else:
-                value = _deprecated_defaults.get(argname, default)
+                value = _deprecated_defaults.get(
+                    argname, _DeprecationConfig(default, None)
+                ).default_value
             options[argname] = value
 
         if engine == "python-fwf":
@@ -1059,10 +1077,10 @@ def _clean_options(self, options, engine):
         for arg in _deprecated_defaults.keys():
             parser_default = _c_parser_defaults.get(arg, parser_defaults[arg])
             depr_default = _deprecated_defaults[arg]
-            if result.get(arg, depr_default) != depr_default:
+            if result.get(arg, depr_default) != depr_default.default_value:
                 msg = (
                     f"The {arg} argument has been deprecated and will be "
-                    "removed in a future version.\n\n"
+                    f"removed in a future version. {depr_default.msg}\n\n"
                 )
                 warnings.warn(msg, FutureWarning, stacklevel=find_stack_level())
             else:

pandas/tests/io/excel/test_readers.py

@@ -1195,7 +1195,8 @@ def test_read_excel_squeeze(self, read_ext):
         with tm.assert_produces_warning(
             FutureWarning,
             match="The squeeze argument has been deprecated "
-            "and will be removed in a future version.\n\n",
+            "and will be removed in a future version. "
+            'Append .squeeze\\("columns"\\) to the call to squeeze.\n\n',
         ):
             actual = pd.read_excel(
                 f, sheet_name="two_columns", index_col=0, squeeze=True

pandas/tests/io/parser/common/test_common_basic.py

@@ -143,7 +143,8 @@ def test_squeeze(all_parsers, squeeze):
     result = parser.read_csv_check_warnings(
         FutureWarning,
         "The squeeze argument has been deprecated "
-        "and will be removed in a future version.\n\n",
+        "and will be removed in a future version. "
+        'Append .squeeze\\("columns"\\) to the call to squeeze.\n\n',
         StringIO(data),
         index_col=0,
         header=None,
@@ -877,7 +878,8 @@ def test_deprecated_bad_lines_warns(all_parsers, csv1, on_bad_lines):
     parser.read_csv_check_warnings(
         FutureWarning,
         f"The {on_bad_lines}_bad_lines argument has been deprecated "
-        "and will be removed in a future version.\n\n",
+        "and will be removed in a future version. "
+        "Use on_bad_lines in the future.\n\n",
         csv1,
         **kwds,
     )