Persian

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

Tests

Installation

pip install persian

Quick Start

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

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:

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.

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

Contributors

Contributing

See docs/CONTRIBUTING.md for setup instructions and code style rules.

Project links

Data verified by PyPI on May 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for itmard from gravatar.com itmard

Credits

Author/Maintainer: Reza Kamali

GitHub Statistics

Data verified by PyPI on May 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

dev docs

Tags

persian farsi localization i18n internationalization arabic numbers characters text-processing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

persian-1.1.1.tar.gz (76.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

persian-1.1.1-py3-none-any.whl (9.2 kB view details)

Uploaded Python 3

File details

Details for the file persian-1.1.1.tar.gz.

File metadata

  • Download URL: persian-1.1.1.tar.gz
  • Upload date:
  • Size: 76.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for persian-1.1.1.tar.gz
Algorithm Hash digest
SHA256 77606b8a4f2e427c1b4cb8e5af8cfaaf7ac13ab51cb3631b66b76c275c85075a
MD5 17ebd4cb4055c50c856a6875ff185361
BLAKE2b-256 1ad2a170f81fc443b5204fd2922097dfe99b756f8e8558b9379e30900d58386c

See more details on using hashes here.

Provenance

The following attestation bundles were made for persian-1.1.1.tar.gz:

Publisher: publish.yml on rezkam/persian

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file persian-1.1.1-py3-none-any.whl.

File metadata

  • Download URL: persian-1.1.1-py3-none-any.whl
  • Upload date:
  • Size: 9.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for persian-1.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 a0aac87390698cccd238c97c8a5871cf60e3e954085c87fe5bdc4ffb1f3eadae
MD5 040ebc2147f20bc568adb8f10e4a54c1
BLAKE2b-256 aeec20dd8eb0d5979b9c0b2869b6bd7b3eb1440af63d340b580765c242ddd3b2

See more details on using hashes here.

Provenance

The following attestation bundles were made for persian-1.1.1-py3-none-any.whl:

Publisher: publish.yml on rezkam/persian

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.1.1 This release

2 files

1.1.0

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.0

2 files

0.5.0

2 files

0.4.0

1 file

0.0.3

1 file

0.0.2

1 file

0.0.1

1 file

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page