NamQR

Professional QR Code Toolkit for Developers and Power Users.

NamQR is a typed Python CLI for generating, scanning, analyzing, exporting, and organizing QR codes. The command layer is intentionally thin: business logic lives in namqr.core, while the Typer CLI handles input and presentation.

Install

pip install namqr

For image and camera scanning extras:

pip install "namqr[scan]"

Quick Start

namqr create "https://example.com" --output example.png
namqr create --type wifi --ssid "Office WiFi" --password "correct horse battery staple"
namqr scan example.png
namqr analyze example.png
namqr history list
namqr stats
namqr doctor

Commands

NamQR exposes the project roadmap as first-class commands:

• create: generate QR codes from plain text, URLs, WiFi, email, phone, SMS, geo, vCard, MeCard, WhatsApp, Telegram, Discord, Zoom, Meet, Teams, crypto, UPI, PayPal, calendar, file/folder links, app/social links, and custom data.
• scan: decode a single image, multiple images, folders, recursive folders, clipboard content, PDFs, GIFs, videos, and camera sources when optional scan dependencies are installed.
• analyze: inspect decoded content, image dimensions, hash, detected type, color hints, quality signals, and duplicate status.
• export: convert QR payloads to PNG, SVG, PDF, EPS, ASCII, UTF-8 block text, Base64, clipboard text, or ZIP.
• batch: generate QR codes from CSV, JSON, TXT, SQLite, Excel, clipboard, or folder sources.
• history, favorite, stats, config, doctor, plugins, and template: manage the local SQLite workspace and automation surface.

Some advanced scanning modes are implemented as optional integrations. When a dependency or platform feature is unavailable, NamQR reports the exact missing capability instead of crashing.

Development

python -m pip install -e ".[dev,scan]"
ruff check .
black --check .
mypy src
pytest
namqr --help

Release

Always publish to TestPyPI first:

python -m pip install -U ".[release]"
ruff check .
black --check .
mypy src
pytest
python -m build
twine check dist/*
twine upload --repository testpypi dist/*

After installing and checking the TestPyPI build, publish the same artifacts to PyPI:

twine upload dist/*

Architecture

• CLI code lives in src/namqr/cli.py.
• Core business logic lives under src/namqr/core.
• SQLite persistence is isolated in core/database.py.
• Payload formatting is centralized in core/payloads.py.
• Optional integrations raise friendly NamQRError subclasses.

Status

This repository is scaffolded as a production-oriented foundation for NamQR. The command surface is complete, typed, and testable; advanced device scanning and highly custom module rendering are intentionally dependency-backed so the core remains stable across Windows, Linux, and macOS.