MyPacer Scraper 🏃

Scraper haute performance des données d'athlétisme de la FFA depuis athle.fr.

🎯 Rôle Fonctionnel

Ce module est la brique d'acquisition de données de l'écosystème MyPacer. Son rôle est de constituer un annuaire local indexable pour contourner les limitations de recherche du site officiel.

Il ne stocke pas les performances (qui sont récupérées en live par l'API), mais construit le référentiel d'identité (Nom, Club, ID FFA) nécessaire pour :

1. Permettre une recherche instantanée (auto-complétion).
2. Autoriser la recherche floue (trouver un athlète avec une orthographe approximative).
3. Normaliser les données des licenciés.

🚀 Installation

Prérequis

• Python 3.12+
• PostgreSQL 16
• Docker (pour les tests)

Installation des dépendances

# Production
pip install -r requirements.txt

# Développement (inclut tests + qualimétrie)
pip install -r requirements-dev.txt

Configuration

Créer un fichier .env à la racine :

POSTGRES_DEFAULT_DB=postgres
POSTGRES_DB=athle
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres

📊 Usage

Peuplement initial de la base de données (2004-2025)

./populate_database.sh

⚠️ Cette opération peut prendre plusieurs heures.

Mise à jour régulière (saison en cours uniquement)

./update_database.sh

Analyse de la base de données

python3 -m tools.analyze_database

🧪 Tests

# Lancer tous les tests
make test

# Tests avec coverage
make coverage

# Voir le rapport HTML
open htmlcov/index.html

Couverture actuelle : ~54% (objectif : 80%)

🔍 Qualimétrie

Le projet utilise une stack moderne de qualimétrie :

# Formater le code automatiquement
make format

# Vérifier la qualité (linter + type checking)
make lint

# Simuler la CI en local
make ci

Outils utilisés

• black : Formatage automatique du code
• ruff : Linter ultra-rapide (remplace flake8, isort, pylint)
• mypy : Type checking statique
• pytest + pytest-cov : Tests et coverage
• testcontainers : Tests d'intégration avec PostgreSQL

🛠️ Développement

Structure du projet

.
├── core/                 # Configuration, DB, schéma
│   ├── config.py         # Logging et configuration
│   ├── db.py             # Connexions PostgreSQL
│   └── schema.sql        # Schéma complet (tables, index, triggers)
├── scraper/              # Scrapers
│   ├── list_clubs.py     # Scraper des clubs
│   └── list_athletes.py  # Scraper des athlètes
├── tools/                # Outils d'analyse
│   └── analyze_database.py
├── tests/                # Tests unitaires (pytest + testcontainers)
└── logs/                 # Logs d'exécution

Commandes Make disponibles

make help              # Liste toutes les commandes
make install           # Installe les dépendances dev
make test              # Lance les tests
make coverage          # Tests + rapport coverage HTML
make lint              # Vérifie la qualité (ruff + mypy)
make format            # Formate le code (black + ruff)
make check             # Lint + tests
make ci                # Simule la CI en local
make clean             # Nettoie les fichiers temporaires

🐳 Docker

Lancer PostgreSQL

docker-compose up -d postgres

Lancer le scraper dockerisé

docker-compose up scraper

Les logs sont persistés dans ./logs/ sur l'host.

📈 CI/CD

Le projet utilise GitHub Actions pour :

• ✅ Vérifier le formatage (black)
• ✅ Linter le code (ruff)
• ✅ Type checking (mypy)
• ✅ Lancer les tests avec PostgreSQL
• ✅ Générer un rapport de coverage

Voir .github/workflows/ci.yml

📝 Schéma de base de données

Tables principales

clubs

• id : SERIAL PRIMARY KEY (auto-généré)
• ffa_id : TEXT NOT NULL UNIQUE (identifiant FFA)
• name : TEXT NOT NULL
• normalized_name : TEXT NOT NULL (pour recherche floue)
• first_year, last_year : INTEGER (période d'activité)
• created_at, updated_at : TIMESTAMP

athletes

• id : SERIAL PRIMARY KEY (auto-généré)
• ffa_id : TEXT NOT NULL UNIQUE (identifiant FFA)
• license_id : TEXT (numéro de licence, unique si valide)
• name : TEXT NOT NULL
• normalized_name : TEXT NOT NULL
• birth_date, sexe, nationality : TEXT
• created_at, updated_at : TIMESTAMP

Fonctionnalités PostgreSQL

• Triggers : Mise à jour automatique de normalized_name et updated_at
• Extensions : pg_trgm (recherche floue), unaccent (normalisation)
• Index GIN : Recherche trigram sur les noms
• Index partiel : Unicité conditionnelle sur license_id

📚 Documentation

• REFACTORING.md - Historique et détails du refactoring du projet
• SETUP_SONARCLOUD.md - Guide de configuration de SonarCloud
• DOCKER_CRON.md - Automatisation avec Supercronic (tâches planifiées)

🤝 Contribution

1. Fork le projet
2. Crée une branche (git checkout -b feature/amazing-feature)
3. Formate ton code (make format)
4. Vérifie la qualité (make check)
5. Commit tes changements
6. Push et ouvre une Pull Request

📄 Licence

Ce projet est sous licence MIT.