BUG: PeriodIndex.to_datetime inconsistent with its docstring

doc/source/whatsnew/v3.0.0.rst

@@ -710,6 +710,7 @@ I/O
 
 Period
 ^^^^^^
+- Bug in :meth:`PeriodIndex.to_timestamp` casting to a DatetimeIndex of timestamps at the end of the period, instead of at the beginning of the period. (:issue:`59371`)
 - Fixed error message when passing invalid period alias to :meth:`PeriodIndex.to_timestamp` (:issue:`58974`)
 -
 

pandas/core/arrays/period.py

@@ -822,7 +822,14 @@ def to_timestamp(self, freq=None, how: str = "start") -> DatetimeArray:
 
         new_parr = self.asfreq(freq, how=how)
 
-        new_data = libperiod.periodarr_to_dt64arr(new_parr.asi8, base)
+        is_start = how == "S"
+        if is_start:
+            new_data = np.asarray(
+                [(NaT if period is NaT else period.start_time) for period in new_parr]
+            )
+        else:
+            new_data = libperiod.periodarr_to_dt64arr(new_parr.asi8, base)
+
         dta = DatetimeArray._from_sequence(new_data, dtype=np.dtype("M8[ns]"))
 
         if self.freq.name == "B":

pandas/tests/indexes/datetimes/methods/test_to_period.py

@@ -116,13 +116,12 @@ def test_to_period_infer(self):
 
         tm.assert_index_equal(pi1, pi2)
 
-    @pytest.mark.filterwarnings(r"ignore:PeriodDtype\[B\] is deprecated:FutureWarning")
     def test_period_dt64_round_trip(self):
-        dti = date_range("1/1/2000", "1/7/2002", freq="B")
+        dti = date_range("1/1/2000", "1/7/2002", freq="D")
         pi = dti.to_period()
         tm.assert_index_equal(pi.to_timestamp(), dti)
 
-        dti = date_range("1/1/2000", "1/7/2002", freq="B")
+        dti = date_range("1/1/2000", "1/7/2002", freq="D")
         pi = dti.to_period(freq="h")
         tm.assert_index_equal(pi.to_timestamp(), dti)
 

pandas/tests/indexes/period/methods/test_to_timestamp.py

@@ -141,6 +141,18 @@ def test_to_timestamp_1703(self):
         result = index.to_timestamp()
         assert result[0] == Timestamp("1/1/2012")
 
+    def test_cast_to_timestamps_at_beginning_of_period(self):
+        # GH 59371
+        index = period_range("2000", periods=3, freq="M")
+        result = index.to_timestamp("M")
+
+        expected = DatetimeIndex(
+            ["2000-01-01", "2000-02-01", "2000-03-01"],
+            dtype="datetime64[ns]",
+            freq="MS",
+        )
+        tm.assert_equal(result, expected)
+
 
 def test_ms_to_timestamp_error_message():
     # https://github.com/pandas-dev/pandas/issues/58974#issuecomment-2164265446

pandas/tests/plotting/test_datetimelike.py

@@ -862,15 +862,12 @@ def test_mixed_freq_lf_first_hourly(self):
         for line in ax.get_lines():
             assert PeriodIndex(data=line.get_xdata()).freq == "min"
 
-    @pytest.mark.filterwarnings(r"ignore:PeriodDtype\[B\] is deprecated:FutureWarning")
     def test_mixed_freq_irreg_period(self):
         ts = Series(
             np.arange(30, dtype=np.float64), index=date_range("2020-01-01", periods=30)
         )
         irreg = ts.iloc[[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 16, 17, 18, 29]]
-        msg = r"PeriodDtype\[B\] is deprecated"
-        with tm.assert_produces_warning(FutureWarning, match=msg):
-            rng = period_range("1/3/2000", periods=30, freq="B")
+        rng = period_range("1/3/2000", periods=30, freq="D")
         ps = Series(np.random.default_rng(2).standard_normal(len(rng)), rng)
         _, ax = mpl.pyplot.subplots()
         irreg.plot(ax=ax)

pandas/tests/resample/test_period_index.py

@@ -127,20 +127,30 @@ def test_selection(self, freq, kwargs):
 
     @pytest.mark.parametrize("month", MONTHS)
     @pytest.mark.parametrize("meth", ["ffill", "bfill"])
-    @pytest.mark.parametrize("conv", ["start", "end"])
     @pytest.mark.parametrize(
-        ("offset", "period"), [("D", "D"), ("B", "B"), ("ME", "M"), ("QE", "Q")]
+        ("offset", "period", "conv"),
+        [
+            ("D", "D", "start"),
+            ("D", "D", "end"),
+            ("B", "B", "start"),
+            ("B", "B", "end"),
+            ("MS", "M", "start"),
+            ("ME", "M", "end"),
+            ("QS", "Q", "start"),
+            ("QE", "Q", "end"),
+        ],
     )
     def test_annual_upsample_cases(
         self, offset, period, conv, meth, month, simple_period_range_series
     ):
         ts = simple_period_range_series("1/1/1990", "12/31/1991", freq=f"Y-{month}")
-        warn = FutureWarning if period == "B" else None
-        msg = r"PeriodDtype\[B\] is deprecated"
-        if warn is None:
-            msg = "Resampling with a PeriodIndex is deprecated"
-            warn = FutureWarning
-        with tm.assert_produces_warning(warn, match=msg):
+
+        msg = (
+            r"PeriodDtype\[B\] is deprecated"
+            if period == "B"
+            else "Resampling with a PeriodIndex is deprecated"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
             result = getattr(ts.resample(period, convention=conv), meth)()
             expected = result.to_timestamp(period, how=conv)
             expected = expected.asfreq(offset, meth).to_period()
@@ -217,21 +227,29 @@ def test_annual_upsample2(self):
         tm.assert_series_equal(result, expected)
 
     @pytest.mark.parametrize("month", MONTHS)
-    @pytest.mark.parametrize("convention", ["start", "end"])
     @pytest.mark.parametrize(
-        ("offset", "period"), [("D", "D"), ("B", "B"), ("ME", "M")]
+        ("offset", "period", "convention"),
+        [
+            ("D", "D", "start"),
+            ("D", "D", "end"),
+            ("B", "B", "start"),
+            ("B", "B", "end"),
+            ("MS", "M", "start"),
+            ("ME", "M", "end"),
+        ],
     )
     def test_quarterly_upsample(
         self, month, offset, period, convention, simple_period_range_series
     ):
         freq = f"Q-{month}"
         ts = simple_period_range_series("1/1/1990", "12/31/1995", freq=freq)
-        warn = FutureWarning if period == "B" else None
-        msg = r"PeriodDtype\[B\] is deprecated"
-        if warn is None:
-            msg = "Resampling with a PeriodIndex is deprecated"
-            warn = FutureWarning
-        with tm.assert_produces_warning(warn, match=msg):
+
+        msg = (
+            r"PeriodDtype\[B\] is deprecated"
+            if period == "B"
+            else "Resampling with a PeriodIndex is deprecated"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
             result = ts.resample(period, convention=convention).ffill()
             expected = result.to_timestamp(period, how=convention)
             expected = expected.asfreq(offset, "ffill").to_period()
@@ -242,12 +260,12 @@ def test_quarterly_upsample(
     def test_monthly_upsample(self, target, convention, simple_period_range_series):
         ts = simple_period_range_series("1/1/1990", "12/31/1995", freq="M")
 
-        warn = None if target == "D" else FutureWarning
-        msg = r"PeriodDtype\[B\] is deprecated"
-        if warn is None:
-            msg = "Resampling with a PeriodIndex is deprecated"
-            warn = FutureWarning
-        with tm.assert_produces_warning(warn, match=msg):
+        msg = (
+            "Resampling with a PeriodIndex is deprecated"
+            if target == "D"
+            else r"PeriodDtype\[B\] is deprecated"
+        )
+        with tm.assert_produces_warning(FutureWarning, match=msg):
             result = ts.resample(target, convention=convention).ffill()
             expected = result.to_timestamp(target, how=convention)
             expected = expected.asfreq(target, "ffill").to_period()
@@ -923,7 +941,7 @@ def test_resample_with_offset_month(self):
             rs = ser.resample("M", offset="3h")
         result = rs.mean()
         result = result.to_timestamp("M")
-        expected = ser.to_timestamp().resample("ME", offset="3h").mean()
+        expected = ser.to_timestamp().resample("MS", offset="3h").mean()
         # TODO: is non-tick the relevant characteristic? (GH 33815)
         expected.index = expected.index._with_freq(None)
         tm.assert_series_equal(result, expected)