refactor(series)!: drop IntervalSeries

pandas-stubs/core/base.pyi

@@ -5,6 +5,7 @@ from collections.abc import (
 )
 from typing import (
     Any,
+    ClassVar,
     Generic,
     Literal,
     TypeAlias,
@@ -20,6 +21,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 +71,7 @@ class IndexOpsMixin(OpsMixin, Generic[S1, GenericT_co]):
     def nbytes(self) -> int: ...
     @property
     def size(self) -> int: ...
-    @property
-    def array(self) -> ExtensionArray: ...
+    array: ClassVar = ArrayDescriptor()  # noqa
     @overload
     def to_numpy(
         self,

pandas-stubs/core/indexes/accessors.pyi

@@ -1,14 +1,15 @@
-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
@@ -25,18 +26,24 @@ from pandas.core.arrays import (
     DatetimeArray,
     PeriodArray,
 )
-from pandas.core.base import NoNewAttributesMixin
+from pandas.core.arrays.base import ExtensionArray
+from pandas.core.arrays.categorical import Categorical
+from pandas.core.arrays.interval import IntervalArray
+from pandas.core.arrays.timedeltas import TimedeltaArray
+from pandas.core.base import (
+    IndexOpsMixin,
+    NoNewAttributesMixin,
+)
 from pandas.core.frame import DataFrame
 from pandas.core.series import (
     PeriodSeries,
     Series,
 )
-from typing_extensions import Never
 
+from pandas._libs.interval import Interval
 from pandas._libs.tslibs import BaseOffset
 from pandas._libs.tslibs.offsets import DateOffset
 from pandas._typing import (
-    S1,
     TimeAmbiguous,
     TimeNonexistent,
     TimestampConvention,
@@ -46,6 +53,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 +138,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]):
@@ -380,8 +389,8 @@ class CombinedDatetimelikeProperties(
         Series[int],
         Series[bool],
         Series,
-        Series[dt.date],
-        Series[dt.time],
+        Series[date],
+        Series[time],
         str,
         Series[Timestamp],
         Series[str],
@@ -395,8 +404,8 @@ class TimestampProperties(
         Series[int],
         Series[bool],
         Series[Timestamp],
-        Series[dt.date],
-        Series[dt.time],
+        Series[date],
+        Series[time],
         str,
         Series[Timestamp],
         Series[str],
@@ -434,49 +443,37 @@ 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[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: ...
+
+@type_check_only
+class ArrayDescriptor:
     @overload
     def __get__(
-        self, instance: Series[S1], owner: Any
-    ) -> CombinedDatetimelikeProperties: ...
-    def round(
-        self,
-        freq: str | BaseOffset | 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: str | BaseOffset | 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: str | BaseOffset | 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: 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,7 +36,6 @@ from pandas import (
     Series,
     TimedeltaIndex,
 )
-from pandas.core.arrays import ExtensionArray
 from pandas.core.base import (
     IndexOpsMixin,
     NumListLike,
@@ -324,7 +323,7 @@ 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=..., name: Hashable = ...) -> Series[S1]: ...
     def to_frame(self, index: bool = True, name=...) -> DataFrame: ...
     @property
     def name(self) -> Hashable | None: ...
@@ -413,8 +412,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

@@ -20,7 +20,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
@@ -60,10 +59,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]

pandas-stubs/core/indexes/period.pyi

@@ -11,6 +11,7 @@ from pandas import Index
 from pandas.core.indexes.accessors import PeriodIndexFieldOps
 from pandas.core.indexes.datetimelike import DatetimeIndexOpsMixin
 from pandas.core.indexes.timedeltas import TimedeltaIndex
+from pandas.core.series import PeriodSeries
 from typing_extensions import Self
 
 from pandas._libs.tslibs import (
@@ -74,6 +75,7 @@ class PeriodIndex(DatetimeIndexOpsMixin[pd.Period, np.object_], PeriodIndexField
     @property
     def freqstr(self) -> str: ...
     def shift(self, periods: int = 1, freq: Frequency | None = None) -> Self: ...
+    def to_series(self, index=..., name: Hashable = ...) -> PeriodSeries: ...
 
 def period_range(
     start: (

pandas-stubs/core/series.pyi

@@ -55,11 +55,9 @@ from pandas.core.api import (
     Int32Dtype as Int32Dtype,
     Int64Dtype as Int64Dtype,
 )
-from pandas.core.arrays import TimedeltaArray
-from pandas.core.arrays.base import ExtensionArray
 from pandas.core.arrays.categorical import CategoricalAccessor
 from pandas.core.arrays.datetimes import DatetimeArray
-from pandas.core.arrays.interval import IntervalArray
+from pandas.core.arrays.timedeltas import TimedeltaArray
 from pandas.core.base import (
     IndexOpsMixin,
     NumListLike,
@@ -71,8 +69,8 @@ from pandas.core.groupby.generic import SeriesGroupBy
 from pandas.core.groupby.groupby import BaseGroupBy
 from pandas.core.indexers import BaseIndexer
 from pandas.core.indexes.accessors import (
+    DtDescriptor,
     PeriodProperties,
-    _dtDescriptor,
 )
 from pandas.core.indexes.category import CategoricalIndex
 from pandas.core.indexes.datetimes import DatetimeIndex
@@ -392,7 +390,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
         dtype: Literal["Interval"] = ...,
         name: Hashable = ...,
         copy: bool = ...,
-    ) -> IntervalSeries[_OrderableT]: ...
+    ) -> Series[Interval[_OrderableT]]: ...
     @overload
     def __new__(  # type: ignore[overload-overlap]
         cls,
@@ -479,8 +477,6 @@ class Series(IndexOpsMixin[S1], NDFrame):
     def name(self, value: Hashable | None) -> None: ...
     @property
     def values(self) -> ArrayLike: ...
-    @property
-    def array(self) -> ExtensionArray: ...
     def ravel(self, order: _str = ...) -> np.ndarray: ...
     def __len__(self) -> int: ...
     def view(self, dtype=...) -> Series[S1]: ...
@@ -841,11 +837,10 @@ class Series(IndexOpsMixin[S1], NDFrame):
     @overload
     def diff(self: Series[complex], periods: int = ...) -> Series[complex]: ...  # type: ignore[overload-overlap]
     @overload
-    def diff(self: Series[bytes], periods: int = ...) -> Never: ...
-    @overload
-    def diff(self: Series[type], periods: int = ...) -> Never: ...
-    @overload
-    def diff(self: Series[_str], periods: int = ...) -> Never: ...
+    def diff(
+        self: Series[bytes] | Series[type] | Series[_str] | Series[Interval],
+        periods: int = ...,
+    ) -> Never: ...
     @overload
     def diff(self: Series[Timestamp], periods: int = ...) -> Series[Timedelta]: ...  # type: ignore[overload-overlap]
     @overload
@@ -1234,8 +1229,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
         Series[_str],
         Series,
     ]: ...
-    @property
-    def dt(self) -> _dtDescriptor[S1]: ...
+    dt: ClassVar = DtDescriptor()  # noqa
     @property
     def plot(self) -> PlotAccessor: ...
     sparse = ...
@@ -4211,9 +4205,6 @@ class Series(IndexOpsMixin[S1], NDFrame):
     def __xor__(self, other: int | np_ndarray_anyint | Series[int]) -> Series[int]: ...
     @final
     def __invert__(self) -> Series[bool]: ...
-    # properties
-    # @property
-    # def array(self) -> _npndarray
     @property
     def at(self) -> _AtIndexer: ...
     @property
@@ -4593,7 +4584,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
     @overload  # type: ignore[override]
     def to_numpy(  # pyrefly: ignore[bad-override]
         self: Series[Timestamp],
-        dtype: None | type[np.datetime64] = None,
+        dtype: type[np.datetime64] | None = None,
         copy: bool = False,
         na_value: Scalar = ...,
         **kwargs,
@@ -4609,7 +4600,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
     @overload
     def to_numpy(  # pyrefly: ignore[bad-override]
         self: Series[Timedelta],
-        dtype: None | type[np.timedelta64] = None,
+        dtype: type[np.timedelta64] | None = None,
         copy: bool = False,
         na_value: Scalar = ...,
         **kwargs,
@@ -4623,6 +4614,22 @@ class Series(IndexOpsMixin[S1], NDFrame):
         **kwargs,
     ) -> np_1darray[GenericT]: ...
     @overload
+    def to_numpy(
+        self: Series[Interval],
+        dtype: type[np.object_] | None = None,
+        copy: bool = False,
+        na_value: Scalar = ...,
+        **kwargs,
+    ) -> np_1darray[np.object_]: ...
+    @overload
+    def to_numpy(
+        self: Series[Interval],
+        dtype: np.dtype[GenericT] | SupportsDType[GenericT] | type[GenericT],
+        copy: bool = False,
+        na_value: Scalar = ...,
+        **kwargs,
+    ) -> np_1darray[GenericT]: ...
+    @overload
     def to_numpy(  # pyright: ignore[reportIncompatibleMethodOverride]
         self,
         dtype: DTypeLike | None = None,
@@ -4718,7 +4725,7 @@ class _SeriesSubclassBase(Series[S1], Generic[S1, GenericT_co]):
 
 class PeriodSeries(_SeriesSubclassBase[Period, np.object_]):
     @property
-    def dt(self) -> PeriodProperties: ...  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
+    def dt(self) -> PeriodProperties: ...  # type: ignore[override]
     def __sub__(self, other: PeriodSeries) -> OffsetSeries: ...  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
     def diff(self, periods: int = ...) -> OffsetSeries: ...  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
 
@@ -4729,10 +4736,3 @@ class OffsetSeries(_SeriesSubclassBase[BaseOffset, np.object_]):
     def __radd__(  # pyright: ignore[reportIncompatibleMethodOverride]
         self, other: BaseOffset
     ) -> OffsetSeries: ...
-
-class IntervalSeries(
-    _SeriesSubclassBase[Interval[_OrderableT], np.object_], Generic[_OrderableT]
-):
-    @property
-    def array(self) -> IntervalArray: ...
-    def diff(self, periods: int = ...) -> Never: ...  # pyrefly: ignore