url2qr 0.1.0

Zero-dependency QR code generator optimized for URLs

url2qr

Zero-dependency QR code generator optimized for URLs. Parallel implementations in Python and Rust, verified to produce bit-exact identical output.

Features

• Byte mode encoding (required for URLs with lowercase letters)
• EC-L error correction (7% recovery, optimized for clean screen display)
• Versions 1-6 (up to 134 characters)
• Fixed mask pattern (no scoring overhead)
• Terminal output with Unicode half-blocks

Installation

Python (pip)

pip install url2qr

Python (conda)

conda install -c mcg url2qr

Rust (cargo)

cargo install url2qr

Or add to your Cargo.toml:

[dependencies]
url2qr = "0.1"

Usage

Python

from url2qr import generate_qr, qr_to_terminal

# Display in terminal
print(qr_to_terminal("https://example.com"))

# Get raw matrix (list of lists, 1=dark, 0=light)
matrix = generate_qr("https://example.com")

Rust

use url2qr::{generate_qr, qr_to_terminal};

let matrix = generate_qr("https://example.com").unwrap();
let output = qr_to_terminal("https://example.com", 4, false).unwrap();
println!("{output}");

CLI

# Python
python url2qr.py "https://example.com"

# Rust
cargo run -- "https://example.com"

Vendoring

The Python module (url2qr.py) is designed to be vendored directly into larger projects. Simply copy the single file into your project. It is licensed under BSD 3-Clause and may be freely vendored into any other BSD 3-Clause software without credit or attribution.

Development

Prerequisites

• Python 3.9+ with pytest and qrcode (test dependency)
• Rust 1.70+ (MSRV)

Setup

# Python
pip install -e ".[test]"
pre-commit install

# Rust
cd rust && cargo build

Running Tests

# Python tests (validates against qrcode reference package)
pytest test_url2qr.py -v

# Rust tests (unit + integration with embedded reference matrices)
cd rust && cargo test

# Cross-language validation (regenerate vectors and compare)
python test-vectors/generate.py
cd rust && cargo run --bin dump_vectors > /tmp/rust_vectors.json
# Compare the two JSON files

Linting

# Python
pre-commit run --all-files

# Rust
cd rust && cargo fmt --check && cargo clippy -- -D warnings

Cross-Language Verification

Both implementations are verified to produce bit-exact identical QR matrices for all test URLs. The test-vectors/ directory contains shared test vectors generated from the Python implementation (which is itself validated against the qrcode reference package). CI runs cross-validation on every push.

Constraints

• Maximum URL length: 134 characters
• Only supports byte mode (URLs with lowercase require this)
• Fixed to EC-L and mask pattern 0

Acknowledgment

This module was developed by Michael Grant from scratch using Claude. There are quite a few more capable QR code libraries in existence, most notably the qrcode module used to drive our unit tests. This module does not fork these other libraries; instead it was constructed from first principles with significantly reduced functionality in order to support a particular embedded use case.