Natural Language to Number Converter

3.0.1 · active · verified Thu Apr 16

text2num (v3.0.1) is an actively maintained Python library designed to parse and convert numbers expressed in natural language words from French, Spanish, English, Portuguese, German, Dutch, or Italian into their digit representations. It handles both integer parsing (`text2num`) and detection/transcription of cardinal, ordinal, and decimal numbers within a text stream (`alpha2digit`). The library is regularly updated and recently underwent a significant rewrite with a Rust backend.

Common errors

```
ImportError: cannot import name 'text2num' from 'text2num'
```
cause Attempting to import from the PyPI package name (`text2num`) instead of the actual module name (`text_to_num`).

fix Change your import statement to `from text_to_num import text2num` or `from text_to_num import alpha2digit`.
```
ValueError: invalid literal for text2num: 'thousand thousand and two hundreds'
```
cause The input string does not represent a valid single number for parsing by `text2num`, or contains ambiguous/malformed numerical phrases.

fix Ensure the input to `text2num` is a well-formed phrase representing a single number. For complex sentences with multiple numbers or non-standard phrasing, use `alpha2digit` which is designed for broader text transcription, or pre-process the input to isolate valid number phrases.

Warnings

breaking Version 3.0.0 was a complete rewrite, transitioning from a pure Python implementation (v2.x) to a Rust backend. This introduced several backward incompatible changes.
Fix: Review the official documentation for v3.x to understand the new API, especially for `alpha2digit` and language support. If encountering issues, consider pinning to `text2num<3.0.0` if V2.x behavior is required.
breaking Support for signed numbers was dropped in version 3.x, as the feature was previously broken. The library now focuses on positive numbers.
Fix: Handle negative number parsing externally if your application requires it. The library will not automatically convert 'minus five' to -5.
breaking The signature of the `alpha2digit` function changed in v3.x; the `threshold` optional parameter now applies to both ordinals and cardinals, instead of separate parameters.
Fix: Update calls to `alpha2digit` to use the unified `threshold` parameter. Consult the v3.x documentation for its usage.
gotcha The Russian and Catalan languages, which were supported in previous 2.x versions, have not yet been fully ported to the 3.x Rust-based backend.
Fix: Avoid using Russian ('ru') or Catalan ('ca') language codes with v3.x for critical applications, or pin to a v2.x version if these languages are essential. Check the latest release notes for updates on their support.

Install

pip install text2num Install latest version

Imports

text2num
wrong:
```
from text2num import text2num
```
correct:
```
from text_to_num import text2num
```
The top-level package name on PyPI is 'text2num', but the Python module to import from is 'text_to_num'.
alpha2digit
wrong:
```
from text2num import alpha2digit
```
correct:
```
from text_to_num import alpha2digit
```
The top-level package name on PyPI is 'text2num', but the Python module to import from is 'text_to_num'.

Quickstart

The `text2num` function converts a full number phrase into an integer, while `alpha2digit` finds and transcribes all numbers (cardinals, ordinals, decimals) within a longer text. Both require specifying the language code (e.g., 'en', 'fr', 'es').

from text_to_num import text2num, alpha2digit

# Convert a number expressed in words to its digit representation
num_en = text2num("fifty-one million five hundred seventy-eight thousand three hundred two", "en")
print(f"English number: {num_en}") # Expected: 51578302

num_fr = text2num('quatre-vingt-quinze', "fr")
print(f"French number: {num_fr}") # Expected: 95

# Find and transcribe all numbers (cardinals, ordinals, decimals) in a text
text_en = "On May twenty-third, I bought twenty-five cows, twelve chickens and one hundred twenty five point five kg of potatoes."
alphad_en = alpha2digit(text_en, "en")
print(f"Processed English text: {alphad_en}") # Expected: 'On May 23rd, I bought 25 cows, 12 chickens and 125.5 kg of potatoes.'

text_es = "Compramos veinticinco vacas, doce gallinas y ciento veinticinco coma cuarenta kg de patatas."
alphad_es = alpha2digit(text_es, "es")
print(f"Processed Spanish text: {alphad_es}") # Expected: 'Compramos 25 vacas, 12 gallinas y 125,40 kg de patatas.'

view raw JSON →