From 685ecab473011611b93233e160d1c3c776b192c3 Mon Sep 17 00:00:00 2001
From: Simon Hawkins <simonjayhawkins@gmail.com>
Date: Fri, 12 Sep 2025 20:26:51 +0100
Subject: [PATCH] TYP: add type annotations for holidays and dtypes modules

- Add overloads and type annotations to Holiday.dates and AbstractHolidayCalendar.holidays
- Add type annotations for holiday_calendars and _cache
- Add missing type annotations for subdtype and base in dtypes.py
---
 pandas/core/dtypes/dtypes.py |  4 ++--
 pandas/tseries/holiday.py    | 34 +++++++++++++++++++++++-----------
 2 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py
index becd49fe4300f..1e6761b2e1db0 100644
--- a/pandas/core/dtypes/dtypes.py
+++ b/pandas/core/dtypes/dtypes.py
@@ -123,7 +123,7 @@ class PandasExtensionDtype(ExtensionDtype):
     # problem dealing with multiple inheritance from PandasExtensionDtype
     # and ExtensionDtype's @properties in the subclasses below. The kind and
     # type variables in those subclasses are explicitly typed below.
-    subdtype = None
+    subdtype: DtypeObj | None = None
     str: str_type
     num = 100
     shape: tuple[int, ...] = ()
@@ -1604,7 +1604,7 @@ class BaseMaskedDtype(ExtensionDtype):
     Base class for dtypes for BaseMaskedArray subclasses.
     """
 
-    base = None
+    base: DtypeObj | None = None
     type: type
     _internal_fill_value: Scalar
 
diff --git a/pandas/tseries/holiday.py b/pandas/tseries/holiday.py
index e61fd6594ea84..b5ab8cb2eb8be 100644
--- a/pandas/tseries/holiday.py
+++ b/pandas/tseries/holiday.py
@@ -4,7 +4,11 @@
     datetime,
     timedelta,
 )
-from typing import TYPE_CHECKING
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    overload,
+)
 import warnings
 
 from dateutil.relativedelta import (
@@ -281,6 +285,17 @@ def __repr__(self) -> str:
         repr = f"Holiday: {self.name} ({info})"
         return repr
 
+    @overload
+    def dates(self, start_date, end_date, return_name: Literal[True]) -> Series: ...
+
+    @overload
+    def dates(
+        self, start_date, end_date, return_name: Literal[False]
+    ) -> DatetimeIndex: ...
+
+    @overload
+    def dates(self, start_date, end_date) -> DatetimeIndex: ...
+
     def dates(
         self, start_date, end_date, return_name: bool = False
     ) -> Series | DatetimeIndex:
@@ -411,7 +426,7 @@ def _apply_rule(self, dates: DatetimeIndex) -> DatetimeIndex:
         return dates
 
 
-holiday_calendars = {}
+holiday_calendars: dict[str, type[AbstractHolidayCalendar]] = {}
 
 
 def register(cls) -> None:
@@ -449,7 +464,7 @@ class AbstractHolidayCalendar(metaclass=HolidayCalendarMetaClass):
     rules: list[Holiday] = []
     start_date = Timestamp(datetime(1970, 1, 1))
     end_date = Timestamp(datetime(2200, 12, 31))
-    _cache = None
+    _cache: tuple[Timestamp, Timestamp, Series] | None = None
 
     def __init__(self, name: str = "", rules=None) -> None:
         """
@@ -478,7 +493,9 @@ def rule_from_name(self, name: str) -> Holiday | None:
 
         return None
 
-    def holidays(self, start=None, end=None, return_name: bool = False):
+    def holidays(
+        self, start=None, end=None, return_name: bool = False
+    ) -> DatetimeIndex | Series:
         """
         Returns a curve with holidays between start_date and end_date
 
@@ -515,14 +532,9 @@ def holidays(self, start=None, end=None, return_name: bool = False):
                 rule.dates(start, end, return_name=True) for rule in self.rules
             ]
             if pre_holidays:
-                # error: Argument 1 to "concat" has incompatible type
-                # "List[Union[Series, DatetimeIndex]]"; expected
-                # "Union[Iterable[DataFrame], Mapping[<nothing>, DataFrame]]"
-                holidays = concat(pre_holidays)  # type: ignore[arg-type]
+                holidays = concat(pre_holidays)
             else:
-                # error: Incompatible types in assignment (expression has type
-                # "Series", variable has type "DataFrame")
-                holidays = Series(index=DatetimeIndex([]), dtype=object)  # type: ignore[assignment]
+                holidays = Series(index=DatetimeIndex([]), dtype=object)
 
             self._cache = (start, end, holidays.sort_index())