parsikit 2.1.0

A comprehensive and pure Python library for Persian data formatting, validation, and graphical reshaping.

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:

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

---

Quick Start & Examples

1. Text Normalization & Keyboard Layout Correction

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

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

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

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("[phone]"):
    local_mobile = parsikit.normalize_mobile("[phone]", 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

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:

python test.py

---

License

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