مستندات فارسی (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.
- 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.typedmarker and complete type hints. - 100% Test Coverage: Thoroughly tested across all linguistic edge cases.
Install via pip:
pip install persian-yaOr using uv:
uv add persian-yafrom 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: 'علی عزیز'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: 'پروانهٔ عزیز'from persian_ya import attach_adjective
print(attach_adjective("محمد رضا", "عزیز")) # 'محمد رضای عزیز'
print(attach_adjective("امیر علی", "گرامی")) # 'امیر علی گرامی'
print(attach_adjective("سید محمد رضا", "محترم")) # 'سید محمد رضای محترم'
print(attach_adjective("دکتر پروانه", "گرامی")) # 'دکتر پروانهی گرامی'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("علی")) # ''from persian_ya import normalize_persian
raw_text = " على رضاى عَزِيز "
clean_text = normalize_persian(raw_text)
print(clean_text) # 'علی رضای عزیز'| 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 |
"علی" + "عزیز"
|
"علی عزیز" |
git clone https://github.com/Mazafard/persian-ya.git
cd persian-ya
pip install -e ".[dev]"uv run pytestuv run mypy src/
uv run ruff check .This project is licensed under the MIT License.