Python PyQt6 Application Template

A modern, feature-rich template for building desktop applications with PyQt6. This template provides a solid foundation with theming, internationalization, settings management, and a modular architecture.

Features

• Modern UI Framework: Built with PyQt6 for cross-platform compatibility
• Theme System: Dark and light themes with easy customization
• Internationalization: Multi-language support (English and French included)
• Settings Management: Persistent user preferences with QSettings
• Modular Architecture: Clean separation of concerns with managers and observers
• Tabbed Interface: Flexible tab widget system with customizable positioning
• Window State Management: Remembers window size, position, and maximized state
• Email Integration: Built-in suggestion/feedback system with secure email configuration
• Build Automation: Automated building with PyInstaller
• Virtual Environment Management: Automated environment setup

Project Structure

Template/
├── app/
│   ├── core/                         # Core application managers
│   │   ├── main_manager.py           # Singleton manager coordinator
│   │   ├── settings_manager.py       # User settings and configuration
│   │   ├── theme_manager.py          # Theme and styling management
│   │   ├── language_manager.py       # Internationalization
│   │   └── observer_manager.py       # Event notification system
│   ├── ui/
│   │   ├── main_window.py            # Main application window
│   │   ├── widgets/                  # Custom widgets
│   │   │   └── tabs_widget.py        # Customizable tab system
│   │   └── windows/                  # Application windows
│   │       ├── settings_window.py
│   │       └── suggestion_window.py
│   └── utils/
│       └── paths.py                  # Path utilities for resources
├── data/
│   ├── assets/                       # Icons and images
│   ├── lang/                         # Language files (JSON)
│   ├── themes/                       # Theme configuration files
│   └── others/                       # Default settings
├── tools/                            # Build and development tools
│   ├── build.bat/.sh/.command        # Platform-specific build script
│   └── open.bat/.sh/.command         # Platform-specific development setup
├── config.json                       # Application configuration
├── requirements.txt                  # Python dependencies
├── BUILD.spec                        # PyInstaller specification
└── main.py                           # Application entry point

Development Setup

1. Clone/Download this template

2. Configure your application in config.json:

   {
     "app_name": "YourAppName",
     "python_version": "YourPythonVersion",
     "app_os": "Windows or Linux or Mac",
     "app_version": "YourAppVersion",
     "architecture": "x64 or x32",
     "icon_path": "data/assets/icon.ico",
     "main_script": "main.py"
   }
   

3. Setup environment configuration:

   • Copy .env.example to .env
   • Configure your Python path and email credentials:

   # Python Configuration
   PYTHON_PATH=C:/Path/To/Your/Python/python.exe
   
   # Email Configuration (optional)
   EMAIL_ADDRESS=your_email@gmail.com
   EMAIL_PASSWORD=your_app_password
   EMAIL_SMTP_SERVER=smtp.gmail.com
   EMAIL_SMTP_PORT=587
   

   • For Gmail, use an App Password instead of your regular password

4. Run development environment:

   • Windows: tools\open.bat
   • Linux: tools/open.sh
   • macOS: tools/open.command

   This will:

   • Create a virtual environment
   • Install dependencies
   • Open VS Code with proper environment

Building for Production

• Windows: tools\build.bat
• Linux: tools/build.sh
• macOS: tools/build.command

This creates a standalone executable in the build/ directory.

Adding Themes

Create JSON files in data/themes/. Important: Use the predefined color names as they are used throughout the application's styling system.

{
  "theme_name": "custom",
  "colors": {
    "background": "#FFFFFF",       // Main background color
    "background2": "#F5F5F5",      // Secondary background
    "background3": "#E0E0E0",      // Tertiary background
    "font_color": "#000000",       // Text color
    "selected_icon": "#000000",    // Selected icon color
    "unselected_icon": "#5D5A5A",  // Unselected icon color
    "selected_border_icon": "#000000", // Selected border color
    "hover_icon": "#000000"        // Hover state color
  }
}

Warning: Do not change the color property names (background, background2, etc.) as they are hardcoded in the theme system. Only modify the hex color values.

Adding Languages

Create JSON files in data/lang/. Important: Use the existing translation keys to ensure proper functionality.

{
  "lang_name": "Español",
  "yes": "Sí",
  "no": "No",
  "language": "Idioma:",
  "settings": "Configuración",
  "theme": "Tema:",
  "dark_theme": "Tema Oscuro",
  "light_theme": "Tema Claro",
  "suggestion_text": "¿Tienes una pregunta o idea para mejorar esta aplicación?",
  "suggestion_placeholder": "Escribe tu mensaje aquí...",
  "send_suggestion": "Enviar",
  "sending": "Enviando...",
  "success": "Éxito",
  "error": "Error",
  "suggestion_sent_success": "¡Tu mensaje ha sido enviado exitosamente!",
  "suggestion_send_error": "Error al enviar el mensaje. Inténtalo de nuevo más tarde.",
  "email_credentials_error": "Credenciales de email no configuradas. Por favor configura tu email y contraseña en el archivo .env."
}

Warning: Do not change the translation keys (left side of the colon) as they are used throughout the application code. Only translate the values (right side).

Architecture

Manager Pattern

The application uses a centralized manager system:

• MainManager: Singleton coordinator for all managers
• SettingsManager: Handles user preferences and persistence
• ThemeManager: Manages themes and styling
• LanguageManager: Handles internationalization
• ObserverManager: Event notification system

Observer Pattern

Components can subscribe to events:

self.observer_manager.subscribe(NotificationType.THEME, self.update_theme)
self.observer_manager.subscribe(NotificationType.LANGUAGE, self.update_language)

Tab System

The flexible tab widget supports multiple positioning options:

# Add a tab with custom positioning
self.side_menu.add_widget(
    widget=your_widget,
    button_text="",
    icon_path=paths.get_asset_svg_path("icon_name"),
    position=ButtonPosition.CENTER
)

Email Integration

The template includes a suggestion system with email capabilities. Configure in your .env file:

Security Note: Never commit your .env file to version control. It's already included in .gitignore.

For Gmail users:

• Enable 2-factor authentication
• Generate an App Password specifically for this application
• Use the App Password in the EMAIL_PASSWORD field

Customization

Adding New Windows

1. Create window class inheriting from QWidget
2. Subscribe to language notifications
3. Add to main window tab system

class YourWindow(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.main_manager = MainManager.get_instance()
        # Subscribe to notifications
        self.observer_manager.subscribe(NotificationType.LANGUAGE, self.update_language)
        self.setup_ui()

Custom Widgets

Place custom widgets in app/ui/widgets/ and follow the existing patterns for theme integration.

Dependencies

• PyQt6: Modern GUI framework
• pyinstaller: Executable building
• python-dotenv: Environment variable management

Add additional dependencies to requirements.txt.

Building

The build system automatically:

• Creates virtual environments per architecture
• Installs dependencies
• Builds with PyInstaller
• Names executables with config.json
• Includes all assets and data files

Cross-Platform Notes

The template supports multiple platforms with platform-specific scripts:

• Windows: Uses .bat files
• Linux: Uses .sh files
• macOS: Uses .command files

Adjust config.json for your target platform.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues or questions:

• Check existing issues
• Create detailed bug reports
• Include system information and error logs

---

Happy coding! 🚀