nieve 1.0.0__tar.gz

nieve-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+node_modules
+.pnpm-store
+dist
+coverage
+*.tsbuildinfo
+.DS_Store
+
+# Python
+.venv
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+.ruff_cache/
+.env

nieve-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dud-cl
+
+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.

nieve-1.0.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: nieve
+Version: 1.0.0
+Summary: Lean Chilean RUT validation and formatting for Python
+Project-URL: Homepage, https://github.com/enemigos/nieve
+Project-URL: Repository, https://github.com/enemigos/nieve
+Project-URL: Issues, https://github.com/enemigos/nieve/issues
+Author: enemigos
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chile,format,rut,validate
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nieve
+
+Validate and format Chilean RUT values in Python.
+
+The core API matches [`nieve`](https://www.npmjs.com/package/nieve) for TypeScript and uses `snake_case` names. Both packages share one set of fixtures, including a generated conformance suite that fails CI when the two implementations disagree, and both are released with the same version number. The TypeScript-only `formatPartial` helper is for progressive browser input and is intentionally omitted here.
+
+## Motivation
+
+The last releases of the legacy JavaScript libraries [`rut.js`](https://github.com/jlobos/rut.js) and [`rutjs`](https://github.com/jeam/rut) were published in 2021 and 2013, respectively, and they still have open issues. This package brings strict validation and structured issues to Python. See the [agent reference](https://github.com/enemigos/nieve/blob/main/llms.txt) for complete contracts and recipes.
+
+## Install
+
+```bash
+pip install nieve
+```
+
+## Usage
+
+Examples import the package as `rut` so each call reads on its own.
+
+```python
+import nieve as rut
+
+value = rut.parse("21.272.789-K")
+# "21272789K"
+
+rut.format(value)                          # "21.272.789-K"
+rut.format(value, style="plain")           # "21272789-K"
+rut.format(value, verifier_case="lower")   # "21.272.789-k"
+
+rut.safe_parse("21.272.789-0", "en")
+# SafeParseFailure(
+#     success=False,
+#     issue=VerifierIssue(
+#         kind="verifier",
+#         message='RUT verifier does not match. Replace "0" with "K".',
+#         input="21.272.789-0",
+#         expected="K",
+#         received="0",
+#     ),
+# )
+
+rut.is_rut("21272789k")  # True (the TypeScript name is `is`)
+
+rut.clean("0021.272.789-k")                # "21272789K" (does not validate)
+rut.get_verifier("21.272.789")             # "K"
+rut.compare("21.272.789-K", "21272789K")   # True
+```
+
+### Accepted input
+
+```text
+21.272.789-K
+21.272.789K
+21272789-K
+21272789K
+21.272.789-k
+```
+
+- Input must be a string.
+- Surrounding whitespace is ignored. Whitespace inside the value is not.
+- The body contains 7 or 8 digits and does not start with zero.
+- Dots are either all present in groups of three or entirely absent: `21.272789-K` is rejected.
+- The hyphen before the verifier is optional.
+- `k` is accepted in either case.
+
+The 7-digit floor is deliberate: it rejects modulo-11 false positives in short input such as `17353`. It also rejects very low real RUT values and test values such as `1-9`, which report `length`.
+
+### Issue kinds
+
+`safe_parse` returns one issue, and each `kind` means one thing:
+
+| `kind` | When |
+|---|---|
+| `type` | Input is not a string. |
+| `format` | The syntax is not a RUT: stray characters, mixed or misplaced separators, a leading zero. |
+| `length` | The syntax is valid but the body does not contain 7 or 8 digits. Carries `body_length`. |
+| `verifier` | The size is valid but the verifier does not match. Carries `expected` and `received`. |
+
+Narrow on the concrete dataclass or on `kind`:
+
+```python
+from nieve import VerifierIssue, safe_parse
+
+result = safe_parse("21.272.789-0")
+
+if not result.success and isinstance(result.issue, VerifierIssue):
+    result.issue.expected  # "K"
+```
+
+### Stored values
+
+`format` accepts anything `parse` accepts and raises `RutError` for anything else, so a canonical value read back from storage formats directly:
+
+```python
+stored = "21272789K"
+
+rut.format(stored)  # "21.272.789-K"
+```
+
+### With Pydantic
+
+`parse` raises `RutError`, a `ValueError` subclass. Use it directly with `AfterValidator`:
+
+```python
+from typing import Annotated
+from pydantic import AfterValidator, BaseModel
+from nieve import parse
+
+class User(BaseModel):
+    national_id: Annotated[str, AfterValidator(parse)]
+
+user = User(national_id="21.272.789-K")
+user.national_id  # "21272789K"
+```
+
+## API
+
+| API | Purpose |
+|---|---|
+| `parse(input, language="es")` | Validate input. Return the canonical RUT or raise `RutError`. |
+| `safe_parse(input, language="es")` | Validate input without raising. Return a structured result. |
+| `is_rut(input)` | Return whether the input is valid. |
+| `format(value, *, style="dotted", verifier_case="upper")` | Format a RUT. Validates first and raises `RutError` for invalid input. |
+| `clean(input)` | Normalize input without validating it. The output is untrusted. |
+| `compare(left, right)` | Return whether two inputs are the same RUT. |
+| `get_verifier(body)` | Calculate the verifier for a valid body. Return `None` for an invalid body. |
+
+`style` is `"dotted"` or `"plain"`. `verifier_case` is `"upper"` or `"lower"`.
+
+Errors use Spanish (`es`) by default. Pass `en` as the second argument to `parse` or `safe_parse` for English messages.
+
+`compare` returns `False` when either input is invalid, so it cannot distinguish "different" from "invalid". Use `safe_parse` when that difference matters.
+
+Exported names: `Rut`, `Language`, `RutError`, `RutIssue`, `RutIssueKind`, `TypeIssue`, `FormatIssue`, `LengthIssue`, `VerifierIssue`, `SafeParseResult`, `SafeParseSuccess`, `SafeParseFailure`, `Style`, `VerifierCase`.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run mypy
+uv run ruff check .
+```
+
+## License
+
+MIT

nieve-1.0.0/README.md

@@ -0,0 +1,148 @@
+# nieve
+
+Validate and format Chilean RUT values in Python.
+
+The core API matches [`nieve`](https://www.npmjs.com/package/nieve) for TypeScript and uses `snake_case` names. Both packages share one set of fixtures, including a generated conformance suite that fails CI when the two implementations disagree, and both are released with the same version number. The TypeScript-only `formatPartial` helper is for progressive browser input and is intentionally omitted here.
+
+## Motivation
+
+The last releases of the legacy JavaScript libraries [`rut.js`](https://github.com/jlobos/rut.js) and [`rutjs`](https://github.com/jeam/rut) were published in 2021 and 2013, respectively, and they still have open issues. This package brings strict validation and structured issues to Python. See the [agent reference](https://github.com/enemigos/nieve/blob/main/llms.txt) for complete contracts and recipes.
+
+## Install
+
+```bash
+pip install nieve
+```
+
+## Usage
+
+Examples import the package as `rut` so each call reads on its own.
+
+```python
+import nieve as rut
+
+value = rut.parse("21.272.789-K")
+# "21272789K"
+
+rut.format(value)                          # "21.272.789-K"
+rut.format(value, style="plain")           # "21272789-K"
+rut.format(value, verifier_case="lower")   # "21.272.789-k"
+
+rut.safe_parse("21.272.789-0", "en")
+# SafeParseFailure(
+#     success=False,
+#     issue=VerifierIssue(
+#         kind="verifier",
+#         message='RUT verifier does not match. Replace "0" with "K".',
+#         input="21.272.789-0",
+#         expected="K",
+#         received="0",
+#     ),
+# )
+
+rut.is_rut("21272789k")  # True (the TypeScript name is `is`)
+
+rut.clean("0021.272.789-k")                # "21272789K" (does not validate)
+rut.get_verifier("21.272.789")             # "K"
+rut.compare("21.272.789-K", "21272789K")   # True
+```
+
+### Accepted input
+
+```text
+21.272.789-K
+21.272.789K
+21272789-K
+21272789K
+21.272.789-k
+```
+
+- Input must be a string.
+- Surrounding whitespace is ignored. Whitespace inside the value is not.
+- The body contains 7 or 8 digits and does not start with zero.
+- Dots are either all present in groups of three or entirely absent: `21.272789-K` is rejected.
+- The hyphen before the verifier is optional.
+- `k` is accepted in either case.
+
+The 7-digit floor is deliberate: it rejects modulo-11 false positives in short input such as `17353`. It also rejects very low real RUT values and test values such as `1-9`, which report `length`.
+
+### Issue kinds
+
+`safe_parse` returns one issue, and each `kind` means one thing:
+
+| `kind` | When |
+|---|---|
+| `type` | Input is not a string. |
+| `format` | The syntax is not a RUT: stray characters, mixed or misplaced separators, a leading zero. |
+| `length` | The syntax is valid but the body does not contain 7 or 8 digits. Carries `body_length`. |
+| `verifier` | The size is valid but the verifier does not match. Carries `expected` and `received`. |
+
+Narrow on the concrete dataclass or on `kind`:
+
+```python
+from nieve import VerifierIssue, safe_parse
+
+result = safe_parse("21.272.789-0")
+
+if not result.success and isinstance(result.issue, VerifierIssue):
+    result.issue.expected  # "K"
+```
+
+### Stored values
+
+`format` accepts anything `parse` accepts and raises `RutError` for anything else, so a canonical value read back from storage formats directly:
+
+```python
+stored = "21272789K"
+
+rut.format(stored)  # "21.272.789-K"
+```
+
+### With Pydantic
+
+`parse` raises `RutError`, a `ValueError` subclass. Use it directly with `AfterValidator`:
+
+```python
+from typing import Annotated
+from pydantic import AfterValidator, BaseModel
+from nieve import parse
+
+class User(BaseModel):
+    national_id: Annotated[str, AfterValidator(parse)]
+
+user = User(national_id="21.272.789-K")
+user.national_id  # "21272789K"
+```
+
+## API
+
+| API | Purpose |
+|---|---|
+| `parse(input, language="es")` | Validate input. Return the canonical RUT or raise `RutError`. |
+| `safe_parse(input, language="es")` | Validate input without raising. Return a structured result. |
+| `is_rut(input)` | Return whether the input is valid. |
+| `format(value, *, style="dotted", verifier_case="upper")` | Format a RUT. Validates first and raises `RutError` for invalid input. |
+| `clean(input)` | Normalize input without validating it. The output is untrusted. |
+| `compare(left, right)` | Return whether two inputs are the same RUT. |
+| `get_verifier(body)` | Calculate the verifier for a valid body. Return `None` for an invalid body. |
+
+`style` is `"dotted"` or `"plain"`. `verifier_case` is `"upper"` or `"lower"`.
+
+Errors use Spanish (`es`) by default. Pass `en` as the second argument to `parse` or `safe_parse` for English messages.
+
+`compare` returns `False` when either input is invalid, so it cannot distinguish "different" from "invalid". Use `safe_parse` when that difference matters.
+
+Exported names: `Rut`, `Language`, `RutError`, `RutIssue`, `RutIssueKind`, `TypeIssue`, `FormatIssue`, `LengthIssue`, `VerifierIssue`, `SafeParseResult`, `SafeParseSuccess`, `SafeParseFailure`, `Style`, `VerifierCase`.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run mypy
+uv run ruff check .
+```
+
+## License
+
+MIT

nieve-1.0.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nieve"
+version = "1.0.0"
+description = "Lean Chilean RUT validation and formatting for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "enemigos" }]
+keywords = ["rut", "chile", "validate", "format"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/enemigos/nieve"
+Repository = "https://github.com/enemigos/nieve"
+Issues = "https://github.com/enemigos/nieve/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "mypy>=1.14", "ruff>=0.9"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/nieve", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nieve"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "A", "RUF"]
+# `input` and `format` shadow builtins on purpose: the public API mirrors the
+# TypeScript package, where `format` and the `input` issue field are the names
+# users already know.
+ignore = ["A001", "A002", "A004"]
+
+[tool.ruff.format]
+# Documentation code blocks use aligned trailing comments on purpose.
+exclude = ["*.md"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+mypy_path = "src"
+packages = ["nieve", "tests"]

nieve-1.0.0/src/nieve/__init__.py

@@ -0,0 +1,46 @@
+"""Lean Chilean RUT validation and formatting."""
+
+from ._verifier import get_verifier
+from .clean import clean
+from .error import RutError
+from .format import format
+from .parse import compare, is_rut, parse, safe_parse
+from .types import (
+    FormatIssue,
+    Language,
+    LengthIssue,
+    Rut,
+    RutIssue,
+    RutIssueKind,
+    SafeParseFailure,
+    SafeParseResult,
+    SafeParseSuccess,
+    Style,
+    TypeIssue,
+    VerifierCase,
+    VerifierIssue,
+)
+
+__all__ = [
+    "FormatIssue",
+    "Language",
+    "LengthIssue",
+    "Rut",
+    "RutError",
+    "RutIssue",
+    "RutIssueKind",
+    "SafeParseFailure",
+    "SafeParseResult",
+    "SafeParseSuccess",
+    "Style",
+    "TypeIssue",
+    "VerifierCase",
+    "VerifierIssue",
+    "clean",
+    "compare",
+    "format",
+    "get_verifier",
+    "is_rut",
+    "parse",
+    "safe_parse",
+]

nieve-1.0.0/src/nieve/_syntax.py

@@ -0,0 +1,49 @@
+"""Shared syntax rules. Keep these aligned with the TypeScript package.
+
+A body is either bare digits (``21272789``) or dot separated groups of three
+digits after a leading group of one to three digits (``21.272.789``). Mixing the
+two styles is rejected, and a leading zero is rejected. Body size is checked
+separately so that a well formed token of the wrong size reports ``length``
+instead of ``format``.
+"""
+
+from __future__ import annotations
+
+import re
+
+_BODY = r"(?:[1-9][0-9]{0,2}(?:\.[0-9]{3})+|[1-9][0-9]*)"
+
+# Optional body, optional hyphen, verifier.
+RUT_SYNTAX = re.compile(rf"{_BODY}?-?[0-9kK]")
+
+# A body on its own, with an optional trailing hyphen.
+BODY_SYNTAX = re.compile(rf"{_BODY}-?")
+
+MIN_BODY_LENGTH = 7
+MAX_BODY_LENGTH = 8
+
+# Surrounding whitespace that both packages ignore: ASCII whitespace plus the
+# no-break space, which is common in values pasted from documents. The set is
+# explicit so TypeScript and Python trim exactly the same characters.
+_TRIMMED = " \t\n\r\v\f\u00a0"
+
+
+def trim_whitespace(value: str) -> str:
+    return value.strip(_TRIMMED)
+
+
+def strip_separators(value: str) -> str:
+    """Remove the separators allowed by the syntax rules."""
+    return value.replace(".", "").replace("-", "")
+
+
+def group_thousands(digits: str) -> str:
+    """Insert dots every three digits from the right."""
+    result = digits[-3:]
+    rest = digits[:-3]
+
+    while rest:
+        result = f"{rest[-3:]}.{result}"
+        rest = rest[:-3]
+
+    return result

nieve-1.0.0/src/nieve/_verifier.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import re
+
+from ._syntax import (
+    BODY_SYNTAX,
+    MAX_BODY_LENGTH,
+    MIN_BODY_LENGTH,
+    strip_separators,
+    trim_whitespace,
+)
+
+_DIGITS = re.compile(r"[0-9]+")
+
+
+def _calculate_verifier(body: str) -> str:
+    """Compute the modulo-11 verifier for a body of digits.
+
+    Internal: callers must pass a body that already matched the syntax rules.
+    """
+    if _DIGITS.fullmatch(body) is None:
+        raise ValueError(f'"{body}" is not a RUT body')
+
+    total = sum(
+        int(char) * ((index % 6) + 2) for index, char in enumerate(reversed(body))
+    )
+    digit = 11 - (total % 11)
+
+    if digit == 10:
+        return "K"
+    if digit == 11:
+        return "0"
+    return str(digit)
+
+
+def get_verifier(input: object) -> str | None:
+    """Compute the verifier for a RUT body.
+
+    Accepts the same body syntax as ``parse``, with an optional trailing hyphen
+    and surrounding whitespace. Returns ``None`` for anything else.
+    """
+    if not isinstance(input, str):
+        return None
+
+    value = trim_whitespace(input)
+
+    if BODY_SYNTAX.fullmatch(value) is None:
+        return None
+
+    body = strip_separators(value)
+
+    if not MIN_BODY_LENGTH <= len(body) <= MAX_BODY_LENGTH:
+        return None
+
+    return _calculate_verifier(body)

nieve-1.0.0/src/nieve/clean.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import re
+
+_UNRELATED = re.compile(r"[^0-9kK]+")
+
+
+def clean(input: object) -> str:
+    """Strip everything that is not a digit or ``K``, uppercase, drop leading zeros.
+
+    This is a lossy normalizer, not a validator: it happily turns unrelated text
+    into a RUT-looking string, and returns an empty string for non-string input.
+    Always pass the result through ``parse``, ``safe_parse``, or ``is_rut``
+    before using it.
+    """
+    if not isinstance(input, str):
+        return ""
+
+    return _UNRELATED.sub("", input).lstrip("0").upper()

nieve-1.0.0/src/nieve/error.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from .types import RutIssue
+
+
+class RutError(ValueError):
+    """Raised by ``parse`` when validation fails."""
+
+    def __init__(self, issue: RutIssue) -> None:
+        super().__init__(issue.message)
+        self.issue = issue

nieve-1.0.0/src/nieve/format.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from ._syntax import group_thousands
+from .parse import parse
+from .types import Rut, Style, VerifierCase
+
+
+def format(
+    value: Rut | str,
+    *,
+    style: Style = "dotted",
+    verifier_case: VerifierCase = "upper",
+) -> str:
+    """Format a RUT for display.
+
+    Accepts a parsed ``Rut`` or any string ``parse`` accepts, which makes stored
+    values usable without a cast. Raises ``RutError`` for invalid input, so it
+    never returns a formatted string that is not a real RUT. Use ``safe_parse``
+    for untrusted input.
+    """
+    canonical = parse(value)
+    body = canonical[:-1]
+    verifier = canonical[-1].lower() if verifier_case == "lower" else canonical[-1]
+
+    if style == "plain":
+        return f"{body}-{verifier}"
+
+    return f"{group_thousands(body)}-{verifier}"

nieve-1.0.0/src/nieve/parse.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from typing import TypedDict
+
+from ._syntax import (
+    MAX_BODY_LENGTH,
+    MIN_BODY_LENGTH,
+    RUT_SYNTAX,
+    strip_separators,
+    trim_whitespace,
+)
+from ._verifier import _calculate_verifier
+from .error import RutError
+from .types import (
+    FormatIssue,
+    Language,
+    LengthIssue,
+    Rut,
+    SafeParseFailure,
+    SafeParseResult,
+    SafeParseSuccess,
+    TypeIssue,
+    VerifierIssue,
+)
+
+
+class _Messages(TypedDict):
+    type: str
+    format: str
+    length: str
+    verifier: str
+
+
+_MESSAGES: dict[Language, _Messages] = {
+    "es": {
+        "type": (
+            'El RUT debe ser una cadena de texto. Usa un valor como "21.272.789-K" '
+            "e intenta de nuevo."
+        ),
+        "format": (
+            "El formato del RUT es incorrecto. Usa 7 u 8 d\u00edgitos y un "
+            'verificador, por ejemplo, "21.272.789-K".'
+        ),
+        "length": (
+            "El cuerpo del RUT debe tener 7 u 8 d\u00edgitos antes del verificador; "
+            "tiene {body_length}. Corrige el cuerpo e intenta de nuevo."
+        ),
+        "verifier": (
+            'El verificador no coincide. Reemplaza "{received}" por "{expected}".'
+        ),
+    },
+    "en": {
+        "type": (
+            'RUT must be a string. Use a value such as "21.272.789-K", then try again.'
+        ),
+        "format": (
+            "RUT format is incorrect. Use 7 or 8 digits and a verifier, "
+            'for example, "21.272.789-K".'
+        ),
+        "length": (
+            "RUT body must contain 7 or 8 digits before the verifier; it contains "
+            "{body_length}. Correct the body, then try again."
+        ),
+        "verifier": (
+            'RUT verifier does not match. Replace "{received}" with "{expected}".'
+        ),
+    },
+}
+
+
+def safe_parse(input: object, language: Language = "es") -> SafeParseResult:
+    """Validate input without raising.
+
+    Surrounding whitespace is ignored. Everything else must already be a RUT:
+    dots are all present or all absent, the hyphen is optional, and ``k`` may be
+    written in either case. ``issue.input`` always reports the original input.
+    """
+    messages = _MESSAGES[language]
+
+    if not isinstance(input, str):
+        return SafeParseFailure(
+            success=False,
+            issue=TypeIssue(kind="type", message=messages["type"], input=input),
+        )
+
+    value = trim_whitespace(input)
+
+    if RUT_SYNTAX.fullmatch(value) is None:
+        return SafeParseFailure(
+            success=False,
+            issue=FormatIssue(kind="format", message=messages["format"], input=input),
+        )
+
+    cleaned = strip_separators(value).upper()
+    body = cleaned[:-1]
+    received = cleaned[-1]
+
+    if not MIN_BODY_LENGTH <= len(body) <= MAX_BODY_LENGTH:
+        return SafeParseFailure(
+            success=False,
+            issue=LengthIssue(
+                kind="length",
+                message=messages["length"].format(body_length=len(body)),
+                input=input,
+                body_length=len(body),
+            ),
+        )
+
+    expected = _calculate_verifier(body)
+
+    if expected != received:
+        return SafeParseFailure(
+            success=False,
+            issue=VerifierIssue(
+                kind="verifier",
+                message=messages["verifier"].format(
+                    expected=expected,
+                    received=received,
+                ),
+                input=input,
+                expected=expected,
+                received=received,
+            ),
+        )
+
+    return SafeParseSuccess(success=True, output=Rut(cleaned))
+
+
+def parse(input: object, language: Language = "es") -> Rut:
+    """Validate input. Return the canonical RUT or raise ``RutError``."""
+    result = safe_parse(input, language)
+    if not result.success:
+        raise RutError(result.issue)
+    return result.output
+
+
+def is_rut(input: object) -> bool:
+    """Return whether input is a valid RUT.
+
+    Named ``is_rut`` because ``is`` is a Python keyword (the TypeScript export
+    is ``is``).
+    """
+    return safe_parse(input).success
+
+
+def compare(left: object, right: object) -> bool:
+    """Return whether two inputs are the same RUT.
+
+    Returns ``False`` when either input is invalid, so it cannot distinguish
+    "different" from "invalid". Validate with ``safe_parse`` when that matters.
+    """
+    left_result = safe_parse(left)
+    right_result = safe_parse(right)
+    return (
+        left_result.success
+        and right_result.success
+        and left_result.output == right_result.output
+    )

nieve-1.0.0/src/nieve/py.typed

@@ -0,0 +1 @@
+

nieve-1.0.0/src/nieve/types.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, NewType, TypeAlias
+
+Rut = NewType("Rut", str)
+Language: TypeAlias = Literal["es", "en"]
+
+#: ``dotted`` renders ``21.272.789-K``. ``plain`` renders ``21272789-K``.
+Style: TypeAlias = Literal["dotted", "plain"]
+
+#: Case of the ``K`` verifier. Digits are unaffected.
+VerifierCase: TypeAlias = Literal["upper", "lower"]
+
+RutIssueKind: TypeAlias = Literal["type", "format", "length", "verifier"]
+
+
+@dataclass(frozen=True, slots=True)
+class TypeIssue:
+    """Input is not a string."""
+
+    kind: Literal["type"]
+    message: str
+    input: object
+
+
+@dataclass(frozen=True, slots=True)
+class FormatIssue:
+    """Input is a string whose syntax is not a RUT.
+
+    Stray characters, mixed or misplaced separators, or a leading zero.
+    """
+
+    kind: Literal["format"]
+    message: str
+    input: str
+
+
+@dataclass(frozen=True, slots=True)
+class LengthIssue:
+    """Syntax is valid but the body does not contain 7 or 8 digits."""
+
+    kind: Literal["length"]
+    message: str
+    input: str
+    body_length: int
+
+
+@dataclass(frozen=True, slots=True)
+class VerifierIssue:
+    """Syntax and length are valid but the verifier does not match."""
+
+    kind: Literal["verifier"]
+    message: str
+    input: str
+    expected: str
+    received: str
+
+
+RutIssue: TypeAlias = TypeIssue | FormatIssue | LengthIssue | VerifierIssue
+
+
+@dataclass(frozen=True, slots=True)
+class SafeParseSuccess:
+    success: Literal[True]
+    output: Rut
+
+
+@dataclass(frozen=True, slots=True)
+class SafeParseFailure:
+    success: Literal[False]
+    issue: RutIssue
+
+
+SafeParseResult: TypeAlias = SafeParseSuccess | SafeParseFailure