Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Removed

  • Python 3.10, which reached its end of life in October 2026. On Python 3.10, pip keeps installing khatt 0.17.

0.17.0 - 2026-11-19

Added

  • align="justify" on draw_text, text_bbox, overlay, word_art, word_boxes, render_svg, tk_image and caption_image (text_align): with max_width, every wrapped line but a paragraph’s last fills the width. Arabic words stretch with one kashida each first (after س ش ص ض, else before the last letter; never in short words or the name of God), then the spaces widen.

  • khatt.poem(verses, ...): verses of Arabic poetry in two columns, the first half of each verse on the right, every half stretched with kashida to the same width.

  • khatt.ocr_lines(texts, ...): line images for training Arabic OCR, each with its exact label in typed order and every word’s box (khatt.OcrLine, khatt.OcrWord). Fonts, sizes and colours are picked at random from lists, with optional tilt, blur and noise, and seed repeats them. khatt.write_ocr_dataset and khatt FILE --ocr-data FOLDER (with --augment and --seed) save the images with a Hugging Face imagefolder metadata.jsonl and a PaddleOCR-style labels.txt.

0.16.0 - 2026-11-19

Added

  • digits="arabic-indic" on draw_text, text_bbox, overlay, word_art, put_text, render_svg, word_boxes, caption_image and video.TextClip draws the numbers in the text as ٠١٢٣٤٥٦٧٨٩, with ٫, ٬ and ٪ inside numbers. khatt.arabic_digits(text) returns the converted string, one character for one, so spans stay valid.

  • khatt.tk_image(text, ...): the text drawn by khatt as a Tkinter PhotoImage, for labels, buttons and canvases, in any font file and with a line’s height so a row of buttons lines up.

Changed

  • khatt --arabic-digits now applies to any text, not only to --fetch (where it still changes only counts and dates).

Fixed

  • khatt.pillow.textbbox and textlength now count spaces at either end of Arabic text, as Pillow does, and khatt.pillow.text places the text so the anchor includes them. Code that draws a line piece by piece no longer runs the pieces together.

0.15.0 - 2026-11-19

Added

  • khatt.pillow: Pillow’s text, textbbox and textlength with the ImageDraw first and the same arguments, drawing text with Arabic letters through khatt (and turning strings already shaped with arabic_reshaper back first), and everything else through Pillow untouched. khatt.pillow.routing() does the same for code you can’t change, such as a library, while a with block lasts.

  • khatt.word_boxes(text, ...) lays the text out as draw_text does and returns each word’s box and coverage mask (khatt.WordBox), in reading order, for highlighting a recited word, word-level OCR labels or hit-testing. ranges= measures any parts of the text instead of its words.

0.14.0 - 2026-11-18

Added

  • khatt --version (-V) and python -m khatt, the same as the khatt command.

  • A pre-commit hook, khatt-doctor, that fails when code pre-shapes Arabic with arabic_reshaper or get_display. khatt --doctor PATH now exits with status 1 when it finds any, so CI can use it too.

  • khatt --doctor reports OpenCV: 5.1 and later shape Arabic in cv2.putText, so arabic_reshaper code is now shaped twice there too; earlier versions draw it as ??? or unjoined.

  • Moving off arabic_reshaper gains a checklist for the day Pillow shapes Arabic in all its wheels.

Changed

  • The docs no longer say cv2.putText has no Arabic letters: OpenCV 5.1 joins them, but still reverses Arabic-Indic digits and misplaces a bracket that starts a line, which khatt.put_text gets right on every version.

Changed

  • Releases are published only after the whole CI suite passes on the tagged commit and the built wheel installs and runs in a clean environment.

0.13.0 - 2026-11-17

Added

  • --arabizi writes Arabizi (Franco-Arabic, such as 7abibi) in Arabic letters before drawing it, with every option; --arabizi both keeps the Arabizi as a line under the Arabic, and --arabizi-words FILE adds your own spellings. A short list of common words in several dialects plus simple rules for the digit letters, letter pairs, vowels, the feminine -a and the article; no new dependency. khatt suggests the option when input looks like Arabizi but never converts on its own. API: khatt.from_arabizi() and khatt.is_arabizi().

0.12.0 - 2026-11-16

Added

  • --animate (-a) animates text art without breaking Arabic apart: every frame is shaped as a whole, so typed letters take their end-of-word form and then join the next one. Effects: type, wipe (from the right for Arabic), kashida (the words stretch with tatweel and settle) and shimmer (the palette flows through). Frames share one grid with the line’s start fixed, and a palette’s gradient stays in place. Plays in the terminal (--fps, --loop) or saves as GIF, APNG, WebP or an asciinema .cast. API: khatt.animate() and khatt.Animation.

  • The letters style draws a word out of letters: its own, or a phrase given with --fill (API: render(..., fill=)), read right to left along each row when Arabic, left to right for Arabizi. Letters take their isolated forms; lines go out wrapped in a left-to-right override for terminals that lay Arabic out themselves and in saved .txt files, so no run gets reversed. Images draw the letters in Cairo, and HTML output now keeps every character in its cell.

  • --frame puts text art inside a frame: single, round, double, heavy or lawha (double lines with ۞ ornaments). Images draw frame lines as crisp shapes, and frames work in animations. API: khatt.frame_art() and khatt.list_frames().

  • --canvas sizes a .png of the art for a post: social (1280×640), square, story, header, wallpaper or WIDTHxHEIGHT, with the art as large as fits and centred. API: art_to_image(..., canvas=) and khatt.CANVASES.

0.11.0 - 2026-11-16

Added

  • Colour for text art. --palette (-p) colours the art with a gradient that starts at the right edge, where an Arabic line starts, or runs --gradient ltr, down or up; --bands gives solid stripes. Six palettes (andalus, damask, desert, fajr, gold, nile, see --list-palettes) or any colours separated by commas. Colour is printed only to a terminal and never with NO_COLOR; --color always|never overrides that. API: khatt.color_art(art, palette) and khatt.list_palettes().

  • Three new styles: halfblocks (2 blocks per cell), quadrants (2×2) and sextants (2×3, Unicode 13).

  • Text art saved as SVG (--svg art, khatt.art_to_svg), as coloured HTML (.html, khatt.art_to_html) and with terminal colour codes (.ans). khatt.art_to_image and .png output take the palette too.

  • khatt --fetch: your machine’s details under Arabic labels beside an Arabic logo, like neofetch. The logo defaults to the system’s name in Arabic letters; uptime is written in Arabic grammar; --arabic-digits writes counts and dates in Eastern Arabic digits; --private leaves out user@host; the Hijri date appears when hijridate is installed. Terminals that can’t lay Arabic out get the labels already joined and in display order, and --rtl-terminal yes|no overrides the guess. Saved as an image (.png, .webp, .jpg), .txt or .ans. API: khatt.fetch(), khatt.fetch_image() and khatt.Fact.

0.10.0 - 2026-11-13

Added

  • khatt.put_text(frame, text, org) draws shaped Arabic onto NumPy images, such as OpenCV frames, whose cv2.putText has no Arabic letters. Same order of arguments and BGR colours by default; grayscale, RGB and RGBA work too, and only the part under the text is touched. NumPy is only needed when it is called.

  • khatt.receipt_image(rows) lays out a receipt for a thermal (ESC/POS) printer at its width: lines, (item, price) rows, dividers, a centered title and footer, as a 1-bit image for printer.image().

  • Recipes for OpenCV, pygame, Dear PyGui, Tkinter, Streamlit and receipt printers.

0.9.0 - 2026-11-12

Changed

  • khatt no longer needs freetype-py, which hasn’t had a release since August 2024 and has no Windows ARM64 wheel. Glyphs are now drawn by HarfBuzz’s own rasterizer, which uharfbuzz already includes, so khatt depends on 3 packages: Pillow, uharfbuzz and python-bidi. Line spacing and anchors are unchanged (the font metrics are rounded exactly as FreeType did); glyph edges can differ by a shade, and outlines (stroke_width) are drawn to the same width.

Added

  • A rescue kit for code that used arabic_reshaper, which Pillow with Raqm and matplotlib 3.11+ now shape a second time. khatt --doctor src/ (or khatt.find_reshaping) lists every place a project still pre-shapes Arabic. khatt.unreshape(text) turns reshaped text, also after get_display, back into text as typed, and khatt.is_reshaped tells whether a string is reshaped. Drawing reshaped text now gives a khatt.ReshapedTextWarning. The guide is Moving off arabic_reshaper.

0.8.0 - 2026-11-12

Added

  • Spans: draw_text(..., spans=[(start, end, "gold")]) draws part of the text in its own colour, such as the word being spoken in a caption. The line is still shaped as one, so letters keep their joins where the colour changes, and the layout is the same as without spans. caption_image takes spans too, and khatt.Span is the same as a (start, end, fill) tuple.

  • Word-timed captions: khatt.video.word_captions(words, video.size) makes a moviepy clip where each word lights up as it’s said. khatt.words_from_whisper reads the word timings of openai-whisper, faster-whisper, whisperX and stable-ts, and khatt.caption_steps gives the same steps without moviepy, for any video tool.

  • Quran recitations: khatt.words_from_quran(timings, verses) pairs the word timings of Quran.com or Tarteel QUL with the verses’ text, and khatt.video.quran_captions lights up each word one verse at a time, with the verse medallion and room for the marks.

0.7.1 - 2026-11-11

Changed

  • khatt is lighter: it no longer needs typer. The khatt command now runs on Python’s own argparse, with the same options and output. Installing khatt now pulls in 4 packages (Pillow, uharfbuzz, freetype-py, python-bidi) instead of 17, as typer brought pydantic, rich, Pygments and others with it.

  • Python 3.14 is tested and listed as supported. CI also runs the whole suite with Pillow’s Raqm turned on, to prove khatt draws the same with or without it.

0.7.0 - 2026-11-11

Added

  • Zakhrafa: khatt.zakhrafa("محمد", "royal") decorates text to copy and paste, in 10 styles (khatt.list_zakhrafa()). Decorations only go where letters join, never inside lam-alef, so words stay joined and tashkeel stays with its letter. In the CLI: khatt "محمد" --zakhrafa all.

  • SVG: khatt.render_svg(text) draws text as vector glyph outlines, shaped and laid out exactly as for images, with draw_text’s options plus padding and background. In the CLI, an .svg output: khatt "خط" -o khatt.svg.

0.6.0 - 2026-11-09

Added

  • Text on curves: khatt.word_art(text, curve="arc"), with the presets arc, smile, ring and wave (khatt.list_curves()), or khatt.Arc and khatt.Wave for your own. The whole line bends as one sheet, so Arabic letters stay joined and marks stay in place, and effects are drawn on the bent text. In the CLI: --curve and --list-curves.

  • Calligrams: khatt.calligram(text, shape="heart") flows text inside a shape, line by line, without cutting a letter at the edge. The presets are arch, circle, crescent, diamond and heart (khatt.list_shapes()), and any image works as a shape. The text repeats until the shape is full, or fits in once with repeat=False, and Arabic lines are stretched to their full width with kashida. Effects work too. In the CLI: --shape, --repeat/--no-repeat and --list-shapes.

0.5.0 - 2026-11-07

Added

  • Word art: khatt.word_art() draws text as a finished image, and draw_text and overlay take effect=. Presets are 3d, fire, gold, ice, neon, retro, silver and sticker (khatt.list_effects()), and khatt.Effect builds your own from Gradient, Shadow, Glow, Extrude, an outline and a bevel. Effects work on the finished text, so letters stay joined and marks stay in place. In the CLI: khatt "خط" --effect gold -o gold.png, with --size-px and --list-effects.

  • Four more bundled fonts: aref-ruqaa, lalezar, rakkas and reem-kufi. Style names work as fonts too: naskh, ruqaa, kufi, display and modern.

  • khatt-fonts, a new package with 22 more open Arabic fonts in Kufi, Naskh, Nastaliq, display, handwriting and modern styles. Install it and khatt finds it on its own.

0.4.2 - 2026-11-05

Fixed

  • Sizes can be NumPy numbers or floats, as they often are when worked out from an image. size_px in draw_text and text_bbox, max_size_px, min_size_px and padding in overlay, and size in caption_image raised ctypes.ArgumentError from FreeType unless that size had been drawn before, so the same call could work or fail depending on what came first. overlay could also hang on a fractional max_size_px, or on a size in a small NumPy type such as uint8. Sizes now round to whole pixels, and NaN or infinity raises ValueError.

0.4.1 - 2026-11-03

Fixed

  • Brackets in right-to-left text now face the right way. (مرحبا) was drawn as )مرحبا(, and سيارة (أجرة) with its closing bracket reversed, because a bracket at the start or end of an Arabic or Hebrew line was laid out left to right. It now takes the line’s direction and is mirrored. Brackets in left-to-right lines are unchanged.

Removed

  • The Gradio demo app (app.py), its app extra and its deployment files (Dockerfile, render.yaml, requirements.txt). khatt is a library and a CLI; uvx khatt "مرحبا" is the quickest way to try it.

0.4.0 - 2026-10-30

Added

  • Fallback fonts: fallback_fonts=[...] on render, render_image, draw_text, text_bbox, overlay, caption_image, khatt.video.TextClip and missing_characters. A character the font has no glyph for is drawn from the first fallback that has one, instead of being skipped, so Arabic mixed with Chinese, Hebrew or Cyrillic keeps every script. Marks stay in their base letter’s font, spaces and punctuation in the font of the text before them, and line spacing and anchors follow font. Text the font covers draws exactly as before.

0.3.0 - 2026-10-20

Added

  • khatt.draw_text(image, xy, text, ...): draws correctly shaped text onto an existing RGB or RGBA Pillow image, a drop-in for ImageDraw.text with Pillow-style anchors, max_width word-wrap, line_spacing, auto or explicit align, and alpha-aware fills. It never uses Pillow’s text layout, so its output is identical with or without Raqm and text is never shaped twice. Glyphs are rendered at the target size with quarter-pixel positioning.

  • khatt.overlay(image, text, box, fit=...): places text inside a box. fit="shrink" picks the largest size that fits with wrapping (a binary search measured from glyph outlines, without rendering), "wrap" wraps at a fixed size and "none" draws as is; plus align, valign and padding. Nothing is drawn outside the box: text that doesn’t fit is clipped with a khatt.TextOverflowWarning.

  • Your own fonts: every font parameter (render, render_image, draw_text, overlay, the CLI’s --font) also accepts the path to a .ttf/.otf file, as a string or pathlib.Path, including non-ASCII paths on Windows. Bundled names still win over a file of the same name. A missing file raises KeyError like an unknown name; a file khatt can’t shape and render (not a font, bitmap-only, or a WOFF/WOFF2 web font that FreeType reads but HarfBuzz can’t) raises a ValueError saying why.

  • Outlined text: stroke_width= and stroke_fill= on draw_text and overlay, with the same meaning as Pillow’s. The outline is FreeType’s own stroke (round corners), filled like Pillow’s, and grows outward around the text without moving it; stroke_fill defaults to fill, and an outline in the text’s own colour is painted in one coat, so translucent text stays even. overlay fits the outline inside the padding too. Arabic joins stay continuous because the text is painted over its outline.

  • khatt.text_bbox(text, xy=..., ...): measures text without drawing it, like Pillow’s textbbox, with draw_text’s arguments. The box is exact: every pixel draw_text would paint, outline included. Empty text gives an empty box at xy.

  • spacing= on draw_text, overlay and text_bbox: pixels between lines, with the same meaning as Pillow’s multiline_text spacing (each line’s ascender line sits spacing pixels below the previous baseline, plus twice the stroke width), so lines land within a pixel per line of where Pillow puts them. Like Pillow’s, it doesn’t apply to a single line. It replaces line_spacing, whose default is still 1.2; passing both raises a ValueError. The a anchor uses the same ascender, rounded up to whole pixels as in Pillow.

  • khatt.missing_characters(text, font): the characters a font has no glyph for, each once, in the order typed. These are exactly the ones drawing skips with an UnsupportedCharacterWarning, so you can check first and fall back to another font. Invisible characters (ZWJ, ZWNJ, bidi marks) and line breaks don’t count; keep_tashkeel=False leaves out diacritics, as drawing with it (or render) does.

  • khatt.video.TextClip (new khatt[video] extra): a drop-in for moviepy’s TextClip that shapes text with khatt. It takes moviepy 2.2’s arguments in the same order, including method="caption" wrapping and the automatic font size; font defaults to Amiri and text_align to each paragraph’s direction; fractional font sizes round to whole pixels. Clips follow moviepy’s documented height formula and grow only when stacked diacritics reach beyond it, so nothing is cut off (text too wide for a fixed size and font size warns with TextOverflowWarning); moviepy’s own TextClip crops the bottom of label clips with Pillow 11 and later. The automatic font size is found without rendering, like overlay’s.

  • khatt.caption_image(text, ...): the same caption as a Pillow image, without moviepy.

  • Regression tests against HarfBuzz itself: every glyph of بِتَ (the kasra/fatha case from moviepy and MoneyPrinterTurbo reviews) lands where HarfBuzz’s positions and glyph extents put it, within a pixel, in all four fonts; the whole vocalized Al-Fatiha and Persian and Urdu text match HarfBuzz’s ink boxes; Persian and Urdu letters take their joined forms; and each font’s coverage of Quranic marks and Urdu letters is pinned down.

  • khatt --doctor / khatt.doctor(): reports the Pillow version and whether it has Raqm, the matplotlib version (3.11+ shapes Arabic natively), and whether arabic_reshaper is importable, with a warning that combining it with native shaping corrupts text (double-shaping).

Changed

  • khatt now installs alongside older Pillow and typer: the minimums drop from Pillow 12.3 and typer 0.26.8 to Pillow 10.1 and typer 0.15.4, the oldest versions the full test suite passes with. Projects pinned to Pillow 10/11 (for example through moviepy 2.2.1) can now depend on khatt. CI tests the minimums and MoneyPrinterTurbo’s pins (Pillow 11.3.0, typer 0.26.5) on every change.

  • Vertical metrics (the a, d and m anchors, and spacing) come from FreeType’s scaled metrics, exactly what Pillow’s getmetrics reports, for any font; the d and m anchors can move by a pixel.

  • Development: moviepy holds Pillow below 12, so the lockfile resolves the video extra separately. uv sync keeps the newest Pillow; use uv sync --extra video --no-group latest-pillow for the video extra.

Fixed

  • When a font had no glyph for a diacritic, UnsupportedCharacterWarning named the letter it sat on instead of the diacritic itself.

  • overlay(fit="shrink") repeated each UnsupportedCharacterWarning once per size it tried; it now warns once.

  • Rubik rendered at its Light weight: a variable font’s default instance isn’t always Regular, and Rubik’s is Light (300). Variable fonts now render at their Regular weight (400) in both shaping and rasterization, so Rubik output is heavier and easier to read. Cairo and Noto Naskh Arabic already defaulted to Regular and are unchanged.

0.2.0 - 2026-10-19

Changed

  • Breaking: default sizing. Text now renders at a fixed font size (size, in character rows per em, default 10) and wraps at spaces to fit width, like FIGlet. Before, width always stretched the whole text to fill it, so a short word came out huge and a sentence came out unreadably flat. Pass size=None (CLI: --fit) for the old behaviour; for single-line text its output is byte-identical to 0.1.0.

  • Breaking: PNG output. The CLI’s --output x.png now saves the art itself as an image, in the chosen --style, with --fg / --bg colours (--bg none for transparent). --png text saves the plain high-resolution text instead, which was the only option in 0.1.0.

  • The CLI’s --width now defaults to the terminal width instead of 80.

  • --keep-tashkeel is now a --keep-tashkeel/--strip-tashkeel pair: with neither, the art strips diacritics and --png text images keep them.

  • Rendering is ~20× faster: rasterized glyphs are cached per font and glyph, and FreeType bitmaps are copied directly instead of pixel by pixel (2000 characters: 5.7 s → 0.25 s).

  • LICENSE is now the plain MIT text, so GitHub and other tools detect the license; the note about the bundled OFL fonts moved to a new NOTICE file, which ships in the wheel and sdist.

Added

  • Multi-line input: line breaks start new art lines, separated by a blank line; right-to-left paragraphs are right-aligned.

  • khatt.art_to_image(art, fg=, bg=, cell_width=, padding=): draws text art as an image. Braille dots and shade blocks are drawn as shapes (crisp at any size), ascii characters in a bold sans font; bg=None gives a transparent background.

  • khatt.render_image(text, font, keep_tashkeel=True): the shaped text as a high-resolution Pillow image (black on white), with the same multi-line layout. --png text and the Gradio app use it. Unlike text art, these images keep Arabic diacritics by default; --strip-tashkeel (API: keep_tashkeel=False) removes them.

  • --size and --fit CLI options; khatt.DEFAULT_SIZE.

  • Gradio app: size slider, “Fill width” checkbox, and a download of the art as an image.

Fixed

  • A line break in the input was reported as an unsupported character and the lines were merged into one.

  • The Gradio app left a temporary PNG behind on every keystroke; images are now served from Gradio’s cache, which is pruned hourly.

  • Rendering from several threads at once (as the Gradio app does) could race on the shared FreeType face.

0.1.0 - 2026-07-11

Added

  • Engine A, the rasterize-then-map rendering pipeline: HarfBuzz shaping (uharfbuzz + python-bidi) → FreeType rasterization (freetype-py) → density mapping to character ramps.

  • Correct Arabic shaping: positional forms, the mandatory لا ligature, mixed Arabic/Latin/digit visual ordering, and a keep_tashkeel flag (diacritics are stripped by default).

  • Three output styles: blocks (░▒▓█), ascii (density ramp), braille (2×4 dot patterns), all with an optional coverage threshold.

  • Four bundled OFL fonts: Amiri (default), Cairo, Noto Naskh Arabic, Rubik, with license texts preserved under khatt/fonts/LICENSES/.

  • Public API: khatt.render(text, font, style, width, threshold, keep_tashkeel), khatt.list_fonts(), khatt.list_styles().

  • khatt CLI (typer): --font/--style/--width/--threshold/--keep-tashkeel, --list-fonts, --list-styles, --output (text art or PNG of the rendered text), stdin input, UTF-8 output on Windows consoles.

  • Single-file Gradio app (app.py) with live preview, deployable unchanged to a Hugging Face Space ([app] extra).

  • Golden-file snapshot tests with a pytest --update-golden refresh flow; 83-test suite at ≥85% enforced coverage on a 3.10 to 3.13 × Ubuntu/Windows CI matrix.