Improve dateparser (#13796)

stubs/dateparser/dateparser/calendars/hijri.pyi

@@ -1,6 +1,5 @@
-from typing import Any
-
 from dateparser.calendars import CalendarBase
+from dateparser.calendars.hijri_parser import hijri_parser
 
 class HijriCalendar(CalendarBase):
-    parser: Any
+    parser: type[hijri_parser]

stubs/dateparser/dateparser/calendars/hijri_parser.pyi

@@ -1,15 +1,16 @@
-from _typeshed import Incomplete
-from typing import Any
+from typing import Any, SupportsIndex
 
 from dateparser.calendars import non_gregorian_parser
 
 class hijri:
     @classmethod
-    def to_gregorian(cls, year: Incomplete | None = ..., month: Incomplete | None = ..., day: Incomplete | None = ...): ...
+    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: Incomplete | None = ..., month: Incomplete | None = ..., day: Incomplete | None = ...): ...
+    def from_gregorian(
+        cls, year: SupportsIndex | None = None, month: SupportsIndex | None = None, day: SupportsIndex | None = None
+    ) -> tuple[int, int, int]: ...
     @classmethod
-    def month_length(cls, year, month): ...
+    def month_length(cls, year: int, month: int) -> int: ...
 
 class HijriDate:
     year: Any
@@ -19,9 +20,9 @@ class HijriDate:
     def weekday(self): ...
 
 class hijri_parser(non_gregorian_parser):
-    calendar_converter: Any
+    calendar_converter: type[hijri]
     default_year: int
     default_month: int
     default_day: int
-    non_gregorian_date_cls: Any
+    non_gregorian_date_cls: type[HijriDate]
     def handle_two_digit_year(self, year: int) -> int: ...

stubs/dateparser/dateparser/calendars/jalali.pyi

@@ -1,6 +1,6 @@
-from typing import Any
+from dateparser.calendars.jalali_parser import jalali_parser
 
 from . import CalendarBase
 
 class JalaliCalendar(CalendarBase):
-    parser: Any
+    parser: type[jalali_parser]

stubs/dateparser/dateparser/calendars/jalali_parser.pyi

@@ -14,5 +14,5 @@ class jalali_parser(non_gregorian_parser):
     default_year: int
     default_month: int
     default_day: int
-    non_gregorian_date_cls: Any
+    non_gregorian_date_cls: type[PersianDate]
     def handle_two_digit_year(self, year: int) -> int: ...

stubs/dateparser/dateparser/conf.pyi

@@ -1,18 +1,17 @@
-from _typeshed import Incomplete
 from typing import Any
 from typing_extensions import Self
 
 class Settings:
     def __new__(cls, *args, **kw) -> Self: ...
-    def __init__(self, settings: Incomplete | None = None) -> None: ...
+    def __init__(self, settings: dict[str, Any] | None = None) -> None: ...
     @classmethod
-    def get_key(cls, settings: Incomplete | None = None): ...
-    def replace(self, mod_settings: Incomplete | None = None, **kwds): ...
+    def get_key(cls, settings: dict[str, Any] | None = None) -> str: ...
+    def replace(self, mod_settings: dict[str, Any] | None = None, **kwds) -> Self: ...
 
-settings: Any
+settings: Settings
 
 def apply_settings(f): ...
 
 class SettingValidationError(ValueError): ...
 
-def check_settings(settings) -> None: ...
+def check_settings(settings: Settings) -> None: ...

stubs/dateparser/dateparser/data/languages_info.pyi

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

stubs/dateparser/dateparser/date.pyi

@@ -1,8 +1,8 @@
 import collections
 from collections.abc import Callable, Iterable, Iterator
-from datetime import datetime
+from datetime import datetime, tzinfo
 from re import Pattern
-from typing import ClassVar, Literal, overload
+from typing import ClassVar, Final, Literal, overload
 from typing_extensions import TypeAlias
 
 from dateparser import _Settings
@@ -13,23 +13,23 @@ from dateparser.languages.locale import Locale
 _DetectLanguagesFunction: TypeAlias = Callable[[str, float], list[str]]
 _Period: TypeAlias = Literal["time", "day", "week", "month", "year"]
 
-APOSTROPHE_LOOK_ALIKE_CHARS: list[str]
-RE_NBSP: Pattern[str]
-RE_SPACES: Pattern[str]
-RE_TRIM_SPACES: Pattern[str]
-RE_TRIM_COLONS: Pattern[str]
-RE_SANITIZE_SKIP: Pattern[str]
-RE_SANITIZE_RUSSIAN: Pattern[str]
-RE_SANITIZE_PERIOD: Pattern[str]
-RE_SANITIZE_ON: Pattern[str]
-RE_SANITIZE_APOSTROPHE: Pattern[str]
-RE_SEARCH_TIMESTAMP: Pattern[str]
-RE_SANITIZE_CROATIAN: Pattern[str]
-RE_SEARCH_NEGATIVE_TIMESTAMP: Pattern[str]
+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]]
 
 def sanitize_spaces(date_string: str) -> str: ...
-def date_range(begin, end, **kwargs) -> None: ...
-def get_intersecting_periods(low, high, period: str = "day") -> None: ...
+def date_range(begin: datetime, end: datetime, **kwargs) -> None: ...
+def get_intersecting_periods(low: datetime, high: datetime, period: str = "day") -> None: ...
 def sanitize_date(date_string: str) -> str: ...
 def get_date_from_timestamp(date_string: str, settings: Settings, negative: bool = False) -> datetime | None: ...
 def parse_with_formats(date_string: str, date_formats: Iterable[str], settings: Settings) -> DateData: ...
@@ -58,7 +58,7 @@ class _DateLocaleParser:
     def _try_freshness_parser(self) -> DateData | None: ...
     def _try_absolute_parser(self) -> DateData | None: ...
     def _try_nospaces_parser(self) -> DateData | None: ...
-    def _try_parser(self, parse_method) -> DateData | None: ...
+    def _try_parser(self, parse_method: Callable[[str, Settings, tzinfo | None], tuple[datetime, str]]) -> DateData | None: ...
     def _try_given_formats(self) -> DateData | None: ...
     def _get_translated_date(self) -> str: ...
     def _get_translated_date_with_formatting(self) -> str: ...

stubs/dateparser/dateparser/date_parser.pyi

@@ -1,7 +1,14 @@
-from _typeshed import Incomplete
-from typing import Any
+from collections.abc import Callable
+from datetime import datetime, tzinfo
+
+from dateparser.conf import Settings
 
 class DateParser:
-    def parse(self, date_string, parse_method, settings: Incomplete | None = None): ...
+    def parse(
+        self,
+        date_string: str,
+        parse_method: Callable[[str, Settings, tzinfo | None], tuple[datetime, str]],
+        settings: Settings | None = None,
+    ) -> tuple[datetime, str]: ...
 
-date_parser: Any
+date_parser: DateParser

stubs/dateparser/dateparser/freshness_date_parser.pyi

@@ -1,12 +1,16 @@
+import re
 from _typeshed import Incomplete
-from typing import Any
+from typing import Final
+from zoneinfo import ZoneInfo
 
-PATTERN: Any
+from dateparser.date import DateData
+
+PATTERN: Final[re.Pattern[str]]
 
 class FreshnessDateDataParser:
-    def get_local_tz(self): ...
-    def parse(self, date_string, settings): ...
-    def get_kwargs(self, date_string): ...
-    def get_date_data(self, date_string, settings: Incomplete | None = None): ...
+    def get_local_tz(self) -> ZoneInfo: ...
+    def parse(self, date_string: str, settings) -> tuple[Incomplete | None, str | None]: ...
+    def get_kwargs(self, date_string: str) -> dict[str, float]: ...
+    def get_date_data(self, date_string: str, settings: Incomplete | None = None) -> DateData: ...
 
-freshness_date_parser: Any
+freshness_date_parser: FreshnessDateDataParser

stubs/dateparser/dateparser/languages/__init__.pyi

@@ -0,0 +1,2 @@
+from .loader import default_loader as default_loader
+from .locale import Locale as Locale

stubs/dateparser/dateparser/languages/dictionary.pyi

@@ -1,24 +1,28 @@
+import re
 from _typeshed import Incomplete
-from typing import Any
+from typing import Any, Final, overload
 
-PARSER_HARDCODED_TOKENS: Any
-PARSER_KNOWN_TOKENS: Any
-ALWAYS_KEEP_TOKENS: list[str]
-KNOWN_WORD_TOKENS: Any
-PARENTHESES_PATTERN: Any
-NUMERAL_PATTERN: Any
-KEEP_TOKEN_PATTERN: Any
+PARSER_HARDCODED_TOKENS: Final[list[str]]
+PARSER_KNOWN_TOKENS: Final[list[str]]
+ALWAYS_KEEP_TOKENS: Final[list[str]]
+KNOWN_WORD_TOKENS: Final[list[str]]
+PARENTHESES_PATTERN: Final[re.Pattern[str]]
+NUMERAL_PATTERN: Final[re.Pattern[str]]
+KEEP_TOKEN_PATTERN: Final[re.Pattern[str]]
 
 class UnknownTokenError(Exception): ...
 
 class Dictionary:
     info: Any
-    def __init__(self, locale_info, settings: Incomplete | None = None) -> None: ...
+    def __init__(self, locale_info: dict[str, Incomplete], settings: Incomplete | None = None) -> None: ...
     def __contains__(self, key): ...
     def __getitem__(self, key): ...
     def __iter__(self) -> Any: ...
-    def are_tokens_valid(self, tokens): ...
-    def split(self, string, keep_formatting: bool = False): ...
+    def are_tokens_valid(self, tokens: list[str]) -> bool: ...
+    @overload
+    def split(self, string: None, keep_formatting: bool = False) -> None: ...
+    @overload
+    def split(self, string: str, keep_formatting: bool = False) -> list[str]: ...
 
 class NormalizedDictionary(Dictionary):
-    def __init__(self, locale_info, settings: Incomplete | None = None) -> None: ...
+    def __init__(self, locale_info: dict[str, Incomplete], settings: Incomplete | None = None) -> None: ...

stubs/dateparser/dateparser/languages/loader.pyi

@@ -1,10 +1,11 @@
+import re
 from collections import OrderedDict
 from collections.abc import Iterator
-from typing import Any
+from typing import Any, Final
 
 from .locale import Locale
 
-LOCALE_SPLIT_PATTERN: Any
+LOCALE_SPLIT_PATTERN: Final[re.Pattern[str]]
 
 class LocaleDataLoader:
     def get_locale_map(
@@ -25,4 +26,4 @@ class LocaleDataLoader:
     ) -> Iterator[Locale]: ...
     def get_locale(self, shortname: str) -> Locale: ...
 
-default_loader: Any
+default_loader: LocaleDataLoader

stubs/dateparser/dateparser/languages/locale.pyi

@@ -1,8 +1,9 @@
 from re import Pattern
+from typing import Final
 
 from dateparser.conf import Settings
 
-NUMERAL_PATTERN: Pattern[str]
+NUMERAL_PATTERN: Final[Pattern[str]]
 
 class Locale:
     shortname: str

stubs/dateparser/dateparser/languages/validation.pyi

@@ -1,9 +1,10 @@
-from typing import Any
+from _typeshed import Incomplete
+from logging import Logger
 
 class LanguageValidator:
-    logger: Any
-    VALID_KEYS: Any
+    logger: Logger | None
+    VALID_KEYS: list[str]
     @classmethod
-    def get_logger(cls): ...
+    def get_logger(cls) -> Logger: ...
     @classmethod
-    def validate_info(cls, language_id, info): ...
+    def validate_info(cls, language_id, info: dict[str, Incomplete]) -> bool: ...

stubs/dateparser/dateparser/parser.pyi

@@ -1,53 +1,64 @@
+import collections
 import datetime
+import re
 from _typeshed import Incomplete
-from typing import Any
+from collections.abc import Callable, Generator
+from io import StringIO
+from typing import Any, Final, Literal, overload
 
-NSP_COMPATIBLE: Any
-MERIDIAN: Any
-MICROSECOND: Any
-EIGHT_DIGIT: Any
-HOUR_MINUTE_REGEX: Any
+from dateparser.conf import Settings
 
-def no_space_parser_eligibile(datestring): ...
-def get_unresolved_attrs(parser_object): ...
+NSP_COMPATIBLE: Final[re.Pattern[str]]
+MERIDIAN: Final[re.Pattern[str]]
+MICROSECOND: Final[re.Pattern[str]]
+EIGHT_DIGIT: Final[re.Pattern[str]]
+HOUR_MINUTE_REGEX: Final[re.Pattern[str]]
 
-date_order_chart: Any
+def no_space_parser_eligibile(datestring: str) -> bool: ...
+def get_unresolved_attrs(
+    parser_object: object,
+) -> tuple[list[Literal["year", "month", "day"]], list[Literal["year", "month", "day"]]]: ...
 
-def resolve_date_order(order, lst: Incomplete | None = None): ...
+date_order_chart: Final[dict[str, str]]
+
+@overload
+def resolve_date_order(order: str, lst: Literal[True]) -> list[str]: ...
+@overload
+def resolve_date_order(order: str, lst: Literal[False] | None = None) -> str: ...
 
 class _time_parser:
-    time_directives: Any
-    def __call__(self, timestring): ...
+    time_directives: list[str]
+    def __call__(self, timestring: str) -> datetime.time: ...
 
-time_parser: Any
+time_parser: _time_parser
 
 class _no_spaces_parser:
-    period: Any
-    date_formats: Any
+    period: dict[str, list[str]]
+    date_formats: dict[str, list[str]]
     def __init__(self, *args, **kwargs): ...
     @classmethod
-    def parse(cls, datestring, settings): ...
+    def parse(cls, datestring: str, settings: Settings) -> tuple[datetime.datetime, str]: ...
 
 class _parser:
-    alpha_directives: Any
-    num_directives: Any
-    settings: Any
-    tokens: Any
-    filtered_tokens: Any
-    unset_tokens: Any
-    day: Any
-    month: Any
-    year: Any
-    time: Any
-    auto_order: Any
-    ordered_num_directives: Any
-    def __init__(self, tokens, settings): ...
+    alpha_directives: collections.OrderedDict[str, list[str]]
+    num_directives: dict[str, list[str]]
+    settings: Settings
+    tokens: list[tuple[Incomplete, Incomplete]]
+    filtered_tokens: list[tuple[Incomplete, Incomplete, int]]
+    unset_tokens: list[Incomplete]
+    day: int | None
+    month: int | None
+    year: int | None
+    time: Callable[[], datetime.time] | None
+    auto_order: list[str]
+    ordered_num_directives: collections.OrderedDict[str, list[str]]
+    def __init__(self, tokens, settings: Settings): ...
     @classmethod
-    def parse(cls, datestring, settings, tz: datetime.tzinfo | None = None): ...
+    def parse(cls, datestring: str, settings: Settings, tz: datetime.tzinfo | None = None): ...
 
 class tokenizer:
-    digits: str
-    letters: str
-    instream: Any
-    def __init__(self, ds) -> None: ...
-    def tokenize(self) -> None: ...
+    digits: Literal["0123456789:"]
+    letters: Literal["abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]
+    instream: StringIO
+    def __init__(self, ds: str) -> None: ...
+    def tokenize(self) -> Generator[tuple[str, Literal[0, 1, 2]], Any, None]: ...

stubs/dateparser/dateparser/timezone_parser.pyi

@@ -1,18 +1,19 @@
-from datetime import tzinfo
-from typing import Any
+import re
+from collections.abc import Generator
+from datetime import datetime, timedelta, tzinfo
 
 class StaticTzInfo(tzinfo):
-    def __init__(self, name, offset) -> None: ...
-    def tzname(self, dt): ...
-    def utcoffset(self, dt): ...
-    def dst(self, dt): ...
-    def localize(self, dt, is_dst: bool = False): ...
-    def __getinitargs__(self): ...
+    def __init__(self, name: str, offset: timedelta) -> None: ...
+    def tzname(self, dt) -> str: ...
+    def utcoffset(self, dt) -> timedelta: ...
+    def dst(self, dt) -> timedelta: ...
+    def localize(self, dt: datetime, is_dst: bool = False) -> datetime: ...
+    def __getinitargs__(self) -> tuple[str, timedelta]: ...
 
-def pop_tz_offset_from_string(date_string, as_offset: bool = True): ...
-def word_is_tz(word): ...
-def convert_to_local_tz(datetime_obj, datetime_tz_offset): ...
-def build_tz_offsets(search_regex_parts): ...
-def get_local_tz_offset(): ...
+def pop_tz_offset_from_string(date_string: str, as_offset: bool = True) -> tuple[str, StaticTzInfo | str | None]: ...
+def word_is_tz(word: str) -> bool: ...
+def convert_to_local_tz(datetime_obj: datetime, datetime_tz_offset: timedelta) -> datetime: ...
+def build_tz_offsets(search_regex_parts: list[str]) -> Generator[tuple[str, dict[str, re.Pattern[str] | timedelta]]]: ...
+def get_local_tz_offset() -> timedelta: ...
 
-local_tz_offset: Any
+local_tz_offset: timedelta

stubs/dateparser/dateparser/timezones.pyi

@@ -1 +1,3 @@
-timezone_info_list: list[dict[str, list[str | tuple[str, ...]]]]
+from typing import Final
+
+timezone_info_list: Final[list[dict[str, list[str | tuple[str, str | int]]]]]

stubs/dateparser/dateparser/utils/__init__.pyi

@@ -1,6 +1,7 @@
 from _typeshed import Incomplete
 from collections import OrderedDict
 from collections.abc import Mapping
+from logging import Logger
 from typing import Any
 
 def strip_braces(date_string: str) -> str: ...
@@ -20,7 +21,7 @@ def get_next_leap_year(year): ...
 def set_correct_day_from_settings(date_obj, settings, current_day: Incomplete | None = None): ...
 def set_correct_month_from_settings(date_obj, settings, current_month=None): ...
 def registry(cls): ...
-def get_logger() -> Any: ...
+def get_logger() -> Logger: ...
 def setup_logging() -> None: ...
 
 # TODO: this needs `types-pytz` and a type-alias

stubs/dateparser/dateparser/utils/strptime.pyi

@@ -1,8 +1,9 @@
+import re
 from datetime import datetime
-from typing import Any
+from typing import Any, Final
 
-TIME_MATCHER: Any
-MS_SEARCHER: Any
+TIME_MATCHER: Final[re.Pattern[str]]
+MS_SEARCHER: Final[re.Pattern[str]]
 
 def patch_strptime() -> Any: ...
 def strptime(date_string, format) -> datetime: ...

stubs/dateparser/dateparser_data/settings.pyi

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Final
 
-default_parsers: Any
-settings: Any
+default_parsers: Final[list[str]]
+settings: Final[dict[str, str | bool | list[str] | float | int]]