Metadata-Version: 2.4
Name: parsikit
Version: 2.1.0
Summary: A comprehensive and pure Python library for Persian data formatting, validation, and graphical reshaping.
Author: Ali Kamrani
Author-email: Ali Kamrani <kamrani.exe@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: Persian
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: requires-python

# ParsiKit

A lightweight, zero-dependency, pure Python library designed for Persian text standardization, layout reshaping for legacy graphics engines, financial calculations, and Iranian standard format validations.

---

## Key Features

- **Text Normalization & Correction**: Character mapping (Arabic `ي`/`ك` to Persian `ی`/`ک`), robust Zero-Width Non-Joiner (ZWNJ / نیم‌فاصله) formatting for verbs and suffixes, diacritics stripping, and English-to-Persian keyboard layout correction.
- **Digit & Number Conversions**: Convert digits between English, Persian, and Arabic formats, and translate numbers up to quadrillions into written Persian words.
- **Currency & Financial Utilities**: Thousand-separator formatting, Rial and Toman conversions, VAT calculator, loan monthly installment calculator, and verbal currency representations.
- **Iranian Standards Validators**: Real-time validation and clean formatting for National Codes, Mobile Numbers, Bank Cards (with Luhn checksum validation), and Sheba (IBAN) codes.
- **Graphical Text Reshaper**: A zero-dependency Persian reshaper that connects letters and handles RTL bidirectional flow for rendering text on Left-to-Right graphics engines (such as PIL/Pillow, Unity, Pygame, OpenCV, Matplotlib, or After Effects).

---

## Installation

You can install the package directly from source:

```bash
git clone https://github.com/MRThugh/ParsiKit.git
cd ParsiKit
pip install .
```

---

## Quick Start & Examples

### 1. Text Normalization & Keyboard Layout Correction

```python
import parsikit

# Standardize Persian characters and ZWNJ formatting
raw_text = "ي كافيه ك کتاب ها ميباشد سَلامٌ"
standardized = parsikit.standardize_persian(raw_text)
print(standardized)  # "ی کافیه ک کتاب‌ها میباشد سلام"

# Strip diacritics (Harakat)
clean_text = parsikit.strip_diacritics("سَلامٌ")
print(clean_text)  # "سلام"

# Correct mistyped English layout text (e.g., typing standard words on wrong layout)
corrected = parsikit.correct_keyboard_layout("sghl")
print(corrected)  # "سلام"
```

### 2. Digit Conversion & Verbal Number Representation

```python
import parsikit

# Convert digits
fa_digits = parsikit.english_to_persian("Price: 12500 Toman")
print(fa_digits)  # "Price: ۱۲۵۰۰ Toman"

# Convert numeric values to written Persian words
words = parsikit.number_to_words(1453200)
print(words)  # "یک میلیون و چهارصد و پنجاه و سه هزار و دویست"
```

### 3. Currency & Loan Installment Planning

```python
import parsikit

# Format with thousands separators
formatted = parsikit.format_currency("1500000", currency="toman", persian_digits=True)
print(formatted)  # "۱،۵۰۰،۰۰۰ تومان"

# Convert currency directly into words
words = parsikit.format_currency_to_words(1000000, currency="toman")
print(words)  # "یک میلیون تومان"

# Add Value Added Tax (VAT - Default is 10%)
total_with_tax = parsikit.add_tax_and_toll(100000)
print(total_with_tax)  # 110000

# Calculate monthly loan installments (e.g., 10M loan at 18% interest over 12 months)
monthly_payment = parsikit.calculate_installments(10000000, annual_interest_rate=18.0, months=12)
print(monthly_payment)  # 916799
```

### 4. Identity & Banking Validators

```python
import parsikit

# National Code Checksum Validation & Formatting
if parsikit.is_valid_national_code("7730123452"):
    formatted_nc = parsikit.format_national_code("7730123452")
    print(formatted_nc)  # "773-012345-2"

# Mobile Normalization (Standardizes input with various country code formats)
if parsikit.is_valid_mobile("+989123456789"):
    local_mobile = parsikit.normalize_mobile("+989123456789", prefix="0")
    print(local_mobile)  # "09123456789"

# Luhn Checksum Card Verification
is_card_valid = parsikit.is_valid_card_number("6037991122334455")
print(is_card_valid)  # True

# Standard Sheba (IBAN) Checksum Validation & Formatting
if parsikit.is_valid_sheba("050170000000123456789012"):
    readable_sheba = parsikit.format_sheba("050170000000123456789012", format_type="spaced")
    print(readable_sheba)  # "IR05 0170 0000 0012 3456 7890 12"
```

### 5. Layout Reshaping for Graphical Renderers

```python
import parsikit

# Forces Left-to-Right layout simulation engines (like PIL/Pillow or Pygame)
# to render Persian words connected and beautifully aligned.
graphical_text = parsikit.reshape_for_graphics("سلام Hello جهان", reverse=True)
print(graphical_text)  # "ﻡﻼﺳ Hello ﻥﺎﻬﺟ"
```

---

## Running Tests

To verify package integrity, execute the comprehensive test suite locally:

```bash
python test.py
```

---

## License

This project is licensed under the MIT License - see the LICENSE file for details.
