vn-collate 0.1.0__tar.gz

vn_collate-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+node_modules/
+dist/
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editors / OS
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Build output of the conformance tooling
+.tmp/
+
+# Traction snapshots. Machine-generated history for scripts/track-traction.mjs,
+# not something to review in a diff.
+.traction/
+
+# LICENSE copies staged into each package at pack time by
+# scripts/stage-license.mjs. One canonical file at the repository root; these
+# are build output, and a staged one in a diff is a bug, not a licence update.
+packages/*/LICENSE
+packages/*/*/LICENSE

vn_collate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vn-toolkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vn_collate-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: vn-collate
+Version: 0.1.0
+Summary: Vietnamese collation sort keys, derived from ICU. Store the key in a binary column and ORDER BY it, because Postgres and MySQL have no Vietnamese collation. Standard library only.
+Project-URL: Homepage, https://github.com/leeloc1809/vn-toolkit
+Project-URL: Repository, https://github.com/leeloc1809/vn-toolkit
+Project-URL: Issues, https://github.com/leeloc1809/vn-toolkit/issues
+License: MIT
+License-File: LICENSE
+Keywords: collate,collation,i18n,icu,mysql,postgres,sort,sort-key,unicode,vietnam,vietnamese
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Vietnamese
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vn-collate
+
+Vietnamese collation sort keys, derived from ICU. **No runtime dependencies** —
+standard library only.
+
+```bash
+pip install vn-collate
+```
+
+```python
+from vn_collate import collate_key, compare, sort
+
+sort(['Đặng Minh', 'An Nguyễn', 'Bảo Châu', 'Lê Duẩn'])
+# ['An Nguyễn', 'Bảo Châu', 'Đặng Minh', 'Lê Duẩn']
+
+compare('Đặng', 'Dũng')   # 1   — Đ follows D, it does not fall through to the end
+compare('bao', 'Bảo')     # -1  — tone order is huyền hỏi ngã sắc nặng
+```
+
+## Why
+
+Postgres has no Vietnamese collation. MySQL's `utf8mb4_vietnamese_ci` exists,
+but it is one of a fixed set of orders the server ships, and whichever one you
+get depends on the server's version and configuration rather than on anything
+you can pin. The result is that a Vietnamese `ORDER BY` is either
+unreproducible between environments or not Vietnamese at all.
+
+This library takes the order out of the server's hands. It builds a **sort
+key** — a string whose byte order is the Vietnamese collation order — so you
+store the key once and the database only has to do byte comparison, which
+every database already does correctly.
+
+```sql
+-- Postgres
+CREATE TABLE people (
+  name    text,
+  sortkey bytea          -- or text COLLATE "C"
+);
+CREATE INDEX ON people (sortkey);
+
+INSERT INTO people VALUES ('Đặng Minh', decode(:key, 'hex'));
+SELECT name FROM people ORDER BY sortkey;   -- correct Vietnamese order
+```
+
+**The column has to be binary.** `ORDER BY key` on a `text` or `varchar` column
+re-sorts the key using the column's own collation rules and produces nonsense.
+This is the one way to use the library incorrectly, and it fails silently.
+
+## The order, and where it comes from
+
+| | |
+|---|---|
+| letters | `a ă â b c d đ e ê f g h i j k l m n o ô ơ p q r s t u ư v w x y z` |
+| tones | `none > huyền > hỏi > ngã > sắc > nặng` |
+| digits | before every letter, `0`–`9` in numeric order |
+| case | secondary to tone: `a A á Á` |
+| unknown | after everything, ordered deterministically |
+
+33 letters, not 29: ICU's `vi-VN` locale still collates `w` and `z` as letters
+in meaningful positions rather than dropping them in with the punctuation, so
+they are kept where ICU puts them. That is what makes "sorts like ICU" true
+rather than approximately true.
+
+**Every value in that table was read out of `Intl.Collator('vi-VN')`, not
+written from memory.** `scripts/generate-collation-conformance.mjs` probes the
+runtime and emits both the table and the conformance suite, which records the
+runtime it came from:
+
+```json
+"derivedFrom": "Intl.Collator('vi-VN') on win32/x64, ICU 75.1, Unicode 15.1"
+```
+
+If ICU ever changes the order, the next regeneration shows it as a diff landing
+in review — instead of a silent behaviour change shipping to users.
+
+## Why a sort key and not a comparison function
+
+A comparator answers one question. A sort key answers every question the
+database will ever be asked, including the ones you did not anticipate: range
+queries on names, exact lookup, `ORDER BY` on one or several key columns, and
+an index on any of them.
+
+A key is also the only formulation where a Python service and a Node service
+agree. Both ports emit byte-identical keys, checked on every push by
+`scripts/verify-collate-parity.mjs` across 445 strings — so a key written by one
+service sorts correctly against data written by the other.
+
+## Known limitations
+
+Stated precisely, because the boundaries are where this kind of library
+usually lies.
+
+**Punctuation and spaces sort after every letter, not before.** ICU sorts them
+first. This only changes the order of records that differ *only* in
+punctuation:
+
+```python
+sort(['Nguyen Van An', 'NguyenVanAn'])   # ours: NguyenVanAn, Nguyen Van An
+                                      #  ICU: Nguyen Van An, NguyenVanAn
+```
+
+A corpus that is internally consistent — every name punctuated the same way,
+which is the normal case — orders identically to ICU. Verified: six real
+multi-word Vietnamese names sort the same in both. A corpus that mixes
+`Nguyễn Văn An` with `NguyễnVănAn` does not, and ICU's answer is the more
+natural one. Handling this properly means ICU's variable weighting, which is a
+configuration axis rather than a fixed order; that is v1 work.
+
+**An unrecognised combining mark is dropped.** `ä` is `a` + U+0308, U+0308 is
+not a Vietnamese tone or letter modifier, so it contributes no weight and `ä`
+collates identically to `a`:
+
+```python
+collate_key('a') == collate_key('ä')   # True
+```
+
+This never happens for Vietnamese text. It is a real key collision for text
+that mixes in other languages, and it is deliberate — a guessed weight for an
+unknown mark would be wrong in a way that is much harder to notice.
+
+**Latin letters outside the Vietnamese set are in the fallback bucket.**
+`ç`, `ñ`, `š`, `ž` and friends sort after every letter rather than beside their
+base letter as ICU does. `ß` and `æ` are in the same bucket.
+
+**No numeric collation.** `a2 > a10`, matching ICU's default.
+
+## Validation
+
+519 cases in
+[`conformance/vn-collate-1.0.0.json`](../../conformance/vn-collate-1.0.0.json),
+generated from ICU rather than hand-authored, every one carrying the note
+explaining what breaks if you get it wrong. The TypeScript port reads the same
+file.
+
+The test file runs with or without pytest, because a library whose correctness
+guarantee depends on a test runner is a library you cannot check on a machine
+that has no test runner:
+
+```bash
+python packages/vn-collate-py/tests/test_vn_collate.py   # stdlib only
+pytest packages/vn-collate-py/tests -q                     # if you have it
+```
+
+## API parity
+
+```python
+collate_key(text) -> str
+compare(a, b) -> int            # -1, 0 or 1
+sort(items, key=None) -> list   # stable, does not mutate the input
+```
+
+`collateKey` is exported as an alias so a call site moves between the Python and
+TypeScript ports without renaming. The tables are exported as constants for
+callers who want to inspect or extend them.
+
+`compare` is defined in terms of `collate_key`, so the two can never disagree.
+
+## Licence
+
+MIT

vn_collate-0.1.0/README.md

@@ -0,0 +1,160 @@
+# vn-collate
+
+Vietnamese collation sort keys, derived from ICU. **No runtime dependencies** —
+standard library only.
+
+```bash
+pip install vn-collate
+```
+
+```python
+from vn_collate import collate_key, compare, sort
+
+sort(['Đặng Minh', 'An Nguyễn', 'Bảo Châu', 'Lê Duẩn'])
+# ['An Nguyễn', 'Bảo Châu', 'Đặng Minh', 'Lê Duẩn']
+
+compare('Đặng', 'Dũng')   # 1   — Đ follows D, it does not fall through to the end
+compare('bao', 'Bảo')     # -1  — tone order is huyền hỏi ngã sắc nặng
+```
+
+## Why
+
+Postgres has no Vietnamese collation. MySQL's `utf8mb4_vietnamese_ci` exists,
+but it is one of a fixed set of orders the server ships, and whichever one you
+get depends on the server's version and configuration rather than on anything
+you can pin. The result is that a Vietnamese `ORDER BY` is either
+unreproducible between environments or not Vietnamese at all.
+
+This library takes the order out of the server's hands. It builds a **sort
+key** — a string whose byte order is the Vietnamese collation order — so you
+store the key once and the database only has to do byte comparison, which
+every database already does correctly.
+
+```sql
+-- Postgres
+CREATE TABLE people (
+  name    text,
+  sortkey bytea          -- or text COLLATE "C"
+);
+CREATE INDEX ON people (sortkey);
+
+INSERT INTO people VALUES ('Đặng Minh', decode(:key, 'hex'));
+SELECT name FROM people ORDER BY sortkey;   -- correct Vietnamese order
+```
+
+**The column has to be binary.** `ORDER BY key` on a `text` or `varchar` column
+re-sorts the key using the column's own collation rules and produces nonsense.
+This is the one way to use the library incorrectly, and it fails silently.
+
+## The order, and where it comes from
+
+| | |
+|---|---|
+| letters | `a ă â b c d đ e ê f g h i j k l m n o ô ơ p q r s t u ư v w x y z` |
+| tones | `none > huyền > hỏi > ngã > sắc > nặng` |
+| digits | before every letter, `0`–`9` in numeric order |
+| case | secondary to tone: `a A á Á` |
+| unknown | after everything, ordered deterministically |
+
+33 letters, not 29: ICU's `vi-VN` locale still collates `w` and `z` as letters
+in meaningful positions rather than dropping them in with the punctuation, so
+they are kept where ICU puts them. That is what makes "sorts like ICU" true
+rather than approximately true.
+
+**Every value in that table was read out of `Intl.Collator('vi-VN')`, not
+written from memory.** `scripts/generate-collation-conformance.mjs` probes the
+runtime and emits both the table and the conformance suite, which records the
+runtime it came from:
+
+```json
+"derivedFrom": "Intl.Collator('vi-VN') on win32/x64, ICU 75.1, Unicode 15.1"
+```
+
+If ICU ever changes the order, the next regeneration shows it as a diff landing
+in review — instead of a silent behaviour change shipping to users.
+
+## Why a sort key and not a comparison function
+
+A comparator answers one question. A sort key answers every question the
+database will ever be asked, including the ones you did not anticipate: range
+queries on names, exact lookup, `ORDER BY` on one or several key columns, and
+an index on any of them.
+
+A key is also the only formulation where a Python service and a Node service
+agree. Both ports emit byte-identical keys, checked on every push by
+`scripts/verify-collate-parity.mjs` across 445 strings — so a key written by one
+service sorts correctly against data written by the other.
+
+## Known limitations
+
+Stated precisely, because the boundaries are where this kind of library
+usually lies.
+
+**Punctuation and spaces sort after every letter, not before.** ICU sorts them
+first. This only changes the order of records that differ *only* in
+punctuation:
+
+```python
+sort(['Nguyen Van An', 'NguyenVanAn'])   # ours: NguyenVanAn, Nguyen Van An
+                                      #  ICU: Nguyen Van An, NguyenVanAn
+```
+
+A corpus that is internally consistent — every name punctuated the same way,
+which is the normal case — orders identically to ICU. Verified: six real
+multi-word Vietnamese names sort the same in both. A corpus that mixes
+`Nguyễn Văn An` with `NguyễnVănAn` does not, and ICU's answer is the more
+natural one. Handling this properly means ICU's variable weighting, which is a
+configuration axis rather than a fixed order; that is v1 work.
+
+**An unrecognised combining mark is dropped.** `ä` is `a` + U+0308, U+0308 is
+not a Vietnamese tone or letter modifier, so it contributes no weight and `ä`
+collates identically to `a`:
+
+```python
+collate_key('a') == collate_key('ä')   # True
+```
+
+This never happens for Vietnamese text. It is a real key collision for text
+that mixes in other languages, and it is deliberate — a guessed weight for an
+unknown mark would be wrong in a way that is much harder to notice.
+
+**Latin letters outside the Vietnamese set are in the fallback bucket.**
+`ç`, `ñ`, `š`, `ž` and friends sort after every letter rather than beside their
+base letter as ICU does. `ß` and `æ` are in the same bucket.
+
+**No numeric collation.** `a2 > a10`, matching ICU's default.
+
+## Validation
+
+519 cases in
+[`conformance/vn-collate-1.0.0.json`](../../conformance/vn-collate-1.0.0.json),
+generated from ICU rather than hand-authored, every one carrying the note
+explaining what breaks if you get it wrong. The TypeScript port reads the same
+file.
+
+The test file runs with or without pytest, because a library whose correctness
+guarantee depends on a test runner is a library you cannot check on a machine
+that has no test runner:
+
+```bash
+python packages/vn-collate-py/tests/test_vn_collate.py   # stdlib only
+pytest packages/vn-collate-py/tests -q                     # if you have it
+```
+
+## API parity
+
+```python
+collate_key(text) -> str
+compare(a, b) -> int            # -1, 0 or 1
+sort(items, key=None) -> list   # stable, does not mutate the input
+```
+
+`collateKey` is exported as an alias so a call site moves between the Python and
+TypeScript ports without renaming. The tables are exported as constants for
+callers who want to inspect or extend them.
+
+`compare` is defined in terms of `collate_key`, so the two can never disagree.
+
+## Licence
+
+MIT

vn_collate-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vn-collate"
+version = "0.1.0"
+description = "Vietnamese collation sort keys, derived from ICU. Store the key in a binary column and ORDER BY it, because Postgres and MySQL have no Vietnamese collation. Standard library only."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+license-files = { paths = ["LICENSE"] }
+keywords = [
+  "vietnamese",
+  "collation",
+  "collate",
+  "sort",
+  "sort-key",
+  "unicode",
+  "icu",
+  "postgres",
+  "mysql",
+  "i18n",
+  "vietnam",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Natural Language :: Vietnamese",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Text Processing :: Linguistic",
+  "Typing :: Typed",
+]
+
+# Intentionally empty. A collation library that drags in dependencies is a
+# dependency every consumer has to audit, and this one has to stay auditable
+# itself.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/leeloc1809/vn-toolkit"
+Repository = "https://github.com/leeloc1809/vn-toolkit"
+Issues = "https://github.com/leeloc1809/vn-toolkit/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vn_collate"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/vn_collate", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vn_collate-0.1.0/src/vn_collate/__init__.py

@@ -0,0 +1,45 @@
+"""vn-collate — Vietnamese collation sort keys.
+
+Standard library only. Mirrors the TypeScript port function for function, and
+both are validated against the shared conformance suite in
+``conformance/vn-collate-1.0.0.json``.
+
+    >>> from vn_collate import collate_key, compare, sort
+    >>> sort(['Đặng', 'Anh', 'Bảo', 'bao'])
+    ['Anh', 'bao', 'Bảo', 'Đặng']
+"""
+
+from __future__ import annotations
+
+from .core import (
+    DIGIT_PRIMARY_BASE,
+    FALLBACK_PRIMARY,
+    LETTER_MODIFIERS,
+    LETTER_PRIMARY_BASE,
+    PRIMARY_ORDER,
+    TONE_MARKS,
+    TONE_ORDER,
+    collateKey,
+    collate_key,
+    compare,
+    sort,
+)
+from .weights import TERMINATOR
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "collate_key",
+    "compare",
+    "sort",
+    "collateKey",
+    "PRIMARY_ORDER",
+    "TONE_ORDER",
+    "LETTER_MODIFIERS",
+    "TONE_MARKS",
+    "TERMINATOR",
+    "FALLBACK_PRIMARY",
+    "DIGIT_PRIMARY_BASE",
+    "LETTER_PRIMARY_BASE",
+]

vn_collate-0.1.0/src/vn_collate/core.py

@@ -0,0 +1,187 @@
+"""Vietnamese collation: sort keys, comparison, sorting.
+
+Standard library only, deliberately. This has to be trustworthy, and it has to
+be the same answer in both ports, so it has as few moving parts as possible.
+
+Every function is validated against ``conformance/vn-collate-1.0.0.json``,
+which the TypeScript port also reads.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from typing import Callable, Iterable, Sequence, TypeVar
+
+from .weights import (
+    DIGITS,
+    DIGIT_PRIMARY_BASE,
+    FALLBACK_PRIMARY,
+    LETTER_MODIFIERS,
+    LETTER_PRIMARY_BASE,
+    PRIMARY_INDEX,
+    PRIMARY_ORDER,
+    TONE_MARKS,
+    TONE_ORDER,
+    TERMINATOR,
+)
+
+__all__ = [
+    "collate_key",
+    "compare",
+    "sort",
+    "collateKey",
+    "PRIMARY_ORDER",
+    "TONE_ORDER",
+    "LETTER_MODIFIERS",
+    "TONE_MARKS",
+    "FALLBACK_PRIMARY",
+    "DIGIT_PRIMARY_BASE",
+    "LETTER_PRIMARY_BASE",
+]
+
+T = TypeVar("T")
+
+
+def _clusters(text: str) -> list[str]:
+    """Split a string into one base character plus its combining marks.
+
+    This has to run on the NFD form. NFC does not guarantee that a combining
+    mark stays attached to its base -- ``B`` followed by U+0301 has no
+    precomposed form, so NFC leaves it as two code points, and walking that
+    string would treat the bare acute accent as a character of its own. NFD
+    always leaves marks trailing their base, so the grouping is unambiguous.
+    """
+    out: list[str] = []
+    for ch in unicodedata.normalize("NFD", text):
+        if out and unicodedata.combining(ch):
+            out[-1] += ch
+        else:
+            out.append(ch)
+    return out
+
+
+def _weights_for(cluster: str) -> tuple[int, int, int]:
+    base = ""
+    modifiers = ""
+    tone = 0
+
+    for mark in cluster:
+        if mark in TONE_MARKS:
+            weight = TONE_MARKS[mark]
+            # Deterministic when a character carries more than one tone mark:
+            # the heaviest wins. Documented rather than accidental.
+            if weight > tone:
+                tone = weight
+        elif mark in LETTER_MODIFIERS:
+            modifiers += mark
+        elif not base:
+            base = mark
+
+    # Recompose the base letter from its modifiers so ă, â, ê, ô, ơ and ư find
+    # their own primary instead of collapsing onto a, e, o or u.
+    letter = unicodedata.normalize("NFC", base + modifiers)
+
+    # The table is lowercase. Case belongs on the tertiary level, so look the
+    # letter up folded and record the case separately -- otherwise every
+    # capital lands in the fallback bucket and sorts after all the lowercase.
+    folded = letter.lower()
+
+    primary = PRIMARY_INDEX.get(folded)
+    if primary is None:
+        digit = DIGITS.find(folded)
+        primary = DIGIT_PRIMARY_BASE + digit if digit >= 0 else FALLBACK_PRIMARY
+
+    return primary, tone, 1 if letter != folded else 0
+
+
+def collate_key(text: str) -> str:
+    """Build a sort key for ``text``, as a hex string.
+
+    Why the key is emitted level by level
+    -------------------------------------
+    Interleaving the levels per character is the obvious encoding and it is
+    wrong. Comparing ``"ab"`` against ``"á"`` that way looks at the tone of the
+    second character before noticing that ``"á"`` has no second character, and
+    orders ``"ab"`` first. ICU orders ``"á"`` first, because a string that ends
+    earlier in the primary level sorts first. So the key is laid out primaries,
+    then secondaries, then tertiaries, each terminated -- the same shape the
+    Unicode Collation Algorithm uses.
+
+    Storing the key
+    ---------------
+    The key is **hex**, not raw bytes, so that both ports return the same type
+    and the value can live in a text column.
+
+    That does not mean you can sort it with the database's default collation.
+    ``ORDER BY key`` on a ``text``/``varchar`` column re-sorts the key with the
+    column's own rules and produces nonsense. It has to be a binary
+    comparison:
+
+    - Postgres: ``bytea``, or ``text COLLATE "C"``
+    - MySQL: ``varbinary``, or ``varchar`` with ``COLLATE utf8mb4_bin``
+
+    >>> collate_key('a') < collate_key('A')
+    True
+    >>> collate_key('Đặng') < collate_key('Dũng')
+    False
+    """
+    primary: list[int] = []
+    secondary: list[int] = []
+    tertiary: list[int] = []
+
+    for cluster in _clusters(text):
+        p, s, t = _weights_for(cluster)
+        primary.append(p)
+        secondary.append(s)
+        tertiary.append(t)
+
+    raw = (
+        primary + [TERMINATOR] + secondary + [TERMINATOR] + tertiary + [TERMINATOR]
+    )
+    return "".join(f"{b:02x}" for b in raw)
+
+
+def compare(a: str, b: str) -> int:
+    """Compare two strings the way ICU's Vietnamese collation does.
+
+    Defined as a comparison of their sort keys, so ``compare`` and
+    ``collate_key`` can never disagree with each other. Returns -1, 0 or 1.
+
+    >>> compare('Đặng', 'Dũng')
+    1
+    >>> compare('Thảo', 'Thao')
+    1
+    >>> compare('bao', 'Bảo')
+    -1
+    """
+    ka = collate_key(a)
+    kb = collate_key(b)
+    if ka == kb:
+        return 0
+    # Hex digits compare in value order under Python code point order, so a
+    # plain string comparison is a byte comparison.
+    return -1 if ka < kb else 1
+
+
+def sort(items: Iterable[T], key: Callable[[T], str] | None = None) -> list[T]:
+    """Sort a list of items by Vietnamese collation order.
+
+    Stable, and does not mutate the input. ``key`` defaults to treating each
+    item as a string, mirroring the TypeScript port.
+
+    >>> sort(['Đặng', 'Anh', 'Bảo', 'bao'])
+    ['Anh', 'bao', 'Bảo', 'Đặng']
+    """
+    key_fn: Callable[[T], str] = key if key is not None else (lambda x: x)  # type: ignore[assignment,arg-type]
+    indexed = [
+        (collate_key(key_fn(item)), index, item)
+        for index, item in enumerate(items)
+    ]
+    # Sort on the key and the original index only. Including the item would ask
+    # Python to compare items of a type that may not be orderable.
+    indexed.sort(key=lambda entry: (entry[0], entry[1]))
+    return [item for _, _, item in indexed]
+
+
+#: API-parity aliases, so call sites move between the ports without renaming.
+collateKey = collate_key

vn_collate-0.1.0/src/vn_collate/weights.py

@@ -0,0 +1,72 @@
+"""Collation weights for Vietnamese, derived from ICU.
+
+Do not hand-edit this table. Every value was read out of ICU by
+``scripts/generate-collation-conformance.mjs`` and pinned by the 519 cases in
+``conformance/vn-collate-1.0.0.json``. The suite records the exact runtime it
+came from, so a future ICU change surfaces as a failing test rather than as a
+silent behaviour change.
+"""
+
+from __future__ import annotations
+
+#: Primary weights, in ICU order. 33 letters.
+#:
+#: The first 29 are the Vietnamese alphabet in its official order. The last four
+#: are w, x, y, z: x and y are Vietnamese, but w and z are not -- they appear
+#: because ICU's vi-VN locale still collates them as letters in meaningful
+#: positions instead of dropping them into the fallback bucket alongside
+#: punctuation. Keeping them where ICU puts them is what makes "sorts like ICU"
+#: true rather than approximately true.
+PRIMARY_ORDER: tuple[str, ...] = (
+    "a", "ă", "â", "b", "c", "d", "đ", "e", "ê",
+    "f", "g", "h", "i", "j", "k", "l", "m", "n",
+    "o", "ô", "ơ", "p", "q", "r", "s", "t", "u",
+    "ư", "v", "w", "x", "y", "z",
+)
+
+#: Tone weights. Uniform across every base letter, confirmed by probing all 33.
+TONE_ORDER: tuple[str, ...] = ("none", "huyền", "hỏi", "ngã", "sắc", "nặng")
+
+
+def cp(code_point: int) -> str:
+    """Return the character for a code point.
+
+    Combining marks are written as code points, never as literal characters.
+    They are invisible in an editor, and a stray reformat can silently corrupt
+    a lookup table that still compiles.
+    """
+    return chr(code_point)
+
+
+#: Marks that modify the base letter rather than carrying tone.
+LETTER_MODIFIERS: frozenset[str] = frozenset(
+    {cp(0x0302), cp(0x0306), cp(0x031B)}  # circumflex, breve, horn
+)
+
+#: Marks that carry tone, mapped to their weight in TONE_ORDER.
+TONE_MARKS: dict[str, int] = {
+    cp(0x0300): 1,  # huyền
+    cp(0x0309): 2,  # hỏi
+    cp(0x0303): 3,  # ngã
+    cp(0x0301): 4,  # sắc
+    cp(0x0323): 5,  # nặng
+}
+
+#: Primary byte layout.
+#:
+#:     0x01..0x0A   digits 0-9, which ICU sorts before every letter
+#:     0x0B..0x2B   the 33 letters above
+#:     0xFE         anything else
+#:
+#: 0x00 is reserved as the level terminator, so no weight may be zero.
+DIGIT_PRIMARY_BASE = 0x01
+LETTER_PRIMARY_BASE = 0x0B
+FALLBACK_PRIMARY = 0xFE
+
+DIGITS = "0123456789"
+
+PRIMARY_INDEX: dict[str, int] = {
+    letter: LETTER_PRIMARY_BASE + i for i, letter in enumerate(PRIMARY_ORDER)
+}
+
+TERMINATOR = 0x00

vn_collate-0.1.0/tests/test_vn_collate.py

@@ -0,0 +1,202 @@
+"""Run the shared collation conformance suite against the Python port.
+
+Runnable two ways, on purpose:
+
+    pytest packages/vn-collate-py/tests -q
+    python packages/vn-collate-py/tests/test_vn_collate.py
+
+The second form needs nothing installed. The conformance suite is the contract
+between the two ports, and being able to check it with nothing but a Python
+interpreter is what stops them drifting apart.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import unicodedata
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from vn_collate import (  # noqa: E402  (path set up above)
+    PRIMARY_ORDER,
+    TONE_ORDER,
+    collate_key,
+    compare,
+    sort,
+)
+
+CONFORMANCE_PATH = (
+    Path(__file__).resolve().parents[3] / "conformance" / "vn-collate-1.0.0.json"
+)
+
+
+def load_suite() -> dict[str, Any]:
+    with CONFORMANCE_PATH.open(encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+SUITE = load_suite()
+CASES = SUITE["cases"]
+
+
+def test_schema_is_understood() -> None:
+    assert SUITE["schema"] == "vn-collate-conformance/1", SUITE["schema"]
+
+
+def test_package_ships_a_py_typed_marker() -> None:
+    # The package declares "Typing :: Typed" on the PyPI page. Without this
+    # marker a type checker ignores every annotation in the module, so the claim
+    # is false and a consumer running mypy gets "untyped import" from a library
+    # that is annotated throughout.
+    import vn_collate
+
+    marker = Path(vn_collate.__file__).resolve().parent / "py.typed"
+    assert marker.exists(), (
+        f"{marker} is missing. The wheel must contain it, or drop the "
+        f"Typing :: Typed classifier instead of advertising types it hides."
+    )
+
+
+def test_suite_records_its_provenance() -> None:
+    # If a future ICU disagrees, this string is how you find out what moved.
+    assert "ICU " in SUITE["derivedFrom"], SUITE["derivedFrom"]
+
+
+def test_case_ids_are_unique() -> None:
+    ids = [c["id"] for c in CASES]
+    assert len(set(ids)) == len(ids), "duplicate case ids in conformance file"
+
+
+def test_suite_pins_both_directions_and_reflexivity() -> None:
+    expected = {c["expected"] for c in CASES}
+    assert expected == {-1, 0, 1}, f"suite cannot reject a constant comparator: {expected}"
+
+
+def test_table_matches_the_suite() -> None:
+    assert list(PRIMARY_ORDER) == SUITE["primaryOrder"]
+    assert list(TONE_ORDER) == SUITE["toneOrder"]
+
+
+def test_conformance_suite() -> None:
+    failures: list[str] = []
+    for case in CASES:
+        actual = compare(case["a"], case["b"])
+        if actual != case["expected"]:
+            failures.append(
+                f"{case['id']}  compare({case['a']!r}, {case['b']!r})\n"
+                f"    expected: {case['expected']}\n"
+                f"    actual:   {actual}\n"
+                f"    note:     {case.get('note', '')}"
+            )
+    assert not failures, f"{len(failures)} conformance failures:\n" + "\n".join(failures[:10])
+
+
+# --- Invariants ---------------------------------------------------------------
+
+
+def test_compare_agrees_with_comparing_the_keys() -> None:
+    for a, b in [
+        ("a", "A"),
+        ("a", "á"),
+        ("Đặng", "Dũng"),
+        ("1", "An"),
+        ("ab", "á"),
+        ("", "a"),
+    ]:
+        ka, kb = collate_key(a), collate_key(b)
+        expected = 0 if ka == kb else (-1 if ka < kb else 1)
+        assert compare(a, b) == expected, f"{a!r} vs {b!r}"
+
+
+def test_antisymmetric() -> None:
+    words = ["a", "A", "á", "Á", "à", "b", "đ", "Đ", "Thảo", "Thao", "1", ""]
+    for a in words:
+        for b in words:
+            assert compare(a, b) + compare(b, a) == 0, f"{a!r} vs {b!r}"
+
+
+def test_prefix_sorts_before_its_extension() -> None:
+    # The case that breaks per-character interleaved keys.
+    assert compare("á", "ab") == -1
+    assert compare("a", "ab") == -1
+
+
+def test_nfc_and_nfd_input_collate_identically() -> None:
+    # The last two have no precomposed form at all, so NFD is their only
+    # spelling and cluster splitting cannot be avoided. The combining mark is
+    # written as a code point because a literal one is invisible in an editor,
+    # and an invisible mark in a test about cluster splitting is precisely the
+    # bug the test exists to catch.
+    cases = [
+        "Đặng",
+        "Thảo",
+        "đường",
+        "Ăn",
+        "B" + chr(0x0301),
+        "b" + chr(0x0303) + chr(0x031B),
+    ]
+    for s in cases:
+        assert compare(s, unicodedata.normalize("NFD", s)) == 0, s
+        assert collate_key(s) == collate_key(unicodedata.normalize("NFD", s)), s
+
+
+def test_digits_sort_before_every_letter() -> None:
+    for digit in "0123456789":
+        for letter in PRIMARY_ORDER:
+            assert compare(digit, letter) == -1, f"{digit} vs {letter}"
+
+
+def test_unknown_characters_sort_last_deterministically() -> None:
+    assert compare("z", "☃") == -1
+    assert compare("☃", "☃") == 0
+
+
+def test_key_is_hex_only() -> None:
+    # Hex only, so the key is safe in a text column with binary collation.
+    key = collate_key("Đặng Thảo 1")
+    assert all(c in "0123456789abcdef" for c in key), key
+
+
+def test_sort_is_stable_and_does_not_mutate() -> None:
+    original = ["b", "B", "b", "B"]
+    snapshot = list(original)
+    out = sort(original)
+    assert original == snapshot, "sort mutated its input"
+    # b sorts before B, and the two of each keep their input order.
+    assert out == ["b", "b", "B", "B"], out
+    # An already-sorted list comes back unchanged.
+    already = ["a", "A", "á", "Á"]
+    assert sort(already) == already, already
+
+
+def test_sort_accepts_a_key_function() -> None:
+    people = [{"n": "Đặng"}, {"n": "Anh"}, {"n": "Bảo"}]
+    assert [p["n"] for p in sort(people, key=lambda p: p["n"])] == ["Anh", "Bảo", "Đặng"]
+
+
+def _run_standalone() -> int:
+    tests = [
+        (name, obj)
+        for name, obj in sorted(globals().items())
+        if name.startswith("test_") and callable(obj)
+    ]
+    failed = 0
+    for name, fn in tests:
+        try:
+            fn()
+        except AssertionError as exc:
+            failed += 1
+            print(f"FAIL {name}\n{exc}\n")
+        else:
+            print(f"ok   {name}")
+    print()
+    print(f"{len(tests) - failed}/{len(tests)} test functions passed")
+    print(f"{len(CASES)} conformance cases across {len(SUITE['primaryOrder'])} letters")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_run_standalone())