Updates several type hints where incomplete or inaccurate

Author: rgkimball

pandas/_typing.py

@@ -122,6 +122,8 @@
 JSONSerializable = Optional[Union[PythonScalar, List, Dict]]
 Frequency = Union[str, "DateOffset"]
 Axes = Collection[Any]
+MergeTypes = Literal['inner', 'outer', 'left', 'right', 'cross']
+ConcatTypes = Literal['inner', 'outer']
 
 # dtypes
 NpDtype = Union[str, np.dtype]

pandas/core/apply.py

@@ -9,6 +9,7 @@
     Hashable,
     Iterator,
     List,
+    Literal,
     cast,
 )
 import warnings
@@ -504,7 +505,10 @@ def apply_multiple(self) -> FrameOrSeriesUnion:
         return self.obj.aggregate(self.f, self.axis, *self.args, **self.kwargs)
 
     def normalize_dictlike_arg(
-        self, how: str, obj: FrameOrSeriesUnion, func: AggFuncTypeDict
+        self,
+        how: Literal['apply', 'agg', 'transform'],
+        obj: FrameOrSeriesUnion,
+        func: AggFuncTypeDict,
     ) -> AggFuncTypeDict:
         """
         Handler for dict-like argument.

pandas/core/arrays/_ranges.py

@@ -3,7 +3,10 @@
 (and possibly TimedeltaArray/PeriodArray)
 """
 
-from typing import Union
+from typing import (
+    Literal,
+    Union,
+)
 
 import numpy as np
 
@@ -75,7 +78,7 @@ def generate_regular_range(
 
 
 def _generate_range_overflow_safe(
-    endpoint: int, periods: int, stride: int, side: str = "start"
+    endpoint: int, periods: int, stride: int, side: Literal['start', 'end'] = "start"
 ) -> int:
     """
     Calculate the second endpoint for passing to np.arange, checking
@@ -143,7 +146,7 @@ def _generate_range_overflow_safe(
 
 
 def _generate_range_overflow_safe_signed(
-    endpoint: int, periods: int, stride: int, side: str
+    endpoint: int, periods: int, stride: int, side: Literal['start', 'end']
 ) -> int:
     """
     A special case for _generate_range_overflow_safe where `periods * stride`
@@ -154,7 +157,7 @@ def _generate_range_overflow_safe_signed(
     if side == 'end':
         stride *= -1
 
-    with np.errstate(over="raise"):
+    with np.errstate(over='raise'):
         addend = np.int64(periods) * np.int64(stride)
         try:
             # easy case with no overflows

pandas/core/arrays/datetimes.py

@@ -1958,12 +1958,12 @@ def sequence_to_datetimes(
 
 def sequence_to_dt64ns(
     data,
-    dtype=None,
-    copy=False,
-    tz=None,
-    dayfirst=False,
-    yearfirst=False,
-    ambiguous="raise",
+    dtype: str = None,
+    copy: bool = False,
+    tz: tzinfo | str = None,
+    dayfirst: bool = False,
+    yearfirst: bool = False,
+    ambiguous: str | bool = "raise",
     *,
     allow_object: bool = False,
     allow_mixed: bool = False,
@@ -2117,10 +2117,10 @@ def sequence_to_dt64ns(
 
 def objects_to_datetime64ns(
     data: np.ndarray,
-    dayfirst,
-    yearfirst,
-    utc=False,
-    errors="raise",
+    dayfirst: bool,
+    yearfirst: bool,
+    utc: bool = False,
+    errors: Literal["raise", "coerce", "ignore"] = "raise",
     require_iso8601: bool = False,
     allow_object: bool = False,
     allow_mixed: bool = False,

pandas/core/frame.py

@@ -9165,7 +9165,7 @@ def merge(
         sort: bool = False,
         suffixes: Suffixes = ("_x", "_y"),
         copy: bool = True,
-        indicator: bool = False,
+        indicator: bool | str = False,
         validate: str | None = None,
     ) -> DataFrame:
         from pandas.core.reshape.merge import merge

pandas/core/indexes/base.py

@@ -5694,7 +5694,7 @@ def _validate_indexer(self, form: str_t, key, kind: str_t):
         if key is not None and not is_integer(key):
             raise self._invalid_indexer(form, key)
 
-    def _maybe_cast_slice_bound(self, label, side: str_t, kind=no_default):
+    def _maybe_cast_slice_bound(self, label, side: str_t, kind: Literal["loc", "getitem"] = no_default):
         """
         This function should be overloaded in subclasses that allow non-trivial
         casting on label-slice bounds, e.g. datetime-like indices allowing

pandas/core/missing.py

@@ -11,6 +11,7 @@
     TYPE_CHECKING,
     Any,
     cast,
+    Literal,
 )
 
 import numpy as np
@@ -164,7 +165,7 @@ def clean_interp_method(method: str, index: Index, **kwargs) -> str:
     return method
 
 
-def find_valid_index(values, *, how: str) -> int | None:
+def find_valid_index(values, *, how: Literal['first', 'last']) -> int | None:
     """
     Retrieves the index of the first valid value.
 

pandas/core/reshape/merge.py

@@ -29,6 +29,8 @@
     FrameOrSeries,
     IndexLabel,
     Suffixes,
+    MergeTypes,
+    TimedeltaConvertibleTypes,
 )
 from pandas.errors import MergeError
 from pandas.util._decorators import (
@@ -92,7 +94,7 @@
 def merge(
     left: DataFrame | Series,
     right: DataFrame | Series,
-    how: str = "inner",
+    how: MergeTypes = "inner",
     on: IndexLabel | None = None,
     left_on: IndexLabel | None = None,
     right_on: IndexLabel | None = None,
@@ -101,7 +103,7 @@ def merge(
     sort: bool = False,
     suffixes: Suffixes = ("_x", "_y"),
     copy: bool = True,
-    indicator: bool = False,
+    indicator: bool | str = False,
     validate: str | None = None,
 ) -> DataFrame:
     op = _MergeOperation(
@@ -331,11 +333,11 @@ def merge_asof(
     right_on: IndexLabel | None = None,
     left_index: bool = False,
     right_index: bool = False,
-    by=None,
-    left_by=None,
-    right_by=None,
+    by: IndexLabel | None = None,
+    left_by: Hashable | None = None,
+    right_by: Hashable | None = None,
     suffixes: Suffixes = ("_x", "_y"),
-    tolerance=None,
+    tolerance: None | TimedeltaConvertibleTypes = None,
     allow_exact_matches: bool = True,
     direction: str = "backward",
 ) -> DataFrame:
@@ -622,7 +624,7 @@ def __init__(
         sort: bool = True,
         suffixes: Suffixes = ("_x", "_y"),
         copy: bool = True,
-        indicator: bool = False,
+        indicator: bool | str = False,
         validate: str | None = None,
     ):
         _left = _validate_operand(left)

pandas/tseries/frequencies.py

@@ -445,7 +445,7 @@ def _maybe_add_count(base: str, count: float) -> str:
 # Frequency comparison
 
 
-def is_subperiod(source, target) -> bool:
+def is_subperiod(source: str | DateOffset, target: str | DateOffset) -> bool:
     """
     Returns True if downsampling is possible between source and target
     frequencies
@@ -501,7 +501,7 @@ def is_subperiod(source, target) -> bool:
         return False
 
 
-def is_superperiod(source, target) -> bool:
+def is_superperiod(source: str | DateOffset, target: str | DateOffset) -> bool:
     """
     Returns True if upsampling is possible between source and target
     frequencies
@@ -559,7 +559,7 @@ def is_superperiod(source, target) -> bool:
         return False
 
 
-def _maybe_coerce_freq(code) -> str:
+def _maybe_coerce_freq(code: str | DateOffset) -> str:
     """we might need to coerce a code to a rule_code
     and uppercase it
 

pandas/tseries/holiday.py

@@ -1,4 +1,9 @@
 from __future__ import annotations
+from typing import (
+    Any,
+    Callable,
+    Tuple,
+)
 
 from datetime import (
     datetime,
@@ -33,6 +38,10 @@
     Easter,
 )
 
+from pandas._typing import (
+    TimestampConvertibleTypes
+)
+
 
 def next_monday(dt: datetime) -> datetime:
     """
@@ -151,27 +160,39 @@ class Holiday:
 
     def __init__(
         self,
-        name,
-        year=None,
-        month=None,
-        day=None,
-        offset=None,
-        observance=None,
-        start_date=None,
-        end_date=None,
-        days_of_week=None,
+        name: str,
+        year: int | None = None,
+        month: int | None = None,
+        day: int | None = None,
+        offset: list[Any] | Any = None,
+        observance: Callable[..., DatetimeIndex] = None,
+        start_date: TimestampConvertibleTypes = None,
+        end_date: TimestampConvertibleTypes = None,
+        days_of_week: Tuple[int, ...] = None,
     ):
         """
         Parameters
         ----------
         name : str
             Name of the holiday , defaults to class name
+        year : int, optional
+            the year in which the holiday occurs
+        month : int, optional
+            the month in which the holiday occurs
+        day : int, optional
+             the day on which the holiday occurs
         offset : array of pandas.tseries.offsets or
                 class from pandas.tseries.offsets
             computes offset from date
         observance: function
             computes when holiday is given a pandas Timestamp
-        days_of_week:
+        start_date : datetime-like
+            optionally constrain the period in which the holdiday occurs
+            can be any valid value for a pandas Timestamp
+        end_date : datetime-like
+            optionally constrain the period in which the holdiday occurs
+            can be any valid value for a pandas Timestamp
+        days_of_week: tuple(int, ...)
             provide a tuple of days e.g  (0,1,2,3,) for Monday Through Thursday
             Monday=0,..,Sunday=6
 
@@ -239,7 +260,12 @@ def __repr__(self) -> str:
         repr = f"Holiday: {self.name} ({info})"
         return repr
 
-    def dates(self, start_date, end_date, return_name=False):
+    def dates(
+            self,
+            start_date: TimestampConvertibleTypes,
+            end_date: TimestampConvertibleTypes,
+            return_name: bool = False,
+    ):
         """
         Calculate holidays observed between start date and end date
 
@@ -286,7 +312,7 @@ def dates(self, start_date, end_date, return_name=False):
             return Series(self.name, index=holiday_dates)
         return holiday_dates
 
-    def _reference_dates(self, start_date, end_date):
+    def _reference_dates(self, start_date: TimestampConvertibleTypes, end_date: TimestampConvertibleTypes):
         """
         Get reference dates for the holiday.
 
@@ -319,7 +345,7 @@ def _reference_dates(self, start_date, end_date):
 
         return dates
 
-    def _apply_rule(self, dates):
+    def _apply_rule(self, dates: DatetimeIndex):
         """
         Apply the given offset/observance to a DatetimeIndex of dates.
 
@@ -390,7 +416,7 @@ class AbstractHolidayCalendar(metaclass=HolidayCalendarMetaClass):
     end_date = Timestamp(datetime(2200, 12, 31))
     _cache = None
 
-    def __init__(self, name=None, rules=None):
+    def __init__(self, name: str = None, rules: list[Holiday] = None):
         """
         Initializes holiday object with a given set a rules.  Normally
         classes just have the rules defined within them.
@@ -417,7 +443,12 @@ def rule_from_name(self, name):
 
         return None
 
-    def holidays(self, start=None, end=None, return_name=False):
+    def holidays(
+            self,
+            start: TimestampConvertibleTypes = None,
+            end: TimestampConvertibleTypes = None,
+            return_name: bool = False
+    ) -> DatetimeIndex:
         """
         Returns a curve with holidays between start_date and end_date