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
|
||||
- **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
|
||||
## ✨ Fonctionnalités clés
|
||||
|
||||
## 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/
|
||||
├── 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
|
||||
│ ├── core/ # Managers (thème, langue, update, etc.)
|
||||
│ ├── 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
|
||||
│ │ ├── widgets/ # Onglets, loading bar, etc.
|
||||
│ │ └── windows/ # Paramètres, suggestion...
|
||||
│ └── utils/ # Fonctions utilitaires
|
||||
├── 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
|
||||
│ ├── assets/ # Icônes, images
|
||||
│ ├── lang/ # Traductions
|
||||
│ ├── themes/ # Thèmes
|
||||
│ └── others/ # Paramètres par défaut
|
||||
├── tools/ # Scripts build/dev
|
||||
├── config.json # Config principale
|
||||
├── requirements.txt # Dépendances
|
||||
├── BUILD.spec # PyInstaller
|
||||
└── main.py # Point d’entrée
|
||||
```
|
||||
|
||||
### 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