STYLE: Prohibit parsing exeption messages in try/except code flows

doc/source/reference/testing.rst

@@ -66,6 +66,7 @@ Exceptions and warnings
    errors.PyperclipException
    errors.PyperclipWindowsException
    errors.SpecificationError
+   errors.TimezoneDtypeMismatchError
    errors.UndefinedVariableError
    errors.UnsortedIndexError
    errors.UnsupportedFunctionCall

pandas/core/arrays/datetimes.py

@@ -45,7 +45,10 @@
     tzconversion,
 )
 from pandas._libs.tslibs.dtypes import abbrev_to_npy_unit
-from pandas.errors import PerformanceWarning
+from pandas.errors import (
+    PerformanceWarning,
+    TimezoneDtypeMismatchError,
+)
 from pandas.util._exceptions import find_stack_level
 from pandas.util._validators import validate_inclusive
 
@@ -2830,7 +2833,7 @@ def _validate_tz_from_dtype(
             # We also need to check for the case where the user passed a
             #  tz-naive dtype (i.e. datetime64[ns])
             if tz is not None and not timezones.tz_compare(tz, dtz):
-                raise ValueError(
+                raise TimezoneDtypeMismatchError(
                     "cannot supply both a tz and a "
                     "timezone-naive dtype (i.e. datetime64[ns])"
                 )

pandas/core/dtypes/cast.py

@@ -45,6 +45,7 @@
 from pandas.errors import (
     IntCastingNaNError,
     LossySetitemError,
+    TimezoneDtypeMismatchError,
 )
 
 from pandas.core.dtypes.common import (
@@ -1095,14 +1096,13 @@ def maybe_cast_to_datetime(
     else:
         try:
             dta = DatetimeArray._from_sequence(value, dtype=dtype)
-        except ValueError as err:
-            # We can give a Series-specific exception message.
-            if "cannot supply both a tz and a timezone-naive dtype" in str(err):
-                raise ValueError(
-                    "Cannot convert timezone-aware data to "
-                    "timezone-naive dtype. Use "
-                    "pd.Series(values).dt.tz_localize(None) instead."
-                ) from err
+        except TimezoneDtypeMismatchError as err:
+            raise ValueError(
+                "Cannot convert timezone-aware data to "
+                "timezone-naive dtype. Use "
+                "pd.Series(values).dt.tz_localize(None) instead."
+            ) from err
+        except ValueError:
             raise
 
         return dta

pandas/errors/__init__.py

@@ -1038,6 +1038,30 @@ class InvalidComparison(Exception):
     """
 
 
+class TimezoneDtypeMismatchError(ValueError):
+    """
+    Raised when a tz is supplied with a timezone-naive numpy datetime64 dtype.
+
+    Use case / message:
+        "cannot supply both a tz and a timezone-naive dtype (i.e. datetime64[ns])"
+
+    See Also
+    --------
+    core.dtypes.dtypes.DatetimeTZDtype : Datetime dtype with an associated timezone.
+    core.arrays.datetimes._validate_tz_from_dtype : Validation helper that may
+        raise this error.
+
+    Examples
+    --------
+    >>> from pandas.core.arrays import datetimes  # doctest: +SKIP
+    >>> datetimes._validate_tz_from_dtype("datetime64[ns]", tz="UTC")  # doctest: +SKIP
+    Traceback (most recent call last):
+    ...
+    TimezoneDtypeMismatchError: cannot supply both a tz and a timezone-naive dtype
+    (i.e. datetime64[ns])
+    """
+
+
 __all__ = [
     "AbstractMethodError",
     "AttributeConflictWarning",
@@ -1081,6 +1105,7 @@ class InvalidComparison(Exception):
     "PyperclipException",
     "PyperclipWindowsException",
     "SpecificationError",
+    "TimezoneDtypeMismatchError",
     "UndefinedVariableError",
     "UnsortedIndexError",
     "UnsupportedFunctionCall",

pandas/tests/indexes/datetimes/test_constructors.py

@@ -19,6 +19,7 @@
     astype_overflowsafe,
     timezones,
 )
+from pandas.errors import TimezoneDtypeMismatchError
 
 import pandas as pd
 from pandas import (
@@ -709,7 +710,7 @@ def test_constructor_dtype_tz_mismatch_raises(self):
             "cannot supply both a tz and a timezone-naive dtype "
             r"\(i\.e\. datetime64\[ns\]\)"
         )
-        with pytest.raises(ValueError, match=msg):
+        with pytest.raises(TimezoneDtypeMismatchError, match=msg):
             DatetimeIndex(idx, dtype="datetime64[ns]")
 
         # this is effectively trying to convert tz's