rut-validator
Framework-agnostic Chilean RUT validation with optional integrations for Pydantic, FastAPI, Django, SQLAlchemy, and SQLModel.
Features
- Strict modulo-11 check digit validation.
- Formatted, hyphenated, and normalized input detection.
- Immutable and hashable
Rutvalue object. - Small functional validation API.
- Structured errors with stable machine-readable codes.
- CLI validation, formatting, inspection, and batch processing.
- Normalized persistence through optional ORM adapters.
- Strict ASCII input handling.
- Python 3.10 through 3.14 support.
Validation confirms syntax and the check digit. It does not confirm that a RUT exists, is active, or belongs to a particular person or organization. Values shown below are synthetic validation fixtures and must not be interpreted as identifying real people.
Installation
Install the standalone API and CLI:
pip install rut-validator
Install only the integrations your application needs:
pip install "rut-validator[pydantic]"
pip install "rut-validator[fastapi]"
pip install "rut-validator[django]"
pip install "rut-validator[sqlalchemy]"
pip install "rut-validator[sqlmodel]"
pip install "rut-validator[all]"
Basic usage
from rut_validator import calculate_check_digit, validate_rut
rut = validate_rut("20.884.437-7")
assert rut.normalized == "208844377"
assert rut.formatted == "20.884.437-7"
assert rut.hyphenated == "20884437-7"
assert rut.body == 20884437
assert rut.check_digit == "7"
assert calculate_check_digit("20884437") == "7"
For boolean-only checks:
from rut_validator import is_valid_rut
assert is_valid_rut("12.345.678-5")
assert not is_valid_rut("12.345.678-0")
assert not is_valid_rut(None)
Error handling
from rut_validator import RutValidationError, validate_rut
try:
validate_rut("12.345.678-0")
except RutValidationError as error:
print(error.code)
print(error.as_dict())
Public error codes are invalid_value, invalid_format, and
invalid_check_digit.
Pydantic
from pydantic import BaseModel
from rut_validator.integrations.pydantic import RutPydantic
class User(BaseModel):
name: str
rut: RutPydantic
user = User(name="Ana", rut="12.345.678-5")
assert user.rut == "123456785"
FastAPI
from fastapi import FastAPI
from pydantic import BaseModel
from rut_validator.integrations.pydantic import RutPydantic
app = FastAPI()
class Person(BaseModel):
rut: RutPydantic
@app.post("/people")
def create_person(person: Person) -> Person:
return person
Invalid values produce FastAPI's standard HTTP 422 response, and
RutPydantic contributes examples and a description to OpenAPI. Runtime
validation additionally verifies the modulo-11 check digit.
Django
from django.db import models
from rut_validator.integrations.django import RutDjango
class Person(models.Model):
name = models.CharField(max_length=100)
rut = RutDjango(unique=True)
The field accepts formatted input and stores the normalized nine-character representation.
SQLAlchemy
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from rut_validator.integrations.sqlalchemy import RutSQLAlchemy
class Base(DeclarativeBase):
pass
class Person(Base):
__tablename__ = "people"
id: Mapped[int] = mapped_column(primary_key=True)
rut: Mapped[str] = mapped_column(RutSQLAlchemy(), unique=True)
RutSQLAlchemy validates values both before persistence and after database
reads.
SQLModel
from typing import Annotated
from sqlmodel import Field, SQLModel
from rut_validator.integrations.sqlmodel import RutSQLModel, rut_sqlmodel_field
class Person(SQLModel, table=True):
id: int | None = Field(default=None, primary_key=True)
rut: Annotated[
RutSQLModel,
rut_sqlmodel_field(unique=True, index=True),
]
Version 2 integrations live only under rut_validator.integrations; see the
version 2 migration guide when upgrading from 1.x.
CLI
rut-validator validate 12.345.678-5
rut-validator validate 12.345.678-5 --json
rut-validator format 123456785 --format formatted
rut-validator info 12.345.678-5 --detailed
rut-validator batch ruts.txt --output result.jsonl
Documentation
Read the published documentation or serve it locally:
poetry install --all-extras
poetry run mkdocs serve
Examples
Development
git clone https://github.com/ezer-mackenzie/rut-validator.git
cd rut-validator
poetry install --all-extras
poetry run pytest --cov=rut_validator
poetry run ruff check src tests examples
poetry run black --check src tests examples
poetry run mypy src/rut_validator
poetry run basedpyright
poetry run actionlint
poetry run mkdocs build --strict
poetry build
Install the Git hooks with:
poetry run pre-commit install
See CONTRIBUTING.md for the contribution workflow.
Security
Report security issues according to SECURITY.md. Do not include real personal RUT values in public bug reports or test fixtures.
License
Licensed under the MIT License.
Metadata
Release files for rut-validator 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rut_validator-2.0.0.tar.gz | 13.4 kB | With provenance | Details for rut_validator-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rut_validator-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for rut_validator-2.0.0-py3-none-any.whl |
Total release size: 29.0 kB
Release files / rut_validator-2.0.0.tar.gz
| Download URL | rut_validator-2.0.0.tar.gz |
|---|---|
| Size | 13.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5a5cb262015eee529348ff417c7ab232e90e7559e95894a18c37051271e05ea6
|
|
BLAKE2b-256 checksum How to use checksums |
3505c5a215df818ce9f3e2f41cd00588610d89bc3d56043e4fa4dfaaadd7fcef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / rut_validator-2.0.0-py3-none-any.whl
| Download URL | rut_validator-2.0.0-py3-none-any.whl |
|---|---|
| Size | 15.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d6dfe15b2c7d9acbbd82f132ec05812e3018aab67121cd5b30280135537dd3d9
|
|
BLAKE2b-256 checksum How to use checksums |
8b95c3fc625e8e46b803eeca183f5735a10a30c8961b859fe958d689f0b3c7e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logSecurity for rut-validator 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for rut_validator-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.