If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/x-hw/amazing-qr shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 6 active contributors
• GPL-3.0 licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live x-hw/amazing-qr repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/x-hw/amazing-qr.

What it runs against: a local clone of x-hw/amazing-qr — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in x-hw/amazing-qr | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 918 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of x-hw/amazing-qr. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/x-hw/amazing-qr.git
#   cd amazing-qr
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of x-hw/amazing-qr and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "x-hw/amazing-qr(\\.git)?\\b" \\
  && ok "origin remote is x-hw/amazing-qr" \\
  || miss "origin remote is not x-hw/amazing-qr (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "amzqr/amzqr.py" \\
  && ok "amzqr/amzqr.py" \\
  || miss "missing critical file: amzqr/amzqr.py"
test -f "amzqr/mylibs/matrix.py" \\
  && ok "amzqr/mylibs/matrix.py" \\
  || miss "missing critical file: amzqr/mylibs/matrix.py"
test -f "amzqr/mylibs/draw.py" \\
  && ok "amzqr/mylibs/draw.py" \\
  || miss "missing critical file: amzqr/mylibs/draw.py"
test -f "amzqr/mylibs/ECC.py" \\
  && ok "amzqr/mylibs/ECC.py" \\
  || miss "missing critical file: amzqr/mylibs/ECC.py"
test -f "amzqr/mylibs/data.py" \\
  && ok "amzqr/mylibs/data.py" \\
  || miss "missing critical file: amzqr/mylibs/data.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 918 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~888d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/x-hw/amazing-qr"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Amazing-QR is a Python library that generates QR codes with advanced styling capabilities—supporting standard monochrome QR codes, artistic QR codes (colorized or with custom artistic overlays), and animated GIF QR codes. It wraps the QR code generation logic (error correction encoding, matrix construction) with PIL-based rendering to produce publication-ready QR codes that maintain scannability while embedding images or animations. Modular single-package structure: amzqr/ contains the public API (__init__.py, amzqr.py, terminal.py), with heavy lifting delegated to amzqr/mylibs/ (QR matrix encoding in matrix.py, error correction in ECC.py, rendering in draw.py, constants in constant.py). Entry point is amzqr.py in the repo root for direct CLI usage.

Python developers building applications that need branded or visually distinctive QR codes (e.g., e-commerce platforms, marketing materials, payment systems) where standard black-and-white QR codes lack visual impact or brand integration.

Actively maintained but small-scale. The project was recently renamed from MyQR to amzqr (visible in PyPI badges) and has published releases on PyPI with wheel support. However, the codebase shows minimal test infrastructure, no visible CI/CD setup, and dependencies are pinned to dated versions (numpy 1.11.1 from 2016, Pillow 8.1.1 from 2021). Verdict: Stable for basic use, but lightweight on testing and infrastructure.

Low but notable dependency risk: numpy and Pillow are pinned to 5+ year old versions which may have security vulnerabilities and compatibility issues with modern Python (3.9+). The project is maintained by a single author (@x-hw) with no visible test suite or CI pipeline, creating maintenance bus-factor risk. No indication of breaking changes or deprecation policy.

No PR or milestone data visible in file list. The most recent signal is the PyPI rebranding from MyQR → amzqr, suggesting a maintenance refresh. The example/ directory shows diverse use cases (animated GIFs, colorized codes, embedded images) that appear complete and stable.

pip install amzqr
amzqr "https://github.com" -o qrcode.png

Or clone and test locally:

git clone https://github.com/x-hw/amazing-qr.git
cd amazing-qr
pip install -r requirements.txt
python amzqr.py "Hello World" -o test.png

Daily commands: CLI: amzqr "data" [-v version] [-l {L,M,Q,H}] [-p image.png] [-c] [-d /output/dir] Programmatic: from amzqr import generate; generate("text", picture='bg.png', colorized=True) (see example usage in README). No dev server; all operations are batch generation to disk.

• amzqr/amzqr.py — Main entry point and API for QR code generation; all public functions and parameters are defined here.
• amzqr/mylibs/matrix.py — Core QR code matrix generation logic; implements the fundamental QR encoding algorithm.
• amzqr/mylibs/draw.py — Handles rendering of QR matrices to images and animated GIFs; bridges data to visual output.
• amzqr/mylibs/ECC.py — Error correction code implementation; critical for QR code reliability and data integrity.
• amzqr/mylibs/data.py — Data encoding and mode selection; transforms user input into QR-compatible byte streams.
• amzqr/__init__.py — Package initialization; exposes the public API for pip-installed library usage.
• setup.py — Build and distribution configuration; defines dependencies and package metadata.

• data.py (Data Encoding) (Python, NumPy) — Selects optimal encoding mode (numeric, alphanumeric, byte, kanji), converts input to bitstream, calculates required version.
  • Failure mode: If mode detection fails or data exceeds version capacity, generation aborts or selects wrong version.
• matrix.py (QR Matrix) (Python, NumPy) — Constructs 2D QR matrix: position patterns, timing info, data placement, format/version info.
  • Failure mode: Malformed position patterns or incorrect data interleaving produces unreadable QR.
• ECC.py (Error Correction) (Python) — Reed-Solomon encoder; generates parity codewords for specified ECC level (L/M/Q/H).
  • Failure mode: Weak ECC or calculation errors reduce QR recovery capability or prevent scanning.
• draw.py (Rendering) (Pillow, ImageIO, NumPy) — Converts QR matrix and style params (colors, logo, frame animation) into image files (PNG/JPG/GIF).
  • Failure mode: Logo blend artifacts, frame timing issues, or color space errors produce visually broken output.
• amzqr.py (Public API) (Python) — Orchestrates encoding → matrix → ECC → rendering pipeline; exposes main generate() function.
  • Failure mode: Parameter validation issues or orchestration bugs cause crashes or invalid QR output.

• User input (text/URL) → data.py — Raw string is analyzed for encoding mode and length.
• data.py → matrix.py — Encoded bitstream and QR version passed to matrix generator.
• matrix.py → ECC.py — Data blocks sent for Reed-Solomon error correction.
• ECC.py → matrix.py — undefined

Add Support for a New QR Encoding Mode

1. Define encoding rules and capacity tables in amzqr/mylibs/constant.py (amzqr/mylibs/constant.py)
2. Implement mode-specific encoding logic in amzqr/mylibs/data.py; add case to mode-selection logic (amzqr/mylibs/data.py)
3. Test with new input types via amzqr/amzqr.py main entry point (amzqr/amzqr.py)

Add a New Image Effect or Style

1. Add effect parameters to the main generate() function in amzqr/amzqr.py (amzqr/amzqr.py)
2. Implement rendering logic in amzqr/mylibs/draw.py; modify pixel color or placement functions (amzqr/mylibs/draw.py)
3. Pass effect config through amzqr/mylibs/theqrmodule.py to drawing methods (amzqr/mylibs/theqrmodule.py)

Extend QR Code Version Support

1. Update capacity and capacity tables in amzqr/mylibs/constant.py for new QR versions (amzqr/mylibs/constant.py)
2. Modify version selection logic in amzqr/mylibs/data.py to auto-select larger versions (amzqr/mylibs/data.py)
3. Verify matrix generation in amzqr/mylibs/matrix.py handles timing and format info for new versions (amzqr/mylibs/matrix.py)

Add a New Output Format (e.g., SVG)

1. Add format parameter to amzqr/amzqr.py public API (amzqr/amzqr.py)
2. Create new renderer in amzqr/mylibs/draw.py or a separate module (e.g., draw_svg.py) (amzqr/mylibs/draw.py)
3. Route format selection through amzqr/mylibs/theqrmodule.py (amzqr/mylibs/theqrmodule.py)

• Python + Pillow — Cross-platform image generation and manipulation; native support for PNG, JPEG, GIF encoding.
• NumPy — Efficient 2D array operations for QR matrix calculations and image data handling.
• ImageIO — Unified interface for animated GIF creation from frame sequences.
• Reed-Solomon ECC — QR spec requirement; provides configurable error correction (L/M/Q/H levels).

• Encode entire data upfront before matrix generation

  • Why: Simplifies matrix sizing and version selection; allows one-pass encoding.
  • Consequence: Breaks streaming for very large datasets; entire data must fit in memory.

• Manual QR spec implementation vs. third-party library

  • Why: Enables custom styling, embedded images, and animated QR codes beyond standard spec.
  • Consequence: Higher maintenance burden; must keep aligned with QR ISO 18004 spec updates.

• Store entire animated GIF in memory as frame list

  • Why: Enables simple frame generation and PIL-based encoding.
  • Consequence: Memory-intensive for large frame counts or high resolutions; not suitable for streaming output.

• Does not implement QR decoding/reading; generation-only.
• Does not support real-time or streaming QR output; all frames pre-generated.
• Does not provide web service or API server; library-only (no built-in HTTP interface).
• Does not handle multi-symbol QR (Micro QR or structured append).

Dependency versions: numpy 1.11.1 and Pillow 8.1.1 are pinned and ancient; may fail on Python 3.9+ or modern systems—you'll likely need to upgrade manually. Image blending: Colorized QR codes require careful contrast tuning (-con, -bri flags); defaults may produce unscannabe codes if image contrast is too high. GIF animation: -p flag with GIF input creates frame-by-frame QR overlays; frame count and timing are inferred from the image, not configurable via CLI. Character encoding: Only supports UTF-8; non-UTF-8 input will silently mangle. No input validation: Passing very long strings without explicit error correction level (-l H) may silently fail or produce overly dense QR codes.

• QR Code Structure (Finder Patterns, Timing Patterns, Format Information) — You must understand where finder patterns (3×3 L-shaped squares), timing patterns (alternating 1D stripes), and format information (error correction level + mask) are placed in the matrix to debug or extend matrix.py.
• Reed-Solomon Error Correction (BCH Codes) — ECC.py implements Reed-Solomon to add redundancy so QR codes remain scannable with up to 30% physical damage; understanding this is critical to verify correctness and tune error correction levels.
• QR Data Encoding Modes (Numeric, Alphanumeric, Byte, Kanji) — structure.py switches between encoding modes based on input characters; choosing the right mode minimizes QR version and affects scannability, especially for international text.
• Masking (XOR Patterns in QR Generation) — QR codes apply one of 8 XOR mask patterns to the data matrix to avoid large uniformly-colored regions that confuse scanners; matrix.py applies masks, which you need to understand when debugging rendering artifacts.
• PIL/Pillow Image Blending (Alpha Compositing, Color Models) — draw.py uses PIL's alpha blending to overlay artistic images onto QR matrices while maintaining scannability; understanding RGB/RGBA and PIL's ImageDraw is essential to modify styling logic.
• Capacity Planning (QR Version vs Data Capacity) — constant.py stores lookup tables mapping QR version (1–40) to max bytes per error correction level; understanding this prevents silent failures when inputs exceed capacity.
• GIF Animation (Frame Sequencing, Delay Timing) — draw.py uses imageio to serialize frames into animated GIFs; you need to understand frame delays and loop behavior to troubleshoot or extend animation features.

• lincolnloop/python-qrcode — Most popular pure-Python QR library; amazing-qr extends its capabilities with artistic styling and animation—good reference for comparison.
• pyqrcode/pyqrcode — Alternative QR library with SVG output support; complements amazing-qr for use cases requiring vector rather than raster QR codes.
• zxing/zxing — ZXing Java library (with Python bindings); de facto QR scanning standard—useful if you need to validate amazing-qr output is actually scannable.
• Pillow/Pillow — Image processing dependency; you'll need to understand PIL drawing primitives to modify awesome-qr's rendering logic in draw.py.
• x-hw/MyQR — Original predecessor repository before rebranding to amazing-qr; historical context and issue tracker if needing legacy context.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for amzqr/mylibs/ core modules

The repo lacks any test directory or test files. Given the complexity of QR code generation logic (ECC.py, matrix.py, data.py, structure.py), unit tests would catch regressions and validate the core encoding/error-correction algorithms. This is critical for a library that users depend on for correct QR code output.

• [ ] Create tests/ directory with init.py
• [ ] Add test_data.py for amzqr/mylibs/data.py covering different QR versions and modes
• [ ] Add test_matrix.py for amzqr/mylibs/matrix.py to validate pattern generation
• [ ] Add test_ECC.py for amzqr/mylibs/ECC.py to verify error correction encoding
• [ ] Add test_draw.py for amzqr/mylibs/draw.py to test image generation outputs
• [ ] Create GitHub Actions workflow (.github/workflows/test.yml) to run pytest on Python 3.7+
• [ ] Update requirements.txt to include pytest and pytest-cov

Refactor amzqr/amzqr.py into focused submodules for better maintainability

The main amzqr.py file likely contains mixed concerns (CLI handling, API functions, animated GIF generation, image compositing). Splitting into amzqr/qr_generator.py, amzqr/gif_handler.py, and amzqr/cli.py would make the codebase easier to test, understand, and extend. This is evident from the animated GIF examples and the terminal.py companion file.

• [ ] Analyze amzqr/amzqr.py to identify function groupings (QR generation vs GIF animation vs image compositing)
• [ ] Extract GIF-related functions into new amzqr/gif_handler.py
• [ ] Extract image composition/drawing logic into new amzqr/image_composer.py
• [ ] Move CLI argument parsing from amzqr/amzqr.py into amzqr/cli.py (or enhance amzqr/terminal.py)
• [ ] Update amzqr/init.py to maintain backward compatibility with existing imports
• [ ] Update example/ and README.md with any API changes

Add validation tests and documentation for supported input/output formats

The dependencies (imageio, Pillow, numpy) and examples suggest support for PNG, JPG, GIF formats, but there's no explicit documentation or validation tests. Adding integration tests that verify animated GIF generation works with various input formats (like the alipay.gif, wechatpay.jpg examples) would prevent format-handling regressions and clarify supported formats.

• [ ] Create tests/test_formats.py with integration tests for each output format (PNG, JPG, GIF)
• [ ] Add test cases for animated GIF generation using example/alipay.gif and example/wechatpay.jpg as inputs
• [ ] Add tests verifying animated QR codes work with different frame counts and durations
• [ ] Document supported input/output formats in README.md with format-specific limitations
• [ ] Add validation in amzqr/amzqr.py to reject unsupported formats with clear error messages
• [ ] Create example script in example/format_demo.py demonstrating all supported conversions

• Add unit tests for amzqr/mylibs/ECC.py error correction encoding against known test vectors; currently no test infrastructure exists to validate Reed-Solomon implementation correctness.
• Upgrade and pin requirements.txt to modern versions (numpy 1.24+, Pillow 10.0+) and add Python 3.9+ compatibility testing via GitHub Actions or tox.
• Document the amzqr/mylibs/structure.py character mode encoding logic in docstrings and add examples showing how numeric/alphanumeric/byte/kanji modes affect QR version selection (currently undocumented).

The codebase has significant security concerns primarily stemming from severely outdated dependencies with multiple known vulnerabilities. Pillow 8.1.1, NumPy 1.11.1, and imageio 1.5 are all several years old and contain patched security issues. The most critical risk is in Pillow, which handles image processing and has known arbitrary code execution vulnerabilities. The project lacks evidence of security scanning and dependency management practices. Immediate action is required to upgrade all dependencies to current versions. The core library logic appears reasonably sound for a QR code generation utility, but without modern, patched dependencies, the application remains vulnerable to exploitation.

• High · Outdated Pillow Dependency with Known Vulnerabilities — requirements.txt - Pillow==8.1.1. The project uses Pillow==8.1.1, which was released in February 2021 and contains multiple known security vulnerabilities including CVE-2021-28675, CVE-2021-28676, CVE-2021-28677, CVE-2021-28678, CVE-2021-34552, and others. These vulnerabilities can lead to arbitrary code execution, denial of service, and information disclosure through malicious image files. Fix: Upgrade Pillow to version 10.0.0 or later. Run 'pip install --upgrade Pillow' and update requirements.txt to specify a minimum secure version (e.g., Pillow>=10.0.0).
• High · Severely Outdated NumPy Dependency — requirements.txt - numpy==1.11.1. The project uses numpy==1.11.1, which was released in 2016 and is over 7 years old. This version contains multiple known vulnerabilities and lacks critical security patches and bug fixes. It may also have compatibility issues with modern Python versions. Fix: Upgrade numpy to a current version (1.24.x or 2.0.x depending on Python version). Update requirements.txt to 'numpy>=1.24.0' or later versions compatible with the target Python version.
• Medium · Outdated imageio Dependency — requirements.txt - imageio==1.5. The project uses imageio==1.5, which was released in 2017 and is significantly outdated. Newer versions contain security improvements and bug fixes. This package is used for GIF generation, which involves parsing and processing image data that could be exploited. Fix: Upgrade imageio to version 2.25.0 or later. Update requirements.txt to 'imageio>=2.25.0' to ensure security patches and modern functionality are available.
• Medium · Pinned Dependency Versions Without Upper Bounds — requirements.txt. While the requirements.txt uses exact versions, they are all outdated. Without proper dependency management and version constraints, the project becomes vulnerable to known exploits. There's no indication of security scanning in the CI/CD pipeline. Fix: Implement semantic versioning with minimum version constraints (e.g., 'Pillow>=10.0.0,<11.0.0'). Use tools like 'pip-audit' in CI/CD to regularly check for known vulnerabilities. Consider using 'safety' or 'bandit' for automated security scanning.
• Low · Missing Security Headers and Validation — amzqr/amzqr.py and amzqr/mylibs/ modules. The codebase appears to accept user input (image paths, QR code data) without explicit validation or sanitization being visible in the file structure. While this is primarily a library (not a web service), improper input handling could lead to path traversal or other attacks if deployed in a web context. Fix: Implement input validation for file paths (use pathlib and resolve paths safely), validate QR code data content, and add checks for malicious image file formats. Document safe usage patterns for developers integrating this library.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.