readme
This commit is contained in:
parent
df598ef183
commit
721088b54d
390
README.md
390
README.md
@ -1,266 +1,152 @@
|
|||||||
# Python PyQt6 Application Template
|
# 🚀 HoDA - 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.
|
Bienvenue ! Ce projet est **bien plus qu'un simple template** : c'est une boîte à outils moderne pour créer rapidement des applications desktop Python élégantes, robustes et évolutives.
|
||||||
|
Vous voulez coder, personnaliser, traduire, mettre à jour, distribuer ? Tout est déjà prêt !
|
||||||
|
|
||||||
## Features
|
---
|
||||||
|
|
||||||
- **Modern UI Framework**: Built with PyQt6 for cross-platform compatibility
|
## ✨ Fonctionnalités clés
|
||||||
- **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
|
- **Interface moderne (PyQt6)** : Responsive, stylée, et facile à personnaliser.
|
||||||
|
- **Thèmes dynamiques** : Passez du clair au sombre en un clic, ou créez le vôtre !
|
||||||
|
- **Multi-langues** : Français, anglais... et ajoutez-en autant que vous voulez.
|
||||||
|
- **Paramètres utilisateurs** : Tout est sauvegardé (thème, langue, taille de fenêtre...).
|
||||||
|
- **Architecture modulaire** : Des managers pour chaque besoin, tout est organisé.
|
||||||
|
- **Notifications automatiques** : Les widgets s'adaptent instantanément aux changements.
|
||||||
|
- **Barre d’onglets flexible** : Ajoutez vos fenêtres où vous voulez, comme vous voulez.
|
||||||
|
- **Système de suggestion** : Vos utilisateurs peuvent vous écrire directement depuis l’app.
|
||||||
|
- **Mise à jour automatique** : Téléchargez la dernière version sans effort, avec barre de progression !
|
||||||
|
- **Build & environnement** : Scripts pour tout automatiser, sur Windows, Linux, macOS.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🗂️ Structure du projet
|
||||||
|
|
||||||
```
|
```
|
||||||
Template/
|
Template/
|
||||||
├── app/
|
├── app/
|
||||||
│ ├── core/ # Core application managers
|
│ ├── core/ # Managers (thème, langue, update, etc.)
|
||||||
│ │ ├── 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/
|
│ ├── ui/
|
||||||
│ │ ├── main_window.py # Main application window
|
│ │ ├── widgets/ # Onglets, loading bar, etc.
|
||||||
│ │ ├── widgets/ # Custom widgets
|
│ │ └── windows/ # Paramètres, suggestion...
|
||||||
│ │ │ └── tabs_widget.py # Customizable tab system
|
│ └── utils/ # Fonctions utilitaires
|
||||||
│ │ └── windows/ # Application windows
|
|
||||||
│ │ ├── settings_window.py
|
|
||||||
│ │ └── suggestion_window.py
|
|
||||||
│ └── utils/
|
|
||||||
│ └── paths.py # Path utilities for resources
|
|
||||||
├── data/
|
├── data/
|
||||||
│ ├── assets/ # Icons and images
|
│ ├── assets/ # Icônes, images
|
||||||
│ ├── lang/ # Language files (JSON)
|
│ ├── lang/ # Traductions
|
||||||
│ ├── themes/ # Theme configuration files
|
│ ├── themes/ # Thèmes
|
||||||
│ └── others/ # Default settings
|
│ └── others/ # Paramètres par défaut
|
||||||
├── tools/ # Build and development tools
|
├── tools/ # Scripts build/dev
|
||||||
│ ├── build.bat/.sh/.command # Platform-specific build script
|
├── config.json # Config principale
|
||||||
│ └── open.bat/.sh/.command # Platform-specific development setup
|
├── requirements.txt # Dépendances
|
||||||
├── config.json # Application configuration
|
├── BUILD.spec # PyInstaller
|
||||||
├── requirements.txt # Python dependencies
|
└── main.py # Point d’entrée
|
||||||
├── BUILD.spec # PyInstaller specification
|
|
||||||
└── main.py # Application entry point
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Development Setup
|
|
||||||
|
|
||||||
1. **Clone/Download** this template
|
|
||||||
2. **Configure** your application in `config.json`:
|
|
||||||
```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:
|
|
||||||
```env
|
|
||||||
# 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](https://support.google.com/accounts/answer/185833) 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.
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"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.
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"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:
|
|
||||||
|
|
||||||
```python
|
|
||||||
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:
|
|
||||||
|
|
||||||
```python
|
|
||||||
# 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
|
|
||||||
|
|
||||||
```python
|
|
||||||
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!** 🚀
|
## ⚡ Démarrage Express
|
||||||
|
|
||||||
|
1. **Configurez `config.json`**
|
||||||
|
(nom, version, OS, architecture, icône, dépôt git...)
|
||||||
|
|
||||||
|
2. **Copiez `.env.example` → `.env`**
|
||||||
|
(chemin Python, email, mot de passe...)
|
||||||
|
|
||||||
|
3. **Lancez le dev**
|
||||||
|
- Windows : `tools\open.bat`
|
||||||
|
- Linux : `tools/open.sh`
|
||||||
|
- macOS : `tools/open.command`
|
||||||
|
|
||||||
|
4. **Build en un clic**
|
||||||
|
- Windows : `tools\build.bat`
|
||||||
|
- Linux : `tools/build.sh`
|
||||||
|
- macOS : `tools/build.command`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎨 Thèmes & 🌍 Langues
|
||||||
|
|
||||||
|
- **Thèmes** : Ajoutez vos fichiers dans `data/themes/` (JSON).
|
||||||
|
Changez les couleurs, créez votre ambiance !
|
||||||
|
- **Langues** : Ajoutez vos fichiers dans `data/lang/` (JSON).
|
||||||
|
Traduisez tout, c’est instantané.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧩 Managers & Architecture
|
||||||
|
|
||||||
|
- **MainManager** : Le chef d’orchestre.
|
||||||
|
- **SettingsManager** : Les préférences utilisateur.
|
||||||
|
- **ThemeManager** : Les couleurs et le style.
|
||||||
|
- **LanguageManager** : Les textes traduits.
|
||||||
|
- **AlertManager** : Les messages, confirmations, erreurs.
|
||||||
|
- **UpdateManager** : Les mises à jour automatiques.
|
||||||
|
- **ObserverManager** : Les notifications internes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Mise à jour automatique
|
||||||
|
|
||||||
|
- Vérifie la dernière version sur le dépôt Git à chaque démarrage.
|
||||||
|
- Propose la mise à jour si disponible.
|
||||||
|
- Télécharge le bon fichier selon votre OS/architecture.
|
||||||
|
- Affiche une barre de progression stylée.
|
||||||
|
- Lance la nouvelle version automatiquement !
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💡 Suggestions & Feedback
|
||||||
|
|
||||||
|
- Fenêtre dédiée pour envoyer vos idées ou questions par email.
|
||||||
|
- Sécurisé via `.env`.
|
||||||
|
- Gestion des erreurs/succès avec AlertManager.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ Ajouter vos fenêtres & widgets
|
||||||
|
|
||||||
|
- Créez une classe héritant de `QWidget`.
|
||||||
|
- Ajoutez-la dans la barre d’onglets (`TabsWidget`).
|
||||||
|
- Abonnez-vous aux notifications pour la langue/le thème.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📦 Dépendances
|
||||||
|
|
||||||
|
- **PyQt6** : GUI moderne.
|
||||||
|
- **pyinstaller** : Build d’exécutables.
|
||||||
|
- **python-dotenv** : Variables d’environnement.
|
||||||
|
- **requests** : Requêtes HTTP (update).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔒 Sécurité
|
||||||
|
|
||||||
|
- **Ne versionnez jamais `.env`** (déjà dans `.gitignore`).
|
||||||
|
- Utilisez un mot de passe d’application pour Gmail.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Licence
|
||||||
|
|
||||||
|
MIT License. Voir le fichier LICENSE.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤝 Contribution
|
||||||
|
|
||||||
|
1. Forkez le dépôt
|
||||||
|
2. Créez une branche
|
||||||
|
3. Proposez vos modifications via pull request
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🆘 Support
|
||||||
|
|
||||||
|
- Ouvrez une issue sur le dépôt
|
||||||
|
- Précisez votre OS, version Python, logs d’erreur
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Ce template est fait pour vous faire gagner du temps et coder avec plaisir !
|
||||||
|
Testez-le, améliorez-le, partagez-le 🚀**
|
||||||
Loading…
x
Reference in New Issue
Block a user