or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

base-converter.mdcurrency-conversion.mdindex.mdlanguage-support.mdnumber-conversion.mdutility-functions.md
tile.json

tessl/pypi-num2words

Modules to convert numbers to words in multiple languages with support for 50+ locales.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/num2words@0.5.x

To install, run

npx @tessl/cli install tessl/pypi-num2words@0.5.0

index.mddocs/

num2words

A comprehensive Python library that converts numbers to words in 50+ languages. The library supports multiple output formats including cardinal numbers (forty-two), ordinal numbers (forty-second), years, and currency representations with proper localization for each language.

Package Information

  • Package Name: num2words
  • Language: Python
  • Installation: pip install num2words

Core Imports

from num2words import num2words

Access to available languages and conversion types:

from num2words import CONVERTER_CLASSES, CONVERTES_TYPES

Basic Usage

from num2words import num2words

# Basic cardinal number conversion (default English)
result = num2words(42)
print(result)  # "forty-two"

# Convert to ordinal form
result = num2words(42, to='ordinal')
print(result)  # "forty-second"

# Convert in different language
result = num2words(42, lang='fr')
print(result)  # "quarante-deux"

# Convert to currency format
result = num2words(42.50, to='currency', lang='en')
print(result)  # "forty-two euros, fifty cents"

# Year format
result = num2words(1984, to='year')
print(result)  # "nineteen eighty-four"

Architecture

The num2words library uses a pluggable architecture where each language is implemented as a separate converter class inheriting from a base class:

  • Num2Word_Base: Foundation class providing core conversion logic and currency handling
  • Language Converters: 50+ language-specific classes implementing localized number conversion rules
  • CONVERTER_CLASSES: Registry mapping language codes to converter instances
  • Conversion Types: Support for cardinal, ordinal, year, and currency formats

This design makes the library easily extensible for new languages and locales while maintaining consistent behavior across all supported languages.

Capabilities

Number Conversion

Core functionality for converting numbers to word representations in multiple languages and formats.

def num2words(number, ordinal=False, lang='en', to='cardinal', **kwargs):
    """
    Convert numbers to words in specified language and format.
    
    Parameters:
    - number: int/float/str - Number to convert
    - ordinal: bool - Backward compatibility for ordinal conversion
    - lang: str - Language code (default: 'en')
    - to: str - Conversion type ('cardinal', 'ordinal', 'ordinal_num', 'year', 'currency')
    - **kwargs: Additional language-specific arguments
    
    Returns:
    str - Number converted to words
    
    Raises:
    NotImplementedError - For unsupported languages or conversion types
    """

Number Conversion

Language Support

Access to 50+ supported languages and their specific conversion capabilities.

CONVERTER_CLASSES: dict  # Maps language codes to converter instances
CONVERTES_TYPES: list    # Available conversion types

Language Support

Base Converter Architecture

Foundation classes and methods for implementing custom language converters.

class Num2Word_Base:
    def to_cardinal(self, value): ...
    def to_ordinal(self, value): ...
    def to_currency(self, val, currency='EUR', **kwargs): ...
    def to_year(self, value, **kwargs): ...

Base Converter Architecture

Currency Conversion

Specialized functionality for converting numbers to currency representations with proper localization.

def to_currency(val, currency='EUR', cents=True, separator=',', adjective=False):
    """
    Convert number to currency format.
    
    Parameters:
    - val: Numeric value
    - currency: str - Currency code (default: 'EUR')
    - cents: bool - Verbose cents representation
    - separator: str - Cent separator character
    - adjective: bool - Include currency adjective prefix
    
    Returns:
    str - Formatted currency string
    """

Currency Conversion

Utility Functions

Helper functions for number parsing, currency processing, and compatibility support.

def parse_currency_parts(value, is_int_with_cents=True): ...
def splitbyx(n, x, format_int=True): ...
def get_digits(n): ...

Utility Functions

CLI Functions

Utility functions for discovering available languages and conversion types, primarily used by the command-line interface.

def get_languages():
    """
    Get sorted list of available language codes.
    
    Returns:
        list: Sorted list of supported language codes
    """

def get_converters():
    """
    Get sorted list of available conversion types.
    
    Returns:
        list: Sorted list of supported conversion types
    """

Types

# Main conversion function type
NumericInput = Union[int, float, str, Decimal]

# Language codes (examples - see language-support.md for complete list)
LanguageCode = Literal[
    'en', 'fr', 'es', 'de', 'it', 'pt', 'ru', 'ja', 'ko', 'zh',
    'ar', 'hi', 'bn', 'th', 'vi', 'tr', 'pl', 'nl', 'sv', 'no',
    'da', 'fi', 'cs', 'sk', 'hu', 'ro', 'bg', 'hr', 'sl', 'sr',
    'uk', 'be', 'lt', 'lv', 'et', 'is', 'mt', 'cy', 'ga', 'gd',
    'eu', 'ca', 'gl', 'ast', 'oc', 'co', 'rm', 'fur', 'lij', 'pms',
    # ... and regional variants like 'en_IN', 'en_NG', 'fr_BE', etc.
]

# Conversion types
ConversionType = Literal['cardinal', 'ordinal', 'ordinal_num', 'year', 'currency']

# Currency codes (examples - see currency-conversion.md for complete list)
CurrencyCode = str  # Various currency codes supported by individual language converters