All public functions live in the top-level ovos_number_parser package and
take a BCP-47 language code (lang). The primary language subtag selects the
parser and must match exactly, in any letter case and with - or _ between
subtags, so "pt-BR", "pt_PT" and "pt" all reach the Portuguese parser
(with variant handling where it matters, e.g. Brazilian vs European
Portuguese), while "fil" (Filipino) does not reach the Finnish parser.
All 40 supported languages provide every public function. Where a language has
no hand-written implementation, a documented generic fallback fills in:
pronounce_number / pronounce_ordinal use
unicode-rbnf. The rest use the
parity fallbacks described in
Full function parity. A lang outside the
supported set (or a value the fallback genuinely cannot handle) raises
NotImplementedError.
Every function returns int/float/str/bool as documented below. The
extraction and classification helpers return False (not None) when no
number is present. Test with is not False rather than truthiness, since a
valid 0 or 0.0 is falsy.
Language-specific *_<code> variants (e.g. pronounce_number_de,
nice_number_de) are also importable from the top-level package if you want to
skip the dispatcher. nice_number_<code> (formats a float as a mixed
fraction with a spoken denominator, e.g. nice_number_de(5.5) →
"5 und ein halb") has no top-level dispatcher and is only exposed
per-language.
pronounce_number(number, lang, places=3, short_scale=True, scientific=False, ordinals=False, digits=..., gender=...)
Convert a numeric value to its spoken form.
>>> pronounce_number(4.5, "en")
'four point five'
>>> pronounce_number(21, "cs")
'dvacet jedna'
>>> pronounce_number(2023, "gl")
'dous mil e vinte e tres'places: decimal places to speak.short_scale: short vs long scale for large numbers (https://en.wikipedia.org/wiki/Names_of_large_numbers).scientific: read5e-6style notation aloud.ordinals: speak"first"instead of"one".digits:DigitPronunciationenum for digit-by-digit reading styles.gender:GrammaticalGenderenum for languages whose numerals inflect (e.g. Portuguese"uma hora"vs"um minuto").
A whole number past the largest scale compound a language uses is read in
scientific form. Romanian reads 10 ** 24 as "un milion de trilioane" and
10 ** 27 as "unu virgulă zero ori zece la puterea douăzeci și șapte".
Belgian and Swiss French (fr-BE, fr-CH) read 70 and 90 as septante and
nonante, and Swiss French reads 80 as huitante. Their ordinals use the same
words (septantième, nonantième, huitantième).
Spoken ordinal form (1 -> "first"). Languages without a handwritten
implementation use the unicode-rbnf fallback.
Speak a fraction string such as "3/4". Currently implemented for Portuguese
and Mirandese.
Extract the first number found in a phrase. Returns int, float, or
False when the text contains no number.
>>> extract_number("set a timer for twenty one minutes", "en")
21
>>> extract_number("dos mil veintitrés", "es")
2023
>>> extract_number("einundzwanzig Katzen", "de")
21Compound-written languages (German, Dutch, Danish, Swedish) split words such
as einundzwanzig, eenentwintig, toogfyrre or tjugoen automatically.
Exact-match test for a fraction word ("half" → 0.5, otherwise False).
Use extract_number to pull fractions out of longer phrases.
Exact-match test for an ordinal word ("third" → 3, otherwise False).
Implemented for en, pt, mwl, de and da.
Rewrite the written numbers inside a phrase as digits, keeping the rest of the text intact.
>>> numbers_to_digits("set a timer for five minutes", "en")
'set a timer for 5 minutes'extract_number, extract_number_spans and numbers_to_digits read a
language through numtag when its
language code is in ovos_number_parser.numtag_readers.NUMTAG_LANGS. Every
other language keeps its numbers_<code>.py reader. A language joins the set
when numtag passes that language's tests in this repository.
numtag gives each value as an exact digit string. The readers convert it to
the int or float the API returns. A value that is no whole number is a
float. When the float drops the part after the point, the value rounds
half up to an int. An integer with more digits than str can write is no
number. numbers_to_digits keeps a number written in digits and an ordinal
as written. numtag_readers.numbers_to_digits writes an ordinal as the
digits of its value when it gets ordinals=True.
is_fractional and is_ordinal answer a question about one
word, which numtag does not read, so they keep the parser for every language.
The set holds et, fi, sk and sl.
Scale:Scale.SHORT/Scale.LONGlarge-number scales.GrammaticalGender:MASCULINE/FEMININE/NEUTRAL.DigitPronunciation: full-number vs digit-by-digit reading styles.