persian-ya

A lightweight, production-ready Python package for Persian Ezafe (کسره اضافه / یای میانجی) grammatical rules.


Keywords
ezafe, farsi, grammar, iranian, nlp, persian, persian-nlp, persian-typography, yaye-mianji, zwnj
License
MIT
Install
pip install persian-ya==0.1.0

Documentation

Persian-Ya

PyPI version Python Versions CI Status Coverage License

مستندات فارسی (Persian Documentation)

A lightweight, zero-dependency, production-ready Python package that correctly attaches adjectives, titles, and descriptions to Persian proper nouns (names) and phrases following Persian Ezafe (Kasre-ye Ezafe / Yaye Mianji) grammatical rules.


Features

  • Zero Dependencies: Pure standard Python 3.10+ with ultra-fast string parsing.
  • 100% Grammar Accuracy: Correctly handles Persian vowel endings (ا, و), silent He (ه, ة, ۀ), and all 32 consonants.
  • Customizable Silent He Style: Switch seamlessly between modern standard (\u200cی - ZWNJ + Ye) and formal Academy style (ٔ - Hamze).
  • Persian Normalizer: Cleans Arabic characters (ي $\rightarrow$ ی, ك $\rightarrow$ ک), stray ZWNJs, diacritics/harakat, and extra whitespace.
  • Compound Names & Titles Support: Properly formats multi-word names (e.g., "محمد رضا" $\rightarrow$ "محمد رضای عزیز").
  • Fully Typed: Includes PEP 561 py.typed marker and complete type hints.
  • 100% Test Coverage: Thoroughly tested across all linguistic edge cases.

Installation

Install via pip:

pip install persian-ya

Or using uv:

uv add persian-ya

Quick Start

Basic Usage

from persian_ya import attach_adjective

# 1. Names ending in "ا" (Alef) or "و" (Vav) -> Appends 'ی'
print(attach_adjective("رضا", "عزیز"))  # Output: 'رضای عزیز'
print(attach_adjective("مینو", "گرامی"))  # Output: 'مینوی گرامی'

# 2. Names ending in "ه" (Silent He) -> Default modern style (ZWNJ + 'ی')
print(attach_adjective("پروانه", "عزیز"))  # Output: 'پروانه‌ی عزیز'

# 3. Names ending in consonants or "ی" -> Standard space concatenation
print(attach_adjective("مریم", "عزیز"))  # Output: 'مریم عزیز'
print(attach_adjective("علی", "عزیز"))  # Output: 'علی عزیز'

Silent He Style Switch (ya vs hamze)

You can easily configure the orthography for words ending in silent He (ه / ة):

from persian_ya import HeStyle, attach_adjective

# Modern Standard (Default): ZWNJ + 'ی'
print(attach_adjective("پروانه", "عزیز"))
# Output: 'پروانه‌ی عزیز'

# Formal / Academy Style (Hamze / Small Ye):
print(attach_adjective("پروانه", "عزیز", he_style="hamze"))
# Output: 'پروانهٔ عزیز'

# Using the boolean convenience flag:
print(attach_adjective("پروانه", "عزیز", use_hamze=True))
# Output: 'پروانهٔ عزیز'

# Using the HeStyle Enum:
print(attach_adjective("پروانه", "عزیز", he_style=HeStyle.HAMZE))
# Output: 'پروانهٔ عزیز'

Compound Names & Multi-Word Titles

from persian_ya import attach_adjective

print(attach_adjective("محمد رضا", "عزیز"))  # 'محمد رضای عزیز'
print(attach_adjective("امیر علی", "گرامی"))  # 'امیر علی گرامی'
print(attach_adjective("سید محمد رضا", "محترم"))  # 'سید محمد رضای محترم'
print(attach_adjective("دکتر پروانه", "گرامی"))  # 'دکتر پروانه‌ی گرامی'

Extracting Suffixes Directly

from persian_ya import get_ezafe_suffix

print(get_ezafe_suffix("رضا"))  # 'ی'
print(get_ezafe_suffix("مینو"))  # 'ی'
print(get_ezafe_suffix("پروانه"))  # '\u200cی' (‌ی)
print(get_ezafe_suffix("پروانه", he_style="hamze"))  # 'ٔ' (\u0654)
print(get_ezafe_suffix("مریم"))  # ''
print(get_ezafe_suffix("علی"))  # ''

Text Normalization

from persian_ya import normalize_persian

raw_text = "  على   رضاى   عَزِيز  "
clean_text = normalize_persian(raw_text)
print(clean_text)  # 'علی رضای عزیز'

Persian Grammar Reference

Word Ending Ezafe Rule Example Output
Alef (ا) Append "ی" "رضا" + "عزیز" "رضای عزیز"
Vav (و) Append "ی" "مینو" + "گرامی" "مینوی گرامی"
Silent He (ه) ZWNJ + "ی" (Default) "پروانه" + "عزیز" "پروانه‌ی عزیز"
Silent He (ه) Hamze (ٔ) "پروانه" + "عزیز" (he_style="hamze") "پروانهٔ عزیز"
Consonants (32 letters) Space separation only "مریم" + "عزیز" "مریم عزیز"
Terminal Ye (ی) Space separation only "علی" + "عزیز" "علی عزیز"

Development & Testing

Clone & Install

git clone https://github.com/Mazafard/persian-ya.git
cd persian-ya
pip install -e ".[dev]"

Run Tests with Coverage

uv run pytest

Run Type Checking & Linting

uv run mypy src/
uv run ruff check .

License

This project is licensed under the MIT License.