Core Functions#

The Persian package provides a comprehensive set of functions for converting and processing Persian text.

Number Conversion#

convert_en_numbers#

persian.convert_en_numbers(input_str)[source]#

Convert English digits to Persian digits.

Parameters:

input_str (str) – Text that may contain English digits.

Return type:

str

Returns:

A copy of the text with English digits replaced by Persian digits.

Raises:

TypeError – If input_str is not a string.
ValueError – If input_str is None.

Examples

>>> convert_en_numbers("Phone 123")
'Phone ۱۲۳'

Examples:

import persian

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

# In sentences
persian.convert_en_numbers("I have 5 apples")  # 'I have ۵ apples'

# Mixed text
persian.convert_en_numbers("سال 2024")  # 'سال ۲۰۲۴'

# Phone numbers
persian.convert_en_numbers("09123456789")  # '۰۹۱۲۳۴۵۶۷۸۹'

convert_fa_numbers#

persian.convert_fa_numbers(input_str)[source]#

Convert Persian digits to English digits.

Parameters:

input_str (str) – Text that may contain Persian digits.

Return type:

str

Returns:

Text containing English digits instead of Persian digits.

Raises:

TypeError – If input_str is not a string.
ValueError – If input_str is None.

Examples

>>> convert_fa_numbers("۱۲۳")
'123'

Examples:

import persian

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

# In sentences
persian.convert_fa_numbers("من ۵ سیب دارم")  # 'من 5 سیب دارم'

# Dates
persian.convert_fa_numbers("۱۴۰۲/۰۱/۱۵")  # '1402/01/15'

# Mixed content
persian.convert_fa_numbers("قیمت: ۱۵۰۰۰ تومان")  # 'قیمت: 15000 تومان'

convert_ar_numbers#

persian.convert_ar_numbers(input_str)[source]#

Convert Arabic digits to Persian digits.

Parameters:

input_str (str) – Text that may contain Arabic digits.

Return type:

str

Returns:

Text with Arabic digits replaced by Persian digits.

Raises:

TypeError – If input_str is not a string.
ValueError – If input_str is None.

Examples

>>> convert_ar_numbers("٣٤٥")
'۳۴۵'

Examples:

import persian

# Arabic digits to Persian
persian.convert_ar_numbers("٣٤٥")  # '۳۴۵'

# Mixed Arabic and English
persian.convert_ar_numbers("٣٤٥ and 678")  # '۳۴۵ and 678'

# In Arabic text with numbers
persian.convert_ar_numbers("العدد ٩٨٧")  # 'العدد ۹۸۷'

Character Conversion#

convert_en_characters#

persian.convert_en_characters(input_str)[source]#

Convert English keyboard characters to standard Persian characters.

Parameters:

input_str (str) – Text typed using an English keyboard layout.

Return type:

str

Returns:

New text containing the mapped Persian characters.

Raises:

TypeError – If input_str is not a string.
ValueError – If input_str is None.

Examples

>>> convert_en_characters("sghl")
'سلام'

Examples:

import persian

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

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

# Mixed content (only converts English keyboard chars)
persian.convert_en_characters("sghl 123")  # 'سلام 123'

convert_ar_characters#

persian.convert_ar_characters(input_str)[source]#

Convert Arabic characters to their Persian equivalents.

Parameters:

input_str (str) – Text that may contain Arabic characters.

Return type:

str

Returns:

Text where Arabic characters are replaced with Persian characters.

Raises:

TypeError – If input_str is not a string.
ValueError – If input_str is None.

Examples

>>> convert_ar_characters("علي")
'علی'

Examples:

import persian

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

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

# Fix common Arabic characters in Persian text
persian.convert_ar_characters("كيك خوشمزه")  # 'کیک خوشمزه'

remove_arabic_diacritics#

persian.remove_arabic_diacritics(input_str)[source]#

Remove Arabic diacritic (tashkeel) characters from the text.

Parameters:

input_str (str) – Text that may include combining Arabic diacritics.

Return type:

str

Returns:

Text without Arabic diacritics.

Raises:

TypeError – If input_str is not a string.
ValueError – If input_str is None.

Examples:

import persian

# Remove Arabic diacritics (harakat/tashkeel)
persian.remove_arabic_diacritics("مَرحَباً")  # 'مرحبا'

# Clean text with various diacritics
persian.remove_arabic_diacritics("الْحَمْدُ لِلَّهِ")  # 'الحمد لله'

Text Processing#

convert_fa_spaces#

persian.convert_fa_spaces(input_value)[source]#

Replace improper spaces around Persian affixes with zero-width non-joiners.

Parameters:

input_value (str) – Persian text that may include incorrect spaces.

Return type:

str

Returns:

Text where required affix boundaries use half-space characters.

Raises:

TypeError – If input_value is not a string.
ValueError – If input_value is None.

Examples

>>> convert_fa_spaces("می روم به خانه")
'می‌روم به خانه'

Examples:

import persian

# Fix spaces with Persian affixes
persian.convert_fa_spaces("می روم")  # 'می‌روم'

# Multiple fixes in one sentence
persian.convert_fa_spaces("من می روم به خانه ام")  # 'من می‌روم به خانه‌ام'

# Common prefixes
persian.convert_fa_spaces("نمی دانم")  # 'نمی‌دانم'

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

decode_url#

persian.decode_url(input_str)[source]#

Decode percent-encoded Persian characters in URLs.

Parameters:

input_str (str) – URL containing percent-encoded segments.

Return type:

str

Returns:

Decoded URL string.

Raises:

TypeError – If input_str is not a string.
ValueError – If input_str is None.

Examples

>>> decode_url("https://example/%D8%B5%D9%81%D8%AD%D9%87")
'https://example/صفحه'

Examples:

import persian

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

# Full URL with multiple Persian segments
url = "https://example.com/%D9%85%D9%82%D8%A7%D9%84%D9%87/%D8%A2%D9%85%D9%88%D8%B2%D8%B4"
persian.decode_url(url)  # 'https://example.com/مقاله/آموزش'

# Query parameters
url = "https://example.com/search?q=%D8%AC%D8%B3%D8%AA%D8%AC%D9%88"
persian.decode_url(url)  # 'https://example.com/search?q=جستجو'

normalize_persian#

persian.normalize_persian(input_str, *, convert_numbers=True, convert_characters=True, fix_spacing=True)[source]#

Normalize Persian text by applying optional conversions.

Parameters:

input_str (str) – Text to normalize.
convert_numbers (bool) – Whether to convert Arabic digits to Persian.
convert_characters (bool) – Whether to convert Arabic characters to Persian.
fix_spacing (bool) – Whether to fix improper spaces with ZWNJ.

Return type:

str

Returns:

Normalized Persian text.

Raises:

TypeError – If input_str is not a string.
ValueError – If input_str is None.

Examples

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

Examples:

import persian

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

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

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

# Custom combination
persian.normalize_persian(
    "علي ٣٤٥ می آید",
    convert_numbers=True,
    convert_characters=True,
    fix_spacing=False
)  # 'علی ۳۴۵ می آید'

# Complete text normalization
text = "كتاب شماره ٣ را می خوانم"
persian.normalize_persian(text)  # 'کتاب شماره ۳ را می‌خوانم'