Home

به مستندات جامع (Wiki) ParsiKit Library خوش آمدید! 🎉

در این صفحه، صفر تا صد کار با این کتابخانه را به زبان ساده، همراه با مثال‌های عملی و جدول‌های راهنما یاد می‌گیرید. این کتابخانه ابزار دست شماست تا با خیال راحت با داده‌های فارسی (متن، عدد و پول) در پایتون کار کنید.

---

📥 نصب و راه‌اندازی

ابتدا مطمئن شوید که نسخه پایتون شما ۳.۱۰ یا بالاتر است. سپس با دستور زیر کتابخانه را نصب کنید:

pip install parsikit

---

📚 فهرست ماژول‌ها

کتابخانه‌ی ParsiKit از ۳ بخش اصلی تشکیل شده است:

1. parsikit.text: تمیزکاری و استانداردسازی متن.
2. parsikit.number: تبدیل اعداد انگلیسی، عربی و فارسی به یکدیگر.
3. parsikit.currency: قالب‌بندی و تبدیل واحدهای پولی ایران.

---

۱. ماژول متن (parsikit.text) 📝

این ماژول برای اصلاح متن‌های ورودی کاربران (مثل جایگزینی حروف عربی با فارسی، اصلاح نیم‌فاصله‌ها و حذف فاصله‌های اضافه) طراحی شده است.

🧰 توابع ماژول متن

نام تابع	ورودی	خروجی	کاربرد
standardize_persian	رشته (str)	رشته (str)	تبدیل حروف عربی (ي، ك)، ایجاد نیم‌فاصله‌ی خودکار برای پیشوند/پسوند، و حذف فاصله‌های اضافی.

💻 مثال استفاده

from parsikit.text import standardize_persian

# ۱. اصلاح حروف و اعداد عربی
text1 = "ي كتاب خوب با قيمت ١٢٣"
print(standardize_persian(text1))
# خروجی: 'ی کتاب خوب با قیمت ۱۲۳'

# ۲. اصلاح نیم‌فاصله‌ها (چسباندن پیشوندها و پسوندها)
text2 = "من می روم تا کتاب ها را بیاورم"
print(standardize_persian(text2))
# خروجی: 'من می‌روم تا کتاب‌ها را بیاورم'

# ۳. حذف فاصله‌های چندگانه
text3 = "سلام     دنیا!   "
print(standardize_persian(text3))
# خروجی: 'سلام دنیا!'

---

۲. ماژول اعداد (parsikit.number) 🔢

مدیریت اعداد در اپلیکیشن‌های فارسی همیشه چالش‌برانگیز است. کاربر ممکن است فرم‌ها را با کیبورد فارسی یا عربی پر کند، در حالی که شما برای محاسبات ریاضی یا ذخیره در دیتابیس به اعداد انگلیسی نیاز دارید (و برعکس برای نمایش به کاربر).

🧰 توابع ماژول اعداد

نام تابع	ورودی	خروجی	کاربرد
english_to_persian	رشته (str)	رشته (str)	تبدیل اعداد انگلیسی ($0-9$) و عربی ($٠-٩$) به اعداد فارسی ($۰-۹$).
persian_to_english	رشته (str)	رشته (str)	تبدیل اعداد فارسی و عربی به اعداد انگلیسی (مناسب دیتابیس).

💻 مثال استفاده

from parsikit.number import english_to_persian, persian_to_english

# نمایش اعداد به کاربر با فونت فارسی
print(english_to_persian("کد سفارش: 4098 - ٩٨٧"))
# خروجی: 'کد سفارش: ۴۰۹۸ - ۹۸۷'

# استخراج اعداد انگلیسی برای ذخیره در دیتابیس
print(persian_to_english("مبلغ: ۱۲۳۴۵"))
# خروجی: 'مبلغ: 12345'

---

۳. ماژول پول و ارز (parsikit.currency) 💳

با استفاده از این ماژول می‌توانید ارقام طولانی را خوانا کنید (جداکننده‌ی ۳ رقم ۳ رقم) و به راحتی بین ریال و تومان جابه‌جا شوید.

فرمول تبدیل ریال به تومان بسیار ساده است: $Toman = \frac{Rial}{10}$. این ماژول این کار را به صورت امن و با تقسیم صحیح (//) انجام می‌دهد.

🧰 توابع ماژول پول

نام تابع	پارامترها	خروجی	کاربرد
format_currency	amount: مبلغ (عدد یا رشته) currency: 'toman' یا 'rial' persian_digits: True/False	رشته قالب‌بندی شده	جدا کردن هزارگان با کاما (یا ویرگول فارسی) و افزودن پسوند پولی.
rial_to_toman	amount: مبلغ به ریال (عدد صحیح)	عدد صحیح	حذف یک صفر از ریال برای تبدیل به تومان.

💻 مثال استفاده

from parsikit.currency import format_currency, rial_to_toman

# ۱. فرمت کردن ساده پول (پیش‌فرض: تومان، اعداد انگلیسی)
print(format_currency(1500000))
# خروجی: '1,500,000 تومان'

# ۲. فرمت کردن با اعداد فارسی (بسیار زیبا برای UI)
print(format_currency("1500000", persian_digits=True))
# خروجی: '۱،۵۰۰،۰۰۰ تومان'

# ۳. استفاده از ریال
print(format_currency(1000000, currency="rial"))
# خروجی: '1,000,000 ریال'

# ۴. تبدیل ریال به تومان
rial_price = 500000
toman_price = rial_to_toman(rial_price)
print(f"Price in Toman: {toman_price}")
# خروجی: Price in Toman: 50000

---

🎯 یک سناریوی کامل (Integration)

فرض کنید کاربری در یک ربات تلگرامی یا فرم وب، متنی نامرتب همراه با قیمت وارد کرده است: "قيمت نهايي: 1500000 ريال است"

ما می‌خواهیم متن را تمیز کنیم، عدد را تشخیص دهیم، ریال را به تومان تبدیل کنیم و خروجی شیک نمایش دهیم:

from parsikit.text import standardize_persian
from parsikit.number import persian_to_english
from parsikit.currency import rial_to_toman, format_currency

raw_input = "قيمت نهايي: 1500000 ريال"

# ۱. استانداردسازی متن (اصلاح ی و ک عربی)
clean_text = standardize_persian(raw_input)
# نتیجه: 'قیمت نهایی: 1500000 ریال'

# ۲. استخراج عدد (اینجا با یه روش ساده فقط اعداد رو جدا می‌کنیم)
digits_only = "".join(char for char in clean_text if char.isdigit())
rial_amount = int(persian_to_english(digits_only)) 
# نتیجه: 1500000

# ۳. تبدیل به تومان
toman_amount = rial_to_toman(rial_amount)
# نتیجه: 150000

# ۴. فرمت کردن برای نمایش نهایی
final_display = format_currency(toman_amount, persian_digits=True)

print(f"خروجی نهایی برای کاربر: {final_display}")
# خروجی: 'خروجی نهایی برای کاربر: ۱۵۰،۰۰۰ تومان'

---

توسعه‌دهنده: Ali Kamrani
لایسنس: MIT
تاریخ ایجاد: 2026-04-28