PythonApplicationTemplate/README.md

Python Application Template

Un socle desktop PyQt6 pret a personnaliser pour lancer rapidement une application Python moderne sous Windows.

Ce template fournit une base complete pour une application de bureau : fenetre principale, ecran de chargement, themes, traductions, gestion des parametres, mises a jour et generation d'un executable avec PyInstaller.

Apercu

• Interface graphique construite avec PyQt6
• Themes dark et light facilement extensibles
• Traductions francaise et anglaise
• Ecran de demarrage avec progression
• Parametres persistants entre les lancements
• Verification des mises a jour depuis GitHub ou Gitea
• Onglet de suggestions avec envoi SMTP asynchrone
• Build automatise pour Windows et script prevu pour macOS/Linux

Demarrage rapide

Prerequis

• Python 3 disponible dans le PATH
• Windows pour utiliser les scripts .bat
• PowerShell pour la lecture de config.json par les scripts Windows
• VS Code et la commande code pour utiliser tools/open.bat

Installation manuelle

Depuis la racine du projet :

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r config\requirements.txt
python main.py

Si PowerShell bloque l'activation de l'environnement, lancez directement :

.venv\Scripts\python.exe main.py

Installation automatisee sous Windows

Le script suivant cree l'environnement dedie dans config/WINenv_x64, installe les dependances puis ouvre le projet dans VS Code :

tools\open.bat

open.bat prepare le workspace mais ne lance pas directement l'application. Utilisez ensuite python main.py depuis l'environnement actif.

Configuration

Identite de l'application

Les informations generales sont centralisees dans config.json :

{
  "app_name": "Application",
  "app_os": "Windows",
  "app_version": "1.0.0",
  "architecture": "x64",
  "icon_path": "data/assets/icon.ico",
  "splash_image": "splash",
  "main_script": "main.py",
  "git_repo": "https://example.com/owner/repository"
}

Adaptez au minimum app_name, app_version, icon_path et git_repo avant de distribuer votre application.

Variables d'environnement

Copiez .env.example vers .env, puis renseignez les valeurs necessaires :

Copy-Item .env.example .env

Variables disponibles :

Variable	Role
PYTHON_PATH	Interpreteur Python utilise par les scripts de build
EMAIL_ADDRESS	Adresse SMTP utilisee pour recevoir les suggestions
EMAIL_PASSWORD	Mot de passe applicatif SMTP
EMAIL_SMTP_SERVER	Serveur SMTP, par defaut smtp.gmail.com
EMAIL_SMTP_PORT	Port SMTP, par defaut 587

Ne committez jamais .env ni un mot de passe SMTP. Pour Gmail, utilisez un mot de passe d'application plutot que le mot de passe principal du compte.

Execution et build

Lancer l'application

python main.py

Au demarrage, l'application initialise ses gestionnaires, verifie les mises a jour disponibles, puis affiche la fenetre principale.

Generer l'executable Windows

tools\build.bat

Le script :

1. cree l'environnement virtuel correspondant a l'architecture configuree ;
2. installe les dependances ;
3. execute PyInstaller avec config/BUILD.spec ;
4. place l'application generee dans build/.

Le resultat est un executable sans console, adapte a une application graphique Windows.

macOS et Linux

Les scripts Unix sont maintenant disponibles pour macOS et Linux.

Pour preparer l'environnement et ouvrir le projet :

bash tools/open.command

Le script choisit automatiquement MACenv_<architecture> sur macOS ou LINenv_<architecture> sur Linux, installe les dependances, puis ouvre le projet avec la commande code. A defaut, il utilise open sur macOS ou xdg-open sur Linux.

Pour construire l'application :

bash tools/build.command

Sur macOS, il utilise un environnement MACenv_<architecture>, produit une application .app et cree une archive ZIP dans build/. Sur Linux, il utilise LINenv_<architecture>, produit un binaire executable ainsi qu'un fichier .desktop, puis cree une archive ZIP dans build/.

La commande zip doit etre installee sur le systeme pour generer l'archive.

Structure du projet

.
├── app/
│   ├── core/              # Gestionnaires : langue, theme, parametres, mises a jour...
│   ├── ui/                # Fenetre principale, ecrans et widgets PyQt6
│   └── utils/             # Utilitaires partages, notamment les chemins
├── config/
│   ├── BUILD.spec         # Configuration PyInstaller
│   └── requirements.txt   # Dependances Python
├── data/
│   ├── assets/            # Icones et images
│   ├── lang/              # Fichiers de traduction JSON
│   ├── themes/            # Themes JSON et feuilles QSS
│   └── others/             # Valeurs par defaut
├── tools/                 # Scripts d'installation, lancement et build
├── config.json            # Configuration de l'application
└── main.py                # Point d'entree

Personnalisation

1. Modifiez config.json pour donner son identite a l'application.
2. Ajoutez ou adaptez les textes dans data/lang/en.json et data/lang/fr.json.
3. Creez un theme dans data/themes/ et referencez-le dans le gestionnaire de themes.
4. Ajoutez vos vues dans app/ui/ et votre logique metier dans app/core/.
5. Ajoutez les ressources necessaires dans data/assets/.
6. Mettez a jour config/BUILD.spec si votre application embarque de nouvelles ressources ou dependances dynamiques.

Architecture simplifiee

flowchart TD
    A[main.py] --> B[MainManager]
    B --> C[SettingsManager]
    B --> D[LanguageManager]
    B --> E[ThemeManager]
    B --> F[UpdateManager]
    A --> G[SplashScreen]
    A --> H[MainWindow]
    H --> I[SettingsWindow]
    H --> J[SuggestionWindow]
    D --> K[data/lang]
    E --> L[data/themes]
    F --> M[GitHub ou Gitea]

Dependances principales

• PyQt6 : interface graphique
• PyInstaller : generation de l'executable
• Requests : appels HTTP pour les mises a jour
• python-dotenv : chargement des variables d'environnement

Licence

Aucune licence n'est actuellement definie dans le depot. Ajoutez un fichier LICENSE avant toute distribution publique.