[dateparser] Improve stubs (#15393)

* Functions with `settings` params actually accepts `Settings` (or
  `dict` only if has `@apply_settings` decorator)
* Use `TypeVar` for date params that are used as return objects
* Use `collections.abc.Set` instead of `set` since there is an
  `isinstance` check specifically for `collections.abc.Set`
* Annotated many other parameters

Author: donbarbos

stubs/dateparser/dateparser/__init__.pyi

@@ -1,18 +1,16 @@
 import datetime
-from typing import Literal, TypedDict, type_check_only
-from typing_extensions import TypeAlias
+from typing import Any, Final, Literal, TypedDict, type_check_only
+
+from dateparser.conf import Settings
 
 from .date import DateDataParser, _DetectLanguagesFunction
 
-__version__: str
+__version__: Final[str]
 
 _default_parser: DateDataParser
 
-_Part: TypeAlias = Literal["day", "month", "year"]
-_ParserKind: TypeAlias = Literal["timestamp", "relative-time", "custom-formats", "absolute-time", "no-spaces-time"]
-
 @type_check_only
-class _Settings(TypedDict, total=False):
+class _Settings(TypedDict, total=False):  # noqa: Y049
     DATE_ORDER: str
     PREFER_LOCALE_DATE_ORDER: bool
     TIMEZONE: str
@@ -23,14 +21,14 @@ class _Settings(TypedDict, total=False):
     PREFER_DATES_FROM: Literal["current_period", "future", "past"]
     RELATIVE_BASE: datetime.datetime
     STRICT_PARSING: bool
-    REQUIRE_PARTS: list[_Part]
+    REQUIRE_PARTS: list[Literal["day", "month", "year"]]
     SKIP_TOKENS: list[str]
     NORMALIZE: bool
     RETURN_TIME_AS_PERIOD: bool
     RETURN_TIME_SPAN: bool
     DEFAULT_START_OF_WEEK: Literal["monday", "sunday"]
     DEFAULT_DAYS_IN_MONTH: int
-    PARSERS: list[_ParserKind]
+    PARSERS: list[Literal["timestamp", "relative-time", "custom-formats", "absolute-time", "no-spaces-time"]]
     DEFAULT_LANGUAGES: list[str]
     LANGUAGE_DETECTION_CONFIDENCE_THRESHOLD: float
     CACHE_SIZE_LIMIT: int
@@ -41,6 +39,6 @@ def parse(
     languages: list[str] | tuple[str, ...] | set[str] | None = None,
     locales: list[str] | tuple[str, ...] | set[str] | None = None,
     region: str | None = None,
-    settings: _Settings | None = None,
+    settings: Settings | dict[str, Any] | None = None,
     detect_languages_function: _DetectLanguagesFunction | None = None,
 ) -> datetime.datetime | None: ...

stubs/dateparser/dateparser/calendars/__init__.pyi

@@ -1,24 +1,47 @@
 from _typeshed import Incomplete
 from abc import abstractmethod
+from typing import ClassVar, Protocol, type_check_only
 
 from dateparser.conf import Settings
+from dateparser.date import DateData
 from dateparser.parser import _parser
 
+# Examples: `hijri_parser.hijri` class or `convertdate.persian` module
+@type_check_only
+class _CalendarConverter(Protocol):
+    @classmethod
+    def to_gregorian(cls, year: int, month: int, day: int) -> tuple[int, int, int]: ...
+    @classmethod
+    def from_gregorian(
+        cls, year: int | None = None, month: int | None = None, day: int | None = None
+    ) -> tuple[int, int, int]: ...
+    @classmethod
+    def month_length(cls, year: int, month: int) -> int: ...
+
+# Examples: `hijri_parser.HijriDate` or `jalali_parser.PersianDate`
+@type_check_only
+class _NonGregorianDate(Protocol):
+    year: int
+    month: int
+    day: int
+    def __init__(self, year: int, month: int, day: int) -> None: ...
+    def weekday(self) -> int | None: ...
+
 class CalendarBase:
-    parser: Incomplete
-    source: Incomplete
-    def __init__(self, source) -> None: ...
-    def get_date(self): ...
+    parser: type[_parser]
+    source: str
+    def __init__(self, source: str) -> None: ...
+    def get_date(self) -> DateData | None: ...
 
 class non_gregorian_parser(_parser):
-    calendar_converter: Incomplete
-    default_year: Incomplete
-    default_month: Incomplete
-    default_day: Incomplete
-    non_gregorian_date_cls: Incomplete
+    calendar_converter: ClassVar[type[_CalendarConverter]]
+    default_year: ClassVar[int]
+    default_month: ClassVar[int]
+    default_day: ClassVar[int]
+    non_gregorian_date_cls: ClassVar[type[_NonGregorianDate]]
     @classmethod
-    def to_latin(cls, source): ...
+    def to_latin(cls, source: str) -> str: ...
     @abstractmethod
     def handle_two_digit_year(self, year: int) -> int: ...
     @classmethod
-    def parse(cls, datestring: str, settings: Settings) -> tuple[Incomplete, Incomplete]: ...  # type: ignore[override]
+    def parse(cls, datestring: str, settings: Settings) -> tuple[Incomplete, str | None]: ...  # type: ignore[override]

stubs/dateparser/dateparser/calendars/hijri_parser.pyi

@@ -1,5 +1,4 @@
-from _typeshed import Incomplete
-from typing import SupportsIndex
+from typing import ClassVar
 
 from dateparser.calendars import non_gregorian_parser
 
@@ -8,22 +7,22 @@ class hijri:
     def to_gregorian(cls, year: int | None = None, month: int | None = None, day: int | None = None) -> tuple[int, int, int]: ...
     @classmethod
     def from_gregorian(
-        cls, year: SupportsIndex | None = None, month: SupportsIndex | None = None, day: SupportsIndex | None = None
+        cls, year: int | None = None, month: int | None = None, day: int | None = None
     ) -> tuple[int, int, int]: ...
     @classmethod
-    def month_length(cls, year: int, month: int) -> int: ...
+    def month_length(cls, year: int | None, month: int | None) -> int: ...
 
 class HijriDate:
-    year: Incomplete
-    month: Incomplete
-    day: Incomplete
-    def __init__(self, year, month, day) -> None: ...
-    def weekday(self): ...
+    year: int
+    month: int
+    day: int
+    def __init__(self, year: int, month: int, day: int) -> None: ...
+    def weekday(self) -> int | None: ...
 
 class hijri_parser(non_gregorian_parser):
-    calendar_converter: type[hijri]
-    default_year: int
-    default_month: int
-    default_day: int
-    non_gregorian_date_cls: type[HijriDate]
+    calendar_converter: ClassVar[type[hijri]]
+    default_year: ClassVar[int]
+    default_month: ClassVar[int]
+    default_day: ClassVar[int]
+    non_gregorian_date_cls: ClassVar[type[HijriDate]]
     def handle_two_digit_year(self, year: int) -> int: ...

stubs/dateparser/dateparser/calendars/jalali_parser.pyi

@@ -1,18 +1,18 @@
-from _typeshed import Incomplete
+from typing import ClassVar
 
 from dateparser.calendars import non_gregorian_parser
 
 class PersianDate:
-    year: Incomplete
-    month: Incomplete
-    day: Incomplete
-    def __init__(self, year, month, day) -> None: ...
-    def weekday(self): ...
+    year: int
+    month: int
+    day: int
+    def __init__(self, year: int, month: int, day: int) -> None: ...
+    def weekday(self) -> int | None: ...
 
 class jalali_parser(non_gregorian_parser):
-    calendar_converter: Incomplete
-    default_year: int
-    default_month: int
-    default_day: int
-    non_gregorian_date_cls: type[PersianDate]
+    # `calendar_converter` is `convertdate.persian` module
+    default_year: ClassVar[int]
+    default_month: ClassVar[int]
+    default_day: ClassVar[int]
+    non_gregorian_date_cls: ClassVar[type[PersianDate]]
     def handle_two_digit_year(self, year: int) -> int: ...

stubs/dateparser/dateparser/conf.pyi

@@ -1,16 +1,45 @@
-from typing import Any
-from typing_extensions import Self
+import datetime
+from collections.abc import Callable
+from typing import Any, Literal, TypeVar
+from typing_extensions import ParamSpec, Self
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
 
 class Settings:
-    def __new__(cls, *args, **kw) -> Self: ...
+    # Next attributes are optional and may be missing.
+    # Please keep in sync with _Settings TypedDict
+    DATE_ORDER: str
+    PREFER_LOCALE_DATE_ORDER: bool
+    TIMEZONE: str
+    TO_TIMEZONE: str
+    RETURN_AS_TIMEZONE_AWARE: bool
+    PREFER_MONTH_OF_YEAR: Literal["current", "first", "last"]
+    PREFER_DAY_OF_MONTH: Literal["current", "first", "last"]
+    PREFER_DATES_FROM: Literal["current_period", "future", "past"]
+    RELATIVE_BASE: datetime.datetime
+    STRICT_PARSING: bool
+    REQUIRE_PARTS: list[Literal["day", "month", "year"]]
+    SKIP_TOKENS: list[str]
+    NORMALIZE: bool
+    RETURN_TIME_AS_PERIOD: bool
+    RETURN_TIME_SPAN: bool
+    DEFAULT_START_OF_WEEK: Literal["monday", "sunday"]
+    DEFAULT_DAYS_IN_MONTH: int
+    PARSERS: list[Literal["timestamp", "relative-time", "custom-formats", "absolute-time", "no-spaces-time"]]
+    DEFAULT_LANGUAGES: list[str]
+    LANGUAGE_DETECTION_CONFIDENCE_THRESHOLD: float
+    CACHE_SIZE_LIMIT: int
+
+    def __new__(cls, *args, **kwargs) -> Self: ...
     def __init__(self, settings: dict[str, Any] | None = None) -> None: ...
     @classmethod
     def get_key(cls, settings: dict[str, Any] | None = None) -> str: ...
     def replace(self, mod_settings: dict[str, Any] | None = None, **kwds) -> Self: ...
 
 settings: Settings
 
-def apply_settings(f): ...
+def apply_settings(f: Callable[_P, _R]) -> Callable[_P, _R]: ...
 
 class SettingValidationError(ValueError): ...
 

stubs/dateparser/dateparser/data/languages_info.pyi

@@ -1,5 +1,5 @@
 from typing import Final
 
 language_order: Final[list[str]]
-language_locale_dict: Final[dict[str, str]]
 language_map: Final[dict[str, list[str]]]
+language_locale_dict: Final[dict[str, list[str]]]

stubs/dateparser/dateparser/date.pyi

@@ -1,56 +1,87 @@
-import collections
-from collections.abc import Callable, Iterable, Iterator
-from datetime import datetime, tzinfo
-from re import Pattern
-from typing import ClassVar, Final, Literal, overload
+import re
+from _typeshed import Incomplete
+from collections import OrderedDict
+from collections.abc import Callable, Iterable, Iterator, Set as AbstractSet
+from datetime import date, datetime, tzinfo
+from typing import Any, ClassVar, Final, Literal, NamedTuple, TypeVar, overload, type_check_only
 from typing_extensions import TypeAlias
 
-from dateparser import _Settings
 from dateparser.conf import Settings
 from dateparser.languages.loader import LocaleDataLoader
 from dateparser.languages.locale import Locale
 
+_DateT = TypeVar("_DateT", bound=date)
+
 _DetectLanguagesFunction: TypeAlias = Callable[[str, float], list[str]]
 _Period: TypeAlias = Literal["time", "day", "week", "month", "year"]
+# Work around attribute and type having the same name.
+_Weekday: TypeAlias = Incomplete  # Actually it's dateutil._common.weekday class
+
+@type_check_only
+class _DateData(NamedTuple):
+    date_obj: datetime | None
+    locale: str | None
+    period: _Period | None
 
 APOSTROPHE_LOOK_ALIKE_CHARS: Final[list[str]]
-RE_NBSP: Final[Pattern[str]]
-RE_SPACES: Final[Pattern[str]]
-RE_TRIM_SPACES: Final[Pattern[str]]
-RE_TRIM_COLONS: Final[Pattern[str]]
-RE_SANITIZE_SKIP: Final[Pattern[str]]
-RE_SANITIZE_RUSSIAN: Final[Pattern[str]]
-RE_SANITIZE_PERIOD: Final[Pattern[str]]
-RE_SANITIZE_ON: Final[Pattern[str]]
-RE_SANITIZE_APOSTROPHE: Final[Pattern[str]]
-RE_SEARCH_TIMESTAMP: Final[Pattern[str]]
-RE_SANITIZE_CROATIAN: Final[Pattern[str]]
-RE_SEARCH_NEGATIVE_TIMESTAMP: Final[Pattern[str]]
+RE_NBSP: Final[re.Pattern[str]]
+RE_SPACES: Final[re.Pattern[str]]
+RE_TRIM_SPACES: Final[re.Pattern[str]]
+RE_TRIM_COLONS: Final[re.Pattern[str]]
+RE_SANITIZE_SKIP: Final[re.Pattern[str]]
+RE_SANITIZE_RUSSIAN: Final[re.Pattern[str]]
+RE_SANITIZE_PERIOD: Final[re.Pattern[str]]
+RE_SANITIZE_ON: Final[re.Pattern[str]]
+RE_SANITIZE_APOSTROPHE: Final[re.Pattern[str]]
+RE_SEARCH_TIMESTAMP: Final[re.Pattern[str]]
+RE_SANITIZE_CROATIAN: Final[re.Pattern[str]]
+RE_SEARCH_NEGATIVE_TIMESTAMP: Final[re.Pattern[str]]
 
 def sanitize_spaces(date_string: str) -> str: ...
-def date_range(begin: datetime, end: datetime, **kwargs) -> None: ...
-def get_intersecting_periods(low: datetime, high: datetime, period: str = "day") -> None: ...
+def date_range(
+    begin: _DateT,
+    end: _DateT,
+    *,
+    dt1: date | None = None,
+    dt2: date | None = None,
+    years: int = 0,
+    months: int = 0,
+    days: int = 0,
+    leapdays: int = 0,
+    weeks: int = 0,
+    hours: int = 0,
+    minutes: int = 0,
+    seconds: int = 0,
+    microseconds: int = 0,
+    weekday: int | _Weekday | None = None,
+    yearday: int | None = None,
+    nlyearday: int | None = None,
+    microsecond: int | None = None,
+) -> Iterator[_DateT]: ...
+def get_intersecting_periods(
+    low: _DateT, high: _DateT, period: Literal["year", "month", "week", "day", "hour", "minute", "second", "microsecond"] = "day"
+) -> Iterator[_DateT]: ...
 def sanitize_date(date_string: str) -> str: ...
-def get_date_from_timestamp(date_string: str, settings: Settings, negative: bool = False) -> datetime | None: ...
+def get_date_from_timestamp(date_string: str, settings: Settings, negative: bool | None = False) -> datetime | None: ...
 def parse_with_formats(date_string: str, date_formats: Iterable[str], settings: Settings) -> DateData: ...
 
 class _DateLocaleParser:
     locale: Locale
     date_string: str
-    date_formats: list[str] | tuple[str, ...] | set[str] | None
+    date_formats: list[str] | tuple[str, ...] | AbstractSet[str] | None
     def __init__(
         self,
         locale: Locale,
         date_string: str,
-        date_formats: list[str] | tuple[str, ...] | set[str] | None,
+        date_formats: list[str] | tuple[str, ...] | AbstractSet[str] | None,
         settings: Settings | None = None,
     ) -> None: ...
     @classmethod
     def parse(
         cls,
         locale: Locale,
         date_string: str,
-        date_formats: list[str] | tuple[str, ...] | set[str] | None = None,
+        date_formats: list[str] | tuple[str, ...] | AbstractSet[str] | None = None,
         settings: Settings | None = None,
     ) -> DateData: ...
     def _parse(self) -> DateData | None: ...
@@ -88,22 +119,26 @@ class DateDataParser:
     try_previous_locales: bool
     use_given_order: bool
     languages: list[str] | None
-    locales: list[str] | tuple[str, ...] | set[str] | None
+    locales: list[str] | tuple[str, ...] | AbstractSet[str] | None
     region: str
     detect_languages_function: _DetectLanguagesFunction | None
-    previous_locales: collections.OrderedDict[Locale, None]
+    previous_locales: OrderedDict[Locale, None]
     def __init__(
         self,
-        languages: list[str] | tuple[str, ...] | set[str] | None = None,
-        locales: list[str] | tuple[str, ...] | set[str] | None = None,
+        languages: list[str] | tuple[str, ...] | AbstractSet[str] | None = None,
+        locales: list[str] | tuple[str, ...] | AbstractSet[str] | None = None,
         region: str | None = None,
         try_previous_locales: bool = False,
         use_given_order: bool = False,
-        settings: _Settings | None = None,
+        settings: Settings | dict[str, Any] | None = None,
         detect_languages_function: _DetectLanguagesFunction | None = None,
     ) -> None: ...
-    def get_date_data(self, date_string: str, date_formats: list[str] | tuple[str, ...] | set[str] | None = None) -> DateData: ...
-    def get_date_tuple(self, date_string: str, date_formats: list[str] | tuple[str, ...] | set[str] | None = ...): ...
+    def get_date_data(
+        self, date_string: str, date_formats: list[str] | tuple[str, ...] | AbstractSet[str] | None = None
+    ) -> DateData: ...
+    def get_date_tuple(
+        self, date_string: str, date_formats: list[str] | tuple[str, ...] | AbstractSet[str] | None = None
+    ) -> _DateData: ...
     def _get_applicable_locales(self, date_string: str) -> Iterator[Locale]: ...
     def _is_applicable_locale(self, locale: Locale, date_string: str) -> bool: ...
     @classmethod