python-arabic-reshaper

Arabic Reshaper solves a specific rendering problem: Arabic script letters change shape depending on their neighbors, and most rendering pipelines outside of native Arabic-aware environments only know how to draw isolated glyphs. python-arabic-reshaper takes a string of Arabic (or Farsi, Urdu, Kurdish, and other Arabic-script languages) and rewrites it using the correct initial, medial, final, and isolated presentation forms, so it displays properly once combined with a right-to-left bidi pass such as python-bidi.

The library ships with a full Unicode letter-shape table and over 100 ligature substitutions (religious phrases, currency symbols, common word forms) that can be toggled individually or in bulk. Configuration can come from a Python dict, an INI file, an environment variable pointing at a config file, or automatically from a TrueType font via the optional fonttools integration, which inspects the font’s glyph coverage to decide which ligatures and forms it actually supports.

What You Get

• Presentation-form reshaping via a single reshape() call or a configurable ArabicReshaper class
• A toggleable ligature substitution table covering sentence-, word-, and letter-level ligatures
• Three independent configuration paths: inline dict, INI file, or environment variable
• Font-aware configuration that auto-detects supported ligatures/forms from a TrueType file via the optional fonttools extra

Common Use Cases

• Rendering Arabic text in PIL/Pillow-based image generation (certificates, memes, charts)
• Displaying Arabic strings correctly in GUI toolkits or game engines lacking native shaping
• Preparing Arabic text for PDF generation libraries that only draw isolated glyphs
• Fixing garbled Arabic output in terminal or logging tools by reshaping the source string before display

Under The Hood

Architecture The library is a small, flat module (arabic_reshaper/) with clear separation of concerns: reshaper_config.py owns configuration loading and merging (dict/INI/env-var/TrueType-font sources) via auto_config(), letters.py and ligatures.py are pure static data tables (Unicode code-point to presentation-form mappings, 100+ ligature patterns), and arabic_reshaper.py holds the single ArabicReshaper class whose reshape() method is a character-by-character state machine walking the input string, tracking Harakat positions, then applying a compiled regex pass for ligature substitution. There’s no plugin system and no external I/O beyond the optional font-file read in config_for_true_type_font; the public surface is intentionally tiny (reshape, ArabicReshaper, config_for_true_type_font, ligature enable flags) — changing the core letter-form data model would ripple through both the character loop and the ligature-form lookup, but nothing else in the codebase depends on internals beyond these tables.

Tech Stack This is a zero-runtime-dependency pure-Python library (only an optional fontTools>=4.0 extra for TrueType-aware configuration), built with the modern hatchling backend declared in pyproject.toml, targeting Python 3.10–3.14. There’s no web/ORM/CLI framework involved — it’s a data-processing library consumed by higher-level rendering stacks, most commonly paired with python-bidi for bidi reordering and Pillow for image drawing per the README’s own examples. Development tooling uses uv for dependency/venv management (uv.lock committed) and pytest with pytest-cov for testing, with GitHub Actions running the test matrix across all five supported Python versions and a separate release workflow that publishes to PyPI via OIDC trusted publishing on GitHub Release events.

Code Quality Tests live under arabic_reshaper/tests/ using Python’s unittest, covering initialization, default reshaping, extended reshaping including ZWJ and ligature edge cases, and font-based configuration, using real reference strings for exact-match comparisons — pytest is configured with --cov=arabic_reshaper --cov-report=term-missing so coverage is enforced by convention. Error handling is minimal but explicit where present (ArabicReshaperConfigurationError raised on invalid configuration); the core reshape() function relies on plain conditionals rather than typed exceptions for its character-classification branches. Naming is consistent, and newer entry points carry type hints per the changelog, though the bulk of arabic_reshaper.py and reshaper_config.py remain untyped. No linter/formatter configuration is present in the repo, and CI runs tests only, not lint.

API Design The public API is deliberately minimal: import arabic_reshaper; arabic_reshaper.reshape(text) works with zero configuration via a module-level default_reshaper singleton, while ArabicReshaper(configuration=...) offers an escape hatch for per-call-site tuning without global state — a good balance of zero-boilerplate default and progressive configuration. Three interchangeable configuration mechanisms (inline dict, INI file, env var) cover both quick scripts and larger deployments that want config outside code, and config_for_true_type_font is a genuinely convenient feature that removes the need to manually curate which of the 100+ ligatures a given font actually supports. Documentation is thorough for a project this size — the README enumerates every setting, includes a full PIL rendering walkthrough, and keeps a versioned changelog — though API docs live only in the README/docstrings, with no hosted docs site or published type stubs.