num2persian 2.0.1

Convert numbers to Persian words

num2persian

Convert numbers to Persian words. Available in both Python and TypeScript implementations.

📖 فارسی بخوانید Persian

Installation

pip install num2persian

TypeScript Implementation

This project also includes a TypeScript implementation available as an NPM package.

npm install persian-number-words

For more information, see typescript/README.md.

Usage

Python API

import num2persian

# Convert numbers to Persian words
print(num2persian.to_words(42))        # Output: چهل و دو
print(num2persian.to_words(1234))      # Output: یک هزار و دویست و سی و چهار
print(num2persian.to_words(-567))      # Output: منفی پانصد و شصت و هفت
print(num2persian.to_words("890"))     # Output: هشتصد و نود

Command Line

# Convert a number to Persian words
num2persian 2025

# Show version
num2persian --version

# Show help
num2persian --help

Features

• Convert integers and decimal numbers (positive, negative, and zero) to Persian words
• Accept string inputs that can be converted to numbers
• Proper Persian grammar with correct "و" (and) placement
• Support for very large numbers with proper Persian word naming
• Decimal numbers with appropriate Persian suffixes (دهم, صدم, هزارم, etc.)
• Command-line interface
• Comprehensive test coverage

Examples

from num2persian import to_words

# Basic numbers
to_words(0)      # "صفر"
to_words(15)     # "پانزده"
to_words(100)    # "یکصد"

# Compound numbers
to_words(123)    # "یکصد و بیست و سه"
to_words(2025)   # "دو هزار و بیست و پنج"

# Large numbers
to_words(1000000)         # "یک میلیون"
to_words(1000000000)      # "یک میلیارد"
to_words(1000000000000)   # "یک تریلیون"

# Decimal numbers
to_words(3.14)   # "سه ممیز چهارده صدم"
to_words(0.5)    # "صفر ممیز پنج دهم"
to_words(1.234)  # "یک ممیز دویست و سی و چهار هزارم"
to_words(12.25)  # "دوازده ممیز بیست و پنج صدم"

# Negative numbers
to_words(-42)    # "منفی چهل و دو"

Development

Setup

# Clone the repository
git clone https://github.com/yourusername/num2persian.git
cd num2persian

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

Testing

# Run tests
pytest

# Run tests with coverage
pytest --cov=persian_numbers

Building

# Build wheel and source distribution
python -m build

# Install build dependencies
pip install build twine

# Upload to TestPyPI (replace with actual credentials)
twine upload --repository testpypi dist/*

# Upload to PyPI (replace with actual credentials)
twine upload dist/*

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! This project includes both Python and TypeScript implementations:

• Python: Located in the root directory
• TypeScript: Located in the typescript/ directory

Both implementations are tested in CI. Please feel free to submit a Pull Request.