{"id":1908,"library":"arabic-reshaper","title":"Arabic Reshaper","description":"Arabic Reshaper is a Python library designed to reconstruct Arabic sentences for use in applications that do not natively support Arabic script rendering. It handles the complex shaping rules of Arabic, converting disjointed characters into their correctly connected forms (initial, medial, final, isolated) and managing ligatures. The library is actively maintained, with its latest major release being v3.0.0, and typically releases updates as needed.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/mpcabd/python-arabic-reshaper/","tags":["arabic","text processing","shaping","bidirectional text","unicode"],"install":[{"cmd":"pip install arabic-reshaper","lang":"bash","label":"Basic Installation"},{"cmd":"pip install --upgrade arabic-reshaper[with-fonttools]","lang":"bash","label":"With Fonttools for Font-based Configuration"}],"dependencies":[{"reason":"Required for generating configuration based on a TrueType font file, enabling automatic ligature and character form detection. It's an optional extra installation.","package":"fonttools","optional":true}],"imports":[{"symbol":"reshape","correct":"import arabic_reshaper\nreshaped_text = arabic_reshaper.reshape('text')"},{"symbol":"ArabicReshaper","correct":"from arabic_reshaper import ArabicReshaper\nreshaper = ArabicReshaper(configuration={'support_ligatures': True})\nreshaped_text = reshaper.reshape('text')"},{"note":"Font-based configuration requires the dedicated `config_for_true_type_font` function and the `[with-fonttools]` extra. It's not a direct setting in the `configuration` dict.","wrong":"ArabicReshaper(configuration={'font_file': '/path/to/font.ttf'})","symbol":"config_for_true_type_font","correct":"from arabic_reshaper import ArabicReshaper, config_for_true_type_font, ENABLE_ALL_LIGATURES\nreshaper = ArabicReshaper(config_for_true_type_font('/path/to/font.ttf', ENABLE_ALL_LIGATURES))"}],"quickstart":{"code":"import arabic_reshaper\n\n# Basic reshaping\ntext_to_be_reshaped = 'اللغة العربية رائعة'\nreshaped_text = arabic_reshaper.reshape(text_to_be_reshaped)\nprint(f\"Original: {text_to_be_reshaped}\")\nprint(f\"Reshaped: {reshaped_text}\")\n\n# Reshaping with custom configuration\nfrom arabic_reshaper import ArabicReshaper\n\nconfiguration = {\n    'delete_harakat': False, # Keep diacritics\n    'support_ligatures': True,\n}\nreshaper = ArabicReshaper(configuration=configuration)\n\ntext_with_harakat = 'الْعَرَبيَّةُ'\nreshaped_text_custom = reshaper.reshape(text_with_harakat)\nprint(f\"Original (with harakat): {text_with_harakat}\")\nprint(f\"Reshaped (custom): {reshaped_text_custom}\")","lang":"python","description":"This quickstart demonstrates how to perform basic Arabic text reshaping using the top-level `reshape` function, and then how to use the `ArabicReshaper` class for more granular control over the reshaping process, such as preserving diacritics (harakat). Note that for proper display in environments that don't support RTL, you might need to combine this with a bidirectional (bidi) algorithm library like `python-bidi`."},"warnings":[{"fix":"Upgrade your Python environment to Python 3.x. If unable to upgrade, pin `arabic-reshaper<3.0.0`.","message":"Python 2.x support has been completely dropped in version 3.0.0. Applications targeting Python 2 must use an older version (e.g., 2.x.x) or migrate to Python 3.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Install `arabic-reshaper` with the `[with-fonttools]` extra: `pip install --upgrade arabic-reshaper[with-fonttools]`.","message":"Using `config_for_true_type_font` requires the `fonttools` package to be installed as an extra dependency (`pip install arabic-reshaper[with-fonttools]`). Without it, attempting to use this function will result in an `ImportError` or `ModuleNotFoundError`.","severity":"gotcha","affected_versions":">=2.1.0"},{"fix":"After reshaping the text with `arabic-reshaper`, pass the output to a bidi algorithm library. Example: `from bidi.algorithm import get_display; bidi_text = get_display(reshaped_text)`.","message":"Arabic Reshaper focuses solely on character shaping. For correct Right-to-Left (RTL) text display, especially when mixing Arabic and LTR languages, you will likely need to use a bidirectional (bidi) algorithm library (e.g., `python-bidi`) in conjunction with `arabic-reshaper`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When initializing `ArabicReshaper`, pass `configuration={'delete_harakat': False}`. For example: `reshaper = ArabicReshaper(configuration={'delete_harakat': False})`.","message":"By default, `delete_harakat` is `True`, meaning diacritics (tashkeel) are removed from the text during reshaping. If you need to preserve harakat, you must explicitly set `delete_harakat=False` in your `ArabicReshaper` instance configuration.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `use_unshaped_instead_of_isolated=True` in your `ArabicReshaper` configuration: `reshaper = ArabicReshaper(configuration={'use_unshaped_instead_of_isolated': True})`.","message":"Some fonts may be missing the isolated forms for certain Arabic letters, leading to incorrect rendering even after reshaping. The `use_unshaped_instead_of_isolated` configuration option can mitigate this by forcing the use of unshaped forms instead.","severity":"gotcha","affected_versions":">=2.0.14"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}