Metadata-Version: 2.4
Name: mnk-persian-words
Version: 1.1.1
Summary: کتابخانه آفلاین Python برای نمونه‌گیری، فیلتر و نرمال‌سازی واژه‌های فارسی
Author-email: Masoud Najafzadeh Kalat <masoudnk2@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/masoudnk/PersianWordsLib
Project-URL: Documentation, https://github.com/masoudnk/PersianWordsLib#readme
Project-URL: Issues, https://github.com/masoudnk/PersianWordsLib/issues
Project-URL: Source, https://github.com/masoudnk/PersianWordsLib
Keywords: persian,farsi,random-words,text-generation,nlp,rtl,unicode
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: Persian
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PersianWords

**PersianWords** (`mnk-persian-words`) یک کتابخانه آفلاین Python برای تولید، فیلتر و نرمال‌سازی واژه‌های فارسی است.

دیتاست همراه خود پکیج منتشر می‌شود؛ بنابراین بعد از نصب برای دریافت واژه‌ها به اینترنت، API خارجی یا دانلود دیتابیس جداگانه نیاز ندارید.

## در یک نگاه

- **628,419 رکورد خام**
- **516,482 واژه نرمال‌شده یکتا**
- **515,541 واژه ساختاری تمیز (`clean`)**
- سه حالت `raw`، `normalized` و `clean`
- فیلتر بر اساس طول، ابتدا، انتها و محتوای واژه
- نمونه‌گیری یکتا و قابل تکرار با `seed`
- ابزار نرمال‌سازی Unicode فارسی
- CLI داخلی
- اجرای کاملاً آفلاین
- تست‌شده روی Python 3.9 تا 3.13

## نصب

```bash
pip install mnk-persian-words
```

## شروع سریع

```python
import mnk_persian_words as pw

print(pw.get_random_persian_word())
print(pw.get_random_persian_words(5))
```

دریافت واژه‌های `clean`:

```python
words = pw.get_random_persian_words(
    10,
    mode="clean",
    seed=42,
)
print(words)
```

## حالت‌های داده

### `raw`

داده اصلی و بدون تغییر دیتاست. این حالت برای سازگاری با نسخه‌های قبلی، حالت پیش‌فرض است.

### `normalized`

شکل canonical و Unicode-normalized واژه‌ها. در این profile مواردی مانند `ي/ی`، `ك/ک`، کشیده، کنترل‌های Unicode و ZWNJهای خراب به‌شکل محافظه‌کارانه اصلاح می‌شوند.

### `clean`

زیرمجموعه‌ای از داده‌های canonical که از نظر **ساختار و Unicode** برای استفاده به‌عنوان یک واژه مستقل مناسب هستند. مواردی مانند HTML، حروف لاتین، اعداد، فاصله داخلی، punctuation و control character در این profile پذیرفته نمی‌شوند.

> `clean` به معنی «فارسی معیار»، «واژه رایج» یا «تأییدشده توسط فرهنگ لغت» نیست؛ فقط کیفیت ساختاری و Unicode داده را مشخص می‌کند.

## فیلترها

```python
words = pw.get_random_persian_words(
    count=20,
    mode="clean",
    min_length=4,
    max_length=8,
    starts_with="م",
    contains="ار",
    unique=True,
    seed=42,
)
```

فیلترهای اصلی:

- `min_length`
- `max_length`
- `starts_with`
- `ends_with`
- `contains`
- `unique`
- `seed`

## نرمال‌سازی فارسی

```python
pw.normalize_persian("علي و كتاب")
# 'علی و کتاب'
```

حذف اختیاری اعراب:

```python
pw.normalize_persian("عَلِی", remove_diacritics=True)
# 'علی'
```

نرمال‌سازی فعلی شامل استانداردسازی حروف عربی/فارسی، حذف Tatweel، حذف کنترل‌های غیرمعنایی و اصلاح ZWNJهای تکراری یا لبه‌ای است؛ نیم‌فاصله معتبر داخل واژه حفظ می‌شود.

## Random قابل تکرار

```python
first = pw.get_random_persian_words(5, mode="clean", seed=42)
second = pw.get_random_persian_words(5, mode="clean", seed=42)

assert first == second
```

استفاده از `seed` state سراسری `random` برنامه را تغییر نمی‌دهد.

## اطلاعات دیتاست

```python
print(pw.dataset_info())
```

این تابع اطلاعاتی مانند نسخه schema، تعداد رکوردهای raw، تعداد واژه‌های normalized و clean، طول واژه‌ها و fingerprint دیتاست نصب‌شده را برمی‌گرداند.

## رابط خط فرمان

```bash
persian-words word
persian-words word --count 20 --mode clean --seed 42
persian-words info
persian-words normalize "علي و كتاب"
```

## کاربردهای پیشنهادی

PersianWords می‌تواند در موارد زیر مفید باشد:

- تولید داده آزمایشی برای نرم‌افزارها
- تست UI/UX فارسی، RTL و فونت
- بازی‌ها و تمرین‌های کلمه‌محور
- نرم‌افزارهای آموزشی
- ساخت placeholder
- نمونه‌سازی سریع
- آزمایش الگوریتم‌های پردازش متن
- تولید داده reproducible برای تست‌های خودکار

## Performance و معماری

کتابخانه در استفاده عادی تمام 628 هزار واژه را داخل یک لیست Python بارگذاری نمی‌کند. نمونه‌گیری و lookupها با SQLite انجام می‌شوند و دیتاست به‌صورت Lazy در cache محلی آماده استفاده می‌شود.

schema v2 تمام رکوردهای raw را حفظ می‌کند و شکل‌های نرمال‌شده را در `canonical_words` deduplicate می‌کند؛ در نتیجه سه حالت `raw`، `normalized` و `clean` بدون ارسال چند دیتابیس تکراری ارائه می‌شوند.

## مجوز و منابع داده

کد پروژه تحت مجوز **MIT** است. وضعیت مجوز داده‌های شخص ثالث مستقل از مجوز کد است.

اطلاعات منابع و provenance دیتاست:

https://github.com/masoudnk/PersianWordsLib/blob/master/DATA_SOURCES.md

سورس، مستندات کامل و issue tracker:

https://github.com/masoudnk/PersianWordsLib
