extended_data.primitives.numbers

Number transformation utilities.

This module provides functions for converting numbers to/from words, Roman numerals, and various formatting operations.

Module Contents

Functions

_normalize_language_code	Return the concrete num2words language key or raise ValueError.
_validate_currency_code	Validate the provided currency for the resolved language code.
to_roman	Convert integer to Roman numerals.
from_roman	Convert Roman numerals to integer.
number_to_words	Convert integers or floats to their word representation.
number_to_ordinal	Convert number to ordinal words.
number_to_currency	Convert number to currency words.

Data

_ROMAN_VALUES
_MAX_ROMAN_VALUE

API

extended_data.primitives.numbers._ROMAN_VALUES: Final[dict[str, int]] = None

extended_data.primitives.numbers._normalize_language_code(lang: str) → str

Return the concrete num2words language key or raise ValueError.

extended_data.primitives.numbers._validate_currency_code(currency: str, lang_code: str) → str

Validate the provided currency for the resolved language code.

extended_data.primitives.numbers._MAX_ROMAN_VALUE: Final[int] = 3999

extended_data.primitives.numbers.to_roman(number: int) → str

Convert integer to Roman numerals.

Args: number: Integer between 1 and 3999

Returns: Roman numeral string

Example: >>> to_roman(42) ‘XLII’

extended_data.primitives.numbers.from_roman(numeral: str) → int

Convert Roman numerals to integer.

Args: numeral: Roman numeral string

Returns: Integer value

Example: >>> from_roman(‘XLII’) 42

extended_data.primitives.numbers.number_to_words(number: float, lang: str = 'en') → str

Convert integers or floats to their word representation.

Supports both integers and floats. Floats are converted using “point” notation.

Args: number: Integer or float to convert lang: Language code (default: ‘en’). Supported languages include ‘en’, ‘es’, ‘fr’, ‘de’, and many others (see num2words documentation)

Returns: Number as words

Raises: ValueError: If the specified language is empty or not supported by num2words

Examples: >>> number_to_words(42) ‘forty-two’ >>> number_to_words(42.5) ‘forty-two point five’

extended_data.primitives.numbers.number_to_ordinal(number: int, lang: str = 'en') → str

Convert number to ordinal words.

Args: number: Integer to convert lang: Language code (default: ‘en’). Supported languages include ‘en’, ‘es’, ‘fr’, ‘de’, and many others (see num2words documentation)

Returns: Ordinal as words

Raises: ValueError: If the specified language is empty or not supported by num2words

Example: >>> number_to_ordinal(42) ‘forty-second’

extended_data.primitives.numbers.number_to_currency(amount: float, currency: str = 'USD', lang: str = 'en') → str

Convert number to currency words.

Args: amount: Amount to convert currency: Currency code (default: ‘USD’). Common codes include ‘USD’, ‘EUR’, ‘GBP’, etc. Supported currencies vary by language. The code is treated case-insensitively. lang: Language code (default: ‘en’). Supported languages include ‘en’, ‘es’, ‘fr’, ‘de’, and many others (see num2words documentation)

Returns: Currency as words

Raises: ValueError: If the specified language or currency code is empty or not supported by num2words for the given language

Example: >>> number_to_currency(42.50) ‘forty-two dollars and fifty cents’