shaped-qr-label

Generate a QR code with a text label drawn on top of it — with correct Arabic shaping and right-to-left layout (letters properly joined, positioned start/middle/end, read right-to-left), while keeping the QR code scannable. English/Latin text is supported too; direction is auto-detected per string.

Built because no existing PyPI/GitHub library reliably combined: QR generation + a still-scannable overlay label + correctly shaped Arabic text.

Why this is hard

Arabic letters are contextual — each letter's shape changes depending on whether it's at the start, middle, or end of a word (منفصل / بداية / وسط / نهاية) — and the script is right-to-left. Most imaging libraries draw each character in isolation, unjoined, and left-to-right, which garbles Arabic text. This library uses Pillow's raqm text-layout backend (HarfBuzz for shaping + FriBidi for bidi reordering) and ships a tested Arabic font (Noto Naskh Arabic) so results don't depend on fonts installed on the host.

Install

pip install shaped-qr-label

Arabic shaping requires Pillow to be built with raqm support. Official Pillow wheels for Linux/macOS/Windows have included it since Pillow 8.2+. You can check at runtime:

from shaped_qr_label import raqm_available
print(raqm_available())  # True if Arabic shaping will work correctly

If it returns False, Arabic text will still render but unjoined and in the wrong visual order — reinstall Pillow from PyPI (not a system package manager) to get a raqm-enabled build.

Usage

from shaped_qr_label import render_qr_label

img = render_qr_label(
    "https://example.com/asset/123",
    primary_text="مستودع الأدوية",
    secondary_text="AST-00123",
)
img.save("qr.png")

Mixed or Latin-only text works the same way:

img = render_qr_label(
    "https://example.com",
    primary_text="Main Warehouse",
    secondary_text="AST-00123",
)

Parameters

Parameter Default Description
url — Data encoded in the QR code
primary_text — Larger, bold line (auto RTL/LTR)
secondary_text None Smaller, grey second line (auto RTL/LTR)
font_path bundled Noto Naskh Arabic Path to a custom .ttf/.otf
box_size 18 QR module pixel size
border 3 QR quiet-zone modules
label_width_ratio 0.55 Label card width as a fraction of QR width
label_height_ratio 0.25 Label card height as a fraction of QR height

Keep the label ratios conservative — beyond roughly 14% of the QR's total area, some scanners fail to decode (error correction level H is used internally to leave headroom for this).

License

Code: MIT, © Musa Alahmed — see LICENSE. Bundled font: SIL Open Font License 1.1 — see src/shaped_qr_label/fonts/NOTICE.txt.

Contributions are welcome under the same MIT license; please keep the copyright notice intact in any fork or redistribution.

Project links

Data verified by PyPI on Aug 5, 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 musaalahmed from gravatar.com musaalahmed

Credits

Author: Musa Alahmed

GitHub Statistics

Data verified by PyPI on Aug 5, 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 License)

Requires

Python >=3.10

Tags

qr qrcode arabic rtl raqm harfbuzz pillow text-shaping

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

shaped_qr_label-0.1.0.tar.gz (93.2 kB view details)

Uploaded Source

Built Distribution

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

shaped_qr_label-0.1.0-py3-none-any.whl (91.3 kB view details)

Uploaded Python 3

File details

Details for the file shaped_qr_label-0.1.0.tar.gz.

File metadata

  • Download URL: shaped_qr_label-0.1.0.tar.gz
  • Upload date:
  • Size: 93.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for shaped_qr_label-0.1.0.tar.gz
Algorithm Hash digest
SHA256 01145688b5a381d1c9a5c71e20f02c19f01b774e36c593070ad06c2a875a470d
MD5 937876b0890f2622e97e4604d47270ba
BLAKE2b-256 27ecd1292754629b8b298d60091d539a7d3ba94c48c0f66ff87a83226c401ccb

See more details on using hashes here.

Provenance

The following attestation bundles were made for shaped_qr_label-0.1.0.tar.gz:

Publisher: publish.yml on MUSAALAHMED4/shaped-qr-label

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

File details

Details for the file shaped_qr_label-0.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for shaped_qr_label-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 06ba53ba8618ffcad0563a76a49d5d45034555e7f17f5deaed449db07a9587b0
MD5 294f639f54b203a6a522039af232bce7
BLAKE2b-256 405e9cc43866950757bf0b3b55058a65cebf63f2b5a2bc5e624155243b4be67b

See more details on using hashes here.

Provenance

The following attestation bundles were made for shaped_qr_label-0.1.0-py3-none-any.whl:

Publisher: publish.yml on MUSAALAHMED4/shaped-qr-label

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

Supported by

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