Persian-Ya

مستندات فارسی (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

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.