persian-number-to-word 1.0.0

تبدیل اعداد به حروف فارسی

📦 Persian Number To Words

تبدیل اعداد به حروف فارسی و انگلیسی به صورت حرفه‌ای، مالی و قابل استفاده در پروژه‌های واقعی.

---

✨ امکانات

• ✅ پشتیبانی از int، float و str
• ✅ پشتیبانی از اعداد فارسی و انگلیسی
• ✅ تبدیل به حروف فارسی 🇮🇷
• ✅ تبدیل به حروف انگلیسی 🇬🇧
• ✅ حالت مالی (تومان / ریال / دلار / سنت)
• ✅ خروجی ساختاریافته (Dataclass)
• ✅ جدا کردن عدد با کاما
• ✅ پشتیبانی از CLI (خط فرمان)
• ✅ Type Hints کامل
• ✅ تست‌پذیر و توسعه‌پذیر

---

📥 نصب

نصب از PyPI

pip install persian-number-to-words

نصب در حالت توسعه (لوکال)

git clone https://github.com/p7deli/persian-number-to-words.git
cd persian-number-to-words
pip install -e .

---

🚀 استفاده سریع

from persian_number_to_words import number_to_words

result = number_to_words(123456)

print(result.formatted)
# 123,456

print(result.words)
# صد و بیست و سه هزار و چهارصد و پنجاه و شش

---

📌 ساختار خروجی

تابع number_to_words یک شیء از نوع NumberResult برمی‌گرداند:

NumberResult(
    formatted="123,456",
    words="صد و بیست و سه هزار و چهارصد و پنجاه و شش",
    language="fa",
    currency=None
)

دسترسی به مقادیر

result.formatted
result.words
result.language
result.currency

تبدیل به دیکشنری (مناسب API)

result.to_dict()

---

🔢 انواع ورودی

پکیج از انواع مختلف ورودی پشتیبانی می‌کند:

عدد صحیح

number_to_words(1000)

عدد اعشاری

number_to_words(1234.56)

رشته عددی انگلیسی

number_to_words("123456")
number_to_words("1,234,567")

رشته عددی فارسی

number_to_words("۱۲۳۴۵۶")

سیستم به صورت خودکار:

• کاما را حذف می‌کند
• اعداد فارسی را تبدیل می‌کند
• مقدار را نرمال‌سازی می‌کند

---

🌍 انتخاب زبان

فارسی (پیش‌فرض)

number_to_words(123456, lang="fa")

انگلیسی

number_to_words(123456, lang="en")

خروجی:

one hundred twenty three thousand four hundred fifty six

---

💰 استفاده از واحد پول

number_to_words(5000, currency="تومان")

خروجی:

پنج هزار تومان

---

🧾 حالت مالی (Financial Mode)

مناسب برای سیستم‌های حسابداری، فروشگاهی و صدور فاکتور.

number_to_words(
    12500.75,
    currency="تومان",
    mode="financial"
)

خروجی:

12,500.75
دوازده هزار و پانصد تومان و هفتاد و پنج ریال

در حالت انگلیسی:

number_to_words(
    12500.75,
    lang="en",
    currency="dollars",
    mode="financial"
)

خروجی:

twelve thousand five hundred dollars and seventy five cents

---

➖ اعداد منفی

number_to_words(-2500)

خروجی:

منفی دو هزار و پانصد

---

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

پس از نصب پکیج:

pnum 123456

مثال با پارامترها:

pnum 12500.75 --currency تومان --mode financial

پارامترهای قابل استفاده

گزینه	توضیح
--lang	انتخاب زبان (fa یا en)
--currency	تعیین واحد پول
--mode	حالت normal یا financial

---

📦 استفاده در پروژه Django

price = number_to_words(150000, currency="تومان")
label.setText(price.words)

---

🌐 استفاده در FastAPI

from fastapi import FastAPI
from persian_number_to_words import number_to_words

app = FastAPI()

@app.get("/convert/{number}")
def convert(number: str):
    result = number_to_words(number)
    return result.to_dict()

---

🌸 استفاده در پروژه‌های دسکتاپ (PyQt / Tkinter)

result = number_to_words(45000)
label.setText(result.words)

---

🧠 نکات مهم

• برای اعداد بسیار بزرگ، می‌توان scale جدید به constants.py اضافه کرد.
• خروجی همیشه یک شیء ساختاریافته است.
• برای API از متد to_dict() استفاده کنید.
• پکیج با Type Hint کامل نوشته شده است.

---

🧪 اجرای تست‌ها

pytest

---

👨‍💻 پیشنهادات

• برای پروژه‌های مالی همیشه از حالت financial استفاده کنید.
• برای API خروجی را با to_dict() ارسال کنید.
• CLI برای تبدیل سریع در خط فرمان مناسب است.

---

📜 لایسنس

MIT

---

نویسنده

Poriya Delavariyan