324 lines
13 KiB
Markdown
324 lines
13 KiB
Markdown
# Améliorations du Scraper Agenda du Libre
|
||
|
||
## Nouvelles Fonctionnalités
|
||
|
||
### 1. Cache JSON Intelligent
|
||
- **Fichier de cache** : `agendadulibre_cache.json`
|
||
- **Détection de changements** : Le script détecte si le contenu iCal a changé via un hash MD5
|
||
- **Évite les re-téléchargements** : Si le contenu est identique, utilise le cache existant
|
||
- **Suivi des événements traités** : Mémorise les événements déjà traités pour éviter les doublons
|
||
|
||
### 2. Limitation du Nombre d'Événements
|
||
- **Argument `--max-events`** : Limite le nombre d'événements à traiter
|
||
- **Utile pour les tests** : Permet de tester avec un petit nombre d'événements
|
||
- **Statistiques** : Affiche le nombre d'événements ignorés à cause de la limite
|
||
|
||
### 3. Mode Dry-Run par Défaut
|
||
- **Sécurité** : Par défaut, aucun événement n'est envoyé à l'API
|
||
- **Simulation** : Affiche ce qui serait envoyé sans faire d'appels API réels
|
||
- **Override** : Utilisez `--no-dry-run` pour l'envoi réel
|
||
|
||
### 4. Logs Détaillés des Événements
|
||
- **Informations complètes** : Affiche tous les détails de l'événement avant insertion
|
||
- **Traçabilité** : ID, titre, description, dates, lieu, URL, source, etc.
|
||
- **Debugging** : Facilite le diagnostic des problèmes d'insertion
|
||
- **Audit** : Permet de vérifier les données avant envoi à l'API
|
||
|
||
### 5. Géocodage Automatique Intelligent
|
||
- **Priorité GEO** : Extrait d'abord les coordonnées du champ `GEO:` dans l'iCal
|
||
- **Détection d'adresses** : Extrait automatiquement les adresses après la première virgule
|
||
- **Géocodage Nominatim** : Utilise l'API Nominatim pour obtenir les coordonnées réelles
|
||
- **Nettoyage intelligent** : Détecte les numéros d'adresse pour améliorer la précision
|
||
- **Fallback robuste** : Utilise le lieu complet si pas d'adresse détectée
|
||
- **Respect des limites** : Pause d'1 seconde entre les requêtes Nominatim
|
||
- **Optimisation** : Évite le géocodage sur les événements déjà traités avec succès
|
||
|
||
### 6. Extraction des Catégories
|
||
- **Champ CATEGORIES** : Extrait automatiquement les catégories du champ `CATEGORIES:` de l'iCal
|
||
- **Tags multiples** : Support des catégories multiples par événement
|
||
- **Intégration OEDB** : Ajoute les catégories comme propriété `tags` dans l'événement
|
||
- **Logs informatifs** : Affiche les catégories trouvées dans les logs détaillés
|
||
|
||
### 7. Extraction des Propriétés Étendues
|
||
- **ORGANIZER** : Extrait l'organisateur de l'événement (email/contact)
|
||
- **X-ALT-DESC** : Extrait la description alternative HTML si disponible
|
||
- **SUMMARY** : Utilise le résumé comme description courte
|
||
- **SEQUENCE** : Extrait le numéro de séquence de l'événement
|
||
- **RRULE** : Extrait les règles de répétition pour les événements récurrents
|
||
- **Enrichissement complet** : Toutes les métadonnées iCal sont préservées
|
||
|
||
### 8. Priorisation des Événements
|
||
- **Événements en attente** : Priorité haute pour les événements avec status `pending`, `failed`, `api_error`
|
||
- **Cache intelligent** : Vérification dans les données locales et le cache
|
||
- **Tri automatique** : Les événements en attente sont traités en premier
|
||
- **Logs informatifs** : Indication claire des événements prioritaires avec emoji 🔄
|
||
- **Robustesse** : Retry automatique des événements échoués
|
||
|
||
### 9. Traitement Parallèle
|
||
- **Activation automatique** : Se déclenche pour plus de 10 événements avec `--parallel`
|
||
- **ThreadPoolExecutor** : Utilise `concurrent.futures` pour la parallélisation
|
||
- **Workers configurables** : Nombre de workers ajustable avec `--max-workers`
|
||
- **Thread-safe** : Méthode `process_single_event()` sécurisée pour les threads
|
||
- **Performance** : Amélioration significative pour les gros volumes d'événements
|
||
|
||
## Utilisation
|
||
|
||
### Commandes de Base
|
||
|
||
```bash
|
||
# Mode dry-run par défaut (sécurisé)
|
||
python agendadulibre.py
|
||
|
||
# Limiter à 5 événements en mode dry-run
|
||
python agendadulibre.py --max-events 5
|
||
|
||
# Mode réel avec limite de 10 événements
|
||
python agendadulibre.py --no-dry-run --max-events 10
|
||
|
||
# Mode verbeux pour voir les détails
|
||
python agendadulibre.py --max-events 3 --verbose
|
||
|
||
# Forcer le rechargement du fichier iCal
|
||
python agendadulibre.py --force-refresh --max-events 5
|
||
|
||
# Traitement parallèle pour gros volumes
|
||
python agendadulibre.py --max-events 50 --parallel --max-workers 8 --no-dry-run
|
||
|
||
# Traitement parallèle en mode dry-run
|
||
python agendadulibre.py --max-events 100 --parallel --max-workers 4
|
||
```
|
||
|
||
### Arguments Disponibles
|
||
|
||
| Argument | Description | Défaut |
|
||
|----------|-------------|---------|
|
||
| `--max-events N` | Limite le nombre d'événements à traiter | Aucune limite |
|
||
| `--dry-run` | Mode simulation (par défaut) | Activé |
|
||
| `--no-dry-run` | Désactive le mode dry-run | - |
|
||
| `--verbose` | Mode verbeux | - |
|
||
| `--force-refresh` | Force le rechargement iCal | - |
|
||
| `--cache-duration N` | Durée de validité du cache (heures) | 1 |
|
||
| `--batch-size N` | Taille des batches | 1 |
|
||
| `--api-url URL` | URL de l'API OEDB | https://api.openeventdatabase.org |
|
||
| `--parallel` | Activer le traitement parallèle pour plus de 10 événements | False |
|
||
| `--max-workers N` | Nombre maximum de workers pour le traitement parallèle | 4 |
|
||
|
||
## Fichiers Générés
|
||
|
||
### Cache JSON (`agendadulibre_cache.json`)
|
||
```json
|
||
{
|
||
"processed_events": {
|
||
"event_id_1": {
|
||
"processed_at": "2024-01-01T12:00:00",
|
||
"status": "saved",
|
||
"event_label": "Nom de l'événement"
|
||
}
|
||
},
|
||
"last_ical_fetch": "2024-01-01T12:00:00",
|
||
"ical_content_hash": "md5_hash_du_contenu"
|
||
}
|
||
```
|
||
|
||
### Données d'Événements (`agendadulibre_events.json`)
|
||
```json
|
||
{
|
||
"events": {
|
||
"event_id": {
|
||
"status": "saved",
|
||
"message": "Créé avec succès",
|
||
"last_attempt": "2024-01-01T12:00:00",
|
||
"event": { /* données de l'événement */ }
|
||
}
|
||
},
|
||
"last_update": "2024-01-01T12:00:00"
|
||
}
|
||
```
|
||
|
||
## Exemples de Sortie
|
||
|
||
### Mode Dry-Run avec Logs Détaillés
|
||
```
|
||
🚀 Démarrage du scraping de l'agenda du libre
|
||
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
|
||
Mode dry-run: OUI
|
||
Limite d'événements: 5
|
||
Cache iCal: valide pendant 1h
|
||
Mode DRY-RUN activé - aucun événement ne sera envoyé à l'API
|
||
|
||
📝 Détails de l'événement à insérer:
|
||
ID: 6a575f6a82922f4501854431fc3f831c
|
||
Titre: Conférence Python
|
||
Description: Présentation sur Python
|
||
Type: scheduled
|
||
Catégorie: culture.floss
|
||
Lieu: Paris, France
|
||
Début: 2024-12-01T10:00:00
|
||
Fin: 2024-12-01T12:00:00
|
||
URL: https://example.com/event1
|
||
Source: Agenda du Libre
|
||
Coordonnées: [0, 0]
|
||
Modifié par: agendadulibre_scraper
|
||
[DRY-RUN] Simulation d'envoi de l'événement: Conférence Python
|
||
✅ Conférence Python - Simulé (dry-run)
|
||
```
|
||
|
||
### Mode Réel avec Propriétés Complètes
|
||
```
|
||
🚀 Démarrage du scraping de l'agenda du libre
|
||
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
|
||
Mode dry-run: NON
|
||
Limite d'événements: 3
|
||
|
||
📍 Coordonnées GEO trouvées: 45.756, 4.84773
|
||
🏷️ Catégories trouvées: entraide, aldil, epn-des-rancy, linux
|
||
👤 Organisateur trouvé: mailto:contact@aldil.org
|
||
📝 Description courte trouvée: Entraide et Bidouille
|
||
🔢 Séquence trouvée: 3
|
||
✅ Coordonnées utilisées depuis le champ GEO: [4.84773, 45.756]
|
||
|
||
📝 Détails de l'événement à insérer:
|
||
ID: 6a575f6a82922f4501854431fc3f831c
|
||
Titre: Entraide et Bidouille
|
||
Description: Atelier d'entraide informatique
|
||
Type: scheduled
|
||
Catégorie: culture.floss
|
||
Lieu: Maison pour tous / salle des Rancy, 249 rue Vendôme, Lyon, France
|
||
Début: 2024-12-01T10:00:00
|
||
Fin: 2024-12-01T12:00:00
|
||
URL: https://example.com/event1
|
||
Source: Agenda du Libre
|
||
Coordonnées: [4.84773, 45.756]
|
||
Tags: entraide, aldil, epn-des-rancy, linux
|
||
Organisateur: mailto:contact@aldil.org
|
||
Description courte: Entraide et Bidouille
|
||
Séquence: 3
|
||
Règles de répétition: N/A
|
||
Description HTML: N/A
|
||
Modifié par: agendadulibre_scraper
|
||
🌐 Envoi à l'API: https://api.openeventdatabase.org/event
|
||
✅ Événement créé avec succès dans l'API
|
||
✅ Entraide et Bidouille - Créé avec succès
|
||
```
|
||
|
||
### Mode Réel avec Géocodage Nominatim
|
||
```
|
||
🚀 Démarrage du scraping de l'agenda du libre
|
||
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
|
||
Mode dry-run: NON
|
||
Limite d'événements: 3
|
||
|
||
📍 Adresse potentielle trouvée: 15 rue de la Paix, Paris, France
|
||
🌍 Géocodage avec Nominatim: 15 rue de la Paix, Paris, France
|
||
✅ Géocodage réussi: 15 rue de la Paix, Paris, France -> (48.8566, 2.3522)
|
||
Adresse trouvée: 15 Rue de la Paix, 75001 Paris, France
|
||
🎯 Coordonnées mises à jour par géocodage: [0, 0] -> [2.3522, 48.8566]
|
||
|
||
📝 Détails de l'événement à insérer:
|
||
ID: 6a575f6a82922f4501854431fc3f831c
|
||
Titre: Conférence Python
|
||
Description: Présentation sur Python
|
||
Type: scheduled
|
||
Catégorie: culture.floss
|
||
Lieu: Centre de conférences, 15 rue de la Paix, Paris, France
|
||
Début: 2024-12-01T10:00:00
|
||
Fin: 2024-12-01T12:00:00
|
||
URL: https://example.com/event1
|
||
Source: Agenda du Libre
|
||
Coordonnées: [2.3522, 48.8566]
|
||
Modifié par: agendadulibre_scraper
|
||
🌐 Envoi à l'API: https://api.openeventdatabase.org/event
|
||
✅ Événement créé avec succès dans l'API
|
||
✅ Conférence Python - Créé avec succès
|
||
```
|
||
|
||
### Mode Optimisé - Événements Déjà Traités
|
||
```
|
||
🚀 Démarrage du scraping de l'agenda du libre
|
||
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
|
||
Mode dry-run: NON
|
||
|
||
⏭️ Événement ignoré: Conférence Python - déjà traité (status: saved)
|
||
⏭️ Événement ignoré: Atelier Linux - déjà dans le cache (status: saved)
|
||
ℹ️ Géocodage ignoré pour Formation Git - déjà traité
|
||
ℹ️ Géocodage ignoré - événement déjà traité
|
||
📝 Détails de l'événement à insérer:
|
||
ID: dd0850de6ed7a6b4d482a7dc5201d09c
|
||
Titre: Formation Git
|
||
Description: Maîtriser Git
|
||
Type: scheduled
|
||
Catégorie: culture.floss
|
||
Lieu: Espace formation, 42 avenue du Général de Gaulle, Marseille, France
|
||
Début: 2024-12-03T09:00:00
|
||
Fin: 2024-12-03T11:00:00
|
||
URL: https://example.com/event3
|
||
Source: Agenda du Libre
|
||
Coordonnées: [5.3698, 43.2965]
|
||
Modifié par: agendadulibre_scraper
|
||
🌐 Envoi à l'API: https://api.openeventdatabase.org/event
|
||
⚠️ Événement déjà existant dans l'API
|
||
✅ Formation Git - Événement déjà existant
|
||
```
|
||
|
||
### Mode Prioritaire - Événements en Attente
|
||
```
|
||
🚀 Démarrage du scraping de l'agenda du libre
|
||
Configuration: batch_size=1, api_url=https://api.openeventdatabase.org
|
||
Mode dry-run: NON
|
||
|
||
🔄 Événement en attente prioritaire: Atelier Linux (status: failed)
|
||
🔄 Événement en attente du cache: Formation Git (status: pending)
|
||
📋 Événements à traiter: 2 (dont 2 en attente)
|
||
🔄 Traitement prioritaire: Atelier Linux
|
||
📝 Détails de l'événement à insérer:
|
||
ID: 5ac96f4ae72cd28d164489580e97daca
|
||
Titre: Atelier Linux
|
||
Description: Apprendre Linux
|
||
Type: scheduled
|
||
Catégorie: culture.floss
|
||
Lieu: Lyon, France
|
||
Début: 2024-12-02T14:00:00
|
||
Fin: 2024-12-02T16:00:00
|
||
URL: https://example.com/event2
|
||
Source: Agenda du Libre
|
||
Coordonnées: [4.8357, 45.764]
|
||
Modifié par: agendadulibre_scraper
|
||
🌐 Envoi à l'API: https://api.openeventdatabase.org/event
|
||
✅ Événement créé avec succès dans l'API
|
||
✅ Atelier Linux - Créé avec succès
|
||
```
|
||
|
||
## Tests
|
||
|
||
Exécutez le script de test pour vérifier les fonctionnalités :
|
||
|
||
```bash
|
||
python test_agendadulibre_improvements.py
|
||
```
|
||
|
||
## Avantages
|
||
|
||
1. **Sécurité** : Mode dry-run par défaut évite les insertions accidentelles
|
||
2. **Performance** : Cache intelligent réduit les téléchargements inutiles
|
||
3. **Contrôle** : Limitation du nombre d'événements pour les tests
|
||
4. **Traçabilité** : Logs détaillés et fichiers de cache pour le suivi
|
||
5. **Flexibilité** : Arguments pour personnaliser le comportement
|
||
6. **Géolocalisation précise** : Géocodage automatique des lieux avec coordonnées réelles
|
||
7. **Intelligence** : Détection et extraction automatique des adresses
|
||
8. **Robustesse** : Fallback intelligent en cas d'échec de géocodage
|
||
9. **Optimisation** : Évite les retraitements inutiles des événements déjà envoyés
|
||
10. **Efficacité** : Skip automatique du géocodage pour les événements déjà traités
|
||
11. **Enrichissement** : Extraction automatique des catégories comme tags
|
||
12. **Classification** : Amélioration de la recherche et du filtrage des événements
|
||
13. **Métadonnées complètes** : Extraction de toutes les propriétés iCal importantes
|
||
14. **Traçabilité** : Organisateur, séquence et règles de répétition préservées
|
||
15. **Flexibilité** : Support des descriptions HTML et des événements récurrents
|
||
16. **Priorisation intelligente** : Traitement prioritaire des événements en attente
|
||
17. **Robustesse** : Retry automatique des événements échoués
|
||
18. **Efficacité** : Optimisation du traitement par priorité
|
||
19. **Parallélisation** : Traitement simultané pour les gros volumes d'événements
|
||
20. **Performance** : Amélioration significative avec `--parallel` et `--max-workers`
|
||
|
||
## Migration
|
||
|
||
Les anciens scripts continuent de fonctionner, mais il est recommandé d'utiliser les nouveaux arguments pour plus de contrôle et de sécurité.
|