# 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)
```bash
pip install url2qr
```
### Python (conda)
```bash
conda install -c mcg url2qr
```
### Rust (cargo)
```bash
cargo install url2qr
```
Or add to your `Cargo.toml`:
```toml
[dependencies]
url2qr = "0.1"
```
## Usage
### Python
```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
```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
```bash
# 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.78+ (MSRV)
### Setup
```bash
# Python
pip install -e ".[test]"
pre-commit install
# Rust
cd rust && cargo build
```
### Running Tests
```bash
# 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
```bash
# 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](https://github.com/mcg1969) from scratch
using Claude. There are quite a few more capable QR code libraries in existence,
most notably the [`qrcode`](https://github.com/lincolnloop/python-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.