FFA Calendar Scraper

Un système complet pour scraper les données du site de la Fédération Française d'Athlétisme (FFA) et les organiser dans des fichiers CSV avec des fonctionnalités de recherche et d'analyse.

📋 Table des matières

• Fonctionnalités
• Structure du projet
• Installation
• Configuration
• Utilisation
• Structure des données
• Scripts disponibles
• Version
• Contribuer
• Licence

✨ Fonctionnalités

Scraping des données

• Calendrier des compétitions: Récupération automatique du calendrier complet (2010-2026)
• Détails des courses: Extraction des informations détaillées de chaque compétition
• Résultats des compétitions: Récupération des résultats par athlète (place, temps, club)
• Multithreading: Scraping optimisé avec plusieurs workers pour accélérer le processus
• Pagination automatique: Détection automatique du nombre de pages et de courses

Analyse des données

• Recherche d'athlètes: Par nom/prénom dans toutes les compétitions
• Recherche de clubs: Identification des athlètes par club
• Recherche de courses: Par période de dates
• Statistiques détaillées: Performances par athlète, podiums, etc.
• Classements: Classements par club pour chaque course

Export et traitement

• Export CSV: Format compatible Excel, encodage UTF-8
• Export personnalisé: Export des résultats par athlète
• Post-traitement: Scripts pour analyser et transformer les données

📁 Structure du projet

ffa-calendar/
├── src/                      # Modules Python principaux
│   ├── ffa_scraper.py       # Scraper principal
│   └── ffa_analyzer.py      # Analyseur de données
├── scripts/                 # Scripts autonomes
│   ├── ffa_cli.py          # Interface CLI principale
│   ├── search_athlete.py    # Recherche d'athlètes
│   ├── search_race.py       # Recherche de courses
│   ├── extract_races.py     # Extraction des courses
│   ├── list_clubs.py        # Liste des clubs
│   ├── post_process.py      # Post-traitement des données
│   ├── monitor_scraping.py  # Surveillance du scraping
│   ├── scrape_all_periods.py # Scraping par périodes
│   └── athlete_summary.py   # Résumé par athlète
├── config/                  # Fichiers de configuration
│   └── config.env          # Configuration du scraper
├── data/                   # Données générées
│   ├── courses/           # Données des courses
│   │   └── periods/       # Courses par périodes
│   ├── resultats/         # Résultats des compétitions
│   ├── clubs/             # Données des clubs
│   └── exports/           # Exports personnalisés
├── docs/                   # Documentation
├── tests/                  # Tests unitaires
├── requirements.txt        # Dépendances Python
├── README.md              # Ce fichier
├── LICENSE                # Licence MIT
└── .gitignore            # Fichiers ignorés par Git

🚀 Installation

Prérequis

• Python 3.8 ou supérieur
• Google Chrome (pour Selenium)
• pip (gestionnaire de paquets Python)

Étapes d'installation

1. Cloner le dépôt

git clone https://github.com/votre-username/ffa-calendar.git
cd ffa-calendar

2. Créer un environnement virtuel (recommandé)

python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate     # Windows

3. Installer les dépendances

pip install -r requirements.txt

4. Configurer le scraper

cp config/config.env config/config.local.env
# Éditez config/config.local.env selon vos besoins

⚙️ Configuration

Le scraper se configure via le fichier config/config.env. Les principaux paramètres sont:

Répertoires

• OUTPUT_DIR: Répertoire de sortie des données (défaut: data)
• EXPORT_DIR: Répertoire pour les exports personnalisés

URLs

• BASE_URL: URL de base du site de la FFA (défaut: https://athle.fr)
• CLUBS_URL: URL du site des clubs (défaut: https://monclub.athle.fr)
• CALENDAR_URL: URL du calendrier des compétitions
• RESULTS_URL: URL des résultats

Performance

• REQUEST_DELAY: Délai entre les requêtes en secondes (défaut: 2)
• MAX_RETRIES: Nombre maximum de tentatives pour une requête (défaut: 3)
• TIMEOUT: Timeout des requêtes en secondes (défaut: 30)
• MAX_WORKERS: Nombre de workers pour le multithreading (défaut: 4)

Scraping

• DEFAULT_LIMIT_COURSES: Limite de courses à scraper (défaut: 10000)
• DEFAULT_LIMIT_RESULTS: Limite de résultats à scraper (défaut: 50000)
• HEADLESS: Mode headless pour Selenium (défaut: True)
• WINDOW_SIZE: Taille de la fenêtre du navigateur (défaut: 1920,1080)

Logs

• LOG_LEVEL: Niveau de log (DEBUG, INFO, WARNING, ERROR)
• LOG_FILE: Fichier de log (défaut: ffa_scraper.log)

CSV

• CSV_ENCODING: Encodage des fichiers CSV (défaut: utf-8-sig)

📖 Utilisation

Via l'interface CLI principale

Le script principal scripts/ffa_cli.py offre une interface complète.

1. Vérifier le nombre de courses disponibles

python scripts/ffa_cli.py check

Cette commande détecte automatiquement:

• Le nombre total de pages de courses
• Le nombre estimé de courses
• Le temps estimé pour le scraping

2. Lister les données disponibles

python scripts/ffa_cli.py list

Affiche un résumé des données actuellement disponibles.

3. Lancer le scraping des données

python scripts/ffa_cli.py scrape --max-pages 7

Options:

• --output: Répertoire de sortie des données
• --limit-courses: Limiter le nombre de courses à scraper
• --limit-results: Limiter le nombre de résultats à scraper
• --fetch-details: Récupérer les détails et résultats de chaque course
• --max-pages: Nombre maximum de pages à scraper
• --multithreading / --no-multithreading: Activer/désactiver le multithreading

3.5. Scraping complet par périodes (2010-2026)

Pour récupérer toutes les courses de 2010 à 2026 par lots de 15 jours:

python scripts/scrape_all_periods.py

Ce script va:

• Générer automatiquement 313 périodes de 15 jours
• Scraper en parallèle avec 8 workers (multithreading)
• Sauvegarder chaque période dans data/courses/periods/
• Fusionner toutes les données dans data/courses/courses_list.csv
• Exécuter automatiquement les scripts de post-traitement

Résultats:

• Fichiers CSV individuels par période : data/courses/periods/courses_YYYY-MM-DD_to_YYYY-MM-DD.csv
• Fichier consolidé : data/courses/courses_list.csv
• Statistiques détaillées par année

Note: Ce processus peut prendre plusieurs heures selon le nombre de courses et votre connexion internet.

4. Rechercher des données

Rechercher un athlète:

python scripts/ffa_cli.py search athlete --nom "BAZALGETTE" --prenom "Romain"

Rechercher un club:

python scripts/ffa_cli.py search club --nom "Moissac"

Rechercher des courses par période:

python scripts/ffa_cli.py search course --start-date "2024-01-01" --end-date "2024-12-31"

5. Afficher des statistiques

Statistiques d'un athlète:

python scripts/ffa_cli.py stats athlete --nom "Dupont" --prenom "Jean"

Classement par club:

python scripts/ffa_cli.py stats club --course-url "https://athle.fr/competitions/course-123"

Top des athlètes:

python scripts/ffa_cli.py top --limit 10 --min-results 3

6. Exporter des données

Exporter les résultats d'un athlète:

python scripts/ffa_cli.py export athlete --nom "Dupont" --prenom "Jean" --filename "dupont_jean_results.csv"

Via les scripts autonomes

Recherche d'athlète

python scripts/search_athlete.py --nom "Dupont" --prenom "Jean"

Options:

• --nom: Nom de famille (obligatoire)
• --prenom: Prénom (optionnel)
• --data-dir: Répertoire des données (défaut: data)
• --csv-only: Utiliser uniquement les fichiers CSV

Recherche de course

python scripts/search_race.py --start-date "2024-01-01" --end-date "2024-12-31"

Extraction des courses

python scripts/extract_races.py --output data

Liste des clubs

python scripts/list_clubs.py

Résumé par athlète

python scripts/athlete_summary.py --data-dir data --output athlete_summary.csv

Via les modules Python

import sys
sys.path.insert(0, 'src')

from ffa_scraper import FFAScraper
from ffa_analyzer import FFADataAnalyzer

# Scraper
scraper = FFAScraper(output_dir="data")
stats = scraper.scrap_all_data(max_pages=7, use_multithreading=True)

# Analyseur
analyzer = FFADataAnalyzer(data_dir="data")
results = analyzer.search_athlete("Dupont", "Jean")

📊 Structure des données

Fichiers générés

data/
├── courses/
│   └── periods/
│       ├── courses_2010-01-01_to_2010-01-15.csv
│       ├── courses_2010-01-16_to_2010-01-30.csv
│       └── ...
├── resultats/
│   └── results.csv
├── clubs/
│   └── clubs.csv
└── exports/
    └── athlete_dupont_jean.csv

Format des CSV

courses_*.csv

• nom: Nom de la course
• date: Date de la course
• lieu: Lieu de la course
• lien: URL vers la page de la course
• type: Type de course (Cross, Stade, Route, etc.)
• categorie: Catégorie de la compétition

results.csv

• place: Place obtenue
• nom: Nom de l'athlète (en majuscules)
• prenom: Prénom de l'athlète
• club: Club de l'athlète
• categorie: Catégorie de compétition
• temps: Temps réalisé
• course_url: URL de la course concernée

🛠️ Scripts disponibles

Scripts principaux

Script	Description
ffa_cli.py	Interface CLI principale
search_athlete.py	Recherche d'athlètes dans les résultats
search_race.py	Recherche de courses par période
extract_races.py	Extraction des courses depuis le calendrier

Scripts utilitaires

Script	Description
list_clubs.py	Liste les clubs disponibles
post_process.py	Post-traitement des données scrapées
monitor_scraping.py	Surveillance en temps réel du scraping
scrape_all_periods.py	Scraping complet par périodes
athlete_summary.py	Génération de résumés par athlète

🚀 Performance

Multithreading

Le multithreading est activé par défaut et utilise 4 workers simultanés. Chaque worker utilise son propre driver Selenium pour scraper les pages en parallèle.

Comparaison de performance:

• Séquentiel: ~14 secondes pour 7 pages
• Multithreading (4 workers): ~8 secondes
• Gain: ~43% plus rapide

Recommandations pour le nombre de workers:

• 2-4 workers: Machines avec 4-8 Go de RAM
• 4-8 workers: Machines avec 8-16 Go de RAM
• 8-16 workers: Machines avec 16+ Go de RAM

Note: Chaque driver Chrome consomme ~200-300 Mo de RAM.

📝 Version

v1.2.0 (Dernière mise à jour)

• Nouveau: Multithreading pour accélérer le scraping (4 workers par défaut)
• Nouveau: Commande check pour détecter le nombre total de pages et de courses
• Nouveau: Détection automatique de la pagination et estimation du temps
• Amélioré: Scraping beaucoup plus rapide (4x plus rapide avec multithreading)
• Amélioré: Barre de progression en temps réel avec tqdm
• Nouveau: Options --multithreading et --no-multithreading

v1.1.0

• Nouveau: Ajout de la commande list pour voir les données disponibles
• Nouveau: Ajout de la commande top pour voir les meilleurs athlètes
• Nouveau: Recherche par club dans les résultats
• Amélioré: Intégration de config.env pour la configuration
• Amélioré: Support de pagination multi-pages pour le calendrier
• Nettoyé: Code optimisé et documenté

⚠️ Notes importantes

Fonctionnalités actuelles

✓ Fonctionne:

• Scraping du calendrier des compétitions (2010-2026)
• Détection automatique de la pagination
• Multithreading pour un scraping 4x plus rapide
• 250+ compétitions récupérées par page
• Scraping des résultats des compétitions
• Recherche d'athlètes, clubs et courses
• Analyse et export des données
• Barre de progression en temps réel

⚠️ Limitations:

• Le site monclub.athle.fr nécessite une connexion pour accéder aux données des clubs
• Les résultats individuels nécessitent un scraping détaillé (option --fetch-details)
• Le multithreading utilise plusieurs drivers Selenium (attention à la RAM)
• Le scraping doit être utilisé de manière responsable (pauses entre les requêtes)
• La structure HTML du site peut changer et nécessiter des mises à jour

Améliorations possibles

• Implémentation de l'authentification pour monclub.athle.fr
• Ajout d'une base de données locale pour des performances accrues
• Interface web pour faciliter l'utilisation
• Support pour la reprise d'un scraping interrompu
• Tests unitaires complets
• Documentation API des modules

🤝 Contribuer

Les contributions sont les bienvenues ! N'hésitez pas à:

1. Forker le projet
2. Créer une branche pour votre fonctionnalité (git checkout -b feature/AmazingFeature)
3. Committer vos changements (git commit -m 'Add some AmazingFeature')
4. Pusher vers la branche (git push origin feature/AmazingFeature)
5. Ouvrir une Pull Request

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

📞 Contact

Pour toute question ou suggestion, n'hésitez pas à:

• Ouvrir une issue sur GitHub
• Contacter le mainteneur du projet

---

Note importante: Ce scraper doit être utilisé de manière responsable. Respectez les conditions d'utilisation du site de la FFA et évitez les requêtes excessives.