Migration Guide#

This guide helps you migrate from older versions of the Persian library to version 1.0.0.

Migration to v1.0.0#

Overview#

Version 1.0.0 is a major release that brings significant improvements while maintaining backward compatibility for supported Python versions.

Breaking Changes#

Python Version Requirement#

Version 1.0.0 requires Python 3.10 or higher (previously 3.6+).

Reason: Python 3.6-3.9 have all reached end-of-life and no longer receive security updates.

Migration Path:

  • If you’re on Python 3.10+: No code changes needed, just update the package

  • If you’re on Python 3.6-3.9: Either upgrade Python or pin to persian<1.0.0

# For Python 3.10+
pip install --upgrade persian

# For Python 3.6-3.9 (legacy)
pip install "persian<1.0.0"

What’s New in v1.0.0#

Performance Improvements#

Major performance enhancements:

  • 3-5× faster number and keyboard conversions using str.translate

  • 2-3× faster spacing fixes with pre-compiled regex

  • ~50% lower memory usage on large strings

No code changes needed - your code automatically benefits from these improvements.

Type Hints#

Full type hints support with py.typed marker:

from persian import convert_en_numbers

result: str = convert_en_numbers("123")  # ✔️ mypy is satisfied

Input Validation#

All functions now validate inputs and raise clear exceptions:

import persian

# Before v1.0.0: might crash or give unexpected results
# After v1.0.0: clear error messages
try:
    persian.convert_en_numbers(None)
except ValueError as e:
    print(e)  # "input_str cannot be None"

try:
    persian.convert_en_numbers(123)
except TypeError as e:
    print(e)  # "input_str must be str, got int"

New Functions#

Several new utility functions:

import persian

# Normalize Persian text (all-in-one)
persian.normalize_persian("سلام ٣٤٥ می آیم")

# Check for Persian digits
persian.contains_persian_digits("۱۲۳")  # True

# Check for Arabic digits
persian.contains_arabic_digits("٣٤٥")  # True

# Check for Persian text
persian.is_persian_text("سلام")  # True

# Remove Arabic diacritics
persian.remove_arabic_diacritics("مَرحَباً")  # "مرحبا"

Deprecated Functions#

CamelCase function names are deprecated but still work with warnings:

import persian

# Deprecated (still works but shows warning)
persian.enToPersianNumb("123")  # DeprecationWarning

# Recommended
persian.convert_en_numbers("123")  # No warning

Deprecation Mapping#

Replace deprecated functions with their modern equivalents:

Deprecated

Use Instead

enToPersianNumb()

convert_en_numbers()

enToPersianChar()

convert_en_characters()

arToPersianNumb()

convert_ar_numbers()

arToPersianChar()

convert_ar_characters()

Migration Example#

Before:

import persian

# Old style (still works with warnings)
result = persian.enToPersianNumb("123")
text = persian.arToPersianChar("علي")

After:

import persian

# New style (recommended)
result = persian.convert_en_numbers("123")
text = persian.convert_ar_characters("علي")

Upgrading from Specific Versions#

From v0.x to v1.0.0#

  1. Check Python version:

    python --version  # Must be 3.10+

  2. Update package:

    pip install --upgrade persian

  3. Replace deprecated functions (optional but recommended):

    # Find deprecated usage
grep -r "enToPersianNumb\|arToPersianChar" .

  4. Add type hints (optional):

    from persian import convert_en_numbers

def process_text(text: str) -> str:
    return convert_en_numbers(text)

  5. Run tests to ensure everything works.

Common Migration Issues#

Issue: Import Error#

Problem:

ModuleNotFoundError: No module named 'persian'

Solution:

Ensure Persian is installed for the correct Python version:

python3.10 -m pip install persian
# Or
python3.11 -m pip install persian

Issue: Python Version Too Old#

Problem:

ERROR: Package 'persian' requires a different Python: 3.9.0 not in '>=3.10'

Solution:

Either upgrade Python or use the legacy version:

# Option 1: Upgrade Python (recommended)
# Install Python 3.10+ from python.org

# Option 2: Use legacy version
pip install "persian<1.0.0"

Issue: Type Errors with mypy#

Problem:

error: Skipping analyzing 'persian': found module but no type hints

Solution:

Update to v1.0.0+ which includes py.typed:

pip install --upgrade persian

Issue: Deprecation Warnings#

Problem:

DeprecationWarning: enToPersianNumb is deprecated, use convert_en_numbers

Solution:

Replace with modern function names:

# Before
persian.enToPersianNumb("123")

# After
persian.convert_en_numbers("123")

Testing Your Migration#

Run this test script to verify your migration:

import persian

def test_migration():
    """Test that Persian library works correctly after migration."""

    # Test number conversions
    assert persian.convert_en_numbers("123") == "۱۲۳"
    assert persian.convert_fa_numbers("۱۲۳") == "123"
    assert persian.convert_ar_numbers("٣٤٥") == "۳۴۵"

    # Test character conversions
    assert persian.convert_en_characters("sghl") == "سلام"
    assert persian.convert_ar_characters("علي") == "علی"

    # Test text processing
    assert "می‌روم" == persian.convert_fa_spaces("می روم")

    # Test normalization
    result = persian.normalize_persian("سلام ٣٤٥ می آیم")
    assert "۳۴۵" in result
    assert "‌" in result  # ZWNJ

    # Test detection
    assert persian.contains_persian_digits("۱۲۳") is True
    assert persian.is_persian_text("سلام") is True

    print("✅ All migration tests passed!")

if __name__ == "__main__":
    test_migration()

Save this as test_migration.py and run:

python test_migration.py

Getting Help#

If you encounter migration issues:

  1. Check the documentation: https://persian.readthedocs.io

  2. Search existing issues: rezkam/persian#issues

  3. Create a new issue: Include Python version, Persian version, and error message

Next Steps#