Quick Start Guide#

This guide will get you started with the Persian library in minutes.

Basic Import#

Start by importing the library:

import persian

All functions are available directly from the persian module.

Number Conversions#

English to Persian#

Convert English digits to Persian digits:

persian.convert_en_numbers("123")
# '۱۲۳'

persian.convert_en_numbers("Price: 1500")
# 'Price: ۱۵۰۰'

Persian to English#

Convert Persian digits to English digits:

persian.convert_fa_numbers("۱۲۳")
# '123'

persian.convert_fa_numbers("قیمت: ۱۵۰۰")
# 'قیمت: 1500'

Arabic to Persian#

Convert Arabic digits to Persian digits:

persian.convert_ar_numbers("٣٤٥")
# '۳۴۵'

Character Conversions#

English Keyboard to Persian#

Convert text typed with English keyboard to Persian:

persian.convert_en_characters("sghl")
# 'سلام'

persian.convert_en_characters("sghl Hkd Hvhgdk")
# 'سلام خوب حوالیک'

Arabic to Persian Characters#

Convert Arabic characters to Persian equivalents:

persian.convert_ar_characters("علي")
# 'علی'

persian.convert_ar_characters("مرحبا يا صديقي")
# 'مرحبا یا صدیقی'

Text Processing#

Fix Persian Spacing#

Replace improper spaces with zero-width non-joiners (ZWNJ):

persian.convert_fa_spaces("می روم")
# 'می‌روم'

persian.convert_fa_spaces("کتاب های من")
# 'کتاب‌های من'

Decode Persian URLs#

Decode percent-encoded Persian characters in URLs:

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

Remove Arabic Diacritics#

Remove Arabic diacritics (harakat/tashkeel) from text:

persian.remove_arabic_diacritics("مَرحَباً")
# 'مرحبا'

All-in-One Normalization#

Use normalize_persian() to apply multiple conversions at once:

persian.normalize_persian("سلام ٣٤٥ می آیم")
# 'سلام ۳۴۵ می‌آیم'

This function:

  1. Converts Arabic digits to Persian

  2. Converts Arabic characters to Persian

  3. Fixes spacing issues

Custom Normalization#

You can control which conversions to apply:

# Only convert numbers
persian.normalize_persian(
    "سلام ٣٤٥",
    convert_characters=False,
    fix_spacing=False
)
# 'سلام ۳۴۵'

# Only fix spacing
persian.normalize_persian(
    "می آیم",
    convert_numbers=False,
    convert_characters=False
)
# 'می‌آیم'

Detection Utilities#

Check for Persian Digits#

persian.contains_persian_digits("۱۲۳")  # True
persian.contains_persian_digits("123")  # False

Check for Arabic Digits#

persian.contains_arabic_digits("٣٤٥")  # True
persian.contains_arabic_digits("۳۴۵")  # False

Check for Persian Text#

persian.is_persian_text("سلام")  # True
persian.is_persian_text("Hello")  # False

Practical Examples#

Clean User Input#

def clean_persian_input(text: str) -> str:
    """Clean and normalize Persian user input."""
    return persian.normalize_persian(text)

user_input = "سلام من می روم به خانه"
clean_text = clean_persian_input(user_input)
# 'سلام من می‌روم به خانه'

Process Mixed Content#

def process_text(text: str) -> str:
    """Process text containing both Persian and English."""
    # First, convert Arabic to Persian
    text = persian.convert_ar_characters(text)
    text = persian.convert_ar_numbers(text)

    # Fix spacing
    text = persian.convert_fa_spaces(text)

    return text

mixed = "كتاب شماره ٣ را می خوانم"
result = process_text(mixed)
# 'کتاب شماره ۳ را می‌خوانم'

Validate Persian Content#

def validate_persian(text: str) -> bool:
    """Check if text contains Persian characters."""
    if not persian.is_persian_text(text):
        raise ValueError("Text must contain Persian characters")
    return True

try:
    validate_persian("سلام")  # OK
    validate_persian("Hello")  # Raises ValueError
except ValueError as e:
    print(f"Error: {e}")

Common Patterns#

Web Forms#

Clean Persian input from web forms:

from persian import normalize_persian

def process_form_data(form_data: dict) -> dict:
    """Normalize all Persian text fields in form data."""
    for key, value in form_data.items():
        if isinstance(value, str):
            form_data[key] = normalize_persian(value)
    return form_data

Database Storage#

Normalize before storing in database:

import persian

class Article:
    def __init__(self, title: str, content: str):
        self.title = persian.normalize_persian(title)
        self.content = persian.normalize_persian(content)

Display URLs#

Decode URLs for display:

import persian

encoded_urls = [
    "https://example.com/%D8%B5%D9%81%D8%AD%D9%87",
    "https://example.com/%D9%85%D9%82%D8%A7%D9%84%D9%87",
]

readable_urls = [persian.decode_url(url) for url in encoded_urls]
# [
#     'https://example.com/صفحه',
#     'https://example.com/مقاله'
# ]

Error Handling#

All functions validate inputs and raise clear exceptions:

Type Errors#

try:
    persian.convert_en_numbers(123)
except TypeError as e:
    print(e)  # "input_str must be str, got int"

Value Errors#

try:
    persian.convert_en_numbers(None)
except ValueError as e:
    print(e)  # "input_str cannot be None"

Empty Strings#

Empty strings are accepted and return empty strings:

persian.convert_en_numbers("")  # ''
persian.normalize_persian("")   # ''

Next Steps#