{"id":48830072,"url":"https://github.com/aiqso/qr-builder","last_synced_at":"2026-04-14T20:00:42.126Z","repository":{"id":327812183,"uuid":"1110902126","full_name":"AIQSO/qr-builder","owner":"AIQSO","description":"Generate and embed QR codes into images via Python, CLI, and FastAPI","archived":false,"fork":false,"pushed_at":"2025-12-14T23:24:16.000Z","size":94,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-17T12:43:06.102Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AIQSO.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-05T22:43:21.000Z","updated_at":"2025-12-14T23:24:10.000Z","dependencies_parsed_at":"2026-04-14T20:00:34.209Z","dependency_job_id":null,"html_url":"https://github.com/AIQSO/qr-builder","commit_stats":null,"previous_names":["aiqso/qr-builder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AIQSO/qr-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIQSO%2Fqr-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIQSO%2Fqr-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIQSO%2Fqr-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIQSO%2Fqr-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AIQSO","download_url":"https://codeload.github.com/AIQSO/qr-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AIQSO%2Fqr-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31812977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-14T20:00:28.423Z","updated_at":"2026-04-14T20:00:42.121Z","avatar_url":"https://github.com/AIQSO.png","language":"Python","readme":"# QR Builder\n\n[![PyPI](https://img.shields.io/pypi/v/qr-builder)](https://pypi.org/project/qr-builder/)\n[![Docker](https://img.shields.io/badge/ghcr.io-aiqso%2Fqr--builder-blue)](https://github.com/AIQSO/qr-builder/pkgs/container/qr-builder)\n[![Docs](https://img.shields.io/badge/docs-aiqso.github.io-blue)](https://aiqso.github.io/qr-builder/)\n[![CI](https://github.com/AIQSO/qr-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/AIQSO/qr-builder/actions/workflows/ci.yml)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n\nA production-ready Python package for generating QR codes with multiple artistic styles. Perfect for marketing materials, product packaging, event flyers, and website integration.\n\n## Features\n\n- **5 QR Code Styles:**\n  - **Basic** - Simple QR codes with custom colors\n  - **With Logo** - Logo/image embedded in QR center\n  - **With Text** - Text/words displayed in QR center\n  - **Artistic** - Image transforms INTO the QR code pattern (colorful)\n  - **QArt** - Halftone/dithered artistic style\n\n- **Multiple Interfaces:**\n  - REST API via FastAPI with OpenAPI documentation\n  - CLI for command-line usage\n  - Web interface with visual builder\n  - WordPress-embeddable widget\n  - Python library for programmatic use\n\n- **Production Ready:**\n  - Docker support\n  - CORS enabled for web integration\n  - Batch processing for multiple images\n  - Quality presets for artistic QR codes\n\n## Quick Start\n\n### Installation\n\n```bash\n# From source\ngit clone https://github.com/aiqso/qr-builder.git\ncd qr-builder\npip install -e \".[dev]\"  # Include dev dependencies for testing\n```\n\n### CLI Usage\n\n```bash\n# Generate a basic QR code\nqr-builder qr \"https://example.com\" qr.png --size 600\n\n# QR with logo in center\nqr-builder logo \"https://example.com\" logo.png output.png --scale 0.25\n\n# QR with text in center\nqr-builder text \"https://example.com\" \"HELLO\" output.png --font-color \"#e07030\"\n\n# Artistic QR (image becomes the QR pattern)\nqr-builder artistic \"https://example.com\" image.png output.png --preset large\n\n# QArt halftone style\nqr-builder qart \"https://example.com\" image.png output.png --version 10\n\n# Embed QR into background image\nqr-builder embed background.jpg \"https://example.com\" output.png \\\n  --scale 0.3 --position bottom-right\n\n# Batch embed into all images in a directory\nqr-builder batch-embed ./images \"https://example.com\" ./output --glob \"*.jpg\"\n```\n\n### Python Library\n\n```python\nfrom qr_builder import (\n    generate_qr_only,\n    generate_qr_with_logo,\n    generate_qr_with_text,\n    generate_artistic_qr,\n    generate_qart,\n    generate_qr_unified,\n    QRConfig,\n    QRStyle,\n    ARTISTIC_PRESETS,\n)\n\n# Basic QR code\ngenerate_qr_only(\"https://example.com\", \"qr.png\", size=500)\n\n# QR with logo\ngenerate_qr_with_logo(\n    \"https://example.com\",\n    \"logo.png\",\n    \"output.png\",\n    logo_scale=0.25,\n)\n\n# QR with text\ngenerate_qr_with_text(\n    \"https://example.com\",\n    \"HELLO\",\n    \"output.png\",\n    font_color=\"#e07030\",\n)\n\n# Artistic QR with preset\ngenerate_artistic_qr(\n    \"https://example.com\",\n    \"image.png\",\n    \"output.png\",\n    preset=\"large\",\n    colorized=True,\n)\n\n# Unified interface with configuration\nconfig = QRConfig(\n    style=QRStyle.ARTISTIC,\n    data=\"https://example.com\",\n    output_path=\"output.png\",\n    source_image=\"image.png\",\n    preset=\"hd\",\n    colorized=True,\n)\ngenerate_qr_unified(config)\n```\n\n### Web Interface\n\nStart the visual web interface:\n\n```bash\npython server.py\n# Visit http://localhost:8080\n```\n\nFeatures:\n- Tab-based interface for all 5 QR styles\n- Live preview\n- Color pickers\n- Preset selection for artistic QR codes\n- Download generated QR codes\n\n### REST API\n\nStart the API server:\n\n```bash\n# Using uvicorn\nuvicorn qr_builder.api:app --reload --port 8000\n\n# Visit http://localhost:8000/docs for interactive API docs\n```\n\n**Endpoints:**\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/health` | Health check |\n| GET | `/styles` | List available styles and presets |\n| POST | `/qr` | Generate basic QR code |\n| POST | `/qr/text` | QR with text in center |\n| POST | `/qr/logo` | QR with logo in center |\n| POST | `/qr/artistic` | Artistic QR (image becomes QR) |\n| POST | `/qr/qart` | Halftone/dithered QR |\n| POST | `/embed` | Embed QR into background image |\n| POST | `/batch/embed` | Batch embed (returns ZIP) |\n| POST | `/batch/artistic` | Batch artistic QR (returns ZIP) |\n\nSee [docs/API.md](docs/API.md) for complete API documentation.\n\n### WordPress Integration\n\nEmbed the QR Builder in any WordPress site:\n\n1. Copy `wordpress/qr-builder-widget.html`\n2. Add to WordPress via Custom HTML block\n3. Update `QR_API_URL` to your server address\n\nSee [wordpress/README.md](wordpress/README.md) for detailed instructions.\n\n## Artistic Presets\n\nFor artistic QR codes, use presets for optimal quality:\n\n| Preset | Version | Best For |\n|--------|---------|----------|\n| `small` | 5 | Web thumbnails, social media |\n| `medium` | 10 | General use, business cards |\n| `large` | 15 | Print, marketing materials |\n| `hd` | 20 | Large format, high detail |\n\n## Docker Deployment\n\n```bash\n# Build and run\ndocker build -t qr-builder .\ndocker run -p 8080:8080 qr-builder python server.py\n\n# Or with Docker Compose\ndocker compose up --build\n```\n\n**Environment variables:**\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `QR_SERVER_HOST` | `0.0.0.0` | Server host binding |\n| `QR_SERVER_PORT` | `8080` | Server port |\n\n## Project Structure\n\n```\nqr-builder/\n├── qr_builder/\n│   ├── __init__.py      # Package exports\n│   ├── core.py          # Core QR generation (5 styles)\n│   ├── cli.py           # Command-line interface\n│   └── api.py           # FastAPI REST API\n├── server.py            # Web interface server\n├── wordpress/\n│   ├── qr-builder-widget.html  # WordPress embed widget\n│   └── README.md               # WordPress integration guide\n├── docs/\n│   └── API.md           # API documentation\n├── tests/\n│   ├── test_core.py     # Core function tests\n│   └── test_api.py      # API endpoint tests\n├── .github/\n│   └── workflows/\n│       └── ci.yml       # GitHub Actions CI\n├── pyproject.toml       # Package configuration\n├── Dockerfile           # Docker image\n├── docker-compose.yml   # Docker Compose config\n└── README.md\n```\n\n## Use Cases\n\n- **Marketing materials** - Branded QR codes with company images\n- **Product packaging** - Artistic QR codes that match design\n- **Event tickets** - Visually appealing check-in codes\n- **Business cards** - QR codes with logos or text\n- **Restaurant menus** - Stylish codes for online ordering\n- **Social media** - Eye-catching QR codes for profiles\n- **Website widgets** - Generate QR codes dynamically via API\n- **WordPress sites** - Embeddable QR generator for visitors\n\n## Requirements\n\n- Python 3.9+\n- Dependencies: qrcode, Pillow, amzqr, pyqart, segno, fastapi, uvicorn\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Support\n\n- **GitHub Issues:** https://github.com/Your Organization/qr-builder/issues\n- **Documentation:** https://github.com/Your Organization/qr-builder\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiqso%2Fqr-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faiqso%2Fqr-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiqso%2Fqr-builder/lists"}