Add more type annotations for Babel (#9125)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
2025-12-15 08:17:07 +08:00 · 2022-11-11 19:29:21 -07:00
parent bc6d91a58e
commit 17d6b97c72
10 changed files with 198 additions and 143 deletions
--- a/stubs/babel/babel/dates.pyi
+++ b/stubs/babel/babel/dates.pyi
@@ -1,8 +1,10 @@
+from collections.abc import Iterable
 from datetime import date, datetime, time, timedelta, tzinfo
-from typing import Any, overload
+from typing import SupportsInt, overload
 from typing_extensions import Literal, TypeAlias

 from babel.core import Locale
+from babel.localedata import LocaleDataDict
 from babel.util import LOCALTZ as LOCALTZ, UTC as UTC
 from pytz import BaseTzInfo

@@ -10,20 +12,22 @@ from pytz import BaseTzInfo
 # http://babel.pocoo.org/en/latest/api/dates.html

 # Date and Time Formatting
-_Instant: TypeAlias = date | time | datetime | float | None
+_Instant: TypeAlias = date | time | float | None
 _PredefinedTimeFormat: TypeAlias = Literal["full", "long", "medium", "short"]
+_Context: TypeAlias = Literal["format", "stand-alone"]

 def format_datetime(
-    datetime: _Instant = ..., format: _PredefinedTimeFormat | str = ..., tzinfo: tzinfo | None = ..., locale: str | Locale = ...
-) -> str: ...
-def format_date(
-    date: date | datetime | None = ..., format: _PredefinedTimeFormat | str = ..., locale: str | Locale = ...
+    datetime: _Instant = ...,
+    format: _PredefinedTimeFormat | str = ...,
+    tzinfo: tzinfo | None = ...,
+    locale: Locale | str | None = ...,
 ) -> str: ...
+def format_date(date: date | None = ..., format: _PredefinedTimeFormat | str = ..., locale: Locale | str | None = ...) -> str: ...
 def format_time(
    time: time | datetime | float | None = ...,
    format: _PredefinedTimeFormat | str = ...,
    tzinfo: tzinfo | None = ...,
-    locale: str | Locale = ...,
+    locale: Locale | str | None = ...,
 ) -> str: ...
 def format_timedelta(
    delta: timedelta | int,
@@ -31,10 +35,10 @@ def format_timedelta(
    threshold: float = ...,
    add_direction: bool = ...,
    format: Literal["narrow", "short", "medium", "long"] = ...,
-    locale: str | Locale = ...,
+    locale: Locale | str | None = ...,
 ) -> str: ...
 def format_skeleton(
-    skeleton: str, datetime: _Instant = ..., tzinfo: tzinfo | None = ..., fuzzy: bool = ..., locale: str | Locale = ...
+    skeleton: str, datetime: _Instant = ..., tzinfo: tzinfo | None = ..., fuzzy: bool = ..., locale: Locale | str | None = ...
 ) -> str: ...
 def format_interval(
    start: _Instant,
@@ -42,7 +46,7 @@ def format_interval(
    skeleton: str | None = ...,
    tzinfo: tzinfo | None = ...,
    fuzzy: bool = ...,
-    locale: str | Locale = ...,
+    locale: Locale | str | None = ...,
 ) -> str: ...

 # Timezone Functionality
@@ -53,18 +57,18 @@ def get_timezone(zone: tzinfo) -> tzinfo: ...
 def get_timezone_gmt(
    datetime: _Instant = ...,
    width: Literal["long", "short", "iso8601", "iso8601_short"] = ...,
-    locale: str | Locale = ...,
+    locale: Locale | str | None = ...,
    return_z: bool = ...,
 ) -> str: ...

 _DtOrTzinfo: TypeAlias = datetime | tzinfo | str | int | time | None

-def get_timezone_location(dt_or_tzinfo: _DtOrTzinfo = ..., locale: str | Locale = ..., return_city: bool = ...) -> str: ...
+def get_timezone_location(dt_or_tzinfo: _DtOrTzinfo = ..., locale: Locale | str | None = ..., return_city: bool = ...) -> str: ...
 def get_timezone_name(
    dt_or_tzinfo: _DtOrTzinfo = ...,
    width: Literal["long", "short"] = ...,
    uncommon: bool = ...,
-    locale: str | Locale = ...,
+    locale: Locale | str | None = ...,
    zone_variant: Literal["generic", "daylight", "standard"] | None = ...,
    return_zone: bool = ...,
 ) -> str: ...
@@ -95,64 +99,74 @@ class TimezoneTransition:
    def to_offset(self) -> int: ...

 # Data Access
-def get_period_names(width: str = ..., context: str = ..., locale=...): ...
-def get_day_names(width: str = ..., context: str = ..., locale=...): ...
-def get_month_names(width: str = ..., context: str = ..., locale=...): ...
-def get_quarter_names(width: str = ..., context: str = ..., locale=...): ...
-def get_era_names(width: str = ..., locale=...): ...
-def get_date_format(format: str = ..., locale=...): ...
-def get_datetime_format(format: str = ..., locale=...): ...
-def get_time_format(format: str = ..., locale=...): ...
+def get_period_names(
+    width: Literal["abbreviated", "narrow", "wide"] = ..., context: _Context = ..., locale: Locale | str | None = ...
+) -> LocaleDataDict: ...
+def get_day_names(
+    width: Literal["abbreviated", "narrow", "short", "wide"] = ..., context: _Context = ..., locale: Locale | str | None = ...
+) -> LocaleDataDict: ...
+def get_month_names(
+    width: Literal["abbreviated", "narrow", "wide"] = ..., context: _Context = ..., locale: Locale | str | None = ...
+) -> LocaleDataDict: ...
+def get_quarter_names(
+    width: Literal["abbreviated", "narrow", "wide"] = ..., context: _Context = ..., locale: Locale | str | None = ...
+) -> LocaleDataDict: ...
+def get_era_names(width: Literal["abbreviated", "narrow", "wide"] = ..., locale: Locale | str | None = ...) -> LocaleDataDict: ...
+def get_date_format(format: _PredefinedTimeFormat = ..., locale: Locale | str | None = ...) -> DateTimePattern: ...
+def get_datetime_format(format: _PredefinedTimeFormat = ..., locale: Locale | str | None = ...) -> DateTimePattern: ...
+def get_time_format(format: _PredefinedTimeFormat = ..., locale: Locale | str | None = ...) -> DateTimePattern: ...

 # Basic Parsing
-def parse_date(string, locale=..., format: str = ...): ...
-def parse_time(string, locale=..., format: str = ...): ...
-def parse_pattern(pattern): ...
+def parse_date(string: str, locale: Locale | str | None = ..., format: _PredefinedTimeFormat = ...) -> date: ...
+def parse_time(string: str, locale: Locale | str | None = ..., format: _PredefinedTimeFormat = ...) -> time: ...
+def parse_pattern(pattern: str) -> DateTimePattern: ...

 # Undocumented
 NO_INHERITANCE_MARKER: str
-LC_TIME: Any
+LC_TIME: str | None
 date_ = date
 datetime_ = datetime
 time_ = time

-TIMEDELTA_UNITS: Any
+TIMEDELTA_UNITS: tuple[tuple[str, int], ...]

-def get_period_id(time, tzinfo: Any | None = ..., type: Any | None = ..., locale=...): ...
+def get_period_id(
+    time: _Instant, tzinfo: BaseTzInfo | None = ..., type: Literal["selection"] | None = ..., locale: Locale | str | None = ...
+): ...

 class DateTimePattern:
-    pattern: Any
-    format: Any
-    def __init__(self, pattern, format) -> None: ...
-    def __mod__(self, other): ...
-    def apply(self, datetime, locale): ...
+    pattern: str
+    format: DateTimeFormat
+    def __init__(self, pattern: str, format: DateTimeFormat) -> None: ...
+    def __mod__(self, other: DateTimeFormat) -> str: ...
+    def apply(self, datetime: _Instant, locale: Locale | str | None) -> str: ...

 class DateTimeFormat:
-    value: Any
-    locale: Any
-    def __init__(self, value, locale) -> None: ...
-    def __getitem__(self, name): ...
-    def extract(self, char): ...
-    def format_era(self, char, num): ...
-    def format_year(self, char, num): ...
-    def format_quarter(self, char, num): ...
-    def format_month(self, char, num): ...
-    def format_week(self, char, num): ...
-    def format_weekday(self, char: str = ..., num: int = ...): ...
-    def format_day_of_year(self, num): ...
-    def format_day_of_week_in_month(self): ...
-    def format_period(self, char, num): ...
-    def format_frac_seconds(self, num): ...
-    def format_milliseconds_in_day(self, num): ...
-    def format_timezone(self, char, num): ...
-    def format(self, value, length): ...
-    def get_day_of_year(self, date: Any | None = ...): ...
-    def get_week_number(self, day_of_period, day_of_week: Any | None = ...): ...
+    value: date | time
+    locale: Locale
+    def __init__(self, value: date | time, locale: Locale | str) -> None: ...
+    def __getitem__(self, name: str) -> str: ...
+    def extract(self, char: str) -> int: ...
+    def format_era(self, char: str, num: int) -> str: ...
+    def format_year(self, char: str, num: int) -> str: ...
+    def format_quarter(self, char: str, num: int) -> str: ...
+    def format_month(self, char: str, num: int) -> str: ...
+    def format_week(self, char: str, num: int) -> str: ...
+    def format_weekday(self, char: str = ..., num: int = ...) -> str: ...
+    def format_day_of_year(self, num: int) -> str: ...
+    def format_day_of_week_in_month(self) -> str: ...
+    def format_period(self, char: str, num: int) -> str: ...
+    def format_frac_seconds(self, num: int) -> str: ...
+    def format_milliseconds_in_day(self, num: int) -> str: ...
+    def format_timezone(self, char: str, num: int) -> str: ...
+    def format(self, value: SupportsInt, length: int) -> str: ...
+    def get_day_of_year(self, date: date | None = ...) -> int: ...
+    def get_week_number(self, day_of_period: int, day_of_week: int | None = ...) -> int: ...

-PATTERN_CHARS: Any
+PATTERN_CHARS: dict[str, list[int] | None]
 PATTERN_CHAR_ORDER: str

-def tokenize_pattern(pattern): ...
-def untokenize_pattern(tokens): ...
-def split_interval_pattern(pattern): ...
-def match_skeleton(skeleton, options, allow_different_fields: bool = ...): ...
+def tokenize_pattern(pattern: str) -> list[tuple[str, str | tuple[str, int]]]: ...
+def untokenize_pattern(tokens: Iterable[tuple[str, str | tuple[str, int]]]) -> str: ...
+def split_interval_pattern(pattern: str) -> list[str]: ...
+def match_skeleton(skeleton: str, options: Iterable[str], allow_different_fields: bool = ...) -> str | None: ...
--- a/stubs/babel/babel/languages.pyi
+++ b/stubs/babel/babel/languages.pyi
@@ -1,2 +1,2 @@
-def get_official_languages(territory, regional: bool = ..., de_facto: bool = ...): ...
-def get_territory_language_info(territory): ...
+def get_official_languages(territory: str, regional: bool = ..., de_facto: bool = ...) -> tuple[str, ...]: ...
+def get_territory_language_info(territory: str) -> dict[str, dict[str, float | str | None]]: ...
--- a/stubs/babel/babel/lists.pyi
+++ b/stubs/babel/babel/lists.pyi
@@ -1,5 +1,12 @@
-from typing import Any
+from collections.abc import Iterable
+from typing_extensions import Literal

-DEFAULT_LOCALE: Any
+from babel.core import Locale

-def format_list(lst, style: str = ..., locale=...): ...
+DEFAULT_LOCALE: str | None
+
+def format_list(
+    lst: Iterable[str],
+    style: Literal["standard", "standard-short", "or", "or-short", "unit", "unit-short", "unit-narrow"] = ...,
+    locale: Locale | str | None = ...,
+) -> str: ...
--- a/stubs/babel/babel/localedata.pyi
+++ b/stubs/babel/babel/localedata.pyi
@@ -1,24 +1,25 @@
-from collections.abc import MutableMapping
+from collections.abc import Iterable, Iterator, Mapping, MutableMapping
+from os import PathLike
 from typing import Any

-def normalize_locale(name): ...
-def resolve_locale_filename(name): ...
-def exists(name): ...
-def locale_identifiers(): ...
-def load(name, merge_inherited: bool = ...): ...
-def merge(dict1, dict2) -> None: ...
+def normalize_locale(name: str) -> str | None: ...
+def resolve_locale_filename(name: PathLike[str] | str) -> str: ...
+def exists(name: str) -> bool: ...
+def locale_identifiers() -> list[str]: ...
+def load(name: PathLike[str] | str, merge_inherited: bool = ...) -> dict[str, Any]: ...
+def merge(dict1: MutableMapping[Any, Any], dict2: Mapping[Any, Any]) -> None: ...

 class Alias:
-    keys: Any
-    def __init__(self, keys) -> None: ...
-    def resolve(self, data): ...
+    keys: tuple[str, ...]
+    def __init__(self, keys: Iterable[str]) -> None: ...
+    def resolve(self, data: Mapping[str, Any]) -> Mapping[str, Any]: ...

 class LocaleDataDict(MutableMapping[Any, Any]):
-    base: Any
-    def __init__(self, data, base: Any | None = ...) -> None: ...
+    base: Mapping[str, Any]
+    def __init__(self, data: Mapping[str, Any], base: Mapping[str, Any] | None = ...) -> None: ...
    def __len__(self) -> int: ...
-    def __iter__(self): ...
-    def __getitem__(self, key): ...
-    def __setitem__(self, key, value) -> None: ...
-    def __delitem__(self, key) -> None: ...
-    def copy(self): ...
+    def __iter__(self) -> Iterator[str]: ...
+    def __getitem__(self, key: str) -> Any: ...
+    def __setitem__(self, key: str, value: Any) -> None: ...
+    def __delitem__(self, key: str) -> None: ...
+    def copy(self) -> LocaleDataDict: ...
--- a/stubs/babel/babel/localtime/init.pyi
+++ b/stubs/babel/babel/localtime/init.pyi
@@ -1,16 +1,17 @@
-from datetime import tzinfo
-from typing import Any
+from datetime import datetime, timedelta, tzinfo

-STDOFFSET: Any
-DSTOFFSET: Any
-DSTDIFF: Any
-ZERO: Any
+from pytz import BaseTzInfo
+
+STDOFFSET: timedelta
+DSTOFFSET: timedelta
+DSTDIFF: timedelta
+ZERO: timedelta

 class _FallbackLocalTimezone(tzinfo):
-    def utcoffset(self, dt): ...
-    def dst(self, dt): ...
-    def tzname(self, dt): ...
+    def utcoffset(self, dt: datetime | None) -> timedelta: ...
+    def dst(self, dt: datetime | None) -> timedelta: ...
+    def tzname(self, dt: datetime | None) -> str: ...

-def get_localzone(): ...
+def get_localzone() -> BaseTzInfo: ...

-LOCALTZ: Any
+LOCALTZ: BaseTzInfo | _FallbackLocalTimezone
--- a/stubs/babel/babel/localtime/_win32.pyi
+++ b/stubs/babel/babel/localtime/_win32.pyi
@@ -1,6 +1,6 @@
 from typing import Any

-tz_names: Any
+tz_names: dict[str, str]

-def valuestodict(key): ...
-def get_localzone_name(): ...
+def valuestodict(key) -> dict[str, Any]: ...
+def get_localzone_name() -> str: ...
--- a/stubs/babel/babel/plural.pyi
+++ b/stubs/babel/babel/plural.pyi
@@ -1,17 +1,19 @@
+import decimal
+from collections.abc import Iterable, Mapping
 from typing import Any

-def extract_operands(source): ...
+def extract_operands(source: float | decimal.Decimal) -> tuple[decimal.Decimal, int, int, int, int, int, int, int]: ...

 class PluralRule:
-    abstract: Any
-    def __init__(self, rules) -> None: ...
+    abstract: list[Any]
+    def __init__(self, rules: Mapping[str, str] | Iterable[tuple[str, str]]) -> None: ...
    @classmethod
-    def parse(cls, rules): ...
+    def parse(cls, rules: Mapping[str, str] | Iterable[tuple[str, str]] | PluralRule) -> PluralRule: ...
    @property
-    def rules(self): ...
+    def rules(self) -> Mapping[str, str]: ...
    @property
-    def tags(self): ...
-    def __call__(self, n): ...
+    def tags(self) -> frozenset[str]: ...
+    def __call__(self, n: float | decimal.Decimal) -> str: ...

 def to_javascript(rule): ...
 def to_python(rule): ...
--- a/stubs/babel/babel/support.pyi
+++ b/stubs/babel/babel/support.pyi
@@ -1,19 +1,34 @@
 import gettext
+from datetime import date as _date, datetime as _datetime, time as _time, timedelta as _timedelta
+from decimal import Decimal
 from typing import Any
+from typing_extensions import Literal
+
+from babel.core import Locale
+from pytz import BaseTzInfo
+
+from .dates import _PredefinedTimeFormat

 class Format:
-    locale: Any
-    tzinfo: Any
-    def __init__(self, locale, tzinfo: Any | None = ...) -> None: ...
-    def date(self, date: Any | None = ..., format: str = ...): ...
-    def datetime(self, datetime: Any | None = ..., format: str = ...): ...
-    def time(self, time: Any | None = ..., format: str = ...): ...
-    def timedelta(self, delta, granularity: str = ..., threshold: float = ..., format: str = ..., add_direction: bool = ...): ...
-    def number(self, number): ...
-    def decimal(self, number, format: Any | None = ...): ...
-    def currency(self, number, currency): ...
-    def percent(self, number, format: Any | None = ...): ...
-    def scientific(self, number): ...
+    locale: Locale
+    tzinfo: BaseTzInfo | None
+    def __init__(self, locale: Locale | str, tzinfo: BaseTzInfo | None = ...) -> None: ...
+    def date(self, date: _date | None = ..., format: _PredefinedTimeFormat | str = ...) -> str: ...
+    def datetime(self, datetime: _date | None = ..., format: _PredefinedTimeFormat | str = ...) -> str: ...
+    def time(self, time: _time | _datetime | None = ..., format: _PredefinedTimeFormat | str = ...) -> str: ...
+    def timedelta(
+        self,
+        delta: _timedelta | int,
+        granularity: Literal["year", "month", "week", "day", "hour", "minute", "second"] = ...,
+        threshold: float = ...,
+        format: _PredefinedTimeFormat = ...,
+        add_direction: bool = ...,
+    ) -> str: ...
+    def number(self, number: float | Decimal) -> str: ...
+    def decimal(self, number: float | Decimal, format: str | None = ...) -> str: ...
+    def currency(self, number: float | Decimal, currency: str) -> str: ...
+    def percent(self, number: float | Decimal, format: str | None = ...) -> str: ...
+    def scientific(self, number: float | Decimal) -> str: ...

 class LazyProxy:
    def __init__(self, func, *args, **kwargs) -> None: ...
--- a/stubs/babel/babel/units.pyi
+++ b/stubs/babel/babel/units.pyi
@@ -1,16 +1,27 @@
-from typing import Any
+import decimal
+from typing_extensions import Literal
+
+from babel.core import Locale

 class UnknownUnitError(ValueError):
-    def __init__(self, unit, locale) -> None: ...
+    def __init__(self, unit: str, locale: Locale) -> None: ...

-def get_unit_name(measurement_unit, length: str = ..., locale=...): ...
-def format_unit(value, measurement_unit, length: str = ..., format: Any | None = ..., locale=...): ...
+def get_unit_name(
+    measurement_unit: str, length: Literal["short", "long", "narrow"] = ..., locale: Locale | str | None = ...
+) -> str: ...
+def format_unit(
+    value: float | decimal.Decimal,
+    measurement_unit: str,
+    length: Literal["short", "long", "narrow"] = ...,
+    format: str | None = ...,
+    locale: Locale | str | None = ...,
+) -> str: ...
 def format_compound_unit(
-    numerator_value,
-    numerator_unit: Any | None = ...,
-    denominator_value: int = ...,
-    denominator_unit: Any | None = ...,
-    length: str = ...,
-    format: Any | None = ...,
-    locale=...,
-): ...
+    numerator_value: float | decimal.Decimal,
+    numerator_unit: str | None = ...,
+    denominator_value: float | decimal.Decimal = ...,
+    denominator_unit: str | None = ...,
+    length: Literal["short", "long", "narrow"] = ...,
+    format: str | None = ...,
+    locale: Locale | str | None = ...,
+) -> str | None: ...
--- a/stubs/babel/babel/util.pyi
+++ b/stubs/babel/babel/util.pyi
@@ -1,42 +1,46 @@
 import collections
 import textwrap
-from datetime import tzinfo
-from typing import Any
+from collections.abc import Generator, Iterable
+from datetime import timedelta, tzinfo
+from re import Pattern
+from typing import IO, Any, TypeVar

 from babel import localtime as localtime
 from pytz import BaseTzInfo

-missing: Any
+missing: object

-def distinct(iterable) -> None: ...
+_T = TypeVar("_T")

-PYTHON_MAGIC_COMMENT_re: Any
+def distinct(iterable: Iterable[_T]) -> Generator[_T, None, None]: ...

-def parse_encoding(fp): ...
+PYTHON_MAGIC_COMMENT_re: Pattern[bytes]

-PYTHON_FUTURE_IMPORT_re: Any
+def parse_encoding(fp: IO[bytes]) -> str | None: ...

-def parse_future_flags(fp, encoding: str = ...): ...
-def pathmatch(pattern, filename): ...
+PYTHON_FUTURE_IMPORT_re: Pattern[str]
+
+def parse_future_flags(fp: IO[bytes], encoding: str = ...) -> int: ...
+def pathmatch(pattern: str, filename: str) -> bool: ...

 class TextWrapper(textwrap.TextWrapper):
-    wordsep_re: Any
+    wordsep_re: Pattern[str]

 def wraptext(text, width: int = ..., initial_indent: str = ..., subsequent_indent: str = ...): ...

 odict = collections.OrderedDict

 class FixedOffsetTimezone(tzinfo):
-    zone: Any
-    def __init__(self, offset, name: Any | None = ...) -> None: ...
-    def utcoffset(self, dt): ...
-    def tzname(self, dt): ...
-    def dst(self, dt): ...
+    zone: str
+    def __init__(self, offset: float, name: str | None = ...) -> None: ...
+    def utcoffset(self, dt: Any) -> timedelta: ...
+    def tzname(self, dt: Any) -> str: ...
+    def dst(self, dt: Any) -> timedelta: ...

 UTC: BaseTzInfo
 LOCALTZ: BaseTzInfo
 get_localzone = localtime.get_localzone
-STDOFFSET: Any
-DSTOFFSET: Any
-DSTDIFF: Any
-ZERO: Any
+STDOFFSET: timedelta
+DSTOFFSET: timedelta
+DSTDIFF: timedelta
+ZERO: timedelta