python-intl 0.5.0__tar.gz → 0.7.1__tar.gz

{python_intl-0.5.0 → python_intl-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-intl
-Version: 0.5.0
+Version: 0.7.1
 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
@@ -86,6 +85,36 @@ formatter.format_range(datetime, datetime_till)
 | `DateTimeFormat.formatRangeToParts` | ✅     | `DateTimeFormat.format_range_to_parts` |
 | `DateTimeFormat.resolvedOptions`    | ❌     |                                        |
 
+### `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 |
+| ------------------ | :----: | ----------- |
+| `Collator.compare` | ✅     |             |
+
+**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:

{python_intl-0.5.0 → python_intl-0.7.1}/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
@@ -73,6 +72,36 @@ formatter.format_range(datetime, datetime_till)
 | `DateTimeFormat.formatRangeToParts` | ✅     | `DateTimeFormat.format_range_to_parts` |
 | `DateTimeFormat.resolvedOptions`    | ❌     |                                        |
 
+### `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 |
+| ------------------ | :----: | ----------- |
+| `Collator.compare` | ✅     |             |
+
+**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:

{python_intl-0.5.0 → python_intl-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-intl"
-version = "0.5.0"
+version = "0.7.1"
 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.5.0 → python_intl-0.7.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-intl"
-version = "0.5.0"
+version = "0.7.1"
 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.5.0 → python_intl-0.7.1}/python_intl/__init__.py

@@ -1,3 +1,7 @@
+from .collator import (
+    Collator as Collator,
+    CollatorOptions as CollatorOptions,
+)
 from .datetimeformat import (
     DateTimeFormat as DateTimeFormat,
     DateTimeFormatOptions as DateTimeFormatOptions,

python_intl-0.7.1/python_intl/_types.py

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

python_intl-0.7.1/python_intl/collator.py

@@ -0,0 +1,142 @@
+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, overload
+
+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)]
+
+    @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.5.0 → python_intl-0.7.1}/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
 
@@ -136,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)
@@ -340,10 +345,7 @@ class DateTimeIntervalPatternPart:
         return {
             "type": _COMPONENT_TO_JSON_MAP.get(self.type, self.type),
             "value": self.value,
-            "source": {
-                "start_range": "startRange",
-                "end_range": "endRange",
-            }.get(self.source, self.source),
+            "source": _SOURCE_TO_JSON_MAP.get(self.source, self.source),
         }
 
 
@@ -402,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)