ENH: Improve error message when constructing period with invalid freq

pandas/_libs/tslibs/offsets.pyx

@@ -4673,7 +4673,9 @@ def _get_offset(name: str) -> BaseOffset:
             offset = klass._from_name(*split[1:])
         except (ValueError, TypeError, KeyError) as err:
             # bad prefix or suffix
-            raise ValueError(INVALID_FREQ_ERR_MSG.format(name)) from err
+            raise ValueError(INVALID_FREQ_ERR_MSG.format(
+                f"{name}, failed to parse with error message: {repr(err)}")
+            )
         # cache
         _offset_map[name] = offset
 
@@ -4757,11 +4759,17 @@ cpdef to_offset(freq, bint is_period=False):
                     )
                     name = c_OFFSET_DEPR_FREQSTR[name]
                 if is_period is True and name in c_REVERSE_OFFSET_DEPR_FREQSTR:
-                    raise ValueError(
-                        f"for Period, please use "
-                        f"\'{c_REVERSE_OFFSET_DEPR_FREQSTR.get(name)}\' "
-                        f"instead of \'{name}\'"
-                    )
+                    if name.startswith("Y"):
+                        raise ValueError(
+                            f"for Period, please use \'Y{name[2:]}\' "
+                            f"instead of \'{name}\'"
+                        )
+                    else:
+                        raise ValueError(
+                            f"for Period, please use "
+                            f"\'{c_REVERSE_OFFSET_DEPR_FREQSTR.get(name)}\' "
+                            f"instead of \'{name}\'"
+                        )
                 elif is_period is True and name in c_OFFSET_DEPR_FREQSTR:
                     if name.startswith("A"):
                         warnings.warn(
@@ -4813,7 +4821,9 @@ cpdef to_offset(freq, bint is_period=False):
                 else:
                     delta = delta + offset
         except (ValueError, TypeError) as err:
-            raise ValueError(INVALID_FREQ_ERR_MSG.format(freq)) from err
+            raise ValueError(INVALID_FREQ_ERR_MSG.format(
+                f"{freq}, failed to parse with error message: {repr(err)}")
+            )
     else:
         delta = None
 

pandas/tests/indexes/period/test_period.py

@@ -273,7 +273,7 @@ def test_map(self):
         tm.assert_index_equal(result, exp)
 
     def test_period_index_frequency_ME_error_message(self):
-        msg = "Invalid frequency: 2ME"
+        msg = "for Period, please use 'M' instead of 'ME'"
 
         with pytest.raises(ValueError, match=msg):
             PeriodIndex(["2020-01-01", "2020-01-02"], freq="2ME")
@@ -302,7 +302,8 @@ def test_a_deprecated_from_time_series(self, freq_depr):
     @pytest.mark.parametrize("freq_depr", ["2ME", "2QE", "2YE"])
     def test_period_index_frequency_error_message(self, freq_depr):
         # GH#9586
-        msg = f"Invalid frequency: {freq_depr}"
+        msg = f"for Period, please use '{freq_depr[1:-1]}' "
+        f"instead of '{freq_depr[1:]}'"
 
         with pytest.raises(ValueError, match=msg):
             period_range("2020-01", "2020-05", freq=freq_depr)

pandas/tests/indexes/period/test_period_range.py

@@ -157,6 +157,6 @@ def test_errors(self):
             period_range(start="2017Q1", periods="foo")
 
     def test_period_range_frequency_ME_error_message(self):
-        msg = "Invalid frequency: 2ME"
+        msg = "for Period, please use 'M' instead of 'ME'"
         with pytest.raises(ValueError, match=msg):
             period_range(start="Jan-2000", end="Dec-2000", freq="2ME")

pandas/tests/resample/test_period_index.py

@@ -931,10 +931,11 @@ def test_resample_t_l_deprecated(self):
         tm.assert_series_equal(result, expected)
 
 
-@pytest.mark.parametrize("freq_depr", ["2ME", "2QE", "2QE-FEB", "2YE"])
+@pytest.mark.parametrize("freq_depr", ["2ME", "2QE", "2QE-FEB", "2YE", "2YE-MAR"])
 def test_resample_frequency_ME_QE_error_message(series_and_frame, freq_depr):
     # GH#9586
-    msg = f"Invalid frequency: {freq_depr}"
+    msg = f"for Period, please use '{freq_depr[1:2]}{freq_depr[3:]}' "
+    f"instead of '{freq_depr[1:]}'"
 
     obj = series_and_frame
     with pytest.raises(ValueError, match=msg):

pandas/tests/scalar/period/test_period.py

@@ -1632,6 +1632,6 @@ def test_invalid_frequency_error_message():
 
 
 def test_invalid_frequency_period_error_message():
-    msg = "Invalid frequency: ME"
+    msg = "for Period, please use 'M' instead of 'ME'"
     with pytest.raises(ValueError, match=msg):
         Period("2012-01-02", freq="ME")