Merge remote-tracking branch 'upstream/main' into unify-freq

Author: MarcoGorelli

pandas-stubs/_libs/tslibs/period.pyi

@@ -12,9 +12,6 @@ from pandas import (
     Timedelta,
     TimedeltaIndex,
 )
-from pandas.core.series import (
-    OffsetSeries,
-)
 from typing_extensions import TypeAlias
 
 from pandas._libs.tslibs import NaTType
@@ -98,7 +95,7 @@ class Period(PeriodMixin):
     def __add__(self, other: Index) -> PeriodIndex: ...
     @overload
     def __add__(
-        self, other: OffsetSeries | Series[Timedelta]
+        self, other: Series[BaseOffset] | Series[Timedelta]
     ) -> Series[Period]: ...  # pyrefly: ignore[bad-specialization]
     #  ignore[misc] here because we know all other comparisons
     #  are False, so we use Literal[False]

pandas-stubs/core/arrays/categorical.pyi

@@ -96,7 +96,6 @@ class Categorical(ExtensionArray):
     @property
     def nbytes(self) -> int: ...
     def memory_usage(self, deep: bool = ...): ...
-    def searchsorted(self, value, side: str = ..., sorter=...): ...
     def isna(self) -> np_1darray[np.bool]: ...
     def isnull(self) -> np_1darray[np.bool]: ...
     def notna(self) -> np_1darray[np.bool]: ...

pandas-stubs/core/arrays/datetimelike.pyi

@@ -84,7 +84,6 @@ class DatetimeLikeArrayMixin(ExtensionOpsMixin, ExtensionArray):
     def unique(self): ...
     def copy(self): ...
     def shift(self, periods: int = 1, fill_value=..., axis: int = ...): ...
-    def searchsorted(self, value, side: str = ..., sorter=...): ...
     def repeat(self, repeats, *args, **kwargs): ...  # pyrefly: ignore
     def value_counts(self, dropna: bool = True): ...
     def map(self, mapper): ...

pandas-stubs/core/base.pyi

@@ -20,6 +20,7 @@ from pandas import (
 from pandas.core.arraylike import OpsMixin
 from pandas.core.arrays import ExtensionArray
 from pandas.core.arrays.categorical import Categorical
+from pandas.core.indexes.accessors import ArrayDescriptor
 from typing_extensions import Self
 
 from pandas._typing import (
@@ -69,8 +70,7 @@ class IndexOpsMixin(OpsMixin, Generic[S1, GenericT_co]):
     def nbytes(self) -> int: ...
     @property
     def size(self) -> int: ...
-    @property
-    def array(self) -> ExtensionArray: ...
+    array = ArrayDescriptor()
     @overload
     def to_numpy(
         self,

pandas-stubs/core/indexes/accessors.pyi

@@ -1,41 +1,43 @@
-import datetime as dt
 from datetime import (
+    date,
+    time,
     timedelta,
     tzinfo as _tzinfo,
 )
 from typing import (
-    Any,
     Generic,
     Literal,
     TypeVar,
     overload,
+    type_check_only,
 )
 
 import numpy as np
-from pandas import (
-    DatetimeIndex,
-    Index,
-    PeriodIndex,
-    Timedelta,
-    TimedeltaIndex,
-    Timestamp,
-)
 from pandas.core.accessor import PandasDelegate
-from pandas.core.arrays import (
-    DatetimeArray,
-    PeriodArray,
+from pandas.core.arrays.base import ExtensionArray
+from pandas.core.arrays.categorical import Categorical
+from pandas.core.arrays.datetimes import DatetimeArray
+from pandas.core.arrays.interval import IntervalArray
+from pandas.core.arrays.period import PeriodArray
+from pandas.core.arrays.timedeltas import TimedeltaArray
+from pandas.core.base import (
+    IndexOpsMixin,
+    NoNewAttributesMixin,
 )
-from pandas.core.base import NoNewAttributesMixin
 from pandas.core.frame import DataFrame
-from pandas.core.series import (
-    Series,
-)
+from pandas.core.indexes.base import Index
+from pandas.core.indexes.datetimes import DatetimeIndex
+from pandas.core.indexes.period import PeriodIndex
+from pandas.core.indexes.timedeltas import TimedeltaIndex
+from pandas.core.series import Series
 from typing_extensions import Never
 
+from pandas._libs.interval import Interval
 from pandas._libs.tslibs import BaseOffset
 from pandas._libs.tslibs.period import Period
+from pandas._libs.tslibs.timedeltas import Timedelta
+from pandas._libs.tslibs.timestamps import Timestamp
 from pandas._typing import (
-    S1,
     Frequency,
     TimeAmbiguous,
     TimeNonexistent,
@@ -46,6 +48,8 @@ from pandas._typing import (
     np_ndarray_bool,
 )
 
+from pandas.core.dtypes.dtypes import CategoricalDtype
+
 class Properties(PandasDelegate, NoNewAttributesMixin): ...
 
 _DTFieldOpsReturnType = TypeVar("_DTFieldOpsReturnType", bound=Series[int] | Index[int])
@@ -129,10 +133,10 @@ class _DatetimeObjectOps(
 ): ...
 
 _DTOtherOpsDateReturnType = TypeVar(
-    "_DTOtherOpsDateReturnType", bound=Series[dt.date] | np_1darray[np.object_]
+    "_DTOtherOpsDateReturnType", bound=Series[date] | np_1darray[np.object_]
 )
 _DTOtherOpsTimeReturnType = TypeVar(
-    "_DTOtherOpsTimeReturnType", bound=Series[dt.time] | np_1darray[np.object_]
+    "_DTOtherOpsTimeReturnType", bound=Series[time] | np_1darray[np.object_]
 )
 
 class _DatetimeOtherOps(Generic[_DTOtherOpsDateReturnType, _DTOtherOpsTimeReturnType]):
@@ -378,8 +382,8 @@ class CombinedDatetimelikeProperties(
         Series[int],
         Series[bool],
         Series,
-        Series[dt.date],
-        Series[dt.time],
+        Series[date],
+        Series[time],
         str,
         Series[Timestamp],
         Series[str],
@@ -388,13 +392,15 @@ class CombinedDatetimelikeProperties(
     _TimedeltaPropertiesNoRounding[Series[int], Series[float]],
     _PeriodProperties,
 ): ...
+
+@type_check_only
 class TimestampProperties(
     DatetimeProperties[
         Series[int],
         Series[bool],
         Series[Timestamp],
-        Series[dt.date],
-        Series[dt.time],
+        Series[date],
+        Series[time],
         str,
         Series[Timestamp],
         Series[str],
@@ -432,51 +438,47 @@ class TimedeltaIndexProperties(
     _DatetimeRoundingMethods[TimedeltaIndex],
 ): ...
 
-class _dtDescriptor(CombinedDatetimelikeProperties, Generic[S1]):
-    @overload
-    def __get__(self, instance: Series[Never], owner: Any) -> Never: ...
+@type_check_only
+class DtDescriptor:
     @overload
-    def __get__(self, instance: Series[Period], owner: Any) -> PeriodProperties: ...
+    def __get__(self, instance: Series[Never], owner: type[Series]) -> Properties: ...
     @overload
     def __get__(
-        self, instance: Series[Timestamp], owner: Any
+        self, instance: Series[Timestamp], owner: type[Series]
     ) -> TimestampProperties: ...
     @overload
     def __get__(
-        self, instance: Series[Timedelta], owner: Any
+        self, instance: Series[Timedelta], owner: type[Series]
     ) -> TimedeltaProperties: ...
     @overload
     def __get__(
-        self, instance: Series[S1], owner: Any
-    ) -> CombinedDatetimelikeProperties: ...
-    def round(
-        self,
-        freq: Frequency | None,
-        ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
-        nonexistent: (
-            Literal["shift_forward", "shift_backward", "NaT", "raise"]
-            | timedelta
-            | Timedelta
-        ) = ...,
-    ) -> Series[S1]: ...
-    def floor(
-        self,
-        freq: Frequency | None,
-        ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
-        nonexistent: (
-            Literal["shift_forward", "shift_backward", "NaT", "raise"]
-            | timedelta
-            | Timedelta
-        ) = ...,
-    ) -> Series[S1]: ...
-    def ceil(
-        self,
-        freq: Frequency | None,
-        ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
-        nonexistent: (
-            Literal["shift_forward", "shift_backward", "NaT", "raise"]
-            | timedelta
-            | Timedelta
-        ) = ...,
-    ) -> Series[S1]: ...
-    def as_unit(self, unit: TimeUnit) -> Series[S1]: ...
+        self, instance: Series[Period], owner: type[Series]
+    ) -> PeriodProperties: ...
+
+@type_check_only
+class ArrayDescriptor:
+    @overload
+    def __get__(
+        self, instance: IndexOpsMixin[Never], owner: type[IndexOpsMixin]
+    ) -> ExtensionArray: ...
+    @overload
+    def __get__(
+        self, instance: IndexOpsMixin[CategoricalDtype], owner: type[IndexOpsMixin]
+    ) -> Categorical: ...
+    @overload
+    def __get__(
+        self, instance: IndexOpsMixin[Interval], owner: type[IndexOpsMixin]
+    ) -> IntervalArray: ...
+    @overload
+    def __get__(
+        self, instance: IndexOpsMixin[Timestamp], owner: type[IndexOpsMixin]
+    ) -> DatetimeArray: ...
+    @overload
+    def __get__(
+        self, instance: IndexOpsMixin[Timedelta], owner: type[IndexOpsMixin]
+    ) -> TimedeltaArray: ...
+    # should be NumpyExtensionArray
+    @overload
+    def __get__(
+        self, instance: IndexOpsMixin, owner: type[IndexOpsMixin]
+    ) -> ExtensionArray: ...

pandas-stubs/core/indexes/base.pyi

@@ -36,12 +36,12 @@ from pandas import (
     Series,
     TimedeltaIndex,
 )
-from pandas.core.arrays import ExtensionArray
 from pandas.core.base import (
     IndexOpsMixin,
     NumListLike,
     _ListLike,
 )
+from pandas.core.indexes.category import CategoricalIndex
 from pandas.core.strings.accessor import StringMethods
 from typing_extensions import (
     Never,
@@ -58,6 +58,7 @@ from pandas._typing import (
     AnyAll,
     ArrayLike,
     AxesData,
+    CategoryDtypeArg,
     DropKeep,
     Dtype,
     DtypeArg,
@@ -229,6 +230,16 @@ class Index(IndexOpsMixin[S1]):
         tupleize_cols: bool = ...,
     ) -> TimedeltaIndex: ...
     @overload
+    def __new__(
+        cls,
+        data: AxesData,
+        *,
+        dtype: CategoryDtypeArg,
+        copy: bool = ...,
+        name: Hashable = ...,
+        tupleize_cols: bool = ...,
+    ) -> CategoricalIndex: ...
+    @overload
     def __new__(
         cls,
         data: Sequence[Interval[_OrderableT]] | IndexOpsMixin[Interval[_OrderableT]],
@@ -324,7 +335,9 @@ class Index(IndexOpsMixin[S1]):
         self, name: bool = ..., formatter: Callable | None = ..., na_rep: _str = ...
     ) -> list[_str]: ...
     def to_flat_index(self): ...
-    def to_series(self, index=..., name: Hashable = ...) -> Series: ...
+    def to_series(
+        self, index: Index | None = None, name: Hashable | None = None
+    ) -> Series[S1]: ...
     def to_frame(self, index: bool = True, name=...) -> DataFrame: ...
     @property
     def name(self) -> Hashable | None: ...
@@ -413,8 +426,6 @@ class Index(IndexOpsMixin[S1]):
     ): ...
     @property
     def values(self) -> np_1darray: ...
-    @property
-    def array(self) -> ExtensionArray: ...
     def memory_usage(self, deep: bool = False): ...
     def where(self, cond, other: Scalar | ArrayLike | None = None): ...
     def __contains__(self, key) -> bool: ...

pandas-stubs/core/indexes/datetimes.pyi

@@ -19,7 +19,6 @@ from pandas import (
     TimedeltaIndex,
     Timestamp,
 )
-from pandas.core.arrays import DatetimeArray
 from pandas.core.indexes.accessors import DatetimeIndexProperties
 from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
 from pandas.core.series import Series
@@ -58,10 +57,6 @@ class DatetimeIndex(
     ) -> Self: ...
     def __reduce__(self): ...
 
-    # Override the array property to return DatetimeArray instead of ExtensionArray
-    @property
-    def array(self) -> DatetimeArray: ...
-
     # various ignores needed for mypy, as we do want to restrict what can be used in
     # arithmetic for these types
     def __add__(  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
@@ -80,10 +75,11 @@ class DatetimeIndex(
         self, other: datetime | np.datetime64 | np_ndarray_dt | DatetimeIndex
     ) -> TimedeltaIndex: ...
     @final
-    def to_series(self, index=..., name: Hashable = ...) -> Series[Timestamp]: ...
+    def to_series(
+        self, index: Index | None = None, name: Hashable | None = None
+    ) -> Series[Timestamp]: ...
     def snap(self, freq: str = ...): ...
     def slice_indexer(self, start=..., end=..., step=...): ...
-    def searchsorted(self, value, side: str = ..., sorter=...): ...
     @property
     def inferred_type(self) -> str: ...
     def indexer_at_time(self, time, asof: bool = ...): ...

pandas-stubs/core/indexes/timedeltas.pyi

@@ -80,11 +80,12 @@ class TimedeltaIndex(
         self, other: dt.timedelta | Sequence[dt.timedelta]
     ) -> Index[int]: ...
     def __rfloordiv__(self, other: dt.timedelta | Sequence[dt.timedelta]) -> Index[int]: ...  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
-    def searchsorted(self, value, side: str = ..., sorter=...): ...
     @property
     def inferred_type(self) -> str: ...
     @final
-    def to_series(self, index=..., name: Hashable = ...) -> Series[Timedelta]: ...
+    def to_series(
+        self, index: Index | None = None, name: Hashable | None = None
+    ) -> Series[Timedelta]: ...
     def shift(
         self, periods: int = 1, freq: Frequency | dt.timedelta | None = None
     ) -> Self: ...