Metadata-Version: 2.4
Name: persian
Version: 1.1.1
Summary: Fast, typed Python library for Persian language localization
Author-email: Reza Kamali <hi@rez.nu>
Maintainer-email: Reza Kamali <hi@rez.nu>
License: MIT
Project-URL: Homepage, https://github.com/rezkam/persian
Project-URL: Documentation, https://persian.readthedocs.io
Project-URL: Repository, https://github.com/rezkam/persian
Project-URL: Issues, https://github.com/rezkam/persian/issues
Project-URL: Changelog, https://github.com/rezkam/persian/releases
Keywords: persian,farsi,localization,i18n,internationalization,arabic,numbers,characters,text-processing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Localization
Classifier: Topic :: Software Development :: Internationalization
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest-benchmark>=5.2.3; extra == "dev"
Requires-Dist: ty>=0.0.34; extra == "dev"
Requires-Dist: ruff>=0.15.12; extra == "dev"
Requires-Dist: build>=1.5.0; extra == "dev"
Requires-Dist: setuptools-scm>=10.0.5; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=9.0.4; python_version < "3.12" and extra == "docs"
Requires-Dist: sphinx>=9.1.0; python_version >= "3.12" and extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=3.6.0; python_version < "3.12" and extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=3.10.2; python_version >= "3.12" and extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.17.1; extra == "docs"
Dynamic: license-file

# Persian

A fast Python toolkit for Persian (Farsi) text normalization, number/character conversion, and localization utilities.

[![Tests](https://github.com/rezkam/persian/workflows/Tests/badge.svg)](https://github.com/rezkam/persian/actions)

## Installation

```bash
pip install persian
```

## Quick Start

```python
import persian

persian.convert_ar_characters("علي")  # 'علی'
persian.convert_fa_numbers("۱۳۷۱")    # '1371'
persian.convert_en_numbers("345")     # '۳۴۵'
persian.convert_en_characters("sghl") # 'سلام'
persian.convert_fa_spaces("آمده ای")  # 'آمده‌ای'
persian.decode_url("https://.../%D8%B5%D9%81%D8%AD%D9%87")  # 'https://.../صفحه'
```

Need a one-stop helper? Use `normalize_persian("سلام ٣٤٥ می آیم")`
to get `سلام ۳۴۵ می‌آیم`.

## Performance

Version 1.0.0 includes major speedups:

- 3–5× faster number and keyboard conversions via `str.translate`
- 2–3× faster spacing fixes using pre-compiled regular expressions
- ~50% lower memory usage on large strings thanks to fewer temporary objects

See [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for benchmark methodology and charts.

## Type Safety & Tooling

The package ships with native type hints (`py.typed`) and strict type checking.
Static analyzers know the exact return type of every function:

```python
from persian import convert_en_numbers

result: str = convert_en_numbers("123")  # ✔️ type checker is satisfied
```

## Error Handling

All public functions validate inputs and raise clear exceptions:

```python
import persian

persian.convert_en_numbers(None)  # ValueError: input_str cannot be None
persian.convert_en_numbers(123)   # TypeError: input_str must be str, got int
```

Empty strings are accepted and return empty strings.

## API Overview

| Category | Functions |
| --- | --- |
| Numbers | `convert_en_numbers`, `convert_fa_numbers`, `convert_ar_numbers` |
| Characters | `convert_en_characters`, `convert_ar_characters`, `remove_arabic_diacritics` |
| Spacing & URLs | `convert_fa_spaces`, `decode_url` |
| Utilities | `normalize_persian`, `contains_persian_digits`, `contains_arabic_digits`, `is_persian_text` |

A detailed description is available in [docs/API.md](docs/API.md).

## Deprecated Functions

CamelCase helpers remain available but emit `DeprecationWarning`:

- `enToPersianNumb()` → `convert_en_numbers()`
- `enToPersianChar()` → `convert_en_characters()`
- `arToPersianNumb()` → `convert_ar_numbers()`
- `arToPersianChar()` → `convert_ar_characters()`

## Documentation

- [Performance Benchmarks](docs/PERFORMANCE.md)
- [API Reference](docs/API.md)
- [Changelog](docs/CHANGELOG.md)
- [Contributing Guide](docs/CONTRIBUTING.md)

## Contributors

- [Reza Kamlifard](https://github.com/rezakamalifard/)
- [Keyvan Hedayati](https://github.com/k1-hedayati)
- [Bahram Aghaei](https://github.com/GreatBahram)
- [Hasan Ramezani](https://github.com/hramezani)
- [Farhad Mortezapour](https://github.com/farhadmpr)

## Contributing

See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for setup instructions and code style rules.
