# 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 :

```powershell
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 :

```powershell
.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 :

```powershell
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](config.json) :

```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 :

```powershell
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

```powershell
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

```powershell
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
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
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

```text
.
├── 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

```mermaid
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](https://pypi.org/project/PyQt6/) : interface graphique
- [PyInstaller](https://pyinstaller.org/) : generation de l'executable
- [Requests](https://pypi.org/project/requests/) : appels HTTP pour les mises a jour
- [python-dotenv](https://pypi.org/project/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.