Metadata-Version: 2.5
Name: spellmoney
Version: 1.0.0
Summary: Convierte montos a letras en español, inglés, portugués y francés para cheques, facturas, recibos y contratos, con soporte para las 154 divisas del estándar ISO 4217.
Project-URL: Homepage, https://github.com/brandriver-bit/spellmoney
Project-URL: Repository, https://github.com/brandriver-bit/spellmoney
Project-URL: Issues, https://github.com/brandriver-bit/spellmoney/issues
Project-URL: Puerto a JavaScript, https://github.com/brandriver-bit/spellmoney-js
Author: Brandon Rivera Alvarado
License-Expression: MIT
License-File: LICENSE
Keywords: amount-to-words,cheques,english,facturacion,french,invoicing,iso4217,latam,monto-en-letras,numero-a-letras,portuguese,spanish
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Natural Language :: English
Classifier: Natural Language :: French
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Natural Language :: Spanish
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 :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Software Development :: Localization
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# 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`.

[![PyPI](https://img.shields.io/pypi/v/spellmoney?logo=pypi&logoColor=white&color=3775A9)](https://pypi.org/project/spellmoney/)
![Python](https://img.shields.io/badge/Python-%3E%3D3.9-3776AB?logo=python&logoColor=white)
![Tests](https://github.com/brandriver-bit/spellmoney/actions/workflows/tests.yml/badge.svg)
![License](https://img.shields.io/badge/license-MIT-green)
![Dependencies](https://img.shields.io/badge/dependencias-cero-brightgreen)
![Idiomas](https://img.shields.io/badge/idiomas-es%20%7C%20en%20%7C%20pt%20%7C%20fr-blue)

Existe también el [puerto a TypeScript/JavaScript](https://github.com/brandriver-bit/spellmoney-js) — misma lógica, mismos datos de moneda, mismo resultado exacto — para quien trabaja en Node.

## Instalación

```bash
pip install spellmoney
```

## Uso

```python
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'
```

### Otros idiomas

```python
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

```python
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:

| Idioma | Divisas cubiertas |
|---|---|
| `es` (español) | 154 — todas |
| `en` (inglés) | 154 — todas |
| `pt` (portugués, Brasil) | 46 — países lusófonos + las divisas más usadas del mundo |
| `fr` (francés) | 45 — países francófonos + las divisas más usadas del mundo |

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`](CONTRIBUTING.md) — en español e inglés.

## API

| Función | Descripción |
|---|---|
| `a_letras(monto, moneda="USD", idioma="es", centavos="fraccion", mayusculas=True)` | Convierte un monto con nombre de moneda. |
| `numero_a_letras(n)` | Solo el número, en español. |
| `numero_a_letras_en(n)` | Solo el número, en inglés. |
| `numero_a_letras_pt(n, genero="m")` | Solo el número, en portugués. |
| `numero_a_letras_fr(n)` | Solo el número, en francés. |
| `MONEDAS` | Catálogo de las 154 divisas ISO 4217. |
| `IDIOMAS` | `("es", "en", "pt", "fr")`. |
| `SpellMoneyError` | Error lanzado ante un monto, moneda o idioma inválidos. |

Parámetros de `a_letras`:

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

## Desarrollo

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

## Licencia

MIT — ver [`LICENSE`](LICENSE).
