Structure de projet

Pourquoi ça compte

Un projet mal structuré est difficile à reprendre, à déployer ou à transmettre. Deux problèmes reviennent systématiquement :

• Les dépendances ne sont pas listées — le projet ne fonctionne pas sur une autre machine
• Les secrets (clés API, mots de passe) sont dans le code — ils se retrouvent sur GitHub

Les deux se règlent en quelques minutes.

Structure de référence

Arborescence recommandée pour un projet Flask + Streamlit :

mon-dashboard/
├── .streamlit/
│   ├── config.toml          # configuration Streamlit (thème, port)
│   └── secrets.toml         # secrets locaux (NE PAS commiter)
├── api/
│   ├── __init__.py
│   ├── app.py               # application Flask
│   ├── blueprints/
│   │   └── ventes.py
│   └── repository.py
├── dashboard/
│   ├── __init__.py
│   ├── api_client.py        # client HTTP (séance 5)
│   └── pages/
│       ├── 1_Ventes.py
│       └── 2_Statistiques.py
├── db/
│   └── ventes.db
├── .env                     # variables d'environnement locales (NE PAS commiter)
├── .gitignore               # fichiers à exclure de Git
├── app.py                   # point d'entrée Streamlit
├── README.md                # documentation minimale
└── requirements.txt         # dépendances Python

requirements.txt

requirements.txt liste les dépendances du projet avec leurs versions. C'est ce qui permet de reproduire l'environnement sur une autre machine ou un serveur de déploiement.

Générer automatiquement depuis l'environnement actuel

pip freeze > requirements.txt

pip freeze liste toutes les bibliothèques installées dans l'environnement courant avec leurs versions exactes. Le résultat ressemble à :

flask==3.0.3
flask-cors==4.0.1
streamlit==1.35.0
plotly==5.22.0
pandas==2.2.2
requests==2.32.3
python-dotenv==1.0.1

Installer depuis un requirements.txt existant

pip install -r requirements.txt

Cette commande installe les dépendances listées dans le fichier, aux versions spécifiées. C'est la première commande à exécuter après avoir cloné un projet.

Environnement virtuel Python

Un environnement virtuel isole les dépendances du projet de l'installation système Python. Chaque projet a ses propres versions de bibliothèques, sans conflit.

python -m venv venv          # créer l'environnement virtuel
source venv/bin/activate     # activer (Linux/Mac)
venv\Scripts\activate        # activer (Windows)
pip install -r requirements.txt

.gitignore

Le fichier .gitignore à la racine du projet liste les fichiers et dossiers que Git ne doit pas suivre : secrets, caches, fichiers générés.

Contenu minimal pour un projet Flask + Streamlit :

# Environnement virtuel
venv/
.venv/
env/

# Secrets — NE JAMAIS commiter
.env
.streamlit/secrets.toml

# Base de données locale
db/*.db

# Cache Python
__pycache__/
*.pyc
*.pyo
.pytest_cache/

# Éditeurs
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

.env pour les variables d'environnement locales

Les variables d'environnement (clé API, URL de base, etc.) sont stockées dans un fichier .env à la racine :

# .env
API_KEY=ma-cle-secrete-dev
FLASK_PORT=5000
DATABASE_PATH=db/ventes.db

Chargement avec python-dotenv :

from dotenv import load_dotenv
import os

load_dotenv()  # charge les variables depuis .env
API_KEY = os.environ.get("API_KEY")
DATABASE_PATH = os.environ.get("DATABASE_PATH", "db/ventes.db")

.env vs .streamlit/secrets.toml

Les deux stockent des secrets, mais pour des usages différents :

.env.example — documenter sans exposer

.env.example contient les clés attendues sans les valeurs. Contrairement à .env, ce fichier doit être commité — il documente les variables attendues :

# .env.example
API_KEY=
FLASK_PORT=5000
DATABASE_PATH=db/ventes.db

Un nouveau développeur clone le projet, copie .env.example en .env, et renseigne les valeurs manquantes.

README.md minimal

Un README bien écrit permet à n'importe qui (y compris vous dans six mois) de comprendre le projet et de le lancer. Structure minimale recommandée :

# Dashboard Ventes

Dashboard analytique des ventes construit avec Flask + Streamlit.

## Installation

git clone <url-du-repo>
cd mon-dashboard
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # puis renseigner les valeurs

## Lancement

# Terminal 1 — API Flask
cd api && flask run

# Terminal 2 — Dashboard Streamlit
streamlit run app.py

## Structure

- `api/` — API Flask (endpoints, repository SQLite)
- `dashboard/` — Application Streamlit (pages, client HTTP)
- `db/` — Base de données SQLite

À retenir

Ressources