TYP: misc Index return types (#57256)

* TYP: misc Index return types * add IndexT to ignore list

Author: twoertwein

pandas/_typing.py

@@ -189,6 +189,7 @@ def __reversed__(self) -> Iterator[_T_co]:
 # passed in, a DataFrame is always returned.
 NDFrameT = TypeVar("NDFrameT", bound="NDFrame")
 
+IndexT = TypeVar("IndexT", bound="Index")
 NumpyIndexT = TypeVar("NumpyIndexT", np.ndarray, "Index")
 
 AxisInt = int

pandas/core/generic.py

@@ -10740,7 +10740,7 @@ def _shift_with_freq(self, periods: int, axis: int, freq) -> Self:
  f"does not match PeriodIndex freq "
  f"{freq_to_period_freqstr(orig_freq.n, orig_freq.name)}"
  )
- new_ax = index.shift(periods)
+ new_ax: Index = index.shift(periods)
  else:
  new_ax = index.shift(periods, freq)
 

pandas/core/indexes/accessors.py

@@ -5,6 +5,7 @@
 
 from typing import (
  TYPE_CHECKING,
+ NoReturn,
  cast,
 )
 import warnings
@@ -108,7 +109,7 @@ def _delegate_property_get(self, name: str):
  # return the result as a Series
  return Series(result, index=index, name=self.name).__finalize__(self._parent)
 
- def _delegate_property_set(self, name: str, value, *args, **kwargs):
+ def _delegate_property_set(self, name: str, value, *args, **kwargs) -> NoReturn:
  raise ValueError(
  "modifications to a property of a datetimelike object are not supported. "
  "Change values on the original."
@@ -483,7 +484,7 @@ def to_pytimedelta(self) -> np.ndarray:
  return self._get_values().to_pytimedelta()
 
  @property
- def components(self):
+ def components(self) -> DataFrame:
  """
  Return a Dataframe of the components of the Timedeltas.
 

pandas/core/indexes/base.py

@@ -55,6 +55,7 @@
  F,
  IgnoreRaise,
  IndexLabel,
+ IndexT,
  JoinHow,
  Level,
  NaPosition,
@@ -2027,7 +2028,7 @@ def sortlevel(
  ascending: bool | list[bool] = True,
  sort_remaining=None,
  na_position: NaPosition = "first",
- ):
+ ) -> tuple[Self, np.ndarray]:
  """
  For internal compatibility with the Index API.
 
@@ -4432,7 +4433,7 @@ def _wrap_reindex_result(self, target, indexer, preserve_names: bool):
  target = self._maybe_preserve_names(target, preserve_names)
  return target
 
- def _maybe_preserve_names(self, target: Index, preserve_names: bool):
+ def _maybe_preserve_names(self, target: IndexT, preserve_names: bool) -> IndexT:
  if preserve_names and target.nlevels == 1 and target.name != self.name:
  target = target.copy(deep=False)
  target.name = self.name
@@ -5987,7 +5988,7 @@ def sort(self, *args, **kwargs):
  """
  raise TypeError("cannot sort an Index object in-place, use sort_values instead")
 
- def shift(self, periods: int = 1, freq=None):
+ def shift(self, periods: int = 1, freq=None) -> Self:
  """
  Shift index by desired number of time frequency increments.
 

pandas/core/indexes/datetimelike.py

@@ -273,7 +273,7 @@ def _can_partial_date_slice(self, reso: Resolution) -> bool:
  def _parsed_string_to_bounds(self, reso: Resolution, parsed):
  raise NotImplementedError
 
- def _parse_with_reso(self, label: str):
+ def _parse_with_reso(self, label: str) -> tuple[datetime, Resolution]:
  # overridden by TimedeltaIndex
  try:
  if self.freq is None or hasattr(self.freq, "rule_code"):
@@ -295,7 +295,7 @@ def _parse_with_reso(self, label: str):
  reso = Resolution.from_attrname(reso_str)
  return parsed, reso
 
- def _get_string_slice(self, key: str):
+ def _get_string_slice(self, key: str) -> slice | npt.NDArray[np.intp]:
  # overridden by TimedeltaIndex
  parsed, reso = self._parse_with_reso(key)
  try:

pandas/core/indexes/datetimes.py

@@ -518,7 +518,9 @@ def snap(self, freq: Frequency = "S") -> DatetimeIndex:
  # --------------------------------------------------------------------
  # Indexing Methods
 
- def _parsed_string_to_bounds(self, reso: Resolution, parsed: dt.datetime):
+ def _parsed_string_to_bounds(
+ self, reso: Resolution, parsed: dt.datetime
+ ) -> tuple[Timestamp, Timestamp]:
  """
  Calculate datetime bounds for parsed time string and its resolution.
 
@@ -555,7 +557,7 @@ def _parsed_string_to_bounds(self, reso: Resolution, parsed: dt.datetime):
  # which localizes parsed.
  return start, end
 
- def _parse_with_reso(self, label: str):
+ def _parse_with_reso(self, label: str) -> tuple[Timestamp, Resolution]:
  parsed, reso = super()._parse_with_reso(label)
 
  parsed = Timestamp(parsed)

pandas/core/indexes/multi.py

@@ -37,6 +37,7 @@
  F,
  IgnoreRaise,
  IndexLabel,
+ IndexT,
  Scalar,
  Self,
  Shape,
@@ -2727,7 +2728,7 @@ def _wrap_reindex_result(self, target, indexer, preserve_names: bool):
  target = self._maybe_preserve_names(target, preserve_names)
  return target
 
- def _maybe_preserve_names(self, target: Index, preserve_names: bool) -> Index:
+ def _maybe_preserve_names(self, target: IndexT, preserve_names: bool) -> IndexT:
  if (
  preserve_names
  and target.nlevels == self.nlevels

pandas/core/indexes/range.py

@@ -876,7 +876,7 @@ def _difference(self, other, sort=None):
 
  def symmetric_difference(
  self, other, result_name: Hashable | None = None, sort=None
- ):
+ ) -> Index:
  if not isinstance(other, RangeIndex) or sort is not None:
  return super().symmetric_difference(other, result_name, sort)
 

pandas/core/indexes/timedeltas.py

@@ -32,6 +32,7 @@
 from pandas.core.indexes.extension import inherit_names
 
 if TYPE_CHECKING:
+ from pandas._libs import NaTType
  from pandas._typing import DtypeObj
 
 
@@ -245,7 +246,10 @@ def get_loc(self, key):
 
  return Index.get_loc(self, key)
 
- def _parse_with_reso(self, label: str):
+ # error: Return type "tuple[Timedelta | NaTType, None]" of "_parse_with_reso"
+ # incompatible with return type "tuple[datetime, Resolution]" in supertype
+ # "DatetimeIndexOpsMixin"
+ def _parse_with_reso(self, label: str) -> tuple[Timedelta | NaTType, None]: # type: ignore[override]
  # the "with_reso" is a no-op for TimedeltaIndex
  parsed = Timedelta(label)
  return parsed, None

pyproject.toml

@@ -761,5 +761,5 @@ exclude_lines = [
 directory = "coverage_html_report"
 
 [tool.codespell]
-ignore-words-list = "blocs, coo, hist, nd, sav, ser, recuse, nin, timere, expec, expecs"
+ignore-words-list = "blocs, coo, hist, nd, sav, ser, recuse, nin, timere, expec, expecs, indext"
 ignore-regex = 'https://([\w/\.])+'