Metadata-Version: 2.5
Name: persian-ya
Version: 0.1.0
Summary: A lightweight, production-ready Python package for Persian Ezafe (کسره اضافه / یای میانجی) grammatical rules.
Project-URL: Homepage, https://github.com/Mazafard/persian-ya
Project-URL: Documentation, https://github.com/Mazafard/persian-ya#readme
Project-URL: Repository, https://github.com/Mazafard/persian-ya
Project-URL: Bug Tracker, https://github.com/Mazafard/persian-ya/issues
Author-email: Mazafard <mazafard@gmail.com>
Maintainer-email: Mazafard <mazafard@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ezafe,farsi,grammar,iranian,nlp,persian,persian-nlp,persian-typography,yaye-mianji,zwnj
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Persian
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Persian-Ya

<p align="center">
  <a href="https://pypi.org/project/persian-ya/"><img src="https://img.shields.io/pypi/v/persian-ya.svg" alt="PyPI version" /></a>
  <a href="https://pypi.org/project/persian-ya/"><img src="https://img.shields.io/pypi/pyversions/persian-ya.svg" alt="Python Versions" /></a>
  <a href="https://github.com/Mazafard/persian-ya/actions"><img src="https://img.shields.io/github/actions/workflow/status/Mazafard/persian-ya/test.yml?branch=main" alt="CI Status" /></a>
  <a href="https://codecov.io/gh/Mazafard/persian-ya"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage" /></a>
  <a href="https://github.com/Mazafard/persian-ya/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Mazafard/persian-ya.svg" alt="License" /></a>
</p>

<p align="center">
  <a href="README.fa.md"><b>مستندات فارسی (Persian Documentation)</b></a>
</p>

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`:

```bash
pip install persian-ya
```

Or using `uv`:

```bash
uv add persian-ya
```

---

## Quick Start

### Basic Usage

```python
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 (`ه` / `ة`):

```python
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

```python
from persian_ya import attach_adjective

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

---

### Extracting Suffixes Directly

```python
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

```python
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

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

### Run Tests with Coverage

```bash
uv run pytest
```

### Run Type Checking & Linting

```bash
uv run mypy src/
uv run ruff check .
```

---

## License

This project is licensed under the [MIT License](LICENSE).
