persianize

کتابخونه‌ی سبک و بدون وابستگی (zero-dependency) پایتون برای تبدیل کاراکترهای عربی به معادل فارسی — هم حروف، هم اعداد.

چرا این کتابخونه؟

متن‌های فارسی‌ای که از منابع عربی، کیبوردهای عربی، یا OCR میان، معمولاً حروف و ارقام عربی توشون قاطی فارسیه (مثلاً ي به‌جای ی، یا ١٢٣ به‌جای ۱۲۳). این باعث می‌شه جست‌وجو، مقایسه‌ی رشته‌ها، یا پردازش متن (NLP) نتیجه‌ی اشتباه بده. persianize این مشکل رو با یک تابع ساده حل می‌کنه.

نصب

pip install persianize

یا برای توسعه از روی سورس:

git clone https://github.com/zigzagjimbo/persianize.git
cd persianize
pip install -e ".[dev]"

استفاده به‌عنوان کتابخونه

from persianize import normalize

text = "كتابخانة علي در سال ١٤٠٣ باز شد."
print(normalize(text))
# کتابخانه علی در سال ۱۴۰۳ باز شد.

توابع در دسترس

تابع	کاربرد
normalize(text, digits=True, strip_diacritics=False)	تبدیل کامل: حروف + (اختیاری) اعداد + (اختیاری) حذف اعراب
convert_letters(text)	فقط تبدیل حروف عربی به فارسی
convert_digits(text)	فقط تبدیل ارقام عربی به فارسی
remove_diacritics(text)	حذف اعراب (فتحه، ضمه، کسره، تشدید...) و کشیده

مثال‌های بیشتر

from persianize import convert_letters, convert_digits, remove_diacritics

convert_letters("كتاب")        # 'کتاب'
convert_digits("٠١٢٣")         # '۰۱۲۳'
remove_diacritics("مُحَمَّد")     # 'محمد'

استفاده از خط فرمان (CLI)

# از آرگومان مستقیم
persianize "كتاب علي"

# از فایل
persianize -f input.txt -o output.txt

# از stdin (pipe)
echo "١٤٠٣" | persianize

# بدون تبدیل اعداد
persianize --no-digits "كتاب ١٤٠٣"

# حذف اعراب هم انجام شود
persianize --strip-diacritics "مُحَمَّد"

چه چیزی تبدیل می‌شه؟

حروف:

عربی	فارسی
ي	ی
ك	ک
ة	ه
ى	ی
ؤ	و
ئ	ی
أ / إ	ا

اعداد: ٠١٢٣٤٥٦٧٨٩ → ۰۱۲۳۴۵۶۷۸۹

اعراب (اختیاری با strip_diacritics=True): فتحه، ضمه، کسره، تشدید، سکون، تنوین، مدّ، کشیده

عیب‌یابی (Troubleshooting)

دستور persianize پیدا نمی‌شه (روی ویندوز)

بعضی وقت‌ها بعد از pip install، دستور CLI به‌خاطر اینکه پوشه‌ی Scripts پایتون تو PATH ویندوز نیست کار نمی‌کنه. راه‌حل‌ها:

راه سریع (بدون تغییر تنظیمات):

python -m persianize.cli "متن شما"

راه دائمی: مسیر Scripts پایتون رو پیدا کن و به PATH اضافه کن:

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

مسیری که چاپ می‌شه رو کپی کن و بعد:

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";<مسیر-کپی‌شده>", "User")

سپس ترمینال رو ببند و دوباره باز کن.

بهترین راه (پیشنهادی): به‌جای pip، از pipx برای نصب استفاده کن — pipx خودش PATH رو به‌طور خودکار مدیریت می‌کنه:

pipx install persianize

اجرای تست‌ها

pip install pytest
pytest

لایسنس

MIT