El parámetro parse_float del módulo tomllib permite controlar cómo se convierten los números de punto flotante encontrados en un archivo TOML. Por defecto, valores como 0.1, 3.14 o 1e-6 se transforman en objetos float. Este comportamiento es práctico, pero puede ser insuficiente para precios, impuestos, límites exactos, auditoría o aplicaciones que necesitan tipos numéricos personalizados.
En esta guía aprenderás a usar parse_float con tomllib.load y tomllib.loads, por qué Decimal suele ser la mejor alternativa, qué restricciones existen y cómo probar el resultado. Para una introducción general, consulta nuestra guía de tomllib en Python.
Qué hace parse_float
parse_float recibe una función. Cada vez que el parser encuentra un literal flotante, entrega a esa función el texto original del número. La función devuelve el objeto que se guardará en el diccionario final.
import tomllib
from decimal import Decimal
config = tomllib.loads('tasa = 0.1', parse_float=Decimal)
print(config['tasa'])
print(type(config['tasa']))
El resultado es Decimal('0.1'), conservando exactamente los dígitos escritos.
Por qué float puede no ser suficiente
El tipo float usa representación binaria IEEE 754. Muchas fracciones decimales sencillas no tienen una representación binaria exacta. Por eso, algunas operaciones producen resultados como 0.30000000000000004. No es un error de TOML, sino una característica del punto flotante binario.
Para gráficos, medidas aproximadas o numerosos cálculos científicos, float es adecuado. Para importes, tasas, reglas contables o comparaciones exactas, Decimal suele ser más apropiado. Puedes ampliar este tema en nuestra guía de Decimal en Python.
Uso con tomllib.load
Al leer un archivo, ábrelo en modo binario y pasa el conversor:
from decimal import Decimal
import tomllib
with open('config.toml', 'rb') as archivo:
datos = tomllib.load(archivo, parse_float=Decimal)
Solo los literales flotantes pasan por la función. Los enteros siguen siendo int, los booleanos siguen siendo bool, las cadenas permanecen como texto y las fechas usan los tipos adecuados de datetime.
Conversores personalizados
La función puede validar valores o devolver un tipo propio:
from decimal import Decimal
def parse_no_negativo(texto: str) -> Decimal:
valor = Decimal(texto)
if valor < 0:
raise ValueError('no se permiten valores negativos')
return valor
Este patrón permite rechazar configuraciones incorrectas durante la lectura. Sin embargo, no sustituye una validación completa del esquema. Después de cargar los datos, comprueba claves obligatorias, estructuras, intervalos y relaciones entre campos. Las dataclasses pueden ayudar; consulta nuestra guía de dataclasses en Python.
Restricciones importantes
La función no debe devolver una lista ni un diccionario. Esos tipos podrían interferir con la estructura que el propio parser crea a partir del TOML. Usa valores escalares o clases personalizadas.
Si el conversor lanza una excepción, el análisis se detiene. Captura tanto errores de sintaxis TOML como errores de validación:
try:
datos = tomllib.loads(texto, parse_float=parse_no_negativo)
except (tomllib.TOMLDecodeError, ValueError) as error:
print(f'Configuración inválida: {error}')
Contexto y precisión de Decimal
Crear un Decimal desde el texto original conserva el literal. Las operaciones posteriores obedecen el contexto decimal activo, incluida la precisión y el redondeo. Configura ese contexto solo cuando sea necesario y, preferiblemente, usa localcontext para mantener los cambios aislados.
No conviertas primero a float y después a Decimal, porque la aproximación binaria ya habrá ocurrido. La ventaja principal de parse_float=Decimal es realizar una conversión directa desde la cadena original.
Ejemplo con precios
# config.toml
[producto]
precio = 19.90
descuento = 0.15
from decimal import Decimal
import tomllib
with open('config.toml', 'rb') as archivo:
config = tomllib.load(archivo, parse_float=Decimal)
precio = config['producto']['precio']
descuento = config['producto']['descuento']
final = precio * (Decimal('1') - descuento)
print(final.quantize(Decimal('0.01')))
Todo el cálculo mantiene semántica decimal desde la entrada hasta el redondeo final.
Notación científica
TOML admite exponentes. El conversor recibe el texto original, por lo que 1e-6 se convierte en Decimal('1e-6'). Esto resulta útil para tolerancias, probabilidades y constantes técnicas que necesitan precisión controlada.
Wrappers numéricos propios
Un proyecto puede devolver una clase que guarde el literal original, unidades, origen del dato o información de auditoría. Esta opción puede ser valiosa en sistemas especializados, pero aumenta la complejidad. Para la mayoría de aplicaciones, Decimal ofrece el mejor equilibrio entre claridad, precisión y compatibilidad.
Validación posterior
El parser garantiza sintaxis, no reglas de negocio. Después de cargar, verifica que existan todas las secciones, que los tipos sean correctos y que los valores estén dentro de límites aceptables. Los type hints ayudan a documentar el contrato; consulta nuestra guía de type hints en Python.
Estrategia de pruebas
Prueba decimales exactos, valores negativos, cero, notación exponencial, números grandes y TOML inválido. Comprueba tanto el valor como el tipo obtenido.
def test_decimal_exacto():
datos = tomllib.loads('valor = 0.1', parse_float=Decimal)
assert datos['valor'] == Decimal('0.1')
assert isinstance(datos['valor'], Decimal)
También verifica que los enteros no pasen por el callback. El literal 1 sigue siendo entero, mientras que 1.0 usa parse_float.
Rendimiento
Decimal es más lento que float, pero los archivos de configuración suelen ser pequeños y se leen pocas veces. La diferencia normalmente es irrelevante. Si tu sistema analiza documentos TOML grandes de forma repetida, mide el caso real antes de optimizar.
TOML es principalmente un formato de configuración, no un formato de procesamiento masivo.
Seguridad y mantenimiento
Mantén el conversor pequeño, determinista y sin acceso a red ni modificaciones globales ocultas. La lectura de configuración no debe ejecutar código arbitrario. Documenta el tipo resultante para que otras partes del sistema no asuman que recibirán float.
La documentación oficial de tomllib describe la API, mientras que la especificación TOML define la sintaxis válida de los números.
Cuándo usar parse_float
Úsalo cuando necesites representación decimal exacta, validación temprana o un tipo numérico personalizado. Mantén el comportamiento predeterminado para medidas aproximadas, ajustes visuales, coordenadas o parámetros donde el punto flotante binario sea esperado.
Conclusión
tomllib.parse_float es un punto de extensión pequeño pero potente. Permite conservar los literales decimales, validar valores y adaptar la lectura TOML a los requisitos numéricos de la aplicación. Combinado con validación posterior, manejo claro de errores, pruebas y documentación, crea un flujo de configuración preciso y mantenible sin depender de un parser externo.
