type PeriodIndex.__new__, PeriodIndex.asof_locs, remove some inherited methods (#1331)

* type ``PeriodIndex.__new__``

* shift and asof_locs too

* fixup return type

* np.integer -> np.intp

* fixup generics

* __new__ return type too

* use np_1darray alias

* one more

Author: MarcoGorelli

pandas-stubs/_typing.pyi

@@ -893,7 +893,7 @@ IndexingInt: TypeAlias = (
 )
 
 # AxesData is used for data for Index
-AxesData: TypeAlias = Mapping[S3, Any] | Axes | KeysView
+AxesData: TypeAlias = Mapping[S3, Any] | Axes | KeysView[S3]
 
 # Any plain Python or numpy function
 Function: TypeAlias = np.ufunc | Callable[..., Any]

pandas-stubs/core/indexes/period.pyi

@@ -1,7 +1,7 @@
 from collections.abc import Hashable
 import datetime
 from typing import (
-    final,
+    Any,
     overload,
 )
 
@@ -14,27 +14,28 @@ from pandas.core.indexes.timedeltas import TimedeltaIndex
 from typing_extensions import Self
 
 from pandas._libs.tslibs import (
-    BaseOffset,
     NaTType,
     Period,
 )
 from pandas._libs.tslibs.period import _PeriodAddSub
+from pandas._typing import (
+    AxesData,
+    Dtype,
+    Frequency,
+    np_1darray,
+)
 
 class PeriodIndex(DatetimeIndexOpsMixin[pd.Period, np.object_], PeriodIndexFieldOps):
     def __new__(
         cls,
-        data=...,
-        ordinal=...,
-        freq=...,
-        tz=...,
-        dtype=...,
-        copy: bool = ...,
-        name: Hashable = ...,
-        **fields,
-    ): ...
+        data: AxesData[Any] | None = None,
+        freq: Frequency | None = None,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+        name: Hashable | None = None,
+    ) -> Self: ...
     @property
-    def values(self): ...
-    def __contains__(self, key) -> bool: ...
+    def values(self) -> np_1darray[np.object_]: ...
     @overload
     def __sub__(self, other: Period) -> Index: ...
     @overload
@@ -53,31 +54,18 @@ class PeriodIndex(DatetimeIndexOpsMixin[pd.Period, np.object_], PeriodIndexField
     def __rsub__(  # pyright: ignore[reportIncompatibleMethodOverride]
         self, other: NaTType
     ) -> NaTType: ...
-    @final
-    def __array_wrap__(self, result, context=...): ...
-    def asof_locs(self, where, mask): ...
-    def searchsorted(self, value, side: str = ..., sorter=...): ...
+    def asof_locs(
+        self,
+        where: pd.DatetimeIndex | PeriodIndex,
+        mask: np_1darray[np.bool_],
+    ) -> np_1darray[np.intp]: ...
     @property
     def is_full(self) -> bool: ...
     @property
     def inferred_type(self) -> str: ...
-    @final
-    def get_indexer(self, target, method=..., limit=..., tolerance=...): ...
-    def get_indexer_non_unique(self, target): ...
-    def insert(self, loc, item): ...
-    @final
-    def join(
-        self,
-        other,
-        *,
-        how: str = ...,
-        level=...,
-        return_indexers: bool = ...,
-        sort: bool = ...,
-    ): ...
     @property
     def freqstr(self) -> str: ...
-    def shift(self, periods: int = 1, freq=...) -> Self: ...
+    def shift(self, periods: int = 1, freq: Frequency | None = None) -> Self: ...
 
 def period_range(
     start: (
@@ -87,6 +75,6 @@ def period_range(
         str | datetime.datetime | datetime.date | pd.Timestamp | pd.Period | None
     ) = None,
     periods: int | None = None,
-    freq: str | BaseOffset | None = None,
+    freq: Frequency | None = None,
     name: Hashable | None = None,
 ) -> PeriodIndex: ...

tests/test_indexes.py

@@ -1489,3 +1489,26 @@ def test_index_naming() -> None:
     check(assert_type(df.index.names, list[Hashable | None]), list)
     df.index.names = (None,)
     check(assert_type(df.index.names, list[Hashable | None]), list)
+
+
+def test_period_index_constructor() -> None:
+    check(
+        assert_type(pd.PeriodIndex(["2000"], dtype="period[D]"), pd.PeriodIndex),
+        pd.PeriodIndex,
+    )
+    check(
+        assert_type(
+            pd.PeriodIndex(["2000"], freq="D", name="foo", copy=True), pd.PeriodIndex
+        ),
+        pd.PeriodIndex,
+    )
+
+
+def test_period_index_asof_locs() -> None:
+    idx = pd.PeriodIndex(["2000", "2001"], freq="D")
+    where = pd.DatetimeIndex(["2023-05-30 00:12:00", "2023-06-01 00:00:00"])
+    mask = np.ones(2, dtype=bool)
+    check(
+        assert_type(idx.asof_locs(where, mask), np_1darray[np.intp]),
+        np_1darray[np.intp],
+    )