rut-validator 0.1.0__py3-none-any.whl

rut_validator/__init__.py

@@ -0,0 +1,26 @@
+"""
+rut-validator: Validation of Chilean RUTs for Pydantic and FastAPI
+"""
+
+from .core.validator import RutValidator
+from .core.patterns import RutFormat
+from .core.orm.pydantic.schema import RutStr
+from .errors import (
+    RutInvalidFormatError,
+    RutInvalidValueError,
+    RutModuleElevenValidationError,
+    RutValidationError,
+)
+from .types.rut import Rut as ValidatedRut
+
+__version__ = "0.1.0"
+__all__ = [
+    "RutValidator",  # For pure validation
+    "ValidatedRut",  # Validation result (alias for Rut)
+    "RutStr",  # For use with Pydantic
+    "RutFormat",  # Format enumeration
+    "RutInvalidFormatError",  # Custom exception
+    "RutInvalidValueError",  # Custom exception
+    "RutModuleElevenValidationError",  # Custom exception
+    "RutValidationError",  # Base exception
+]

rut_validator/constants.py

@@ -0,0 +1,3 @@
+"""Constants for RUT validation."""
+
+RUT_MODULE_ELEVEN_FACTORS = [2, 3, 4, 5, 6, 7]

rut_validator/core/__init__.py

@@ -0,0 +1,14 @@
+"""Core validation logic - no external dependencies"""
+
+from .formatter import RutFormatter
+from .parser import RutParser
+from .patterns import RutPatterns, RutFormat
+from .validator import RutValidator
+
+__all__ = [
+    "RutFormatter",
+    "RutParser",
+    "RutPatterns",
+    "RutFormat",
+    "RutValidator",
+]

rut_validator/core/formatter.py

@@ -0,0 +1,32 @@
+from rut_validator.core.patterns import RutPatterns
+
+
+class RutFormatter:
+    """Formatter for RUT strings with different output formats."""
+
+    @staticmethod
+    def to_original_format(rut: str) -> str:
+        """
+        Converts a RUT string to its original format with dots and dashes (e.g. "12345678-9" -> "12.345.678-9").
+
+        Args:
+            rut (str): The RUT string to format (e.g. "123456789")
+
+        Returns:
+            str: The RUT string in original format (e.g. "12.345.678-9")
+        """
+        return RutPatterns.formatted(rut)
+
+    @staticmethod
+    def to_normalize_format(rut: str) -> str:
+        """
+        Cleans the RUT string by removing dots and dashes, leaving only the digits and check digit.
+        This is used internally to normalize the RUT before validation.
+
+        Args:
+            rut (str): The RUT string to clean (e.g. "12.345.678-9")
+
+        Returns:
+            str: The cleaned RUT string (e.g. "123456789")
+        """
+        return RutPatterns.normalized(rut)

rut_validator/core/orm/django/schema.py

@@ -0,0 +1,86 @@
+from django.db.models import CharField
+from django.core.exceptions import ValidationError
+
+from typing import Any
+
+from ...validator import RutValidator
+from ....errors import (
+    RutInvalidValueError,
+    RutInvalidFormatError,
+    RutModuleElevenValidationError,
+)
+
+
+class RUTField(CharField):
+    description = "A field to store Chilean RUT (Rol Único Tributario) numbers."
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault(
+            "max_length", 12
+        )  # RUT can be up to 12 characters including formatting
+        super().__init__(*args, **kwargs)
+
+        # After initializing the field, we can set up any additional attributes or validators if needed.
+        # For example, we could add a validator that uses the RutValidator from the core module
+
+        def validator(value: Any) -> None:
+            """
+            Custom validator that uses the RutValidator to validate the RUT value.
+
+            Args:
+                value (Any): The value to validate as a RUT.
+
+            Raises:
+                ValidationError: If the value is not a valid RUT.
+            """
+
+            try:
+                if value is None:
+                    raise ValueError("RUT value cannot be None.")
+
+                RutValidator.validate(str(value))
+
+            except (
+                RutInvalidValueError,
+                RutInvalidFormatError,
+                RutModuleElevenValidationError,
+            ) as e:
+                raise ValidationError(str(f"Invalid RUT value: {e}"))
+
+        self.validators.append(validator)
+
+    def to_python(self, value: object | None) -> str | None:
+        """
+        Convert the input value to a Python string and validate it as a RUT.
+
+        Args:
+            value (object | None): The value to convert and validate.
+
+        Returns:
+            str | None: The validated RUT string or None if the input was None.
+        """
+
+        self.ensure_type(value)
+
+        if value is None:
+            return None
+
+        try:
+            return RutValidator.validate(str(value)).normalized
+        except Exception as e:
+            raise ValidationError(str(e))
+
+    def get_prep_value(self, value: object | None) -> str | None:
+        return self.to_python(value)
+
+    def ensure_type(self, value: object | None) -> str | None:
+
+        # If the value is None, we can return it directly (or we could choose to return an empty string if we prefer).
+        if value is None:
+            return value
+
+        # If the value is already a string, we can return it directly.
+        if not isinstance(value, str):
+            raise ValidationError("RUT value must be a string.")
+
+        return str(value)

rut_validator/core/orm/pydantic/schema.py

@@ -0,0 +1,80 @@
+"""RutStr - Pydantic-integrated RUT validator (style: EmailStr)"""
+
+from typing import Any, Annotated
+from typing import TYPE_CHECKING
+
+from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler
+from pydantic.json_schema import JsonSchemaValue
+
+from pydantic_core.core_schema import str_schema, no_info_after_validator_function
+from pydantic_core.core_schema import CoreSchema
+
+from ...validator import RutValidator
+
+
+if TYPE_CHECKING:
+    # For type checkers, we can just treat RutStr as a regular string.
+    RutStr = Annotated[str, ...]
+
+else:
+
+    class RutStr(str):
+        @classmethod
+        def __get_pydantic_core_schema__(
+            cls,
+            _source_type: type[Any],
+            _handler: GetCoreSchemaHandler,
+        ) -> CoreSchema:
+            """
+            Defines the core schema for Pydantic validation.
+            This method is called by Pydantic to get the schema that will be used for validation
+            and parsing of the field.
+            """
+
+            return no_info_after_validator_function(
+                cls._validate,
+                str_schema(),
+            )
+
+        @classmethod
+        def __get_pydantic_json_schema__(
+            cls,
+            schema: CoreSchema,
+            handler: GetJsonSchemaHandler,
+        ) -> JsonSchemaValue:
+            """Defines JSON schema for OpenAPI/Swagger"""
+            field_schema = handler(schema)
+            field_schema.update(
+                {
+                    "type": "string",
+                    "pattern": r"^\d{1,8}-[0-9kK]$|^\d{8}[0-9kK]$",
+                    "example": "12345678-9",
+                    "description": "Valid Chilean RUT (e.g: 12345678-9 or 123456789)",
+                }
+            )
+
+            return field_schema
+
+        def __new__(cls, value: str) -> "RutStr":
+            validated = cls._validate(value)
+            return str.__new__(cls, validated)
+
+        @classmethod
+        def _validate(cls, input_value: str, /) -> str:
+            """
+            Validates the input value as a RUT and returns the normalized form.
+            If the input is not a valid RUT, it raises a ValueError with an appropriate message.
+
+            Args:
+                input_value (str): The input value to validate as a RUT.
+
+            Returns:
+                str: The normalized RUT.
+
+            Raises:
+                ValueError: If the input is not a valid RUT.
+            """
+            try:
+                return RutValidator.validate(input_value).normalized
+            except Exception as e:
+                raise ValueError(str(e))

rut_validator/core/orm/sqlalchemy/schema.py

@@ -0,0 +1,54 @@
+from sqlalchemy.types import String, TypeDecorator
+from sqlalchemy import Dialect
+
+
+from rut_validator.core.validator import RutValidator
+
+
+class RutSQLAlchemy(TypeDecorator):
+    """
+    Custom SQLAlchemy type for RUT validation and normalization. This type will ensure that any value being stored in the database is a valid RUT and is normalized to a consistent format.
+    When retrieving values from the database, it returns the stored normalized string.
+    """
+
+    impl = String  # Save as VARCHAR/String into the database
+    cache_ok = True
+
+    def process_bind_param(self, value: str | None, dialect: Dialect) -> str | None:
+        """
+        the `process_bind_param` method is called when a value is being bound to a parameter in a SQL statement. This is where we can validate and normalize the RUT value before it gets sent to the database.
+        If the value is None, we can return it directly (or we could choose to return an empty string if we prefer). If the value is already a RutStr instance, we can return its normalized form directly.
+        If it's a regular string, we validate and normalize it using the RutStr._validate method before returning it.
+
+        Args:
+            value (Any): The value to be bound to the SQL parameter. This can be a string, a RutStr instance, or None.
+            dialect (Dialect): The SQLAlchemy dialect in use, which can be useful if we need to handle different database backends differently (though in this case we likely won't need it).
+
+        Returns:
+            str | None: The validated and normalized RUT string to be stored in the database, or None if the input was None.
+        """
+        if value is None:
+            return None
+
+        try:
+            validated_rut = RutValidator.validate(str(value))
+            return validated_rut.normalized
+        except Exception as e:
+            raise ValueError(str(e))
+
+    def process_result_value(self, value: str | None, dialect: Dialect) -> str | None:
+        """
+        The `process_result_value` method is called when a value is being retrieved from the database.
+        This is where we can convert the stored string back into a RutStr object for easier manipulation in Python.
+
+        Args:
+            value (Any): The value retrieved from the database. This can be a string or None.
+            dialect (Dialect): The SQLAlchemy dialect in use.
+
+        Returns:
+            str | None: The stored normalized RUT string, or None if the input was None.
+        """
+        if value is None:
+            return None
+
+        return value

rut_validator/core/parser.py

@@ -0,0 +1,59 @@
+from typing import Tuple, Optional
+
+from rut_validator.core.patterns import RutPatterns
+from rut_validator.types.enums import RutFormat
+
+from rut_validator.errors import (
+    RutInvalidFormatError,
+    RutInvalidValueError,
+)
+
+
+class RutParser:
+    """Parser for Chilean RUT strings with format detection."""
+
+    @classmethod
+    def parse(cls, rut: str) -> Tuple[str, str, Optional[RutFormat]]:
+        """
+        Parses a RUT string and returns body, check_digit, and detected format.
+
+        Args:
+            rut: The RUT string to parse.
+
+        Returns:
+            Tuple of (body, check_digit, format).
+
+        Raises:
+            RutInvalidValueError: If RUT is empty or None.
+            RutInvalidFormatError: If RUT format is invalid.
+        """
+        if rut.strip() == "":
+            raise RutInvalidValueError(
+                "No se puede parsear un RUT vacío, por favor ingrese un valor"
+            )
+
+        body, check_digit, format_detected = cls.destructure(rut)
+        return body, check_digit, format_detected
+
+    @classmethod
+    def destructure(cls, rut: str) -> Tuple[str, str, Optional[RutFormat]]:
+        """
+        Destructures a RUT string into its body and check digit components,
+        while also detecting the input format.
+
+        Args:
+            rut: The RUT string to parse.
+
+        Returns:
+            Tuple of (body, check_digit, format).
+        """
+        format_detected = RutPatterns.detect_format(rut)
+
+        if format_detected is None:
+            raise RutInvalidFormatError(
+                "Formato no válido, se esperaba algo como '12345678-9', '123456789' o '12.345.678-9'"
+            )
+
+        normalized = RutPatterns.normalize(rut)
+        body, digit_check = normalized[:-1], normalized[-1]
+        return body, digit_check, format_detected

rut_validator/core/patterns.py

@@ -0,0 +1,123 @@
+"""RUT pattern definitions and format detection."""
+
+from re import compile
+from typing import Optional
+
+from rut_validator.types.enums import RutFormat
+
+
+class RutPatterns:
+    """Collection of regex patterns for RUT validation and format detection."""
+
+    # Individual patterns for format detection
+    FORMATTED_PATTERN = compile(r"^\d{1,2}(?:\.\d{3}){2}-[\dkK]$")
+    HYPHENATED_PATTERN = compile(r"^\d{7,8}-[\dkK]$")
+    NORMALIZED_PATTERN = compile(r"^\d{7,8}[\dkK]$")
+
+    # Combined pattern for general validation
+    VALIDATION_PATTERN = compile(
+        r"^(?:\d{1,2}(?:\.\d{3}){2}-[\dkK]|\d{7,8}-[\dkK]|\d{7,8}[\dkK])$"
+    )
+
+    # Maximum supported length for a formatted RUT string.
+    MAX_RUT_LENGTH = 15
+
+    # Cleaning pattern (removes dots, hyphens, keeps digits and K/k)
+    CLEANING_PATTERN = compile(r"[^0-9kK]")
+
+    @classmethod
+    def detect_format(cls, rut: str) -> Optional[RutFormat]:
+        """
+        Detect the format of a RUT string.
+
+        Args:
+            rut: The RUT string to analyze.
+
+        Returns:
+            RutFormat if the format is recognized, None otherwise.
+        """
+        if cls.FORMATTED_PATTERN.match(rut):
+            return RutFormat.FORMATTED
+
+        elif cls.HYPHENATED_PATTERN.match(rut):
+            return RutFormat.HYPHENATED
+
+        elif cls.NORMALIZED_PATTERN.match(rut):
+            return RutFormat.NORMALIZED
+
+        return None
+
+    @classmethod
+    def is_valid_format(cls, rut: str) -> bool:
+        """
+        Check if a RUT string has a valid format (any supported format).
+
+        Args:
+            rut: The RUT string to validate.
+
+        Returns:
+            True if the format is valid, False otherwise.
+        """
+        if len(rut) > cls.MAX_RUT_LENGTH:
+            return False
+
+        return cls.VALIDATION_PATTERN.match(rut) is not None
+
+    @classmethod
+    def normalize(cls, rut: str) -> str:
+        """
+        Normalize a RUT string by removing formatting characters.
+
+        Args:
+            rut: The RUT string to normalize.
+
+        Returns:
+            The normalized RUT string (digits + check digit, uppercased).
+        """
+        return cls.CLEANING_PATTERN.sub("", rut).upper()
+
+    @classmethod
+    def formatted(cls, rut: str) -> str:
+        """
+        Format a RUT string with dots and hyphen.
+
+        Args:
+            rut: The RUT string to format (any supported RUT format).
+
+        Returns:
+            The formatted RUT string (e.g., "12.345.678-5").
+        """
+        normalized_rut = cls.normalize(rut)
+        body = normalized_rut[:-1]
+        check_digit = normalized_rut[-1]
+        body_formatted = f"{int(body):,}".replace(",", ".")
+        return f"{body_formatted}-{check_digit}"
+
+    @classmethod
+    def hyphenated(cls, rut: str) -> str:
+        """
+        Format a RUT string with hyphen only (hyphenated format).
+
+        Args:
+            rut: The RUT string to format (any supported RUT format).
+
+        Returns:
+            The hyphenated RUT string (e.g., "12345678-5").
+        """
+        normalized_rut = cls.normalize(rut)
+        body = normalized_rut[:-1]
+        check_digit = normalized_rut[-1]
+        return f"{body}-{check_digit}"
+
+    @classmethod
+    def normalized(cls, rut: str) -> str:
+        """
+        Return the normalized RUT string without formatting.
+
+        Args:
+            rut: The RUT string to normalize (any supported RUT format).
+
+        Returns:
+            The normalized RUT string (e.g., "123456785").
+        """
+        return cls.normalize(rut)

rut_validator/core/validator.py

@@ -0,0 +1,165 @@
+"""Pure RUT validator - no dependencies."""
+
+from __future__ import annotations
+
+import logging
+
+from typing import TYPE_CHECKING
+
+from rut_validator.core.parser import RutParser
+from rut_validator.types.enums import ValidationResult
+
+from rut_validator.errors import (
+    RutInvalidFormatError,
+    RutInvalidValueError,
+    RutModuleElevenValidationError,
+)
+
+from rut_validator.constants import RUT_MODULE_ELEVEN_FACTORS
+
+if TYPE_CHECKING:
+    from rut_validator.types.rut import Rut
+
+logger = logging.getLogger(__name__)
+
+
+class RutValidator:
+    """Validator for Chilean RUTs with pure Python logic."""
+
+    __slots__ = []
+
+    @classmethod
+    def get_validation_result(cls, rut: str) -> ValidationResult:
+        """
+        Get the validation result for a RUT string.
+
+        Args:
+            rut (str): The RUT string to validate.
+
+        Returns:
+            ValidationResult: The validation result.
+        """
+        logger.debug(f"Getting validation result for RUT: {rut}")
+
+        try:
+            body, check_digit, _ = RutParser.parse(rut)
+
+        except RutInvalidValueError:
+            logger.debug("RUT invalid due to empty or missing value")
+            return ValidationResult.INVALID_VALUE
+
+        except RutInvalidFormatError:
+            logger.debug("RUT invalid due to incorrect format")
+            return ValidationResult.INVALID_FORMAT
+
+        if cls.is_valid_check_digit(body, check_digit):
+            logger.debug("RUT check digit is valid")
+            return ValidationResult.VALID
+
+        logger.debug("RUT check digit is invalid")
+        return ValidationResult.INVALID_CHECK_DIGIT
+
+    @classmethod
+    def is_valid(cls, rut: str) -> bool:
+        """
+        Check if a RUT string is valid without raising exceptions.
+
+        Args:
+            rut (str): The RUT string to check.
+
+        Returns:
+            bool: True if valid, False otherwise.
+        """
+        validation_result = cls.get_validation_result(rut)
+        is_valid = validation_result == ValidationResult.VALID
+
+        logger.debug(f"RUT {rut} validity: {is_valid} ({validation_result})")
+
+        return is_valid
+
+    @classmethod
+    def validate(cls, rut: str) -> Rut:
+        """
+        Validate a RUT string and return a Rut object.
+
+        Args:
+            rut (str): The RUT string to validate.
+
+        Returns:
+            Rut: A validated Rut object.
+
+        Raises:
+            RutInvalidValueError: If the RUT is empty or missing.
+            RutInvalidFormatError: If the RUT format is invalid.
+            RutModuleElevenValidationError: If the check digit does not match.
+        """
+        logger.debug(f"Validating RUT: {rut}")
+
+        try:
+            body, check_digit, format_detected = RutParser.parse(rut)
+
+        except RutInvalidValueError:
+            raise RutInvalidValueError(
+                "No se puede parsear un RUT vacío, por favor ingrese un valor"
+            )
+
+        except RutInvalidFormatError:
+            raise RutInvalidFormatError(
+                "Formato no válido, se esperaba algo como '12345678-9', "
+                "'123456789' o '12.345.678-9'"
+            )
+
+        if not cls.is_valid_check_digit(body, check_digit):
+            check_digit_expected = cls.module_eleven(body)
+
+            logger.warning(
+                f"Validation failed for RUT {rut}: expected {check_digit_expected}, got {check_digit}"
+            )
+
+            raise RutModuleElevenValidationError(
+                f"El dígito verificador no coincide, se esperaba '{check_digit_expected}' en vez de '{check_digit}'"
+            )
+
+        from rut_validator.types.rut import Rut
+
+        logger.info(f"Validation successful for RUT: {rut}")
+        return Rut(rut, format_detected, skip_validation=True)
+
+    @classmethod
+    def module_eleven(cls, body: str) -> str:
+        """
+        Calculates the check digit using the modulo 11 algorithm.
+
+        Returns:
+            str: The calculated check digit (0-9 or 'K')
+        """
+        reversed_digits = map(int, reversed(body))
+        total = sum(
+            d * RUT_MODULE_ELEVEN_FACTORS[i % len(RUT_MODULE_ELEVEN_FACTORS)]
+            for i, d in enumerate(reversed_digits)
+        )
+        remainder = total % 11
+        result = 11 - remainder
+
+        if result == 11:
+            return "0"
+
+        if result == 10:
+            return "K"
+
+        return str(result)
+
+    @classmethod
+    def is_valid_check_digit(cls, body: str, check_digit: str) -> bool:
+        """
+        Validates that the provided check digit matches the calculated one.
+
+        Args:
+            body (str): The numeric part of the RUT.
+            check_digit (str): The check digit to validate.
+
+        Returns:
+            bool: True if the check digit is valid, False otherwise.
+        """
+        expected_check_digit = cls.module_eleven(body)
+        return check_digit.upper() == expected_check_digit

rut_validator/errors.py

@@ -0,0 +1,25 @@
+"""Custom exceptions for RUT validation."""
+
+
+class RutValidationError(ValueError):
+    """Base exception for all RUT validation errors."""
+
+    pass
+
+
+class RutInvalidValueError(RutValidationError):
+    """Raised when the RUT value is empty or invalid."""
+
+    pass
+
+
+class RutInvalidFormatError(RutValidationError):
+    """Raised when the RUT format is invalid."""
+
+    pass
+
+
+class RutModuleElevenValidationError(RutValidationError):
+    """Raised when the RUT fails the modulo 11 validation."""
+
+    pass

rut_validator/types/__init__.py

@@ -0,0 +1,5 @@
+"""RUT data types"""
+
+from .enums import ValidationResult, RutFormat
+
+__all__ = ["RutFormat", "ValidationResult"]

rut_validator/types/enums.py

@@ -0,0 +1,18 @@
+from enum import Enum
+
+
+class RutFormat(Enum):
+    """Enumeration of supported RUT formats."""
+
+    FORMATTED = "formatted"  # 12.345.678-9
+    HYPHENATED = "hyphenated"  # 12345678-9
+    NORMALIZED = "normalized"  # 123456789
+
+
+class ValidationResult(Enum):
+    """Result states for RUT validation."""
+
+    VALID = "valid"
+    INVALID_VALUE = "invalid_value"
+    INVALID_FORMAT = "invalid_format"
+    INVALID_CHECK_DIGIT = "invalid_check_digit"

rut_validator/types/rut.py

@@ -0,0 +1,136 @@
+"""Validated RUT value object."""
+
+from typing import Optional
+
+from dataclasses import dataclass
+
+from rut_validator.core.parser import RutParser
+from rut_validator.core.patterns import RutPatterns, RutFormat
+from rut_validator.errors import RutModuleElevenValidationError
+
+
+@dataclass(init=True)
+class Rut:
+    """
+    A class representing a validated RUT (Rol Único Tributario) value object.
+
+    This class encapsulates a validated RUT value and provides properties to access its components,
+    such as the body and check digit, as well as formatted and normalized representations.
+
+    The Rut class ensures that the RUT value is valid upon instantiation,
+    and it provides methods to retrieve the normalized and formatted versions of the RUT.
+
+    The normalized version is the raw RUT value without any formatting,
+    while the formatted version includes thousands separators and a hyphen before the check digit.
+
+    Attributes:
+        value (str): The original RUT input string as provided by the caller.
+        format (Optional[RutFormat]): The detected format of the input.
+
+    Methods:
+        normalized: Returns the normalized RUT value.
+        formatted: Returns the formatted RUT value.
+        body: Returns the body of the RUT (the numeric part).
+        check_digit: Returns the check digit of the RUT.
+        is_formatted: Returns True if input was formatted format.
+        is_hyphenated: Returns True if input was hyphenated format.
+        is_normalized: Returns True if input was normalized format.
+    """
+
+    __slots__ = ("value", "format")
+
+    def __init__(
+        self,
+        value: str,
+        format_detected: Optional[RutFormat] = None,
+        *,
+        skip_validation: bool = False,
+    ):
+        body, check_digit, detected_format = RutParser.destructure(value)
+        self.value = value
+        self.format = (
+            format_detected if format_detected is not None else detected_format
+        )
+
+        if not skip_validation:
+            from rut_validator.core.validator import RutValidator
+
+            if not RutValidator.is_valid_check_digit(body, check_digit):
+                raise RutModuleElevenValidationError(
+                    f"El dígito verificador no coincide, se esperaba '{RutValidator.module_eleven(body)}' en vez de '{check_digit}'"
+                )
+
+    @property
+    def normalized(self) -> str:
+        """
+        Returns the normalized RUT value.
+        """
+        return RutPatterns.normalize(self.value)
+
+    @property
+    def formatted(self) -> str:
+        """
+        Returns the formatted RUT value.
+        """
+        return RutPatterns.formatted(self.normalized)
+
+    @property
+    def hyphenated(self) -> str:
+        """
+        Returns the hyphenated RUT value.
+        """
+        return RutPatterns.hyphenated(self.normalized)
+
+    @property
+    def body(self) -> int:
+        """
+        Returns the body of the RUT (the numeric part).
+        """
+        return int(self.normalized[:-1])
+
+    @property
+    def check_digit(self) -> str:
+        """
+        Returns the check digit of the RUT.
+        """
+        return self.normalized[-1]
+
+    @property
+    def is_formatted(self) -> bool:
+        """
+        Returns True if input was formatted format.
+        """
+        return self.format == RutFormat.FORMATTED
+
+    @property
+    def is_hyphenated(self) -> bool:
+        """
+        Returns True if input was hyphenated format.
+        """
+        return self.format == RutFormat.HYPHENATED
+
+    @property
+    def is_normalized(self) -> bool:
+        """
+        Returns True if input was normalized format.
+        """
+        return self.format == RutFormat.NORMALIZED
+
+    def __str__(self) -> str:
+        return self.formatted
+
+    def __repr__(self) -> str:
+        return f"Rut(value='{self.value}', format={self.format})"
+
+    def equals(self, other: object) -> bool:
+        """Return True when two Rut objects represent the same normalized RUT."""
+        return self == other
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Rut):
+            return NotImplemented
+
+        return self.normalized == other.normalized
+
+    def __hash__(self) -> int:
+        return hash(self.normalized)

rut_validator-0.1.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: rut-validator
+Version: 0.1.0
+Summary: Chilean RUT validation library with Pydantic, Django, and SQLAlchemy support
+License: MIT
+License-File: LICENSE
+Keywords: rut,chile,validation,pydantic,django,sqlalchemy,fastapi
+Author: Eli-ezer Reuven Ramirez Ruiz
+Author-email: ramirez.ruiz.eliezer.reuven@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: fastapi
+Provides-Extra: pydantic
+Requires-Dist: black ; extra == "dev"
+Requires-Dist: click (>=8.0.0,<9.0.0)
+Requires-Dist: django (>=3.2,<5.0)
+Requires-Dist: fastapi (>=0.111.0,<1.0.0) ; extra == "fastapi"
+Requires-Dist: flake8 ; extra == "dev"
+Requires-Dist: isort ; extra == "dev"
+Requires-Dist: mypy ; extra == "dev"
+Requires-Dist: myst-parser ; extra == "docs"
+Requires-Dist: pre-commit ; extra == "dev"
+Requires-Dist: pydantic (>=2.12.5,<3.0.0) ; extra == "pydantic"
+Requires-Dist: pytest (>=7.0.0) ; extra == "dev"
+Requires-Dist: pytest-cov ; extra == "dev"
+Requires-Dist: ruff ; extra == "dev"
+Requires-Dist: sphinx ; extra == "docs"
+Requires-Dist: sphinx-rtd-theme ; extra == "docs"
+Requires-Dist: sqlalchemy (>=2.0.49,<3.0.0)
+Project-URL: Changelog, https://github.com/yourusername/rut-validator/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://rut-validator.readthedocs.io/
+Project-URL: Homepage, https://github.com/yourusername/rut-validator
+Project-URL: Issues, https://github.com/yourusername/rut-validator/issues
+Project-URL: Repository, https://github.com/yourusername/rut-validator
+Description-Content-Type: text/markdown
+
+# rut-validator
+
+[![PyPI version](https://badge.fury.io/py/rut-validator.svg)](https://pypi.org/project/rut-validator/)
+[![Python versions](https://img.shields.io/pypi/pyversions/rut-validator.svg)](https://pypi.org/project/rut-validator/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/yourusername/rut-validator/workflows/CI/badge.svg)](https://github.com/yourusername/rut-validator/actions)
+[![codecov](https://codecov.io/gh/yourusername/rut-validator/branch/main/graph/badge.svg)](https://codecov.io/gh/yourusername/rut-validator)
+[![Documentation Status](https://readthedocs.org/projects/rut-validator/badge/?version=latest)](https://rut-validator.readthedocs.io/en/latest/?badge=latest)
+
+Librería para validar RUT chileno con enfoque Pydantic-first y soporte completo para frameworks web.
+
+## ✨ Características
+
+- ✅ **Validación pura de RUT chileno** usando algoritmo módulo 11
+- ✅ **Detección automática de formato**: dotted (`12.345.678-9`), hyphenated (`12345678-9`), numeric (`123456789`)
+- ✅ **Integración completa con Pydantic** (`RutStr`)
+- ✅ **Campo Django** (`RUTField`) listo para usar
+- ✅ **Tipo SQLAlchemy** (`RutSQLAlchemy`) para bases de datos
+- ✅ **Compatible con FastAPI** y otros frameworks web
+- ✅ **Type hints completos** para mejor desarrollo
+- ✅ **Sin dependencias externas** para funcionalidad core
+- ✅ **Tests exhaustivos** con alta cobertura
+
+## 🚀 Instalación
+
+```bash
+pip install rut-validator
+
+# Con soporte Pydantic
+pip install rut-validator[pydantic]
+
+# Con soporte FastAPI
+pip install rut-validator[fastapi]
+
+# Para desarrollo
+pip install rut-validator[dev]
+```
+
+## 📖 Uso Básico
+
+### Validación Simple
+
+```python
+from rut_validator import RutValidator
+
+# Validar RUT con cualquier formato
+rut = RutValidator.validate("20.884.437-7")
+print(f"RUT válido: {rut.formatted}")  # "20.884.437-7"
+print(f"Número: {rut.number}")          # 20884437
+print(f"Dígito: {rut.digit}")          # "7"
+print(f"Formato: {rut.format}")        # RutFormat.DOTTED
+```
+
+### Detección de Formato
+
+```python
+from rut_validator import RutValidator
+
+# La librería detecta automáticamente el formato de entrada
+formats = [
+    "20.884.437-7",  # Formato dotted
+    "20884437-7",    # Formato hyphenated
+    "208844377",     # Formato numeric
+]
+
+for rut_str in formats:
+    rut = RutValidator.validate(rut_str)
+    print(f"'{rut_str}' -> Formato: {rut.format}, Es dotted: {rut.is_dotted}")
+```
+
+### Con Pydantic
+
+```python
+from pydantic import BaseModel
+from rut_validator import RutStr
+
+class User(BaseModel):
+    name: str
+    rut: RutStr  # Validación automática
+
+# Uso
+user = User(name="Juan Pérez", rut="12.345.678-5")
+print(user.rut)  # "12.345.678-5"
+```
+
+### Con Django
+
+```python
+from django.db import models
+from rut_validator.core.orm.django.schema import RUTField
+
+class Person(models.Model):
+    name = models.CharField(max_length=100)
+    rut = RUTField(unique=True)  # Validación automática en DB
+```
+
+### Con SQLAlchemy
+
+```python
+from sqlalchemy import Column, Integer, String
+from sqlalchemy.ext.declarative import declarative_base
+from rut_validator.core.orm.sqlalchemy.schema import RutSQLAlchemy
+
+Base = declarative_base()
+
+class Person(Base):
+    __tablename__ = 'persons'
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+    rut = Column(RutSQLAlchemy)  # Validación automática
+```
+
+## 📚 Guía Completa
+
+Lee la documentación completa en [docs/GUIA_RUT_VALIDATOR.md](docs/GUIA_RUT_VALIDATOR.md)
+
+## 🧪 Ejemplos
+
+- [Validación pura](examples/01_pure_validation.py)
+- [Uso con Pydantic](examples/02_pydantic_usage.py)
+- [Uso con FastAPI](examples/03_fastapi_usage.py)
+
+## 🔧 Desarrollo
+
+### Configuración del entorno
+
+```bash
+# Clonar repositorio
+git clone https://github.com/yourusername/rut-validator.git
+cd rut-validator
+
+# Instalar dependencias de desarrollo
+poetry install --with dev
+
+# Ejecutar tests
+poetry run pytest
+
+# Ejecutar linting
+poetry run black src/ tests/
+poetry run isort src/ tests/
+poetry run flake8 src/ tests/
+poetry run mypy src/rut_validator/
+```
+
+### Pre-commit hooks
+
+```bash
+poetry run pre-commit install
+```
+
+## 🤝 Contribuir
+
+1. Fork el proyecto
+2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
+3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
+4. Push a la rama (`git push origin feature/AmazingFeature`)
+5. Abre un Pull Request
+
+## 📄 Licencia
+
+Este proyecto está bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para más detalles.
+
+## 🙏 Agradecimientos
+
+- Algoritmo de validación basado en el estándar chileno del Servicio de Impuestos Internos
+- Inspirado en bibliotecas similares pero con enfoque moderno y tipado fuerte
+
+## 📞 Soporte
+
+- 🐛 [Reportar bugs](https://github.com/yourusername/rut-validator/issues)
+- 💡 [Sugerir features](https://github.com/yourusername/rut-validator/issues)
+- 📖 [Documentación](https://rut-validator.readthedocs.io/)
+

rut_validator-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+rut_validator/__init__.py,sha256=UaZ-sj1ctf6KeVso3DtqXXudiHDDtoK5BhYeQ6VI_O8,793
+rut_validator/constants.py,sha256=5VXbvM2vHhRGwz_E6bvNuexZTugsKh82DCdrVbB4R5o,84
+rut_validator/core/__init__.py,sha256=S8IGTUcn-COEUEyOiBvQsBt2AzFxBdKwPcVYKyOcB5k,311
+rut_validator/core/formatter.py,sha256=gdwohjrJVYGUYuS-yftnkjj08fKLMZYrUSsExQbcQdE,1022
+rut_validator/core/orm/django/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rut_validator/core/orm/django/schema.py,sha256=FaKdER1GW7EVB582zp4kpiRiAjJ5Oiz-4JsFh0ns-hc,2703
+rut_validator/core/orm/pydantic/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rut_validator/core/orm/pydantic/schema.py,sha256=jG4kCbF2bgqbnZFai-xp_BSR-dyNuwJrY4YPbHCzKEw,2589
+rut_validator/core/orm/sqlalchemy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rut_validator/core/orm/sqlalchemy/schema.py,sha256=YBiO1wBAJUe1MIM0_KUoVEFDFj-APrboH7j8EYbVWBE,2576
+rut_validator/core/parser.py,sha256=HVyn9aI_SaHbAaSJKw30crE0ot-WJX7o2v4dvoSUwg8,1822
+rut_validator/core/patterns.py,sha256=JcDhtQ1FlBLW8sWADRUnG-Gc8YFUeMwRzIsMXkZ5fhs,3538
+rut_validator/core/validator.py,sha256=-jeA86GbLlglfllYSbXh1_A6cCXdNf_NQOcDT7h6uW8,4915
+rut_validator/errors.py,sha256=X_iM1yqssh_-2QAgC0IOud5bGavA_1J6LEFeM5flFss,509
+rut_validator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rut_validator/types/__init__.py,sha256=2t2lpWbiSKLE4P6g8_FCyNYAXBtAw5VMRJNX3QxGOnI,114
+rut_validator/types/enums.py,sha256=72wIRUQN-xcKT1Ix0tOpIafKvW1HE9xr1HYZTiO5xLc,446
+rut_validator/types/rut.py,sha256=7LAYFF3XAbxaVa9XpsnLevJDQXZBEuyCw7hA7dbXO6c,4241
+rut_validator/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rut_validator-0.1.0.dist-info/METADATA,sha256=u7Ovic-hleqo5J7dMHnxfrhgwyGClR8ZfzE2EjXOZp8,7210
+rut_validator-0.1.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+rut_validator-0.1.0.dist-info/entry_points.txt,sha256=UBDN0ZY58VIptPbuUnPIpnJubUOKFcbvXofDgjdUMs0,55
+rut_validator-0.1.0.dist-info/licenses/LICENSE,sha256=RWPNeNp8UvOe5ReVomHctEU8umwticGydzEwaj4Ihag,1084
+rut_validator-0.1.0.dist-info/RECORD,,

rut_validator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.1
+Root-Is-Purelib: true
+Tag: py3-none-any

rut_validator-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+rut-validator=rut_validator.cli:cli
+

rut_validator-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eli-ezer Reuven Ramirez Ruiz
+
+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.