Metadata-Version: 2.4
Name: persian-number-to-word
Version: 1.0.0
Summary: تبدیل اعداد به حروف فارسی
Author-email: Poriya <poria.dell7@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/p7deli/persian-number-to-word
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: licence
Dynamic: license-file

# 📦 Persian Number To Words

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

---

## ✨ امکانات

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

---

# 📥 نصب

### نصب از PyPI

```bash
pip install persian-number-to-words
```

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

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

---

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

```python
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` برمی‌گرداند:

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

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

```python
result.formatted
result.words
result.language
result.currency
```

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

```python
result.to_dict()
```

---

# 🔢 انواع ورودی

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

## عدد صحیح

```python
number_to_words(1000)
```

## عدد اعشاری

```python
number_to_words(1234.56)
```

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

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

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

```python
number_to_words("۱۲۳۴۵۶")
```

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

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

---

# 🌍 انتخاب زبان

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

```python
number_to_words(123456, lang="fa")
```

## انگلیسی

```python
number_to_words(123456, lang="en")
```

خروجی:

```
one hundred twenty three thousand four hundred fifty six
```

---

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

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

خروجی:

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

---

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

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

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

خروجی:

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

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

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

خروجی:

```
twelve thousand five hundred dollars and seventy five cents
```

---

# ➖ اعداد منفی

```python
number_to_words(-2500)
```

خروجی:

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

---

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

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

```bash
pnum 123456
```

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

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

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

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

---

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

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

---

# 🌐 استفاده در FastAPI

```python
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)

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

---

# 🧠 نکات مهم

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

---

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

```bash
pytest
```

---

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

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

---

# 📜 لایسنس

MIT

---

# نویسنده

Poriya Delavariyan
