vn-ident 0.1.0__tar.gz

vn_ident-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_ident-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_ident-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: vn-ident
+Version: 0.1.0
+Summary: Vietnamese tax codes, mobile numbers and card numbers, validated against the sources that define them. A tax code has a check digit; a card number does not, and this says so. 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: carrier,cccd,i18n,id-card,mst,phone,tax-code,validation,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 :: Software Development :: Localization
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vn-ident
+
+Vietnamese tax codes, mobile numbers and card numbers — validated against the
+sources that define them, not against a regex somebody liked. Standard library
+only, zero runtime dependencies.
+
+```bash
+pip install vn-ident
+```
+
+```python
+from vn_ident import is_valid_mst, mst_check_digit, normalize_phone, detect_carrier, parse_cccd, classify_id
+
+is_valid_mst("0100047516")       # True  — the tenth digit is computed, not matched
+mst_check_digit("010004751")     # 6     — the worked example in the circular
+mst_check_digit("000000000")     # None  — and None is the interesting part
+
+normalize_phone("+84912345678")  # '0912345678'
+detect_carrier("0987654321")     # 'viettel'
+detect_carrier("0953456780")     # None  — a valid number that belongs to nobody
+
+parse_cccd("001087123456")       # CardNumber(province_code='001', province='Hà Nội',
+                                 #   century=20, gender='male', birth_year=1987, …)
+classify_id("0912345678")        # 'phone'
+```
+
+The TypeScript port is [`@vntoolkit/vn-ident`](https://www.npmjs.com/package/@vntoolkit/vn-ident)
+and the two are held to the same
+[conformance suite](../../conformance/vn-ident-1.0.0.json) — 258 cases, read by
+both. That suite is the contract; this package is one implementation of it.
+
+## The thing to read first
+
+**A tax code has a check digit. A card number does not.**
+
+A tax code's tenth digit is computed from the first nine, so `is_valid_mst` tells
+you the code is *right*. A card number's last six digits are random, so there is
+nothing to verify: `is_valid_cccd` is a **format check and nothing more** —
+twelve digits, a province code that exists, a fourth digit that is defined. It
+cannot detect a number that is well-formed and wrong, and it will not pretend to.
+
+It also cannot tell you which generation of card it is. The old unchipped
+12-digit number and the current chip number have the same structure, and the 2025
+reduction to 34 provincial units did not renumber any card issued before it.
+`classify_id` returning `"cccd"` does not mean a chip card.
+
+## The zero remainder
+
+Ten minus zero is ten, which is not a digit, so the circular skips that sequence
+number rather than assigning a check digit. That is why the function is typed
+`int | None` and not `int`:
+
+```python
+mst_check_digit("000000000")   # None
+mst_check_digit("000000007")   # 0
+```
+
+A naive implementation returns `10` there and then compares it against a
+character. It rejects valid codes and never says why. No tax code whose first
+nine digits sum to a multiple of 11 can be valid — and one that claims to be is
+not.
+
+## The weights are not a progression
+
+`31 29 23 19 17 13 7 5 3` is transcribed from Thông tư 105/2020/TT-BTC, Phụ
+lục 1, and pinned in the suite. That is the reason the parity check generates ten
+thousand tax codes rather than trusting the hand-picked cases: a transposed pair
+of weights still produces a well-formed digit for every code, so nothing
+downstream would ever notice.
+
+```text
+ident parity: 673311/673311 operations identical across both ports
+```
+
+Six port breakages are introduced on purpose to prove the check catches them —
+two transposed weights, the divisible-by-11 case, the Bắc Giang `023`/`024` typo
+that one of the four published province tables actually carries, two swapped
+carrier prefixes, the trunk-zero inference, and a `\d` widened to Unicode:
+
+```bash
+node scripts/prove-ident-parity-fails.mjs
+# 6/6 real port breakages were caught
+```
+
+## Errors are values, not exceptions
+
+Every function returns `False` or `None` on bad input, and every one accepts
+anything at runtime. A validator that crashes on the wrong type has turned a
+validation error into a 500, and form posts and JSON bodies do not respect your
+type hints:
+
+```python
+is_valid_mst(None)        # False
+parse_cccd(12345)         # None
+classify_id({"a": 1})    # 'unknown'
+```
+
+The one exception is `mst_check_digit`, which raises `TypeError` on a prefix that
+is not nine digits. That is a programming error in the caller rather than bad
+user data, and it should not be a `None` you discover three lines later.
+
+## Reading an amount out of a card number
+
+The fourth digit is the century and the sex in one character, so the two year
+digits alone are ambiguous and it is what settles them:
+
+```python
+parse_cccd("001085123456").birth_year   # 1985
+parse_cccd("001285123456").birth_year   # 2085
+```
+
+A year in the future parses, deliberately: with no check digit nothing can detect
+it, and a date-dependent `valid` would make the conformance suite change its own
+answer over time.
+
+## Known limitations
+
+- **No card number verification is possible.** No check digit exists.
+- **No province lookup for a tax code.** `region_code` comes from the tax
+  authority's catalogue, not the card-number table, and this package does not
+  carry a join between the two.
+- **`detect_carrier` does not normalise.** `detect_carrier("+84912345678")` is
+  `None`. Call `normalize_phone` first.
+- **`is_valid_cmnd` is a shape test.** Nine digits, no structure, no check digit.
+  It accepts `000000000`, which was never issued to anyone.
+- **Non-ASCII digits are refused everywhere.** Both ports agree on that, and the
+  proof script checks that they do.
+
+## Licence
+
+MIT

vn_ident-0.1.0/README.md

@@ -0,0 +1,131 @@
+# vn-ident
+
+Vietnamese tax codes, mobile numbers and card numbers — validated against the
+sources that define them, not against a regex somebody liked. Standard library
+only, zero runtime dependencies.
+
+```bash
+pip install vn-ident
+```
+
+```python
+from vn_ident import is_valid_mst, mst_check_digit, normalize_phone, detect_carrier, parse_cccd, classify_id
+
+is_valid_mst("0100047516")       # True  — the tenth digit is computed, not matched
+mst_check_digit("010004751")     # 6     — the worked example in the circular
+mst_check_digit("000000000")     # None  — and None is the interesting part
+
+normalize_phone("+84912345678")  # '0912345678'
+detect_carrier("0987654321")     # 'viettel'
+detect_carrier("0953456780")     # None  — a valid number that belongs to nobody
+
+parse_cccd("001087123456")       # CardNumber(province_code='001', province='Hà Nội',
+                                 #   century=20, gender='male', birth_year=1987, …)
+classify_id("0912345678")        # 'phone'
+```
+
+The TypeScript port is [`@vntoolkit/vn-ident`](https://www.npmjs.com/package/@vntoolkit/vn-ident)
+and the two are held to the same
+[conformance suite](../../conformance/vn-ident-1.0.0.json) — 258 cases, read by
+both. That suite is the contract; this package is one implementation of it.
+
+## The thing to read first
+
+**A tax code has a check digit. A card number does not.**
+
+A tax code's tenth digit is computed from the first nine, so `is_valid_mst` tells
+you the code is *right*. A card number's last six digits are random, so there is
+nothing to verify: `is_valid_cccd` is a **format check and nothing more** —
+twelve digits, a province code that exists, a fourth digit that is defined. It
+cannot detect a number that is well-formed and wrong, and it will not pretend to.
+
+It also cannot tell you which generation of card it is. The old unchipped
+12-digit number and the current chip number have the same structure, and the 2025
+reduction to 34 provincial units did not renumber any card issued before it.
+`classify_id` returning `"cccd"` does not mean a chip card.
+
+## The zero remainder
+
+Ten minus zero is ten, which is not a digit, so the circular skips that sequence
+number rather than assigning a check digit. That is why the function is typed
+`int | None` and not `int`:
+
+```python
+mst_check_digit("000000000")   # None
+mst_check_digit("000000007")   # 0
+```
+
+A naive implementation returns `10` there and then compares it against a
+character. It rejects valid codes and never says why. No tax code whose first
+nine digits sum to a multiple of 11 can be valid — and one that claims to be is
+not.
+
+## The weights are not a progression
+
+`31 29 23 19 17 13 7 5 3` is transcribed from Thông tư 105/2020/TT-BTC, Phụ
+lục 1, and pinned in the suite. That is the reason the parity check generates ten
+thousand tax codes rather than trusting the hand-picked cases: a transposed pair
+of weights still produces a well-formed digit for every code, so nothing
+downstream would ever notice.
+
+```text
+ident parity: 673311/673311 operations identical across both ports
+```
+
+Six port breakages are introduced on purpose to prove the check catches them —
+two transposed weights, the divisible-by-11 case, the Bắc Giang `023`/`024` typo
+that one of the four published province tables actually carries, two swapped
+carrier prefixes, the trunk-zero inference, and a `\d` widened to Unicode:
+
+```bash
+node scripts/prove-ident-parity-fails.mjs
+# 6/6 real port breakages were caught
+```
+
+## Errors are values, not exceptions
+
+Every function returns `False` or `None` on bad input, and every one accepts
+anything at runtime. A validator that crashes on the wrong type has turned a
+validation error into a 500, and form posts and JSON bodies do not respect your
+type hints:
+
+```python
+is_valid_mst(None)        # False
+parse_cccd(12345)         # None
+classify_id({"a": 1})    # 'unknown'
+```
+
+The one exception is `mst_check_digit`, which raises `TypeError` on a prefix that
+is not nine digits. That is a programming error in the caller rather than bad
+user data, and it should not be a `None` you discover three lines later.
+
+## Reading an amount out of a card number
+
+The fourth digit is the century and the sex in one character, so the two year
+digits alone are ambiguous and it is what settles them:
+
+```python
+parse_cccd("001085123456").birth_year   # 1985
+parse_cccd("001285123456").birth_year   # 2085
+```
+
+A year in the future parses, deliberately: with no check digit nothing can detect
+it, and a date-dependent `valid` would make the conformance suite change its own
+answer over time.
+
+## Known limitations
+
+- **No card number verification is possible.** No check digit exists.
+- **No province lookup for a tax code.** `region_code` comes from the tax
+  authority's catalogue, not the card-number table, and this package does not
+  carry a join between the two.
+- **`detect_carrier` does not normalise.** `detect_carrier("+84912345678")` is
+  `None`. Call `normalize_phone` first.
+- **`is_valid_cmnd` is a shape test.** Nine digits, no structure, no check digit.
+  It accepts `000000000`, which was never issued to anyone.
+- **Non-ASCII digits are refused everywhere.** Both ports agree on that, and the
+  proof script checks that they do.
+
+## Licence
+
+MIT

vn_ident-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vn-ident"
+version = "0.1.0"
+description = "Vietnamese tax codes, mobile numbers and card numbers, validated against the sources that define them. A tax code has a check digit; a card number does not, and this says so. Standard library only."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+license-files = { paths = ["LICENSE"] }
+keywords = [
+  "vietnamese",
+  "tax-code",
+  "mst",
+  "phone",
+  "carrier",
+  "id-card",
+  "cccd",
+  "validation",
+  "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 :: Software Development :: Localization",
+  "Typing :: Typed",
+]
+
+# Intentionally empty. A validation 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_ident"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/vn_ident", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vn_ident-0.1.0/src/vn_ident/__init__.py

@@ -0,0 +1,73 @@
+"""Vietnamese tax codes, mobile numbers and card numbers.
+
+Standard library only, and a conformance suite shared with the TypeScript port
+at conformance/vn-ident-1.0.0.json.
+
+The one thing to read before using it: a tax code has a check digit and this
+can tell you it is right. A card number does not, and this cannot. Both facts
+are stated in the code, in the suite and in the README, because a validation
+library that overstates what it checks is worse than one that checks less.
+"""
+
+from __future__ import annotations
+
+from vn_ident.identity import (
+    CardNumber,
+    IdentifierKind,
+    classify_id,
+    is_valid_cccd,
+    is_valid_cmnd,
+    parse_cccd,
+)
+from vn_ident.mst import TaxCode, is_valid_mst, mst_check_digit, parse_mst
+from vn_ident.phone import detect_carrier, is_valid_phone, normalize_phone
+from vn_ident.tables import (
+    ASSIGNED_PREFIX_COUNT,
+    CARRIERS,
+    CENTURY_GENDER,
+    MST_MODULUS,
+    MST_WEIGHTS,
+    PROVINCES,
+    Carrier,
+    Gender,
+    carrier_of_prefix,
+    century_of,
+    gender_of,
+    is_province_code,
+    province_name,
+)
+
+__all__ = [
+    "ASSIGNED_PREFIX_COUNT",
+    "CARRIERS",
+    "CARRIER_NAMES",
+    "CENTURY_GENDER",
+    "MST_MODULUS",
+    "MST_WEIGHTS",
+    "PROVINCES",
+    "CardNumber",
+    "Carrier",
+    "Gender",
+    "IdentifierKind",
+    "TaxCode",
+    "carrier_of_prefix",
+    "century_of",
+    "classify_id",
+    "detect_carrier",
+    "gender_of",
+    "is_province_code",
+    "is_valid_cccd",
+    "is_valid_cmnd",
+    "is_valid_mst",
+    "is_valid_phone",
+    "mst_check_digit",
+    "normalize_phone",
+    "parse_cccd",
+    "parse_mst",
+    "province_name",
+]
+
+__version__ = "0.1.0"
+
+#: The five carrier names, in the order the table lists them.
+CARRIER_NAMES: tuple[Carrier, ...] = tuple(name for name, _ in CARRIERS)

vn_ident-0.1.0/src/vn_ident/identity.py

@@ -0,0 +1,125 @@
+"""Card numbers, the old paper card, and telling them apart.
+
+The honest limit of this module is stated in every function that hits it: a
+card number has no check digit, so it can be checked for shape and not for
+truth.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal, NamedTuple
+
+from vn_ident.mst import is_valid_mst
+from vn_ident.phone import is_valid_phone
+from vn_ident.tables import Gender, century_of, gender_of, is_province_code, province_name
+
+_CCCD_SHAPE = re.compile(r"[0-9]{12}")
+_CMND_SHAPE = re.compile(r"[0-9]{9}")
+
+
+def is_valid_cccd(code: str) -> bool:
+    """Is this a well-formed card number with a province code that exists?
+
+    **There is no check digit on a card number.** The last six digits are
+    random, so unlike a tax code there is nothing to verify: this cannot detect
+    a number that is well-formed and wrong, and pretending otherwise would be
+    the most expensive thing this package could do. A card number is a format
+    check and nothing more, and the conformance suite says the same.
+
+    **It also cannot tell you which generation of card it is.** The old
+    unchipped 12-digit number and the current chip number have the same
+    structure, the 2025 reduction to 34 provincial units did not renumber any
+    card, and no function here will claim to distinguish them. If you need to
+    know, you need the issuing authority.
+    """
+    if not isinstance(code, str) or not _CCCD_SHAPE.fullmatch(code):
+        return False
+    if not is_province_code(code[:3]):
+        return False
+    # Every fourth digit is defined, so this is a table lookup rather than a
+    # range check. It is written out anyway so that a future table which drops
+    # a digit fails here instead of silently yielding None.
+    return century_of(code[3]) is not None
+
+
+class CardNumber(NamedTuple):
+    """The parts of a card number.
+
+    ``birth_year`` uses the century digit rather than the two digits alone:
+    85 in the fourth digit 0 is 1985, and in the fourth digit 2 it is 2085.
+    That is the whole reason the fourth digit exists.
+    """
+
+    province_code: str
+    province: str
+    century: int
+    gender: Gender
+    birth_year: int
+    serial: str
+
+
+def parse_cccd(code: str) -> CardNumber | None:
+    """The parts of a card number, or ``None`` if it is not a well-formed one.
+
+    A birth year in the future parses. There is no check digit, so nothing here
+    can detect it, and a date-dependent "valid" would make the conformance
+    suite change its own answer over time.
+    """
+    if not is_valid_cccd(code):
+        return None
+    century = century_of(code[3])
+    gender = gender_of(code[3])
+    province = province_name(code[:3])
+    if century is None or gender is None or province is None:
+        return None
+    return CardNumber(
+        province_code=code[:3],
+        province=province,
+        century=century,
+        gender=gender,
+        birth_year=(century - 1) * 100 + int(code[4:6]),
+        serial=code[6:],
+    )
+
+
+def is_valid_cmnd(code: str) -> bool:
+    """The old paper card: nine digits.
+
+    No structure to check and no check digit, so this is a shape test. All
+    zeros is well-formed even though no such card was ever issued, and that is
+    the honest answer: this function cannot tell you more than that.
+    """
+    return isinstance(code, str) and bool(_CMND_SHAPE.fullmatch(code))
+
+
+IdentifierKind = Literal["cccd", "cmnd", "mst", "phone", "unknown"]
+
+
+def classify_id(value: str) -> IdentifierKind:
+    """What is this string, as far as structure goes?
+
+    Ordered so the specific reading wins: a twelve-digit value with a known
+    province code is a card, a ten- or thirteen-digit value is a tax code, a
+    ten-digit value starting 0 is a phone number, and nine digits is the old
+    paper card.
+
+    Note what this does **not** say. ``"cccd"`` does not mean a chip card, and
+    ``"phone"`` does not mean the number is subscribed to anyone. A result of
+    ``"unknown"`` means the structure did not match anything here, which is a
+    statement about this package and not about the value.
+    """
+    if not isinstance(value, str):
+        return "unknown"
+    s = value.strip()
+    if not s:
+        return "unknown"
+    if is_valid_cccd(s):
+        return "cccd"
+    if is_valid_mst(s):
+        return "mst"
+    if is_valid_phone(s):
+        return "phone"
+    if is_valid_cmnd(s):
+        return "cmnd"
+    return "unknown"

vn_ident-0.1.0/src/vn_ident/mst.py

@@ -0,0 +1,107 @@
+"""Tax codes: validate them and take them apart.
+
+The tenth digit is computed, not pattern-matched, so a code is either right or
+it is refused. There is one case in the algorithm that a naive implementation
+gets wrong and that this module is explicit about: the remainder being zero.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+
+from vn_ident.tables import MST_MODULUS, MST_WEIGHTS
+
+_DIGITS = re.compile(r"[0-9]+")
+_PREFIX = re.compile(r"[0-9]{9}")
+_CC = re.compile(r"[0-9]{12}")
+
+
+def _bare(code: str) -> str:
+    """Drop the hyphen the circular writes into the 13-digit form."""
+    return code.replace("-", "")
+
+
+def mst_check_digit(nine: str) -> int | None:
+    """The tenth digit of a tax code, from its first nine.
+
+    Thông tư 105/2020/TT-BTC, Phụ lục 1: multiply the nine digits by the nine
+    weights, add, divide by 11, and take ten minus the remainder.
+
+    **The remainder being zero is a case, not an edge case.** Ten minus zero is
+    ten, which is not a digit, so the circular skips that sequence number rather
+    than assigning a check digit. This returns ``None`` for it, which means no
+    tax code whose first nine digits sum to a multiple of 11 can be valid --
+    and one that claims to be is not. A naive implementation returns 10 here and
+    then compares it against a character, so it rejects a valid code and never
+    says why.
+
+    >>> mst_check_digit("010004751")   # the worked example in the circular
+    6
+    >>> mst_check_digit("000000000") is None
+    True
+    """
+    if not isinstance(nine, str) or not _PREFIX.fullmatch(nine):
+        raise TypeError(f"a tax code prefix is nine digits, got {nine!r}")
+
+    total = sum(int(digit) * weight for digit, weight in zip(nine, MST_WEIGHTS))
+    remainder = total % MST_MODULUS
+    # The circular says it in words: ten minus the remainder.
+    return None if remainder == 0 else 10 - remainder
+
+
+def is_valid_mst(code: str) -> bool:
+    """Is this a tax code with a check digit that matches?
+
+    Ten digits for an independent entity, thirteen for a dependent unit, and
+    the hyphen between them is accepted because that is how the circular prints
+    it. A thirteen-digit code's last three run from 001 to 999, so a branch of
+    000 does not exist and accepting it would let a typo through as a real
+    entity.
+
+    Whitespace is refused rather than trimmed. A paste that arrives with a
+    trailing space is a visible error, not a silent success that hides a broken
+    integration.
+    """
+    if not isinstance(code, str):
+        return False
+    s = _bare(code)
+    if not _DIGITS.fullmatch(s):
+        return False
+    if len(s) not in (10, 13):
+        return False
+    if len(s) == 13 and not 1 <= int(s[10:]) <= 999:
+        return False
+    return mst_check_digit(s[:9]) == int(s[9])
+
+
+class TaxCode(NamedTuple):
+    """The parts of a tax code.
+
+    ``region_code`` is **not** a province. These two digits are the revenue
+    code of the provincial tax office, from the Ministry of Finance's own
+    catalogue. It is a *different list* from the province codes on a card
+    number, and calling this one a province is how two catalogues end up merged
+    in somebody's database.
+
+    ``serial`` is a string because the leading zeros are part of it: 0004751 and
+    4751 are the same serial and this is the representation that says so.
+    """
+
+    region_code: str
+    serial: str
+    check_digit: int
+    branch: str | None
+
+
+def parse_mst(code: str) -> TaxCode | None:
+    """The parts of a tax code, or ``None`` if it is not one."""
+    if not is_valid_mst(code):
+        return None
+    s = _bare(code)
+    return TaxCode(
+        region_code=s[:2],
+        serial=s[2:9],
+        check_digit=int(s[9]),
+        branch=s[10:] if len(s) == 13 else None,
+    )

vn_ident-0.1.0/src/vn_ident/phone.py

@@ -0,0 +1,85 @@
+"""Mobile numbers: reduce what a person typed, and say whose it is.
+
+Everything here is unambiguous except one switch, which exists because a typo
+and a correct number look exactly the same at the boundary.
+"""
+
+from __future__ import annotations
+
+import re
+
+from vn_ident.tables import Carrier, carrier_of_prefix
+
+_TRUNK = "0"
+_COUNTRY = "84"
+
+#: Already normalised: ten digits, starting with the trunk zero.
+_NATIONAL_SHAPE = re.compile(r"0[0-9]{9}")
+_NON_DIGITS = re.compile(r"\D")
+
+
+def normalize_phone(text: str, *, assume_trunk_zero: bool = True) -> str | None:
+    """Reduce what a person typed to a ten-digit national number, or ``None``.
+
+    The ``+84`` forms all say the same thing; spaces, dashes, dots and brackets
+    are how people write a number down rather than information; and a number
+    that is 8, 11 or 12 digits with no country code is refused rather than
+    reshaped.
+
+    ``assume_trunk_zero`` is the one inference in this package, and the one
+    place a typo and a correct number look the same. A national number written
+    without its leading zero is how it appears in a contact form and how it is
+    read aloud, so the default recovers it. Pass ``assume_trunk_zero=False`` to
+    refuse instead, which is the right choice if the input came from a system
+    that always includes it.
+
+    >>> normalize_phone("+84912345678")
+    '0912345678'
+    >>> normalize_phone("0912 345 678")
+    '0912345678'
+    """
+    if not isinstance(text, str):
+        return None
+
+    s = _NON_DIGITS.sub("", text)
+    if not s:
+        return None
+
+    rest = s[len(_COUNTRY) :] if s.startswith(_COUNTRY) else s
+
+    if len(rest) == 9 and not rest.startswith(_TRUNK):
+        if not assume_trunk_zero:
+            return None
+        rest = _TRUNK + rest
+
+    return rest if _NATIONAL_SHAPE.fullmatch(rest) else None
+
+
+def detect_carrier(phone: str) -> Carrier | None:
+    """Which mobile network is this number on, or ``None``.
+
+    Only a normalised number is looked up, on purpose. A nine-digit number has
+    no carrier until the trunk zero is known, and guessing is how a phone
+    number ends up attributed to the wrong network -- which then decides which
+    carrier portal the user is sent to.
+
+    ``None`` covers three different situations, and they are not the same: a
+    number that is not a number, a number whose prefix belongs to nobody, and a
+    ten-digit number that is not a mobile number at all. Call
+    :func:`normalize_phone` first if you need to tell them apart.
+    """
+    if not isinstance(phone, str):
+        return None
+    s = _NON_DIGITS.sub("", phone)
+    if not _NATIONAL_SHAPE.fullmatch(s):
+        return None
+    return carrier_of_prefix(s[:3])
+
+
+def is_valid_phone(text: str) -> bool:
+    """Is this something a person could have meant as a Vietnamese phone number?
+
+    True for a ten-digit number that no carrier owns, which is correct: the
+    shape is what is being checked, not the subscription.
+    """
+    return normalize_phone(text) is not None

vn_ident-0.1.0/src/vn_ident/tables.py

@@ -0,0 +1,181 @@
+"""The tables, and where each one came from.
+
+There is no platform to read these out of the way there is for collation and
+currency, so they are transcribed once, here, and the conformance suite records
+the source of each. The suite's job is to make a transcription error visible: a
+transposed pair of tax weights still produces a well-formed check digit, so it
+would validate real tax codes and reject none.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+# --- Tax codes -------------------------------------------------------------
+
+#: Thông tư 105/2020/TT-BTC Điều 5 and Phụ lục 1, from the official VBQPPL
+#: portal at moj.gov.vn.
+#:
+#: Nine weights for the nine digits before the check digit. The sums are
+#: deliberately not a neat progression, which is exactly why they have to be
+#: transcribed rather than computed.
+MST_WEIGHTS = (31, 29, 23, 19, 17, 13, 7, 5, 3)
+
+#: The circular divides the weighted sum by this.
+MST_MODULUS = 11
+
+# --- Province codes --------------------------------------------------------
+
+#: The 63 province codes on a card number, from Quyết định 124/2004/QĐ-TTg,
+#: cross-checked against chinhphu.gov.vn, thuvienphapluat.vn and vietnamnet.vn.
+#:
+#: One of those four prints Bắc Giang as 023. The other three, and the decree
+#: itself, say 024, so 024 is what is here. A single-source table would have
+#: carried the typo.
+#:
+#: The codes run 001 to 096 with gaps, and a gap is not an assignment: 003 is
+#: nobody, and a card number starting 003 is not a card number.
+PROVINCES: tuple[tuple[str, str], ...] = (
+    ("001", "Hà Nội"),
+    ("002", "Hà Giang"),
+    ("004", "Cao Bằng"),
+    ("006", "Bắc Kạn"),
+    ("008", "Tuyên Quang"),
+    ("010", "Lào Cai"),
+    ("011", "Điện Biên"),
+    ("012", "Lai Châu"),
+    ("014", "Sơn La"),
+    ("015", "Yên Bái"),
+    ("017", "Hòa Bình"),
+    ("019", "Thái Nguyên"),
+    ("020", "Lạng Sơn"),
+    ("022", "Quảng Ninh"),
+    ("024", "Bắc Giang"),
+    ("025", "Phú Thọ"),
+    ("026", "Vĩnh Phúc"),
+    ("027", "Bắc Ninh"),
+    ("030", "Hải Dương"),
+    ("031", "Hải Phòng"),
+    ("033", "Hưng Yên"),
+    ("034", "Thái Bình"),
+    ("035", "Hà Nam"),
+    ("036", "Nam Định"),
+    ("037", "Ninh Bình"),
+    ("038", "Thanh Hóa"),
+    ("040", "Nghệ An"),
+    ("042", "Hà Tĩnh"),
+    ("044", "Quảng Bình"),
+    ("045", "Quảng Trị"),
+    ("046", "Thừa Thiên Huế"),
+    ("048", "Đà Nẵng"),
+    ("049", "Quảng Nam"),
+    ("051", "Quảng Ngãi"),
+    ("052", "Bình Định"),
+    ("054", "Phú Yên"),
+    ("056", "Khánh Hòa"),
+    ("058", "Ninh Thuận"),
+    ("060", "Bình Thuận"),
+    ("062", "Kon Tum"),
+    ("064", "Gia Lai"),
+    ("066", "Đắk Lắk"),
+    ("067", "Đắk Nông"),
+    ("068", "Lâm Đồng"),
+    ("070", "Bình Phước"),
+    ("072", "Tây Ninh"),
+    ("074", "Bình Dương"),
+    ("075", "Đồng Nai"),
+    ("077", "Bà Rịa - Vũng Tàu"),
+    ("079", "Hồ Chí Minh"),
+    ("080", "Long An"),
+    ("082", "Tiền Giang"),
+    ("083", "Bến Tre"),
+    ("084", "Trà Vinh"),
+    ("086", "Vĩnh Long"),
+    ("087", "Đồng Tháp"),
+    ("089", "An Giang"),
+    ("091", "Kiên Giang"),
+    ("092", "Cần Thơ"),
+    ("093", "Hậu Giang"),
+    ("094", "Sóc Trăng"),
+    ("095", "Bạc Liêu"),
+    ("096", "Cà Mau"),
+)
+
+Gender = Literal["male", "female"]
+Carrier = Literal["viettel", "vinaphone", "mobifone", "vietnamobile", "gmobile"]
+
+#: The fourth digit: which century, and which sex.
+#:
+#: The pairs run in order, so even digits are male and odd are female, two per
+#: century, from the twentieth to the twenty-fourth.
+CENTURY_GENDER: tuple[tuple[str, int, Gender], ...] = (
+    ("0", 20, "male"),
+    ("1", 20, "female"),
+    ("2", 21, "male"),
+    ("3", 21, "female"),
+    ("4", 22, "male"),
+    ("5", 22, "female"),
+    ("6", 23, "male"),
+    ("7", 23, "female"),
+    ("8", 24, "male"),
+    ("9", 24, "female"),
+)
+
+# --- Mobile carriers -------------------------------------------------------
+
+#: Published three-digit mobile prefixes, 34 in total.
+#:
+#: 34 is not 100, and the gap is the point: 030, 040, 050, 053, 060, 071, 080,
+#: 087 and 095 belong to nobody. A well-formed ten-digit number can therefore
+#: be valid and still have no carrier, and saying "unknown" is a different
+#: answer from saying "invalid".
+CARRIERS: tuple[tuple[Carrier, tuple[str, ...]], ...] = (
+    ("viettel", ("032", "033", "034", "035", "036", "037", "038", "039", "086", "096", "097", "098")),
+    ("vinaphone", ("081", "082", "083", "084", "085", "088", "091", "094")),
+    ("mobifone", ("070", "076", "077", "078", "079", "089", "090", "093")),
+    ("vietnamobile", ("052", "056", "058", "092")),
+    ("gmobile", ("059", "099")),
+)
+
+PROVINCE_NAMES: dict[str, str] = dict(PROVINCES)
+CENTURY_BY_DIGIT: dict[str, int] = {d: c for d, c, _ in CENTURY_GENDER}
+GENDER_BY_DIGIT: dict[str, Gender] = {d: g for d, _, g in CENTURY_GENDER}
+
+
+def _build_prefix_map() -> dict[str, Carrier]:
+    out: dict[str, Carrier] = {}
+    for name, prefixes in CARRIERS:
+        for prefix in prefixes:
+            # A prefix assigned to two carriers is a transcription error, and it
+            # would otherwise resolve to whichever table was read first. The
+            # conformance generator checks this too, but failing here means it
+            # cannot ship.
+            if prefix in out:
+                raise ValueError(f"prefix {prefix} is assigned to two carriers")
+            out[prefix] = name
+    return out
+
+
+PREFIX_TO_CARRIER: dict[str, Carrier] = _build_prefix_map()
+
+ASSIGNED_PREFIX_COUNT = len(PREFIX_TO_CARRIER)
+
+
+def province_name(code: str) -> str | None:
+    return PROVINCE_NAMES.get(code)
+
+
+def is_province_code(code: str) -> bool:
+    return code in PROVINCE_NAMES
+
+
+def century_of(digit: str) -> int | None:
+    return CENTURY_BY_DIGIT.get(digit)
+
+
+def gender_of(digit: str) -> Gender | None:
+    return GENDER_BY_DIGIT.get(digit)
+
+
+def carrier_of_prefix(prefix: str) -> Carrier | None:
+    return PREFIX_TO_CARRIER.get(prefix)

vn_ident-0.1.0/tests/test_vn_ident.py

@@ -0,0 +1,338 @@
+"""Run the shared identity conformance suite against the Python port.
+
+Runnable two ways, on purpose:
+
+    pytest packages/vn-ident-py/tests -q
+    python packages/vn-ident-py/tests/test_vn_ident.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
+from pathlib import Path
+from typing import Any, Callable
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from vn_ident import (  # noqa: E402  (path set up above)
+    ASSIGNED_PREFIX_COUNT,
+    CARRIERS,
+    CENTURY_GENDER,
+    MST_MODULUS,
+    MST_WEIGHTS,
+    PROVINCES,
+    classify_id,
+    detect_carrier,
+    is_valid_cccd,
+    is_valid_cmnd,
+    is_valid_mst,
+    is_valid_phone,
+    mst_check_digit,
+    normalize_phone,
+    parse_cccd,
+    parse_mst,
+)
+
+CONFORMANCE_PATH = (
+    Path(__file__).resolve().parents[3] / "conformance" / "vn-ident-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"]
+TABLES = SUITE["tables"]
+
+
+def _as_tuple(value: Any) -> tuple[Any, ...]:
+    """The JSON suite gives lists; the port gives tuples.
+
+    Compared as lists, because that is what the file contains and what the
+    TypeScript port sees. A runner that quietly normalised here would hide a
+    real difference in the table order.
+    """
+    return value if isinstance(value, list) else list(value)
+
+
+RUNNERS: dict[str, Callable[[dict[str, Any]], Any]] = {
+    "mstCheckDigit": lambda d: mst_check_digit(d["prefix"]),
+    "isValidMst": lambda d: is_valid_mst(d["code"]),
+    "parseMst": lambda d: (
+        None
+        if parse_mst(d["code"]) is None
+        else {
+            "regionCode": parse_mst(d["code"]).region_code,
+            "serial": parse_mst(d["code"]).serial,
+            "checkDigit": parse_mst(d["code"]).check_digit,
+            "branch": parse_mst(d["code"]).branch,
+        }
+    ),
+    "normalizePhone": lambda d: normalize_phone(
+        d["input"], assume_trunk_zero=(d.get("options") or {}).get("assumeTrunkZero", True)
+    ),
+    "detectCarrier": lambda d: detect_carrier(d["phone"]),
+    "isValidPhone": lambda d: is_valid_phone(d["input"]),
+    "isValidCccd": lambda d: is_valid_cccd(d["code"]),
+    "parseCccd": lambda d: (
+        None
+        if parse_cccd(d["code"]) is None
+        else {
+            "provinceCode": parse_cccd(d["code"]).province_code,
+            "province": parse_cccd(d["code"]).province,
+            "century": parse_cccd(d["code"]).century,
+            "gender": parse_cccd(d["code"]).gender,
+            "birthYear": parse_cccd(d["code"]).birth_year,
+            "serial": parse_cccd(d["code"]).serial,
+        }
+    ),
+    "isValidCmnd": lambda d: is_valid_cmnd(d["code"]),
+    "classifyId": lambda d: classify_id(d["value"]),
+}
+
+
+def test_schema_is_understood() -> None:
+    assert SUITE["schema"] == "vn-ident-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_ident
+
+    marker = Path(vn_ident.__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_every_source() -> None:
+    # Four sources, not one. A single-source transcription of a weight table or
+    # a province list is a typo waiting to be shipped.
+    derived = SUITE["derivedFrom"]
+    assert "105/2020/TT-BTC" in derived, derived
+    assert "124/2004" in derived, derived
+    assert "cross-checked" in derived, derived
+
+
+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_every_function_has_cases() -> None:
+    for fn in SUITE["functions"]:
+        count = sum(1 for c in CASES if c["fn"] == fn)
+        assert count > 0, f"no cases for {fn}"
+        assert count == SUITE["caseCounts"][fn], (
+            f"{fn}: caseCounts says {SUITE['caseCounts'][fn]} but there are {count}"
+        )
+
+
+def test_tables_match_the_suite() -> None:
+    # The tables are the contract. A regeneration cannot quietly reorder them
+    # without showing up here.
+    assert _as_tuple(MST_WEIGHTS) == TABLES["mstWeights"]
+    assert MST_MODULUS == TABLES["mstModulus"]
+    assert len(MST_WEIGHTS) == 9
+
+    assert len(PROVINCES) == 63
+    assert len(TABLES["provinces"]) == 63
+    codes = [code for code, _ in PROVINCES]
+    assert len(set(codes)) == len(codes), "duplicate province codes"
+    names = [name for _, name in PROVINCES]
+    assert len(set(names)) == len(names), "duplicate province names"
+
+    assert len(CENTURY_GENDER) == 10
+    assert sorted(int(d) for d, _, _ in CENTURY_GENDER) == list(range(10))
+
+    all_prefixes = [p for _, prefixes in CARRIERS for p in prefixes]
+    assert len(all_prefixes) == 34
+    assert len(set(all_prefixes)) == 34, "a prefix is assigned to two carriers"
+    assert ASSIGNED_PREFIX_COUNT == 34
+    assert TABLES["carrierCount"] == 34
+
+
+def test_conformance_suite() -> None:
+    failures: list[str] = []
+    for case in CASES:
+        try:
+            actual = RUNNERS[case["fn"]](case["input"])
+        except (TypeError, ValueError) as exc:
+            actual = {"error": type(exc).__name__}
+        if actual != case["expected"]:
+            failures.append(
+                f"{case['id']}  {case['fn']}({case['input']!r})\n"
+                f"    expected: {case['expected']!r}\n"
+                f"    actual:   {actual!r}\n"
+                f"    note:     {case.get('note', '')}"
+            )
+    assert not failures, f"{len(failures)} conformance failures:\n" + "\n".join(failures[:10])
+
+
+# --- Invariants -------------------------------------------------------------
+
+
+def test_reproduces_the_worksed_example_from_the_circular() -> None:
+    # The one anchor that comes from outside this repository. Everything else
+    # about the tax rules is a transcription; this is the transcription being
+    # checked against its source.
+    assert mst_check_digit("010004751") == 6
+    assert is_valid_mst("0100047516") is True
+
+
+def test_zero_remainder_gives_none_not_ten() -> None:
+    # 10 - 0 is 10, which is not a digit, so the circular skips the sequence
+    # number. A naive implementation returns 10 and then compares it against a
+    # character, so it rejects valid codes without ever saying why.
+    assert mst_check_digit("000000000") is None
+    assert is_valid_mst("0000000000") is False
+    for d in range(10):
+        assert is_valid_mst(f"000000000{d}") is False, f"check digit {d}"
+
+
+def test_every_check_digit_value_is_reachable() -> None:
+    seen = set()
+    for n in range(40000):
+        check = mst_check_digit(str(n).zfill(9))
+        if check is not None:
+            seen.add(check)
+        if len(seen) == 10:
+            break
+    assert sorted(seen) == list(range(10))
+
+
+def test_exactly_one_tenth_digit_is_accepted() -> None:
+    # The property the whole thing rests on: change any digit and the code is
+    # refused. If two digits passed, the check digit would not be checking.
+    for prefix in ("010004751", "030475101", "790000000", "012345678"):
+        accepted = [d for d in range(10) if is_valid_mst(f"{prefix}{d}")]
+        assert accepted == [mst_check_digit(prefix)], prefix
+
+
+def test_whitespace_and_separators_are_refused_not_trimmed() -> None:
+    assert is_valid_mst("0100047516") is True
+    assert is_valid_mst("0100047516 ") is False
+    assert is_valid_mst(" 0100047516") is False
+    assert is_valid_mst("01.00047516") is False
+    # The hyphen the circular prints is the one exception, in the right place.
+    assert is_valid_mst("0100047516-001") is True
+
+
+def test_a_non_string_is_refused_rather_than_crashing() -> None:
+    # The TypeScript port takes `unknown` here. A Python caller passing None or
+    # an int must get the same answer, not a traceback.
+    for value in (None, 12345, [], {}, 0):
+        assert is_valid_mst(value) is False, repr(value)
+        assert is_valid_cccd(value) is False, repr(value)
+        assert is_valid_cmnd(value) is False, repr(value)
+        assert is_valid_phone(value) is False, repr(value)
+        assert normalize_phone(value) is None, repr(value)
+        assert detect_carrier(value) is None, repr(value)
+        assert parse_mst(value) is None, repr(value)
+        assert parse_cccd(value) is None, repr(value)
+        assert classify_id(value) == "unknown", repr(value)
+
+
+def test_every_province_code_parses_to_its_own_name() -> None:
+    for code, name in PROVINCES:
+        parsed = parse_cccd(f"{code}098512345")
+        assert parsed is not None, code
+        assert parsed.province == name, code
+        assert parsed.province_code == code
+
+
+def test_the_century_digit_is_what_makes_a_birth_year() -> None:
+    # 85 in the fourth digit 0 is 1985; in the fourth digit 2 it is 2085. This
+    # is the whole reason the fourth digit exists.
+    assert parse_cccd("001085123456").birth_year == 1985
+    assert parse_cccd("001285123456").birth_year == 2085
+    assert parse_cccd("001285123456").century == 21
+
+
+def test_a_future_year_still_parses() -> None:
+    # There is no check digit, so nothing can detect it, and a date-dependent
+    # "valid" would make the conformance suite change its own answer over time.
+    # The fourth digit 8 is the twenty-fourth century, so 99 there is 2399.
+    assert parse_cccd("001899999999").birth_year == 2399
+    assert parse_cccd("001000000000").birth_year == 1900
+
+
+def test_phone_normalisation_is_one_number_many_spellings() -> None:
+    expected = "0912345678"
+    for text in (
+        "0912345678", "+84912345678", "84912345678", "840912345678",
+        "0912 345 678", "0912-345-678", "0912.345.678", "(0912) 345678",
+        "  0912345678  ",
+    ):
+        assert normalize_phone(text) == expected, text
+
+
+def test_the_one_inference_is_switchable() -> None:
+    assert normalize_phone("912345678") == "0912345678"
+    assert normalize_phone("912345678", assume_trunk_zero=False) is None
+
+
+def test_a_valid_number_can_belong_to_nobody() -> None:
+    # 34 of the 100 three-digit prefixes are assigned. "Unassigned" is a
+    # different answer from "invalid", and this is where the two get confused.
+    assert is_valid_phone("0953456780") is True
+    assert detect_carrier("0953456780") is None
+    assert is_valid_phone("0800123456") is True
+    assert detect_carrier("0800123456") is None
+
+
+def test_detect_carrier_does_not_normalise() -> None:
+    # Guessing the trunk zero is how a number ends up attributed to the wrong
+    # network, which then decides which carrier portal the user is sent to.
+    assert detect_carrier("912345678") is None
+    assert detect_carrier("+84912345678") is None
+
+
+def test_classify_id_sorts_out_the_four_shapes() -> None:
+    assert classify_id("001098512345") == "cccd"
+    assert classify_id("001001001") == "cmnd"
+    assert classify_id("0100047516") == "mst"
+    assert classify_id("0100047516001") == "mst"
+    assert classify_id("0912345678") == "phone"
+    assert classify_id("") == "unknown"
+    assert classify_id("abc") == "unknown"
+
+
+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")
+    counts = SUITE["caseCounts"]
+    detail = ", ".join(f"{fn} {counts[fn]}" for fn in SUITE["functions"])
+    print(f"{len(CASES)} conformance cases: {detail}")
+    print(f"63 provinces, {ASSIGNED_PREFIX_COUNT} carrier prefixes")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_run_standalone())