fix difference functionality for period indexes, add additional tests

Author: TiffL

pandas/core/indexes/base.py

@@ -3406,7 +3406,7 @@ def difference(self, other, sort=None):
         return self._wrap_difference_result(other, result)
 
     def _difference(self, other, sort):
-        # overridden by RangeIndex
+        # overridden by RangeIndex, PeriodIndex
         this = self
         if isinstance(self, ABCCategoricalIndex) and self.hasnans and other.hasnans:
             this = this.dropna()
@@ -6209,6 +6209,12 @@ def _maybe_downcast_for_indexing(self, other: Index) -> tuple[Index, Index]:
                 # let's instead try with a straight Index
                 self = Index(self._values)
 
+        elif self.inferred_type == 'string' and isinstance(other, ABCPeriodIndex):
+            try:
+                return self.astype(other.dtype), other
+            except:
+                return self, other
+
         if not is_object_dtype(self.dtype) and is_object_dtype(other.dtype):
             # Reverse op so we dont need to re-implement on the subclasses
             other, self = other._maybe_downcast_for_indexing(self)

pandas/core/indexes/period.py

@@ -514,6 +514,12 @@ def shift(self, periods: int = 1, freq=None) -> Self:
             )
         return self + periods
 
+    def _difference(self, other, sort=None):
+        if not isinstance(other, PeriodIndex):
+            self, other = self._maybe_downcast_for_indexing(other)
+
+        return super()._difference(other, sort=sort)
+
 
 def period_range(
     start=None,

pandas/tests/indexes/period/test_setops.py

@@ -314,6 +314,19 @@ def test_difference(self, sort):
                 expected = expected.sort_values()
             tm.assert_index_equal(result_difference, expected)
 
+    def test_difference_mismatched_dtypes(self, sort):
+        # GH58971
+        index = pd.period_range('2022-01-01', periods=5, freq='M')
+        other = pd.Index(['2022-02', '2022-03'])
+
+        idx_diff = index.difference(other, sort)
+        expected = pd.PeriodIndex(['2022-01', '2022-04', '2022-05'], freq='M')
+        tm.assert_index_equal(idx_diff, expected)
+
+        idx_diff = other.difference(index, sort)
+        expected = pd.Index([])
+        tm.assert_index_equal(idx_diff, expected)
+
     def test_difference_freq(self, sort):
         # GH14323: difference of Period MUST preserve frequency
         # but the ability to union results must be preserved