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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-intl
-Version: 0.4.0
+Version: 0.6.0
 Summary: Python implementation of the Intl JavaScript API
 Author: David Danier
 Author-email: David Danier <david.danier@gmail.com>
@@ -18,8 +18,7 @@ API similar to what the [`Intl` JavaScript API](https://developer.mozilla.org/en
 provides. It is not meant to fully behave the same, but instead be close enough so
 the "same" code works on JavaScript and Python, with similar results.
 
-**Status:** This is very much work in progress. Currently only `Intl.DateTimeFormat`
-exists and this also is not complete yet.
+**Status:** This is very much work in progress.
 
 **Note:** There are a lot of tests running the Python implementation against the
 JavaScript one and comparing the results. In general things should be pretty
@@ -63,23 +62,38 @@ Intl.DateTimeFormatOptions(time_zone_name="short_offset").to_json()
 import datetime as dt
 import python_intl as Intl
 
+# Format a datetime
 datetime = dt.datetime(2026, 8, 15)
 formatter = Intl.DateTimeFormat("de-DE", {"year": "numeric", "month": "2-digit", "day": "2-digit"})
-formatter.format(datetime)  # Will output the German format: "15.08.2026"
+formatter.format(datetime)
+# Result = "15.08.2026"
+
+# Format a datetime range
 datetime_till = dt.datetime(2026, 9, 7)
-formatter.format_range(datetime, datetime_till)  # Will output the German format: "15.08. – 07.09.2026"
+formatter.format_range(datetime, datetime_till)
+# Result = "15.08. – 07.09.2026"
 ```
 
 #### Compatibility
 
-| Method                              | Status | Python name                      |
-| ----------------------------------- | :----: | -------------------------------- |
-| `DateTimeFormat.format`             | ✅     |                                  |
-| `DateTimeFormat.formatToParts`      | ✅     | `DateTimeFormat.format_to_parts` |
-| `DateTimeFormat.supportedLocalesOf` | ❌     |                                  |
-| `DateTimeFormat.formatRange`        | ✅     | `DateTimeFormat.format_range`    |
-| `DateTimeFormat.formatRangeToParts` | ❌     |                                  |
-| `DateTimeFormat.resolvedOptions`    | ❌     |                                  |
+| Method                              | Status | Python name                            |
+| ----------------------------------- | :----: | -------------------------------------- |
+| `DateTimeFormat.format`             | ✅     |                                        |
+| `DateTimeFormat.formatToParts`      | ✅     | `DateTimeFormat.format_to_parts`       |
+| `DateTimeFormat.supportedLocalesOf` | ❌     |                                        |
+| `DateTimeFormat.formatRange`        | ✅     | `DateTimeFormat.format_range`          |
+| `DateTimeFormat.formatRangeToParts` | ✅     | `DateTimeFormat.format_range_to_parts` |
+| `DateTimeFormat.resolvedOptions`    | ❌     |                                        |
+
+### `Intl.Collator`
+
+#### Compatibility
+
+| Method             | Status | Python name |
+| ------------------ | :----: | ----------- |
+| `Collator.compare` | ✅     |             |
+
+**Note:** Not all options are currently supported.
 
 ## Installation
 

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

@@ -5,8 +5,7 @@ API similar to what the [`Intl` JavaScript API](https://developer.mozilla.org/en
 provides. It is not meant to fully behave the same, but instead be close enough so
 the "same" code works on JavaScript and Python, with similar results.
 
-**Status:** This is very much work in progress. Currently only `Intl.DateTimeFormat`
-exists and this also is not complete yet.
+**Status:** This is very much work in progress.
 
 **Note:** There are a lot of tests running the Python implementation against the
 JavaScript one and comparing the results. In general things should be pretty
@@ -50,23 +49,38 @@ Intl.DateTimeFormatOptions(time_zone_name="short_offset").to_json()
 import datetime as dt
 import python_intl as Intl
 
+# Format a datetime
 datetime = dt.datetime(2026, 8, 15)
 formatter = Intl.DateTimeFormat("de-DE", {"year": "numeric", "month": "2-digit", "day": "2-digit"})
-formatter.format(datetime)  # Will output the German format: "15.08.2026"
+formatter.format(datetime)
+# Result = "15.08.2026"
+
+# Format a datetime range
 datetime_till = dt.datetime(2026, 9, 7)
-formatter.format_range(datetime, datetime_till)  # Will output the German format: "15.08. – 07.09.2026"
+formatter.format_range(datetime, datetime_till)
+# Result = "15.08. – 07.09.2026"
 ```
 
 #### Compatibility
 
-| Method                              | Status | Python name                      |
-| ----------------------------------- | :----: | -------------------------------- |
-| `DateTimeFormat.format`             | ✅     |                                  |
-| `DateTimeFormat.formatToParts`      | ✅     | `DateTimeFormat.format_to_parts` |
-| `DateTimeFormat.supportedLocalesOf` | ❌     |                                  |
-| `DateTimeFormat.formatRange`        | ✅     | `DateTimeFormat.format_range`    |
-| `DateTimeFormat.formatRangeToParts` | ❌     |                                  |
-| `DateTimeFormat.resolvedOptions`    | ❌     |                                  |
+| Method                              | Status | Python name                            |
+| ----------------------------------- | :----: | -------------------------------------- |
+| `DateTimeFormat.format`             | ✅     |                                        |
+| `DateTimeFormat.formatToParts`      | ✅     | `DateTimeFormat.format_to_parts`       |
+| `DateTimeFormat.supportedLocalesOf` | ❌     |                                        |
+| `DateTimeFormat.formatRange`        | ✅     | `DateTimeFormat.format_range`          |
+| `DateTimeFormat.formatRangeToParts` | ✅     | `DateTimeFormat.format_range_to_parts` |
+| `DateTimeFormat.resolvedOptions`    | ❌     |                                        |
+
+### `Intl.Collator`
+
+#### Compatibility
+
+| Method             | Status | Python name |
+| ------------------ | :----: | ----------- |
+| `Collator.compare` | ✅     |             |
+
+**Note:** Not all options are currently supported.
 
 ## Installation
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "python-intl"
-version = "0.4.0"
+version = "0.6.0"
 description = "Python implementation of the Intl JavaScript API"
 readme = "README.md"
 license = "MIT"
@@ -21,13 +21,17 @@ dev = [
     "pyright>=1.1.411",
     "pytest>=9.1.1",
     "pytest-cov>=7.1.0",
+    "pytest-xdist>=3.8.0",
     "ruff>=0.16.3",
     "tox>=4.60.0",
     "ty>=0.0.72",
 ]
 
 [tool.pytest.ini_options]
-markers = ["unit: mark a test as a unit test"]
+markers = [
+    "unit: mark a test as a unit test",
+    "node: mark tests jun against the node/JS implementation",
+]
 
 [tool.ruff]
 line-length = 115

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

@@ -1,6 +1,6 @@
 [project]
 name = "python-intl"
-version = "0.4.0"
+version = "0.6.0"
 description = "Python implementation of the Intl JavaScript API"
 readme = "README.md"
 authors = [
@@ -22,6 +22,7 @@ dev = [
     "pyright>=1.1.411",
     "pytest>=9.1.1",
     "pytest-cov>=7.1.0",
+    "pytest-xdist>=3.8.0",
     "ruff>=0.16.3",
     "tox>=4.60.0",
     "ty>=0.0.72",
@@ -30,6 +31,7 @@ dev = [
 [tool.pytest.ini_options]
 markers = [
     "unit: mark a test as a unit test",
+    "node: mark tests jun against the node/JS implementation",
 ]
 
 [tool.ruff]

{python_intl-0.4.0 → python_intl-0.6.0}/python_intl/__init__.py

@@ -1,6 +1,11 @@
+from .collator import (
+    Collator as Collator,
+    CollatorOptions as CollatorOptions,
+)
 from .datetimeformat import (
     DateTimeFormat as DateTimeFormat,
     DateTimeFormatOptions as DateTimeFormatOptions,
+    DateTimeIntervalPatternPart as DateTimeIntervalPatternPart,
     DateTimePatternPart as DateTimePatternPart,
     FormatPatternNotFoundException as FormatPatternNotFoundException,
 )

python_intl-0.6.0/python_intl/_types.py

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

python_intl-0.6.0/python_intl/collator.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import dataclasses
+from functools import cached_property
+from typing import TYPE_CHECKING, Literal
+
+import icu  # type: ignore[import-untyped]
+
+if TYPE_CHECKING:
+    from typing import NotRequired, TypedDict
+
+
+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"]
+
+    type ComparisonResultT = Literal[-1, 0, 1]
+
+    # Important: Must be the same as CollatorOptions
+    # (nothing is required, as this will be used to construct a
+    # CollatorOptions instance, so default values apply then)
+    class CollatorOptionsDictT(TypedDict):
+        locale_matcher: NotRequired[LocaleMatcherT]
+        # usage: NotRequired[UsageT | None]
+        # collation: NotRequired[CollationT | None]
+        numeric: NotRequired[bool]
+        case_first: NotRequired[CaseFirstT]
+        sensitivity: NotRequired[SensitivityT]
+        ignore_punctuation: NotRequired[bool | None]
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class CollatorOptions:
+    locale_matcher: LocaleMatcherT = "best fit"
+    # usage: UsageT | None = None
+    # collation: CollationT | None = None
+    numeric: bool = False
+    case_first: CaseFirstT = "false"
+    sensitivity: SensitivityT = "variant"
+    ignore_punctuation: bool | None = None
+
+    def to_json(self) -> dict[str, str | int]:
+        return {
+            k: v
+            for k, v in (
+                ("localeMatcher", self.locale_matcher),
+                # ("usage", self.usage),
+                # ("collation", self.collation),
+                ("numeric", self.numeric),
+                ("caseFirst", self.case_first),
+                ("sensitivity", self.sensitivity),
+                ("ignorePunctuation", self.ignore_punctuation),
+            )
+            if v is not None
+        }
+
+
+_COLLATOR_RESULT_TO_RESULT: dict[icu.UCollationResult, ComparisonResultT] = {  # ty: ignore[unresolved-attribute]
+    icu.UCollationResult.LESS: -1,  # ty: ignore[unresolved-attribute]
+    icu.UCollationResult.EQUAL: 0,  # ty: ignore[unresolved-attribute]
+    icu.UCollationResult.GREATER: 1,  # ty: ignore[unresolved-attribute]
+}
+
+
+class Collator:
+    locale: str
+    options: CollatorOptions
+
+    def __init__(
+        self,
+        locale: str,
+        options: CollatorOptions | CollatorOptionsDictT | None = None,
+    ) -> None:
+        self.locale = locale
+        if options is None:
+            self.options = CollatorOptions()
+        elif isinstance(options, CollatorOptions):
+            self.options = options
+        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]
+
+        if self.options.numeric:
+            collator.setAttribute(icu.UCollAttribute.NUMERIC_COLLATION, icu.UCollAttributeValue.ON)  # ty: ignore[unresolved-attribute]
+
+        if (
+            self.options.ignore_punctuation
+            or (
+                self.options.ignore_punctuation is None
+                and self._icu_locale.getLanguage() == "th"
+            )
+        ):
+            collator.setAttribute(icu.UCollAttribute.ALTERNATE_HANDLING, icu.UCollAttributeValue.SHIFTED)  # ty: ignore[unresolved-attribute]
+
+        match self.options.case_first:
+            case "upper":
+                collator.setAttribute(icu.UCollAttribute.CASE_FIRST, icu.UCollAttributeValue.UPPER_FIRST)  # ty: ignore[unresolved-attribute]
+            case "lower":
+                collator.setAttribute(icu.UCollAttribute.CASE_FIRST, icu.UCollAttributeValue.LOWER_FIRST)  # ty: ignore[unresolved-attribute]
+
+        collator.setAttribute(icu.UCollAttribute.NORMALIZATION_MODE, icu.UCollAttributeValue.ON)  # ty: ignore[unresolved-attribute]
+        match self.options.sensitivity:
+            case "base":
+                collator.setAttribute(icu.UCollAttribute.STRENGTH, icu.UCollAttributeValue.PRIMARY)  # ty: ignore[unresolved-attribute]
+            case "accent":
+                collator.setAttribute(icu.UCollAttribute.STRENGTH, icu.UCollAttributeValue.SECONDARY)  # ty: ignore[unresolved-attribute]
+            case "case":
+                collator.setAttribute(icu.UCollAttribute.STRENGTH, icu.UCollAttributeValue.TERTIARY)  # ty: ignore[unresolved-attribute]
+            case "variant":
+                collator.setAttribute(icu.UCollAttribute.STRENGTH, icu.UCollAttributeValue.QUATERNARY)  # ty: ignore[unresolved-attribute]
+
+        return collator
+
+    def compare(self, string_a: str, string_b: str) -> ComparisonResultT:
+        return _COLLATOR_RESULT_TO_RESULT[self._icu_collator.compare(string_a, string_b)]

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

@@ -13,7 +13,8 @@ if TYPE_CHECKING:
 
 
 if TYPE_CHECKING:
-    type LocaleMatcherT = Literal["best fit", "lookup"]
+    from ._types import LocaleMatcherT
+
     type Hour12T = bool | None
     type HourCycleT = Literal["h11", "h12", "h23", "h24"] | None
 
@@ -107,6 +108,22 @@ _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]
+    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]
+    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]
+    icu.DateFormat.HOUR_OF_DAY1_FIELD: "hour",  # ty: ignore[unresolved-attribute]
+    icu.DateFormat.MINUTE_FIELD: "minute",  # ty: ignore[unresolved-attribute]
+    icu.DateFormat.SECOND_FIELD: "second",  # ty: ignore[unresolved-attribute]
+    icu.DateFormat.MILLISECOND_FIELD: "fraction_second_digits",  # ty: ignore[unresolved-attribute]
+    icu.DateFormat.TIMEZONE_FIELD: "time_zone_name",  # ty: ignore[unresolved-attribute]
+}
 _PATTERN_QUOTE = "'"
 
 _COMPONENT_TO_JSON_MAP: dict[str, str] = {
@@ -120,6 +137,10 @@ _TIMEZONE_NAME_TO_JSON_MAP: dict[str | None, str] = {
     "short_generic": "shortGeneric",
     "long_generic": "longGeneric",
 }
+_SOURCE_TO_JSON_MAP: dict[str, str] = {
+    "start_range": "startRange",
+    "end_range": "endRange",
+}
 
 
 @dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
@@ -314,6 +335,20 @@ class DateTimePatternPart:
         }
 
 
+@dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
+class DateTimeIntervalPatternPart:
+    type: PatternPartTypeT
+    value: str
+    source: Literal["start_range", "end_range", "shared"]
+
+    def to_json(self) -> dict[str, str]:
+        return {
+            "type": _COMPONENT_TO_JSON_MAP.get(self.type, self.type),
+            "value": self.value,
+            "source": _SOURCE_TO_JSON_MAP.get(self.source, self.source),
+        }
+
+
 @cache
 def _options_to_format_pattern(
     locale: icu.Locale,  # ty: ignore[unresolved-attribute]
@@ -345,6 +380,23 @@ def _options_to_format_pattern(
     raise FormatPatternNotFoundException("Didn't find pattern for desired options")
 
 
+@dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
+class _PartSpan:
+    start: int
+    end: int
+
+    @classmethod
+    def empty(cls) -> _PartSpan:
+        return cls(start=0, end=0)
+
+    @classmethod
+    def from_constrained_fieldposition(cls, position: icu.ConstrainedFieldPosition) -> _PartSpan:  # ty: ignore[unresolved-attribute]
+        return cls(start=position.getStart(), end=position.getLimit())
+
+    def __contains__(self, inner: _PartSpan) -> bool:
+        return inner.start >= self.start and inner.end <= self.end
+
+
 class DateTimeFormat:
     locale: str
     options: DateTimeFormatOptions
@@ -352,10 +404,12 @@ class DateTimeFormat:
     def __init__(
         self,
         locale: str,
-        options: DateTimeFormatOptions | DateTimeFormatOptionsDictT,
+        options: DateTimeFormatOptions | DateTimeFormatOptionsDictT | None = None,
     ) -> None:
         self.locale = locale
-        if isinstance(options, DateTimeFormatOptions):
+        if options is None:
+            self.options = DateTimeFormatOptions()
+        elif isinstance(options, DateTimeFormatOptions):
             self.options = options
         else:
             self.options = DateTimeFormatOptions(**options)
@@ -437,6 +491,66 @@ class DateTimeFormat:
         possible_skeletons = list(_options_to_possible_skeletons(self.options))
         return icu.DateIntervalFormat.createInstance(possible_skeletons[0], self._icu_locale)  # ty: ignore[unresolved-attribute]
 
-    def format_range(self, start_datetime: dt.datetime, end_datetime: dt.datetime) -> str:
+    def format_range(
+        self,
+        start_datetime: dt.datetime,
+        end_datetime: dt.datetime,
+    ) -> str:
         icu_date_interval = icu.DateInterval(start_datetime, end_datetime)  # ty: ignore[unresolved-attribute]
         return self._icu_dateinterval_format.format(icu_date_interval)
+
+    def format_range_to_parts(
+        self,
+        start_datetime: dt.datetime,
+        end_datetime: dt.datetime,
+    ) -> Iterable[DateTimeIntervalPatternPart]:
+        icu_date_interval = icu.DateInterval(start_datetime, end_datetime)  # ty: ignore[unresolved-attribute]
+        formatted = self._icu_dateinterval_format.formatToValue(icu_date_interval)
+
+        # Find spans of both datetimes (used to determine which parts have which source)
+        span_start = _PartSpan.empty()
+        span_end = _PartSpan.empty()
+        for part in formatted:
+            if part.getCategory() == icu.UFieldCategory.DATE_INTERVAL_SPAN:  # ty: ignore[unresolved-attribute]
+                match part.getField():
+                    case 0:
+                        span_start = _PartSpan.from_constrained_fieldposition(part)
+                    case 1:
+                        span_end = _PartSpan.from_constrained_fieldposition(part)
+
+        def source_of(span: _PartSpan) -> Literal["start_range", "end_range", "shared"]:
+            if span in span_start:
+                return "start_range"
+            elif span in span_end:
+                return "end_range"
+            else:
+                return "shared"
+
+        # Break result string into parts
+        result_string = str(formatted)
+        last_end = 0
+        for part in formatted:
+            span = _PartSpan.from_constrained_fieldposition(part)
+            if span.start > last_end:
+                yield DateTimeIntervalPatternPart(
+                    type="literal",
+                    value=result_string[last_end:span.start],
+                    source=source_of(_PartSpan(start=last_end, end=span.start)),
+                )
+
+            if part.getCategory() == icu.UFieldCategory.DATE:  # ty: ignore[unresolved-attribute]
+                yield DateTimeIntervalPatternPart(
+                    type=_PATTERN_FIELD_TO_TYPE.get(part.getField(), "unknown"),
+                    value=result_string[span.start:span.end],
+                    source=source_of(span),
+                )
+
+            last_end = span.end
+
+        # Ensure we didn't miss anything at the end
+        if last_end < len(result_string):
+            yield DateTimeIntervalPatternPart(
+                type="literal",
+                value=result_string[last_end:],
+                source=source_of(_PartSpan(start=last_end, end=len(result_string))),
+            )