Migration Guide: num2words → num2words2

Complete guide for migrating from the original num2words library to num2words2.

Why Migrate?

Active maintenance - Regular updates and bug fixes
AI/LLM optimization - Better support for modern applications
Enhanced language support - More languages and improved implementations
Better reliability - Critical bug fixes for production use
Future-proof - Aligned with evolving AI/ML ecosystem

Quick Start (TL;DR)

# 1. Run migration script
curl -O https://raw.githubusercontent.com/jqueguiner/num2words/master/migrate_to_num2words2.py
python migrate_to_num2words2.py --dry-run .  # Preview changes
python migrate_to_num2words2.py .            # Apply changes

# 2. Install new package
pip install num2words2
pip uninstall num2words  # Optional: remove old package

# 3. Update requirements.txt
# Replace "num2words" with "num2words2"

Detailed Migration Steps

Step 1: Assessment

First, check what needs to be migrated in your project:

# Find all files with num2words imports
grep -r "num2words" --include="*.py" .

# Check requirements files
grep -r "num2words" requirements*.txt setup.py pyproject.toml

Step 2: Automated Migration

Use our migration script for Python code:

# Download the script
curl -O https://raw.githubusercontent.com/jqueguiner/num2words/master/migrate_to_num2words2.py

# Preview changes (recommended)
python migrate_to_num2words2.py --dry-run /path/to/your/project

# Apply changes
python migrate_to_num2words2.py /path/to/your/project

The script handles these import patterns:

Before	After
`from num2words import num2words`	`from num2words2 import num2words`
`import num2words`	`import num2words2 as num2words`
`from num2words.lang_en import Num2Word_EN`	`from num2words2.lang_en import Num2Word_EN`

Step 3: Manual Updates

Requirements Files

Update your dependency declarations:

requirements.txt:

- num2words>=0.5.12
+ num2words2>=0.5.15

pyproject.toml:

dependencies = [
-    "num2words>=0.5.12",
+    "num2words2>=0.5.15",
]

setup.py:

install_requires=[
-    "num2words>=0.5.12",
+    "num2words2>=0.5.15",
]

Docker Files

Update Dockerfiles:

- RUN pip install num2words
+ RUN pip install num2words2

CI/CD Configurations

Update CI configuration files:

.github/workflows/test.yml:

- pip install num2words
+ pip install num2words2

tox.ini:

deps =
-    num2words
+    num2words2

Step 4: Testing

Verify your migration works correctly:

# test_migration.py
from num2words2 import num2words

def test_basic_functionality():
    """Test basic num2words2 functionality"""
    # Cardinal numbers
    assert num2words(42) == "forty-two"
    assert num2words(1000) == "one thousand"

    # Different languages
    assert num2words(42, lang='es') == "cuarenta y dos"
    assert num2words(42, lang='fr') == "quarante-deux"

    # Ordinal numbers
    assert num2words(42, to='ordinal') == "forty-second"

    # Currency
    result = num2words(42.50, to='currency', lang='en')
    assert 'forty' in result and 'fifty' in result

def test_edge_cases():
    """Test edge cases and bug fixes"""
    # Test negative numbers (fixed in num2words2)
    assert num2words(-1, lang='bn') == 'ঋণাত্মক এক'

    # Test float handling (improved in num2words2)
    assert num2words(1.5, lang='en') == 'one point five'

if __name__ == "__main__":
    test_basic_functionality()
    test_edge_cases()
    print("✅ All tests passed! Migration successful.")

Run the test:

python test_migration.py

Common Migration Scenarios

Scenario 1: Simple Import Replacement

Before:

from num2words import num2words

def convert_number(n):
    return num2words(n)

After:

from num2words2 import num2words

def convert_number(n):
    return num2words(n)

Scenario 2: Direct Module Import

Before:

import num2words

def convert_number(n, lang='en'):
    return num2words.num2words(n, lang=lang)

After:

import num2words2 as num2words

def convert_number(n, lang='en'):
    return num2words.num2words(n, lang=lang)

Scenario 3: Submodule Imports

Before:

from num2words.lang_en import Num2Word_EN

converter = Num2Word_EN()

After:

from num2words2.lang_en import Num2Word_EN

converter = Num2Word_EN()

Scenario 4: Gradual Migration

For large codebases, you can migrate gradually:

# compatibility.py - Create a compatibility layer
try:
    from num2words2 import num2words
    print("Using num2words2")
except ImportError:
    from num2words import num2words
    print("Fallback to num2words")

# Use this in your codebase
from .compatibility import num2words

Scenario 5: Library/Framework Integration

Flask Example:

# Before
from flask import Flask
from num2words import num2words

# After
from flask import Flask
from num2words2 import num2words

app = Flask(__name__)

@app.route('/convert/<int:number>')
def convert_endpoint(number):
    return num2words(number)

FastAPI Example:

# Before
from fastapi import FastAPI
from num2words import num2words

# After
from fastapi import FastAPI
from num2words2 import num2words

app = FastAPI()

@app.get("/convert/{number}")
def convert_number(number: int):
    return {"result": num2words(number)}

Rollback Instructions

If you need to rollback the migration:

Automatic Rollback

The migration script creates backups:

# Find all backup files
find . -name "*.num2words_backup"

# Restore all files
for file in $(find . -name "*.num2words_backup"); do
    original="${file%.num2words_backup}"
    cp "$file" "$original"
    echo "Restored $original"
done

# Clean up backup files
find . -name "*.num2words_backup" -delete

Manual Rollback

Revert imports in Python files
Update requirements files back to num2words
Reinstall original package: pip install num2words
Remove new package: pip uninstall num2words2

Troubleshooting

Common Issues

Issue: ImportError after migration

ImportError: No module named 'num2words2'

Solution: Install num2words2: pip install num2words2

Issue: Different output than expected

AssertionError: Expected 'forty-two' but got 'forty two'

Solution: Check if you're using a different language or locale setting.

Issue: Migration script doesn't find files

No Python files found to scan.

Solution: Ensure you're running the script in the correct directory and have Python files.

Performance Comparison

num2words2 maintains the same performance characteristics as the original:

import time
from num2words2 import num2words

# Benchmark
start = time.time()
for i in range(10000):
    num2words(i)
end = time.time()

print(f"Converted 10,000 numbers in {end - start:.2f} seconds")

Getting Help

Documentation: https://github.com/jqueguiner/num2words
Issues: https://github.com/jqueguiner/num2words/issues
Discussions: https://github.com/jqueguiner/num2words/discussions

Migration Checklist

Use this checklist to ensure complete migration:

FAQ

Q: Is num2words2 compatible with the original num2words? A: Yes, num2words2 is designed as a drop-in replacement with full backward compatibility.

Q: Will my existing code break? A: No, the API is identical. Only the import statements need to change.

Q: Can I use both libraries simultaneously? A: Not recommended as they may conflict. Choose one for your project.

Q: What about performance? A: Performance is equivalent or better than the original library.

Q: Are all languages supported? A: Yes, all original languages plus additional languages (Armenian, Mongolian, Shona).

Need more help? Check our migration examples or open an issue.

FilesExpand file tree

MIGRATION_GUIDE.md

Latest commit

History

MIGRATION_GUIDE.md

File metadata and controls

Migration Guide: num2words → num2words2

Why Migrate?

Quick Start (TL;DR)

Detailed Migration Steps

Step 1: Assessment

Step 2: Automated Migration

Step 3: Manual Updates

Requirements Files

Docker Files

CI/CD Configurations

Step 4: Testing

Common Migration Scenarios

Scenario 1: Simple Import Replacement

Scenario 2: Direct Module Import

Scenario 3: Submodule Imports

Scenario 4: Gradual Migration

Scenario 5: Library/Framework Integration

Rollback Instructions

Automatic Rollback

Manual Rollback

Troubleshooting

Common Issues

Performance Comparison

Getting Help

Migration Checklist

FAQ