Skip to content

Latest commit

 

History

History
134 lines (103 loc) · 5.47 KB

api.md

File metadata and controls

134 lines (103 loc) · 5.47 KB

API reference

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: read 5e-6 style notation aloud.
  • ordinals: speak "first" instead of "one".
  • digits: DigitPronunciation enum for digit-by-digit reading styles.
  • gender: GrammaticalGender enum 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).

pronounce_ordinal(number, lang, short_scale=True, gender=...)

Spoken ordinal form (1 -> "first"). Languages without a handwritten implementation use the unicode-rbnf fallback.

pronounce_fraction(fraction_word, lang, scale=Scale.LONG)

Speak a fraction string such as "3/4". Currently implemented for Portuguese and Mirandese.

extract_number(text, lang, short_scale=True, ordinals=False)

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")
21

Compound-written languages (German, Dutch, Danish, Swedish) split words such as einundzwanzig, eenentwintig, toogfyrre or tjugoen automatically.

is_fractional(input_str, lang, short_scale=True)

Exact-match test for a fraction word ("half" → 0.5, otherwise False). Use extract_number to pull fractions out of longer phrases.

is_ordinal(input_str, lang)

Exact-match test for an ordinal word ("third" → 3, otherwise False). Implemented for en, pt, mwl, de and da.

numbers_to_digits(utterance, lang, scale=Scale.LONG)

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'

Readers backed by numtag

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.

Enums

  • Scale: Scale.SHORT / Scale.LONG large-number scales.
  • GrammaticalGender: MASCULINE / FEMININE / NEUTRAL.
  • DigitPronunciation: full-number vs digit-by-digit reading styles.

Home · Language notes →