pysimpleqr 0.1.2
use qr to transit messages from OS to other devices, e.g. handset
Requires Python: >=3.12
Keywords: qr, qrcode, simpleqr

# 🎯 PySimpleQR - Professional QR Code Generator

> **🚀 Vibed and rocks with Trae.ai IDE!** 
Built entirely within Trae.ai's intelligent development environment with AI-powered assistance throughout the development process.

A sleek, modern Python desktop application for generating professional QR codes with advanced features and an intuitive user interface.

## 🎨 Screenshots

![PySimpleQR Main Interface](screenshot.png)

## ✨ Features

### 🖥️ Modern Desktop Application
- **Responsive UI** that adapts to different screen sizes
- **Beautiful color scheme** with professional styling
- **Real-time character counter** with length warnings
- **Intuitive layout** with clear visual hierarchy

### 🔧 Advanced QR Generation
- **High-quality QR code generation** with PIL/Pillow
- **Text truncation** for long content (max 2953 chars)
- **URL escaping** option to prevent auto-detection
- **Plain text mode** toggle for non-URL content

### 🎨 Smart Image Handling
- **Automatic image resizing** to fit preview frame
- **Aspect ratio preservation** during scaling
- **High-quality resampling** with LANCZOS algorithm
- **300x300 optimized display** with responsive sizing

### 📋 Export Options
- **Save QR codes** as PNG files with 95% quality
- **Copy to clipboard** (Windows native + fallback)
- **Test QR generation** with sample content
- **File dialog integration** for easy saving

### ⚡ Enhanced UX
- **Loading indicators** during generation
- **Status bar updates** for user feedback
- **Error handling** with informative messages
- **Keyboard shortcuts** and responsive design

## 🛠️ Installation & Setup

### Prerequisites
- Python 3.12+
- pip or uv package manager

### Quick Start
```bash
# Clone the repository
git clone [your-repo-url]
cd pysimpleqr

# Install dependencies
uv pip install -e .

# Or with pip
pip install -e .

# Run the application
python -m pysimpleqr.main
```

### Dependencies
```bash
# Core dependencies
qrcode[pil]>=7.4.2
Pillow>=10.0.0
FreeSimpleGUI>=5.0.0

# Optional (for Windows clipboard)
pywin32>=306
```

## 🚀 Usage

### Basic Usage
1. **Launch the app**: `python -m pysimpleqr.main`
2. **Enter text**: Type or paste your content in the text area
3. **Generate QR**: Click "✨ QR it" button
4. **Save/Copy**: Use "💾 Save QR" or "📋 Copy QR" buttons

### Advanced Options
- **Plain text mode**: Prevents URL auto-detection by scanners
- **Escape URLs**: Replaces dots and colons to avoid auto-linking
- **Character counter**: Shows remaining capacity with color warnings
- **Test button**: Generates sample QR for quick testing

### Keyboard Shortcuts
- **Generate**: Click "✨ QR it" or press Enter in text area
- **Save**: Ctrl+S or click "💾 Save QR"
- **Copy**: Ctrl+C or click "📋 Copy QR"
- **Close**: Alt+F4 or click "❌ Close"

## 🧪 Development

### Project Structure
```
pysimpleqr/
├── pysimpleqr/
│   ├── __init__.py
│   ├── __main__.py          # Entry point
│   ├── main.py              # GUI application
│   └── qr_core.py           # QR generation logic
├── tests/                   # Comprehensive test suite
├── pyproject.toml          # Project configuration
├── README.md               # This file
└── [other config files]
```

### Running Tests
```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=pysimpleqr tests/

# Run specific test file
pytest tests/test_main.py
```

### Development Features
- **78 comprehensive tests** covering all functionality
- **Mock testing** for GUI components
- **Error handling validation**
- **Cross-platform compatibility**

## 🎯 Recent Updates

### Latest Features (v2.0)
- ✅ **Smart image resizing** - QR codes automatically fit the preview frame
- ✅ **URL escaping** - Prevent unwanted URL detection by scanners
- ✅ **Enhanced error handling** - Better user feedback and recovery
- ✅ **Improved UI responsiveness** - Better layout on different screen sizes
- ✅ **Test button** - Quick QR generation for testing purposes
- ✅ **Clipboard integration** - Native Windows + fallback support

### Technical Improvements
- **Aspect ratio preservation** during image scaling
- **High-quality resampling** with LANCZOS algorithm
- **Optimized memory usage** with proper image handling
- **Comprehensive test coverage** with 78+ tests

## 🖥️ System Requirements

### Supported Platforms
- **Windows** (full feature support)
- **Linux** (with X11/Wayland)
- **macOS** (with tkinter support)

## 🤝 Contributing

We welcome contributions! Please see:
- **Issues**: Report bugs or request features
- **Pull Requests**: Submit improvements
- **Discussions**: Share ideas and feedback

## 📄 License

This project is open source and available under the [MIT License](LICENSE).

## 🔗 Links

- **Homepage**: [GitHub Repository]
- **Issues**: [GitHub Issues]
- **Documentation**: [Project Wiki]

---

<div align="center">

**Built with ❤️ using Trae.ai IDE**

*This project was developed entirely within Trae.ai's intelligent development environment, leveraging AI-powered coding assistance for rapid development and high-quality code generation.*

</div>