Metadata-Version: 2.4
Name: shaped-qr-label
Version: 0.1.0
Summary: Generate QR codes with a correctly-shaped Arabic (or Latin) text label, while keeping the QR scannable
Author: Musa Alahmed
License: MIT License
        
        Copyright (c) 2026 Musa Alahmed
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        ---
        
        The bundled font (src/arabic_qr_label/fonts/NotoNaskhArabic-Bold.ttf) is
        "Noto Naskh Arabic" by Google, licensed separately under the SIL Open Font
        License, Version 1.1. See src/arabic_qr_label/fonts/NOTICE.txt.
        
Project-URL: Homepage, https://github.com/MUSAALAHMED4/shaped-qr-label
Project-URL: Issues, https://github.com/MUSAALAHMED4/shaped-qr-label/issues
Keywords: qr,qrcode,arabic,rtl,raqm,harfbuzz,pillow,text-shaping
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Internationalization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qrcode>=7.4.2
Requires-Dist: Pillow>=10.0.0
Dynamic: license-file

# 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

```bash
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:

```python
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

```python
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:

```python
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](LICENSE).
Bundled font: SIL Open Font License 1.1 — see
[`src/shaped_qr_label/fonts/NOTICE.txt`](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.
