0
# num2words
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: num2words
7
- **Language**: Python
8
- **Installation**: `pip install num2words`
9
10
## Core Imports
11
12
```python
13
from num2words import num2words
14
```
15
16
Access to available languages and conversion types:
17
18
```python
19
from num2words import CONVERTER_CLASSES, CONVERTES_TYPES
20
```
21
22
## Basic Usage
23
24
```python
25
from num2words import num2words
26
27
# Basic cardinal number conversion (default English)
28
result = num2words(42)
29
print(result) # "forty-two"
30
31
# Convert to ordinal form
32
result = num2words(42, to='ordinal')
33
print(result) # "forty-second"
34
35
# Convert in different language
36
result = num2words(42, lang='fr')
37
print(result) # "quarante-deux"
38
39
# Convert to currency format
40
result = num2words(42.50, to='currency', lang='en')
41
print(result) # "forty-two euros, fifty cents"
42
43
# Year format
44
result = num2words(1984, to='year')
45
print(result) # "nineteen eighty-four"
46
```
47
48
## Architecture
49
50
The num2words library uses a pluggable architecture where each language is implemented as a separate converter class inheriting from a base class:
51
52
- **Num2Word_Base**: Foundation class providing core conversion logic and currency handling
53
- **Language Converters**: 50+ language-specific classes implementing localized number conversion rules
54
- **CONVERTER_CLASSES**: Registry mapping language codes to converter instances
55
- **Conversion Types**: Support for cardinal, ordinal, year, and currency formats
56
57
This design makes the library easily extensible for new languages and locales while maintaining consistent behavior across all supported languages.
58
59
## Capabilities
60
61
### Number Conversion
62
63
Core functionality for converting numbers to word representations in multiple languages and formats.
64
65
```python { .api }
66
def num2words(number, ordinal=False, lang='en', to='cardinal', **kwargs):
67
"""
68
Convert numbers to words in specified language and format.
69
70
Parameters:
71
- number: int/float/str - Number to convert
72
- ordinal: bool - Backward compatibility for ordinal conversion
73
- lang: str - Language code (default: 'en')
74
- to: str - Conversion type ('cardinal', 'ordinal', 'ordinal_num', 'year', 'currency')
75
- **kwargs: Additional language-specific arguments
76
77
Returns:
78
str - Number converted to words
79
80
Raises:
81
NotImplementedError - For unsupported languages or conversion types
82
"""
83
```
84
85
[Number Conversion](./number-conversion.md)
86
87
### Language Support
88
89
Access to 50+ supported languages and their specific conversion capabilities.
90
91
```python { .api }
92
CONVERTER_CLASSES: dict # Maps language codes to converter instances
93
CONVERTES_TYPES: list # Available conversion types
94
```
95
96
[Language Support](./language-support.md)
97
98
### Base Converter Architecture
99
100
Foundation classes and methods for implementing custom language converters.
101
102
```python { .api }
103
class Num2Word_Base:
104
def to_cardinal(self, value): ...
105
def to_ordinal(self, value): ...
106
def to_currency(self, val, currency='EUR', **kwargs): ...
107
def to_year(self, value, **kwargs): ...
108
```
109
110
[Base Converter Architecture](./base-converter.md)
111
112
### Currency Conversion
113
114
Specialized functionality for converting numbers to currency representations with proper localization.
115
116
```python { .api }
117
def to_currency(val, currency='EUR', cents=True, separator=',', adjective=False):
118
"""
119
Convert number to currency format.
120
121
Parameters:
122
- val: Numeric value
123
- currency: str - Currency code (default: 'EUR')
124
- cents: bool - Verbose cents representation
125
- separator: str - Cent separator character
126
- adjective: bool - Include currency adjective prefix
127
128
Returns:
129
str - Formatted currency string
130
"""
131
```
132
133
[Currency Conversion](./currency-conversion.md)
134
135
### Utility Functions
136
137
Helper functions for number parsing, currency processing, and compatibility support.
138
139
```python { .api }
140
def parse_currency_parts(value, is_int_with_cents=True): ...
141
def splitbyx(n, x, format_int=True): ...
142
def get_digits(n): ...
143
```
144
145
[Utility Functions](./utility-functions.md)
146
147
### CLI Functions
148
149
Utility functions for discovering available languages and conversion types, primarily used by the command-line interface.
150
151
```python { .api }
152
def get_languages():
153
"""
154
Get sorted list of available language codes.
155
156
Returns:
157
list: Sorted list of supported language codes
158
"""
159
160
def get_converters():
161
"""
162
Get sorted list of available conversion types.
163
164
Returns:
165
list: Sorted list of supported conversion types
166
"""
167
```
168
169
## Types
170
171
```python { .api }
172
# Main conversion function type
173
NumericInput = Union[int, float, str, Decimal]
174
175
# Language codes (examples - see language-support.md for complete list)
176
LanguageCode = Literal[
177
'en', 'fr', 'es', 'de', 'it', 'pt', 'ru', 'ja', 'ko', 'zh',
178
'ar', 'hi', 'bn', 'th', 'vi', 'tr', 'pl', 'nl', 'sv', 'no',
179
'da', 'fi', 'cs', 'sk', 'hu', 'ro', 'bg', 'hr', 'sl', 'sr',
180
'uk', 'be', 'lt', 'lv', 'et', 'is', 'mt', 'cy', 'ga', 'gd',
181
'eu', 'ca', 'gl', 'ast', 'oc', 'co', 'rm', 'fur', 'lij', 'pms',
182
# ... and regional variants like 'en_IN', 'en_NG', 'fr_BE', etc.
183
]
184
185
# Conversion types
186
ConversionType = Literal['cardinal', 'ordinal', 'ordinal_num', 'year', 'currency']
187
188
# Currency codes (examples - see currency-conversion.md for complete list)
189
CurrencyCode = str # Various currency codes supported by individual language converters
190
```