python-intl 0.6.0__tar.gz → 0.8.0__tar.gz

{python_intl-0.6.0 → python_intl-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-intl
-Version: 0.6.0
+Version: 0.8.0
 Summary: Python implementation of the Intl JavaScript API
 Author: David Danier
 Author-email: David Danier <david.danier@gmail.com>
@@ -54,6 +54,23 @@ Intl.DateTimeFormatOptions(time_zone_name="short_offset").to_json()
 
 ## Available `Intl` classes
 
+### `Intl.Locale`
+
+#### Example usage
+
+```python
+import datetime as dt
+import python_intl as Intl
+
+locale = Intl.DateTimeFormat("de-DE")
+```
+
+#### Compatibility
+
+`Locale` currently does not support any methods or options. It is mainly there to
+allow using the locale class instead of a string with the other classes. There will
+be more later.
+
 ### `Intl.DateTimeFormat`
 
 #### Example usage
@@ -87,6 +104,20 @@ formatter.format_range(datetime, datetime_till)
 
 ### `Intl.Collator`
 
+#### Example usage
+
+```python
+import python_intl as Intl
+
+collator = Intl.Collator("de-DE", {"numeric": True})
+collator.compare("10", "9")
+# Result = 1, which means 9 comes before 10
+
+# You can also use sorted, although this is not available in JavaScript
+collator.sorted(["10", "9"])
+# Result = ['9', '10']
+```
+
 #### Compatibility
 
 | Method             | Status | Python name |
@@ -95,6 +126,12 @@ formatter.format_range(datetime, datetime_till)
 
 **Note:** Not all options are currently supported.
 
+#### Additional methods
+
+* `Collator.sorted`: Somewhat like `sorted`, but uses the collator for comparison. If you want
+  to sort complex datastructures you can provide a `key` parameter (like with `sorted`) to
+  get a comparable string value (for example by returning an attribute).
+
 ## Installation
 
 Be sure to be able to install `PyICU`, see the installation docs there:
@@ -105,3 +142,13 @@ setting `PKG_CONFIG_PATH` accordingly helps most of the time I guess.
 
 When this is done you should be able to install `python-intl` using any package
 manager, like `pip install python-intl` or `uv add python-intl`.
+
+## Contributing
+
+If you want to contribute to this project, feel free to just fork the project,
+create a dev branch in your fork and then create a pull request (PR). If you
+are unsure about whether your changes really suits the project please create an
+issue first, to talk about this.
+
+Please do not contribute AI generated code unless we explicitly talked about
+this and agreed upon doing so first. In general I do not want AI contributions.

{python_intl-0.6.0 → python_intl-0.8.0}/README.md

@@ -41,6 +41,23 @@ Intl.DateTimeFormatOptions(time_zone_name="short_offset").to_json()
 
 ## Available `Intl` classes
 
+### `Intl.Locale`
+
+#### Example usage
+
+```python
+import datetime as dt
+import python_intl as Intl
+
+locale = Intl.DateTimeFormat("de-DE")
+```
+
+#### Compatibility
+
+`Locale` currently does not support any methods or options. It is mainly there to
+allow using the locale class instead of a string with the other classes. There will
+be more later.
+
 ### `Intl.DateTimeFormat`
 
 #### Example usage
@@ -74,6 +91,20 @@ formatter.format_range(datetime, datetime_till)
 
 ### `Intl.Collator`
 
+#### Example usage
+
+```python
+import python_intl as Intl
+
+collator = Intl.Collator("de-DE", {"numeric": True})
+collator.compare("10", "9")
+# Result = 1, which means 9 comes before 10
+
+# You can also use sorted, although this is not available in JavaScript
+collator.sorted(["10", "9"])
+# Result = ['9', '10']
+```
+
 #### Compatibility
 
 | Method             | Status | Python name |
@@ -82,6 +113,12 @@ formatter.format_range(datetime, datetime_till)
 
 **Note:** Not all options are currently supported.
 
+#### Additional methods
+
+* `Collator.sorted`: Somewhat like `sorted`, but uses the collator for comparison. If you want
+  to sort complex datastructures you can provide a `key` parameter (like with `sorted`) to
+  get a comparable string value (for example by returning an attribute).
+
 ## Installation
 
 Be sure to be able to install `PyICU`, see the installation docs there:
@@ -92,3 +129,13 @@ setting `PKG_CONFIG_PATH` accordingly helps most of the time I guess.
 
 When this is done you should be able to install `python-intl` using any package
 manager, like `pip install python-intl` or `uv add python-intl`.
+
+## Contributing
+
+If you want to contribute to this project, feel free to just fork the project,
+create a dev branch in your fork and then create a pull request (PR). If you
+are unsure about whether your changes really suits the project please create an
+issue first, to talk about this.
+
+Please do not contribute AI generated code unless we explicitly talked about
+this and agreed upon doing so first. In general I do not want AI contributions.

{python_intl-0.6.0 → python_intl-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-intl"
-version = "0.6.0"
+version = "0.8.0"
 description = "Python implementation of the Intl JavaScript API"
 readme = "README.md"
 license = "MIT"
@@ -35,7 +35,6 @@ markers = [
 
 [tool.ruff]
 line-length = 115
-target-version = "py312"
 output-format = "grouped"
 
 [tool.ruff.lint]
@@ -69,6 +68,7 @@ ignore = [
     "B008",
     "F405",
     "F821",
+    "TD003",
 ]
 
 [tool.ruff.lint.per-file-ignores]
@@ -88,6 +88,9 @@ ignore = [
 combine-as-imports = true
 force-wrap-aliases = true
 
+[tool.pyright]
+pythonVersion = "3.12"
+
 [tool.uv.build-backend]
 module-name = "python_intl"
 module-root = ""

{python_intl-0.6.0 → python_intl-0.8.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-intl"
-version = "0.6.0"
+version = "0.8.0"
 description = "Python implementation of the Intl JavaScript API"
 readme = "README.md"
 authors = [
@@ -36,12 +36,11 @@ markers = [
 
 [tool.ruff]
 line-length = 115
-target-version = "py312"
 output-format = "grouped"
 
 [tool.ruff.lint]
 select = ["F","E","W","C","I","N","UP","ANN","S","B","A","COM","C4","T20","PT","ARG","TD","RUF"]
-ignore = ["A001","A002","A003","ANN401","C901","N8","B008","F405","F821"]
+ignore = ["A001","A002","A003","ANN401","C901","N8","B008","F405","F821","TD003"]
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
@@ -52,6 +51,9 @@ ignore = ["A001","A002","A003","ANN401","C901","N8","B008","F405","F821"]
 combine-as-imports = true
 force-wrap-aliases = true
 
+[tool.pyright]
+pythonVersion = "3.12"
+
 [build-system]
 requires = ["uv_build>=0.12.3,<0.13.0"]
 build-backend = "uv_build"

python_intl-0.8.0/python_intl/_types.py

@@ -0,0 +1,34 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Literal
+
+    type LocaleMatcherT = Literal["best fit", "lookup"]
+    type Hour12T = bool
+    type HourCycleT = Literal["h11", "h12", "h23", "h24"]
+
+    type EraFormatT = Literal["long", "short", "narrow"]
+    type YearFormatT = Literal["numeric", "2-digit"]
+    type MonthFormatT = Literal["numeric", "2-digit", "long", "short", "narrow"]
+    type WeekdayFormatT = Literal["long", "short", "narrow"]
+    type DayFormatT = Literal["numeric", "2-digit"]
+    type DayPeriodFormatT = Literal["long", "short", "narrow"]
+    type HourFormatT = Literal["numeric", "2-digit"]
+    type MinuteFormatT = Literal["numeric", "2-digit"]
+    type SecondFormatT = Literal["numeric", "2-digit"]
+    type FractionSecondDigitsFormatT = Literal[1, 2, 3]
+    type TimezoneNameFormatT = Literal[
+        "short",
+        "long",
+        "short_offset",
+        "long_offset",
+        "short_generic",
+        "long_generic",
+    ]
+
+    # type UsageT = Literal["sort", "search"]
+    # type CollationT = Literal["emoji", "pinyin", "stroke"]
+    type CaseFirstT = Literal["upper", "lower", "false"]
+    type SensitivityT = Literal["base", "accent", "case", "variant"]
+
+    type ComparisonResultT = Literal[-1, 0, 1]

{python_intl-0.6.0 → python_intl-0.8.0}/python_intl/collator.py

@@ -1,24 +1,19 @@
 from __future__ import annotations
 
 import dataclasses
+import functools
+from collections.abc import Callable, Iterable
 from functools import cached_property
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, overload
 
 import icu  # type: ignore[import-untyped]
 
-if TYPE_CHECKING:
-    from typing import NotRequired, TypedDict
-
+from .locale import Locale
 
 if TYPE_CHECKING:
-    from ._types import LocaleMatcherT
-
-    # type UsageT = Literal["sort", "search"]
-    # type CollationT = Literal["emoji", "pinyin", "stroke"]
-    type CaseFirstT = Literal["upper", "lower", "false"]
-    type SensitivityT = Literal["base", "accent", "case", "variant"]
+    from typing import NotRequired, TypedDict
 
-    type ComparisonResultT = Literal[-1, 0, 1]
+    from ._types import CaseFirstT, ComparisonResultT, LocaleMatcherT, SensitivityT
 
     # Important: Must be the same as CollatorOptions
     # (nothing is required, as this will be used to construct a
@@ -67,15 +62,18 @@ _COLLATOR_RESULT_TO_RESULT: dict[icu.UCollationResult, ComparisonResultT] = {  #
 
 
 class Collator:
-    locale: str
+    locale: Locale
     options: CollatorOptions
 
     def __init__(
         self,
-        locale: str,
+        locale: Locale | str,
         options: CollatorOptions | CollatorOptionsDictT | None = None,
     ) -> None:
-        self.locale = locale
+        if isinstance(locale, Locale):
+            self.locale = locale
+        else:
+            self.locale = Locale(locale)
         if options is None:
             self.options = CollatorOptions()
         elif isinstance(options, CollatorOptions):
@@ -83,13 +81,9 @@ class Collator:
         else:
             self.options = CollatorOptions(**options)
 
-    @cached_property
-    def _icu_locale(self) -> icu.Locale:  # ty: ignore[unresolved-attribute]
-        return icu.Locale(self.locale)  # ty: ignore[unresolved-attribute]
-
     @cached_property
     def _icu_collator(self) -> icu.Collator:  # ty: ignore[unresolved-attribute]
-        collator = icu.Collator.createInstance(self._icu_locale)  # ty: ignore[unresolved-attribute]
+        collator = icu.Collator.createInstance(self.locale._icu_locale)  # ty: ignore[unresolved-attribute]
 
         if self.options.numeric:
             collator.setAttribute(icu.UCollAttribute.NUMERIC_COLLATION, icu.UCollAttributeValue.ON)  # ty: ignore[unresolved-attribute]
@@ -98,7 +92,7 @@ class Collator:
             self.options.ignore_punctuation
             or (
                 self.options.ignore_punctuation is None
-                and self._icu_locale.getLanguage() == "th"
+                and self.locale._icu_locale.getLanguage() == "th"
             )
         ):
             collator.setAttribute(icu.UCollAttribute.ALTERNATE_HANDLING, icu.UCollAttributeValue.SHIFTED)  # ty: ignore[unresolved-attribute]
@@ -124,3 +118,17 @@ class Collator:
 
     def compare(self, string_a: str, string_b: str) -> ComparisonResultT:
         return _COLLATOR_RESULT_TO_RESULT[self._icu_collator.compare(string_a, string_b)]
+
+    @overload
+    def sorted(self, items: Iterable[str], /, key: None = None) -> Iterable[str]: ...
+    @overload
+    def sorted[T](self, items: Iterable[T], /, key: Callable[[T], str]) -> Iterable[T]: ...
+    def sorted(self, items, /, key = None):
+        return sorted(
+            items,
+            key=functools.cmp_to_key(
+                (lambda a, b: self.compare(key(a), key(b)))
+                if key
+                else self.compare,
+            ),
+        )

{python_intl-0.6.0 → python_intl-0.8.0}/python_intl/datetimeformat.py

@@ -7,50 +7,30 @@ from typing import TYPE_CHECKING, Literal
 
 import icu  # type: ignore[import-untyped]
 
+from .locale import Locale
+
 if TYPE_CHECKING:
     from collections.abc import Iterable
     from typing import NotRequired, TypedDict
 
-
-if TYPE_CHECKING:
-    from ._types import LocaleMatcherT
-
-    type Hour12T = bool | None
-    type HourCycleT = Literal["h11", "h12", "h23", "h24"] | None
-
-    type EraFormatT = Literal["long", "short", "narrow"]
-    type YearFormatT = Literal["numeric", "2-digit"]
-    type MonthFormatT = Literal["numeric", "2-digit", "long", "short", "narrow"]
-    type WeekdayFormatT = Literal["long", "short", "narrow"]
-    type DayFormatT = Literal["numeric", "2-digit"]
-    type DayPeriodFormatT = Literal["long", "short", "narrow"]
-    type HourFormatT = Literal["numeric", "2-digit"]
-    type MinuteFormatT = Literal["numeric", "2-digit"]
-    type SecondFormatT = Literal["numeric", "2-digit"]
-    type FractionSecondDigitsFormatT = Literal[1, 2, 3]
-    type TimezoneNameFormatT = Literal[
-        "short",
-        "long",
-        "short_offset",
-        "long_offset",
-        "short_generic",
-        "long_generic",
-    ]
-    type AnyFormatT = (
-        EraFormatT
-        | YearFormatT
-        | MonthFormatT
-        | WeekdayFormatT
-        | DayFormatT
-        | DayPeriodFormatT
-        | HourFormatT
-        | MinuteFormatT
-        | SecondFormatT
-        | FractionSecondDigitsFormatT
-        | TimezoneNameFormatT
+    from ._types import (
+        DayFormatT,
+        DayPeriodFormatT,
+        EraFormatT,
+        FractionSecondDigitsFormatT,
+        Hour12T,
+        HourCycleT,
+        HourFormatT,
+        LocaleMatcherT,
+        MinuteFormatT,
+        MonthFormatT,
+        SecondFormatT,
+        TimezoneNameFormatT,
+        WeekdayFormatT,
+        YearFormatT,
     )
 
-    type PatternPartTypeT = Literal[
+    type DatetimePatternPartTypeT = Literal[
         "literal", "unknown",
         "era", "year", "month", "weekday", "day", "day_period",
         "hour", "minute", "second", "fraction_second_digits",
@@ -78,7 +58,7 @@ if TYPE_CHECKING:
         time_zone_name: NotRequired[TimezoneNameFormatT]
 
 _PATTERN_SYMBOLS = "GyYuUrQqMLqQdDFgEecabBhHkKmsSAzZOvVxX"  # includes unused
-_PATTERN_SYMBOL_TO_TYPE: dict[str, PatternPartTypeT] = {
+_PATTERN_SYMBOL_TO_TYPE: dict[str, DatetimePatternPartTypeT] = {
     "G": "era",
     "y": "year",
     "Y": "year",
@@ -92,6 +72,7 @@ _PATTERN_SYMBOL_TO_TYPE: dict[str, PatternPartTypeT] = {
     "d": "day",
     "a": "day_period",
     "b": "day_period",
+    "B": "day_period",
     "C": "day_period",
     "h": "hour",
     "H": "hour",
@@ -108,13 +89,19 @@ _PATTERN_SYMBOL_TO_TYPE: dict[str, PatternPartTypeT] = {
     "x": "time_zone_name",
     "X": "time_zone_name",
 }
-_PATTERN_FIELD_TO_TYPE: dict[icu.UDateTimePatternField, PatternPartTypeT] = {  # ty: ignore[unresolved-attribute]
+_PATTERN_FIELD_TO_TYPE: dict[icu.UDateTimePatternField, DatetimePatternPartTypeT] = {  # ty: ignore[unresolved-attribute]
     icu.DateFormat.ERA_FIELD: "era",  # ty: ignore[unresolved-attribute]
     icu.DateFormat.YEAR_FIELD: "year",  # ty: ignore[unresolved-attribute]
     icu.DateFormat.MONTH_FIELD: "month",  # ty: ignore[unresolved-attribute]
     icu.DateFormat.DAY_OF_WEEK_FIELD: "weekday",  # ty: ignore[unresolved-attribute]
     icu.DateFormat.DATE_FIELD: "day",  # ty: ignore[unresolved-attribute]
     icu.DateFormat.AM_PM_FIELD: "day_period",  # ty: ignore[unresolved-attribute]
+    # TODO(ddanier): Use this instead once PyICU has those values in the enum:
+    # https://gitlab.pyicu.org/main/pyicu/-/work_items/180
+    # icu.DateFormat.AM_PM_MIDNIGHT_NOON_FIELD: "day_period",
+    # icu.DateFormat.FLEXIBLE_DAY_PERIOD_FIELD: "day_period",
+    35: "day_period",
+    36: "day_period",
     icu.DateFormat.HOUR0_FIELD: "hour",  # ty: ignore[unresolved-attribute]
     icu.DateFormat.HOUR1_FIELD: "hour",  # ty: ignore[unresolved-attribute]
     icu.DateFormat.HOUR_OF_DAY0_FIELD: "hour",  # ty: ignore[unresolved-attribute]
@@ -146,8 +133,8 @@ _SOURCE_TO_JSON_MAP: dict[str, str] = {
 @dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
 class DateTimeFormatOptions:
     locale_matcher: LocaleMatcherT = "best fit"
-    hour12: Hour12T = None
-    hour_cycle: HourCycleT = None
+    hour12: Hour12T | None = None
+    hour_cycle: HourCycleT | None = None
 
     era: EraFormatT | None = None
     year: YearFormatT | None = None
@@ -165,6 +152,10 @@ class DateTimeFormatOptions:
         return {
             k: v
             for k, v in (
+                ("localeMatcher", self.locale_matcher),
+                ("hour12", self.hour12),
+                ("hourCycle", self.hour_cycle),
+
                 ("era", self.era),
                 ("year", self.year),
                 ("month", self.month),
@@ -323,7 +314,7 @@ class FormatPatternNotFoundException(Exception):
 
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class DateTimePatternPart:
-    type: PatternPartTypeT
+    type: DatetimePatternPartTypeT
     value: str
     _pattern: str | None = None
 
@@ -337,7 +328,7 @@ class DateTimePatternPart:
 
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class DateTimeIntervalPatternPart:
-    type: PatternPartTypeT
+    type: DatetimePatternPartTypeT
     value: str
     source: Literal["start_range", "end_range", "shared"]
 
@@ -398,15 +389,18 @@ class _PartSpan:
 
 
 class DateTimeFormat:
-    locale: str
+    locale: Locale
     options: DateTimeFormatOptions
 
     def __init__(
         self,
-        locale: str,
+        locale: Locale | str,
         options: DateTimeFormatOptions | DateTimeFormatOptionsDictT | None = None,
     ) -> None:
-        self.locale = locale
+        if isinstance(locale, Locale):
+            self.locale = locale
+        else:
+            self.locale = Locale(locale)
         if options is None:
             self.options = DateTimeFormatOptions()
         elif isinstance(options, DateTimeFormatOptions):
@@ -414,13 +408,9 @@ class DateTimeFormat:
         else:
             self.options = DateTimeFormatOptions(**options)
 
-    @cached_property
-    def _icu_locale(self) -> icu.Locale:  # ty: ignore[unresolved-attribute]
-        return icu.Locale(self.locale)  # ty: ignore[unresolved-attribute]
-
     @cached_property
     def _matched_pattern(self) -> _MatchedFormatPattern:
-        return _options_to_format_pattern(self._icu_locale, self.options)
+        return _options_to_format_pattern(self.locale._icu_locale, self.options)
 
     @cached_property
     def _icu_pattern(self) -> str:
@@ -428,7 +418,7 @@ class DateTimeFormat:
 
     @cached_property
     def _icu_date_format(self) -> icu.SimpleDateFormat:  # ty: ignore[unresolved-attribute]
-        return icu.SimpleDateFormat(self._icu_pattern, self._icu_locale)  # ty: ignore[unresolved-attribute]
+        return icu.SimpleDateFormat(self._icu_pattern, self.locale._icu_locale)  # ty: ignore[unresolved-attribute]
 
     def format(self, datetime_: dt.datetime, /) -> str:
         return self._icu_date_format.format(datetime_)
@@ -448,7 +438,7 @@ class DateTimeFormat:
             if char != prev_char and count > 0:
                 yield DateTimePatternPart(
                     type=_PATTERN_SYMBOL_TO_TYPE.get(prev_char, "unknown"),
-                    value=icu.SimpleDateFormat(prev_char * count, self._icu_locale).format(datetime_),  # ty: ignore[unresolved-attribute]
+                    value=icu.SimpleDateFormat(prev_char * count, self.locale._icu_locale).format(datetime_),  # ty: ignore[unresolved-attribute]
                     _pattern=prev_char * count,
                 )
                 count = 0
@@ -476,7 +466,7 @@ class DateTimeFormat:
         if count > 0:
             yield DateTimePatternPart(
                 type=_PATTERN_SYMBOL_TO_TYPE.get(prev_char, "unknown"),
-                value=icu.SimpleDateFormat(prev_char * count, self._icu_locale).format(datetime_),  # ty: ignore[unresolved-attribute]
+                value=icu.SimpleDateFormat(prev_char * count, self.locale._icu_locale).format(datetime_),  # ty: ignore[unresolved-attribute]
                 _pattern=prev_char * count,
             )
             assert not literal_chars  # noqa: S101
@@ -489,7 +479,7 @@ class DateTimeFormat:
     @cached_property
     def _icu_dateinterval_format(self) -> icu.DateIntervalFormat:  # ty: ignore[unresolved-attribute]
         possible_skeletons = list(_options_to_possible_skeletons(self.options))
-        return icu.DateIntervalFormat.createInstance(possible_skeletons[0], self._icu_locale)  # ty: ignore[unresolved-attribute]
+        return icu.DateIntervalFormat.createInstance(possible_skeletons[0], self.locale._icu_locale)  # ty: ignore[unresolved-attribute]
 
     def format_range(
         self,

python_intl-0.8.0/python_intl/locale.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from functools import cached_property
+
+import icu  # type: ignore[import-untyped]
+
+
+class Locale:
+    tag: str
+
+    def __init__(self, tag: str) -> None:
+        self.tag = tag
+
+    @cached_property
+    def _icu_locale(self) -> icu.Locale:  # ty: ignore[unresolved-attribute]
+        return icu.Locale(self.tag)  # ty: ignore[unresolved-attribute]

python_intl-0.6.0/python_intl/_types.py

@@ -1,3 +0,0 @@
-from typing import Literal
-
-type LocaleMatcherT = Literal["best fit", "lookup"]