Numeralform

Numeralform is a typed, locale-aware number-to-words engine for Python. It provides canonical executable support for all 49 Spokenform base language families plus reviewed regional variants. It preserves semantic values, supports explicit syntax and reviewed morphology, exposes capability discovery, and provides a deterministic num2words compatibility adapter.

Install

python -m pip install numeralform

For development:

python -m pip install -e ".[test]"

Versioning

The package version is derived from Git tags by setuptools-scm. Release tags use the form v<version>; the corresponding package version is generated during the build. A source checkout without generated version metadata falls back to 0+unknown.

Quick start

from numeralform import DecimalNumber, DigitSequence, render, realize

render(42, locale="en")
# "forty-two"
render(DigitSequence("0042"), locale="en")
# "zero zero four two"
render(DecimalNumber("1", "20"), locale="en")
# "one point two zero"
result = realize(42, locale="en-US")
# result.locale == "en-US", result.requested_locale == "en-US"

Why Numeralform

Compatibility

from numeralform.compat import num2words

num2words(42, lang="en")

The runtime adapter is deterministic and does not import upstream num2words. The compatibility profile is pinned to Git revision 07814cb114157f582c40a00119c2e9faba8dcee2 with package metadata 0.5.14.

Development tests

The default suite contains only small Numeralform tests. It needs no benchmark data, network access, ICU, or external num2words package:

python -m pytest

Coverage, lint, formatting, and build checks are described in the release procedure.

Explicit benchmarks

Oracle, corpus, differential, and upstream compatibility work is separate from unit tests:

python -m benchmarks.download num2words
python -m benchmarks.run num2words
python -m benchmarks.run cldr
python -m benchmarks.run all
python -m pytest benchmarks/tests

Benchmark data and reports are generated locally under benchmarks/data/ and are not required for normal tests.

CLI

numeralform 42 --locale en
numeralform 0042 --locale en --digits
numeralform --version
numeralform --list-locales
numeralform --capabilities ru

See the API reference, locale inventory, compatibility contract, and release procedure.