Skip to main content

rut-validator

PyPI version Python versions License: MIT CI codecov Documentation Status

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 Rut value 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)

Source distribution for rut-validator 2.0.0
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)

Table of built distributions (wheels) for rut-validator 2.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page