nieve

Validate and format Chilean RUT values in Python.

The core API matches 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 and rutjs 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 for complete contracts and recipes.

Install

pip install nieve

Usage

Examples import the package as rut so each call reads on its own.

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

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:

Narrow on the concrete dataclass or on kind:

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:

stored = "21272789K"

rut.format(stored)  # "21.272.789-K"

With Pydantic

parse raises RutError, a ValueError subclass. Use it directly with AfterValidator:

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

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

uv sync --extra dev
uv run pytest
uv run mypy
uv run ruff check .

License

MIT