add type annotation, fix namespace usage

Author: TiffL

doc/source/whatsnew/v3.0.0.rst

@@ -624,8 +624,8 @@ Other
 - Bug in :meth:`DataFrame.sort_index` when passing ``axis="columns"`` and ``ignore_index=True`` and ``ascending=False`` not returning a :class:`RangeIndex` columns (:issue:`57293`)
 - Bug in :meth:`DataFrame.transform` that was returning the wrong order unless the index was monotonically increasing. (:issue:`57069`)
 - Bug in :meth:`DataFrame.where` where using a non-bool type array in the function would return a ``ValueError`` instead of a ``TypeError`` (:issue:`56330`)
-- Bug in :meth:`Index.sort_values` when passing a key function that turns values into tuples, e.g. ``key=natsort.natsort_key``, would raise ``TypeError`` (:issue:`56081`)
 - Bug in :meth:`Index.difference` returning too many values / incorrect values for period indexes (:issue:`58971`)
+- Bug in :meth:`Index.sort_values` when passing a key function that turns values into tuples, e.g. ``key=natsort.natsort_key``, would raise ``TypeError`` (:issue:`56081`)
 - Bug in :meth:`Series.diff` allowing non-integer values for the ``periods`` argument. (:issue:`56607`)
 - Bug in :meth:`Series.dt` methods in :class:`ArrowDtype` that were returning incorrect values. (:issue:`57355`)
 - Bug in :meth:`Series.rank` that doesn't preserve missing values for nullable integers when ``na_option='keep'``. (:issue:`56976`)

pandas/core/indexes/period.py

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

pandas/tests/indexes/period/test_setops.py

@@ -316,15 +316,15 @@ def test_difference(self, sort):
 
     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'])
+        index = period_range('2022-01-01', periods=5, freq='M')
+        other = Index(['2022-02', '2022-03'])
 
         idx_diff = index.difference(other, sort)
-        expected = pd.PeriodIndex(['2022-01', '2022-04', '2022-05'], freq='M')
+        expected = 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([])
+        expected = Index([])
         tm.assert_index_equal(idx_diff, expected)
 
     def test_difference_freq(self, sort):