API — Errores

rutificador.errores

Catálogo de errores y estructuras de detalle para Rutificador.

DetalleError dataclass

Detalle estructurado de error o advertencia.

Source code in rutificador/errores.py

@dataclass(frozen=True)
class DetalleError:
    """Detalle estructurado de error o advertencia."""

    codigo: str
    mensaje: str
    hint: str
    severidad: Severidad
    recuperable: bool
    rut: str | None = None
    duracion: float = 0.0

    def __eq__(self, other: object) -> bool:  # pragma: no cover - comparación simple
        if not isinstance(other, DetalleError):
            return NotImplemented
        return (
            self.codigo,
            self.mensaje,
            self.hint,
            self.severidad,
            self.recuperable,
            self.rut,
        ) == (
            other.codigo,
            other.mensaje,
            other.hint,
            other.severidad,
            other.recuperable,
            other.rut,
        )

crear_detalle_error

crear_detalle_error(codigo: str, *, mensaje: str | None = None, hint: str | None = None, severidad: Severidad | None = None, recuperable: bool | None = None, rut: str | None = None, duracion: float = 0.0, idioma: Idioma = 'es') -> DetalleError

Crea un DetalleError a partir del catálogo o con overrides.

Parameters:

Name	Type	Description	Default
codigo	str	Código de error del catálogo.	required
mensaje	str | None	Override del mensaje.	None
hint	str | None	Override del hint.	None
severidad	Severidad | None	Override de la severidad.	None
recuperable	bool | None	Override de recuperabilidad.	None
rut	str | None	RUT asociado al error.	None
duracion	float	Tiempo de procesamiento.	0.0
idioma	Idioma	Idioma para los mensajes ("es" o "en"). Si la entrada no existe en el idioma solicitado, se usa el catálogo en español como fallback.	'es'

Source code in rutificador/errores.py

def crear_detalle_error(
    codigo: str,
    *,
    mensaje: str | None = None,
    hint: str | None = None,
    severidad: Severidad | None = None,
    recuperable: bool | None = None,
    rut: str | None = None,
    duracion: float = 0.0,
    idioma: Idioma = "es",
) -> DetalleError:
    """Crea un DetalleError a partir del catálogo o con overrides.

    Args:
        codigo: Código de error del catálogo.
        mensaje: Override del mensaje.
        hint: Override del hint.
        severidad: Override de la severidad.
        recuperable: Override de recuperabilidad.
        rut: RUT asociado al error.
        duracion: Tiempo de procesamiento.
        idioma: Idioma para los mensajes (``"es"`` o ``"en"``).
            Si la entrada no existe en el idioma solicitado, se usa
            el catálogo en español como fallback.
    """

    catalogo = _LOCALE_CATALOGS.get(idioma, _CATALOGO_ES)
    entrada = catalogo.get(codigo)
    if entrada is None and idioma != "es":
        entrada = _CATALOGO_ES.get(codigo)

    mensaje_final = mensaje or (entrada["mensaje"] if entrada else "Error desconocido")
    hint_final = hint or (
        entrada["hint"] if entrada else "Consulte el catálogo de errores"
    )
    severidad_final = severidad or (entrada["severidad"] if entrada else "error")
    recuperable_final = (
        recuperable
        if recuperable is not None
        else (entrada["recuperable"] if entrada else False)
    )
    return DetalleError(
        codigo=codigo,
        mensaje=mensaje_final,
        hint=hint_final,
        severidad=severidad_final,
        recuperable=recuperable_final,
        rut=rut,
        duracion=duracion,
    )