Persian - Fast Python Toolkit for Persian Language Localization#

Tests

A fast Python toolkit for Persian (Farsi) text normalization, number/character conversion, and localization utilities.

Key Features#

  • Fast: 3-5× faster number and character conversions using str.translate

  • Type-Safe: Ships with native type hints (py.typed) and strict mypy configuration

  • Modern Python: Requires Python 3.10+ with full support for 3.10-3.15

  • Comprehensive: Complete set of utilities for Persian text processing

  • Well-Tested: Extensive test coverage with pytest

  • Zero Dependencies: No external runtime dependencies

Installation#

pip install persian

Requirements: Python 3.10 or higher

For older Python versions (3.6-3.9):

pip install "persian<1.0.0"

Quick Start#

import persian

# Convert Arabic characters to Persian
persian.convert_ar_characters("علي")  # 'علی'

# Convert Persian numbers to English
persian.convert_fa_numbers("۱۳۷۱")    # '1371'

# Convert English numbers to Persian
persian.convert_en_numbers("345")     # '۳۴۵'

# Convert English keyboard to Persian
persian.convert_en_characters("sghl") # 'سلام'

# Fix Persian spacing
persian.convert_fa_spaces("آمده ای")  # 'آمده‌ای'

# Decode Persian URLs
persian.decode_url("https://example.com/%D8%B5%D9%81%D8%AD%D9%87")
# 'https://example.com/صفحه'

# Normalize Persian text (one-stop helper)
persian.normalize_persian("سلام ٣٤٥ می آیم")  # 'سلام ۳۴۵ می‌آیم'

Performance#

Version 1.0.0 includes major speedups:

  • 3–5× faster number and keyboard conversions via str.translate

  • 2–3× faster spacing fixes using pre-compiled regular expressions

  • ~50% lower memory usage on large strings thanks to fewer temporary objects

Contents#

User Guide

API Reference

Additional Information

Indices and tables#