Metadata-Version: 2.4
Name: qrstyle
Version: 1.0.0
Summary: Styled QR codes with a logo: rounded, square or dots, PNG or WEBP, sync and async.
Author: nessshon
Maintainer: nessshon
License-Expression: MIT
Project-URL: Homepage, https://github.com/nessshon/qrstyle/
Keywords: QR code,qrcode,Pillow,image,logo
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.16,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=11.3; python_version < "3.10"
Requires-Dist: Pillow>=12.3; python_version >= "3.10"
Requires-Dist: qrcode>=7.4
Dynamic: license-file

# 🔳 qrstyle

![Python Versions](https://img.shields.io/badge/Python-3.9%20--%203.15-black?color=FFE873&labelColor=3776AB)
[![PyPI](https://img.shields.io/pypi/v/qrstyle.svg?color=FFE873&labelColor=3776AB)](https://pypi.org/project/qrstyle/)
[![License](https://img.shields.io/github/license/nessshon/qrstyle)](https://github.com/nessshon/qrstyle/blob/main/LICENSE)

| `rounded` | `square` | `dots` |
|:---:|:---:|:---:|
| <img src="https://raw.githubusercontent.com/nessshon/qrstyle/main/.assets/rounded.png" width="200" alt="rounded"> | <img src="https://raw.githubusercontent.com/nessshon/qrstyle/main/.assets/square.png" width="200" alt="square"> | <img src="https://raw.githubusercontent.com/nessshon/qrstyle/main/.assets/dots.png" width="200" alt="dots"> |
| <img src="https://raw.githubusercontent.com/nessshon/qrstyle/main/.assets/rounded-logo.png" width="200" alt="rounded with a logo"> | <img src="https://raw.githubusercontent.com/nessshon/qrstyle/main/.assets/square-logo.png" width="200" alt="square with a logo"> | <img src="https://raw.githubusercontent.com/nessshon/qrstyle/main/.assets/dots-logo.png" width="200" alt="dots with a logo"> |

### Styled QR codes for Python

Rounded, square or dots, with a logo in the centre. Draws to a Pillow image, PNG or WEBP bytes, or a file.

## Installation

```bash
pip install qrstyle
```

## Usage

```python
import qrstyle

code = qrstyle.make("https://example.com")

code.save("qrcode.png", 512)  # format from the extension: .png or .webp
image = code.to_image(512)  # PIL.Image, 512 x 512
data = code.to_bytes(512, "webp")  # "png" by default
```

In async code:

```python
code = await qrstyle.amake("https://example.com")
data = await code.ato_bytes(512)
```

Everything `make()` accepts:

```python
code = qrstyle.make(
    "https://example.com",  # text to encode
    style="rounded",  # "rounded" | "square" | "dots", the logo follows it
    logo=None,  # PNG or JPEG bytes, up to 5 MB and 4096 x 4096 px
)
```

The logo goes in as bytes, from a file or downloaded by URL:

```python
from pathlib import Path
from urllib.request import urlopen

logo = Path("logo.png").read_bytes()
# or: logo = urlopen("https://example.com/logo.png", timeout=10).read()

code = qrstyle.make("https://example.com", style="dots", logo=logo)
```

**Errors**

- `DataTooLongError` — the text does not fit a QR code or the size; `code.min_size` is the smallest size that fits
- `LogoError` — the logo is not a PNG or JPEG, or is over 5 MB or 4096 x 4096 px
- `ValueError` — a wrong style or format, or a size over 4096

`DataTooLongError` and `LogoError` are `QRError`.

## HTTP API

The same codes over HTTP, in `api/`:

```bash
git clone https://github.com/nessshon/qrstyle.git && cd qrstyle/api
docker compose up -d --build
```

`GET /create` returns an image:

| Parameter | Default   | Description                                     |
|-----------|-----------|-------------------------------------------------|
| `data`    | required  | Text to encode                                  |
| `size`    | `medium`  | `small`, `medium` or `large`: 256, 512, 1024 px |
| `format`  | `png`     | `png` or `webp`                                 |
| `style`   | `rounded` | `rounded`, `square` or `dots`                   |
| `logo`    | —         | URL of a PNG or JPEG                            |

```bash
curl -G https://example.com/create \
  --data-urlencode "data=https://example.com" \
  --data-urlencode "logo=https://example.com/logo.png" \
  -d style=dots -o qrcode.png
```

**Errors** come as JSON `{"detail": "..."}`

- `400` — the logo can't be used or the text does not fit
- `422` — a wrong parameter

## License

This repository is distributed under the [MIT License](https://github.com/nessshon/qrstyle/blob/main/LICENSE).
