wolof-numbers 0.3.0

Wolof numeral and currency phrase parser (range 1 to 1,000,000,000)

wolof-numbers

Wolof numeral and currency phrase parser. Parse Wolof cardinal numbers from 1 to 1,000,000,000 and currency phrases in XOF/FCFA/CFA. MIT-licensed, PyPI-published as v0.1.0.

Install

pip install wolof-numbers

Quick Start

from wolof_numbers import parse_number, parse_currency_amount, parse_strict

# Cardinal number
result = parse_number("ñaar junni")
print(result.value)       # 2000
print(result.confidence)  # 1.0

# Strict parsing (returns int, raises on ambiguity)
value = parse_strict("ñaar junni")
print(value)  # 2000

# Currency phrase
amt = parse_currency_amount("ñaar junni franc CFA")
print(amt.amount)    # 2000
print(amt.currency)  # "XOF"

Supported Range

Range	Status
1 – 9 (ones)	Supported
10 – 99 (tens)	Supported
100 – 999 (hundreds)	Supported
1,000 – 99,999 (thousands)	Supported
100,000 – 999,999	Supported
1,000,000 – 1,000,000,000	Supported

Supported Forms

• Cardinals only in v0.1.0 — benn (1), ñaar (2), … juróom-ñaar (7), fukk (10), téeméer (100), junni (1000)
• Wolof↔French code-switching — ñaar mille francs is parsed as 2000 XOF
• Diacritic-insensitive input — naar, NAAR, ñaar all resolve to canonical ñaar
• ~100 orthographic aliases covering regional variants (Lebu, Saloum-Saloum, Northern cluster) and common ASR transcript variants

Known Limitations (v0.2 targets)

Form	Example	v0.1.0 Behavior
Ordinals	ñaaréél (second)	Raises UnsupportedNumeralForm(kind="ordinal")
Fractions	genn ci ñaar (one-half)	Raises UnsupportedNumeralForm(kind="fraction")
Arabic loanwords	alfu (1000)	Raises UnsupportedNumeralForm(kind="loanword")

Stability

v0.x.y: public API is committed-to; internals are not. Breaking changes to the public API will bump to 0.(x+1).0 with a migration note in CHANGELOG.

The public API surface consists of: parse, parse_strict, parse_number, parse_currency_amount, normalize, ParseResult, AmountResult, Interpretation, AmbiguityError, UnsupportedNumeralForm.

Linguistic Source

The cardinal numeral system is based on Guérin 2021 (Constance Guérin's linguistic research on Wolof numerals) and supplemented by jangawolof.org.

Contributing

Non-developers can extend the alias table by editing wolof_numbers/data/aliases.yaml — no Python knowledge required. Each entry maps a canonical Wolof orthography to a list of accepted variants. Open a PR with new variants and a usage example.

License

MIT — see LICENSE. Copyright (c) 2026 Kuma Labs.