QR Code Generator
A customizable Python QR code generator that creates QR codes from URLs or plain text.
Customize foreground and background colors, add an optional center icon, and save generated QR codes in PNG, JPG, or JPEG formats.
Use it through a command-line interface (CLI) or integrate it directly into your Python applications.
Features
- URL and Text Support: Generate QR codes from URLs or plain text.
- Custom Colors: Customize QR code foreground and background colors.
- Center Icon: Add an optional image to the center of your QR code.
- Multiple Formats: Save QR codes as PNG, JPG, or JPEG.
- Custom Output: Specify the output filename and destination directory.
- Python API: Integrate QR generation into your own applications.
- Automated Tests: Includes unit tests using pytest.
Requirements
- Python 3.8 or higher
- pip
Installation
Install from PyPI
pip install sah-qr-generator
Install from GitHub
Clone the repository:
git clone https://github.com/Ahmed122000/QR-Code-Generator.git
Navigate to the library directory:
cd QR-Code-Generator/qr-generator
Install the package:
pip install .
Install development dependencies
If you want to contribute or run the tests, install the package in editable mode with its development dependencies:
pip install -e ".[dev]"
Usage
1. Command-Line Interface (CLI)
After installation, you can use the qr command directly from your terminal.
Generate a QR code from a URL:
qr --url https://example.com
Generate a QR code from plain text:
qr --txt "Hello, World!"
Customize QR code colors:
qr --url https://example.com --color blue --bg-color white
Add an icon to the center:
qr --url https://example.com --icon assets/logo.png
Customize the output filename and directory:
qr --url https://example.com \
--output my_qr \
--path custom_output \
--format png
Display available commands and options:
qr --help
Generated QR codes are saved in assets/output/ by default.
2. Python API
You can also use the QR generator directly in your Python applications.
Generate a QR code:
from qr_generator import QRGenerator
qr = QRGenerator.generate_qrcode(
data="https://example.com",
color="black",
background_color="white"
)
The generate_qrcode() method returns a Pillow Image object. It does not save the image automatically.
Save the generated QR code:
saved_path = QRGenerator.save_qrcode(
image=qr,
output="my_qr",
output_path="assets/output",
img_format="png"
)
print(f"QR code saved at: {saved_path}")
Generate and save a QR code with a center icon:
from qr_generator import QRGenerator
qr = QRGenerator.generate_qrcode(
data="https://example.com",
color="blue",
background_color="white",
icon_path="assets/logo.png"
)
saved_path = QRGenerator.save_qrcode(
image=qr,
output="branded_qr",
output_path="assets/output",
img_format="png"
)
CLI Reference
| Option | Description | Default |
|---|---|---|
--url |
URL to encode in the QR code | None |
--txt |
Text to encode in the QR code | None |
--color |
QR code foreground color | black |
--bg-color |
QR code background color | white |
--icon |
Path to the optional center icon | None |
--output |
Output filename without extension | qrcode |
--path |
Output directory | assets/output |
--format |
Output image format: png, jpg, jpeg | png |
-h, --help |
Display help information | — |
The --url and --txt options are mutually exclusive. Provide exactly one of them.
Python API Reference
generate_qrcode()
Generates a QR code and returns a Pillow Image object.
| Parameter | Description | Default |
|---|---|---|
data |
URL or text to encode | Required |
color |
QR code foreground color | black |
background_color |
QR code background color | white |
box_size |
Size of each QR code module in pixels | 10 |
border |
QR code border width in modules | 4 |
icon_path |
Optional path to a center icon | None |
save_qrcode()
Saves a generated Pillow Image to the specified location.
| Parameter | Description | Default |
|---|---|---|
image |
Pillow Image object | Required |
output |
Output filename without extension | qrcode |
output_path |
Destination directory | assets/output |
img_format |
Image format: png, jpg, jpeg | png |
The method returns a Path object representing the saved image.
Project Structure
QR-Code-Generator/
│
├── qr-generator/
│ │
│ ├── src/
│ │ └── qr_generator/
│ │ ├── __init__.py
│ │ ├── generator.py
│ │ └── cli.py
│ │
│ ├── tests/
│ │ ├── test_cli.py
│ │ ├── test_generator.py
│ │ └── test_save_qr.py
│ │
│ ├── assets/
│ │ └── output/
│ │
│ ├── pyproject.toml
│ ├── README.md
│ ├── LICENSE
│ └── .gitignore
│
└── README.md
Testing
The project uses:
- pytest: Automated testing.
- pytest-cov: Test coverage measurement.
Install development dependencies:
pip install -e ".[dev]"
Run all tests:
python -m pytest
Run tests with coverage:
python -m pytest --cov=qr_generator --cov-report=term-missing
Error Handling
The library handles common errors, including:
- Empty or invalid input.
- Invalid QR code configuration.
- Missing or invalid icon files.
- Unsupported image formats.
- File permission errors.
- QR code data overflow.
The core library raises meaningful exceptions, allowing applications to handle errors according to their own requirements. The CLI catches relevant exceptions and displays appropriate error messages.
Technologies Used
- Python: Main programming language.
- qrcode: QR code generation.
- Pillow: Image processing and manipulation.
- argparse: Command-line argument parsing.
- pytest: Automated testing.
- pytest-cov: Test coverage reporting.
- setuptools: Python package building and distribution.
Contributing
Contributions are welcome!
-
Fork the repository.
-
Create a feature branch:
git checkout -b feature/your-feature-name
-
Make your changes.
-
Run the tests:
python -m pytest
-
Commit your changes:
git commit -m "Add your feature"
-
Push your branch and open a Pull Request.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Author
Ahmed Hesham
- GitHub: Ahmed122000
- LinkedIn: Ahmed Hesham
Acknowledgments
- python-qrcode for QR code generation.
- Pillow for image processing.
Metadata
Release files for sah-qr-generator 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sah_qr_generator-1.0.0.tar.gz | 11.9 kB | Without provenance | Details for sah_qr_generator-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sah_qr_generator-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for sah_qr_generator-1.0.0-py3-none-any.whl |
Total release size: 20.6 kB
Release files / sah_qr_generator-1.0.0.tar.gz
| Download URL | sah_qr_generator-1.0.0.tar.gz |
|---|---|
| Size | 11.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
10d06af0f4efee7e36928045e450b23d2391579d3cbfb648e9446c8aa08cc7fa
|
|
BLAKE2b-256 checksum How to use checksums |
30df6b8a2dbf84e1e728b0929fc3da82bdb1cae47972308d7b54a121d79c5412
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.11
|
Release files / sah_qr_generator-1.0.0-py3-none-any.whl
| Download URL | sah_qr_generator-1.0.0-py3-none-any.whl |
|---|---|
| Size | 8.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a5be928ff0778d967f1a42803d4cc7d3460942b6147bf6771df5eb58e2a0b34e
|
|
BLAKE2b-256 checksum How to use checksums |
95eee6865ea5ba0d185308f738b8ef855ef1c02d3d6217ff54e947e4805877b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.11
|
Security for sah-qr-generator 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.