spellmoney

Convierte montos numéricos a letras, con el formato exacto que exigen los documentos legales y financieros — cheques, facturas, recibos y contratos: CIENTO VEINTICINCO DÓLARES CON 50/100.

Existe también el puerto a TypeScript/JavaScript — misma lógica, mismos datos de moneda, mismo resultado exacto — para quien trabaja en Node.

Instalación

pip install spellmoney

Uso

from spellmoney import a_letras

a_letras(125.50)
# 'CIENTO VEINTICINCO DÓLARES CON 50/100'

a_letras(1, moneda="GTQ")
# 'UN QUETZAL CON 00/100'

a_letras(21000000, moneda="EUR")
# 'VEINTIÚN MILLONES DE EUROS CON 00/100'

a_letras(2, moneda="GBP", mayusculas=False)
# 'dos libras esterlinas con 00/100'

a_letras(10.50, centavos="palabras")
# 'DIEZ DÓLARES CON CINCUENTA CENTAVOS'

a_letras("125.50")
# 'CIENTO VEINTICINCO DÓLARES CON 50/100'  (lectura decimal exacta)

Otros idiomas

a_letras(125.50, idioma="en")
# 'ONE HUNDRED TWENTY-FIVE DOLLARS AND 50/100'

a_letras(125.50, idioma="pt", moneda="BRL")
# 'CENTO E VINTE E CINCO REAIS E 50/100'

a_letras(125.50, idioma="fr", moneda="EUR")
# 'CENT VINGT-CINQ EUROS ET 50/100'

Solo el número, sin moneda

from spellmoney import (
    numero_a_letras,
    numero_a_letras_en,
    numero_a_letras_pt,
    numero_a_letras_fr,
)

numero_a_letras(1000000)        # 'un millón'
numero_a_letras(1000000000)     # 'mil millones'   (¡no "un billón"!)
numero_a_letras(1000000000000)  # 'un billón'

numero_a_letras_en(1000000000)  # 'one billion'    (escala corta del inglés)

numero_a_letras_pt(21, "f")     # 'vinte e uma'    (concordancia de género)

numero_a_letras_fr(71)          # 'soixante et onze'  (base vigesimal del francés)

Monedas soportadas

Las 154 divisas activas del estándar ISO 4217. La cobertura varía según el idioma:

Si se pide una combinación de moneda e idioma que aún no existe, a_letras lanza SpellMoneyError con un mensaje explicando exactamente qué falta, en vez de fallar en silencio.

🙋 Ayuda buscada

Portugués y francés todavía tienen huecos en divisas regionales. Los pasos exactos para contribuir (fork, rama, pruebas, Pull Request) están en CONTRIBUTING.md — en español e inglés.

API

Parámetros de a_letras:

• monto — int, float, Decimal o cadena decimal ("125.50").
• moneda — código ISO 4217. Por defecto "USD".
• idioma — "es", "en", "pt" o "fr". Por defecto "es".
• centavos — "fraccion" escribe 50/100; "palabras" escribe CINCUENTA CENTAVOS.
• mayusculas — True devuelve el resultado en mayúsculas; False, en minúsculas.

Rango soportado

Enteros de 0 a 999,999,999,999,999. Un monto fuera de ese rango lanza SpellMoneyError, igual que un monto negativo, una moneda no reconocida o un idioma no soportado.

Redondeo y precisión

Un monto se puede pasar como float, como Decimal o como cadena decimal, y la diferencia importa:

• Cadena o Decimal — a_letras("125.50"), a_letras(Decimal("125.50")): los dígitos se leen tal como fueron escritos, sin pasar por punto flotante. El redondeo del tercer decimal en adelante es half-up exacto, así que "2.675" da 68/100. Es la vía recomendada cuando el monto viene de una base de datos, un formulario o un archivo.
• float — a_letras(125.50): los montos de dos decimales se convierten de forma exacta. Verificado sobre el millón de montos de 0.00 a 9999.99: ninguna diferencia frente a aritmética decimal exacta. Con tres o más decimales, el empate exacto se resuelve según el valor binario que el float almacena realmente, que puede quedar apenas por debajo del decimal escrito: 2.675 da 67/100. Es una propiedad del tipo float, no de esta librería.

Desarrollo

git clone https://github.com/brandriver-bit/spellmoney.git
cd spellmoney
pip install -e ".[dev]"
pytest

Licencia

MIT — ver LICENSE.