Mes notes

Convertir une base Heredis vers Gramps

Unknown — Wed, 18 Oct 2023 00:00:00 +0000

Introduction</h2>
Je voulais convertir ma base Heredis 2020 vers Gramps. Voici mes notes sur ce chantier.</p>
Gramps est un logiciel de généalogie libre et open source.</p>

Avertissement : cette page est en cours de rédaction.</p> </blockquote>
Avant de convertir</h2>
J'ai d'abord essayé d'exporter en GEDCOM</a>, option disponible dans Heredis. Résultat : le fichier n'était pas compatible avec Gramps (données perdues, balises inconnues…).</p>
J'ai trouvé une discussion</a> sur un forum de généalogie français où quelqu'un avait réussi, sans partager son code. Il explique que la base Heredis est une base SQLite.</p>
Alors : écrivons le code !</p>
Code</h2>
Introduction</h3>
J'utilise Python car, mis à part du scripting rapide, je n'ai jamais fait de projet complet dans ce langage.</p>

J'essayerai de poster le code sur Github, mais pour l'instant il contient trop de données perso...</p> </blockquote>
Lire la base SQLite</h3>
`#!/usr/bin/python3 import sys, getopt, sqlite3 con = sqlite3.connect('heredis.db') cur = con.cursor() for row in cur.execute("SELECT * FROM table"): print(row) </code></pre>`Schéma de la base Heredis</h3> J'ai utilisé dbdiagram.io</a> pour visualiser le schéma.</p> </p> Architecture de la solution</h2> Après avoir analysé le schéma SQLite d'Heredis, j'ai structuré le projet en modules Python pour séparer la lecture de la base, la transformation des données et la communication avec Gramps.</p> Structure du projet</h3> heredis-to-gramp/ ├── heredis/ # Accès et utilitaires Heredis ├── gramps/ # Modèles et client Gramps Web ├── utils/ # Outils (géocodage, mapping, affichage) ├── commands.py ├── HeredisToGramps.py └── main.py </code></pre> Connexion à la base Heredis</h3> La première étape reste l'extraction du fichier SQLite depuis l'archive .hmw</code> :</p> cp mon-fichier.hmw/mon-fichier.heredis ./heredis.db </code></pre> (faites des sauvegardes !)</p> </blockquote> J'utilise une classe singleton HeredisDb</code> pour réutiliser une seule connexion SQLite et éviter les ouvertures/fermetures répétées.</p> Comprendre le schéma</h3> Le schéma tourne autour de la table centrale Individus</code>. Les autres tables clés sont : Evts</code>, LienIndividuEvenement</code>, Lieux</code>, Sources</code>, Medias</code>, Unions</code>.</p> Certaines spécificités d'Heredis demandent des adaptations : prénoms multiples, professions hiérarchiques, témoins d'événements, numérotation Sosa, etc.</p> Mapping vers Gramps</h3> Le mapping documente la correspondance entre types d'événements, genres, lieux et les objets Gramps. Un fichier de mapping (heredis_gramps_mapping.txt</code>) centralise ces correspondances.</p> Intégration avec Gramps Web</h3> Pour l'import, j'utilise l'API REST de Gramps Web</a> plutôt que l'interface CLI. Un service Docker Compose facilite le déploiement local de Gramps Web.</p> Au début, j'avais envisagé d'utiliser la CLI de Gramps, mais l'API REST s'est avérée plus flexible et avec une courbe d'apprentissage plus rapide.</p> Il faudrait certainement réécrire une partie du code pour utiliser la CLI, mais pour l'instant je me concentre sur l'API REST (et c'est du one-shot!).</p> Import par lots vs. import unitaire</h3> J'ai expérimenté un import par lots via l'endpoint /objects</code> pour améliorer les performances, mais l'approche s'est révélée instable dans certains cas. En production la méthode la plus fiable est l'import unitaire, même si plus lent.</p> Limitations et améliorations futures</h3> Témoins d'événements non transférés</li> Détection et fusion des doublons</li> Export incrémental</li> Interface web de suivi</li> Rapport détaillé des éléments non convertis</li> </ul> Cette approche réutilise la même connexion pour toutes les requêtes, évitant ainsi le coût d'ouvertures/fermetures répétées.</p> Comprendre le schéma Heredis</h2> Le schéma d'Heredis est organisé autour de la table centrale Individus</code></strong>. Voici les tables principales :</p> Principales tables</h3> Individus</strong> : personnes (noms, prénoms, genre, etc.)</li> Evenements</strong> : naissances, décès, mariages, etc.</li> LienIndividuEvenement</strong> : liaison personnes ↔ événements</li> Lieux</strong> : emplacements géographiques</li> Sources</strong> : sources documentaires</li> Medias</strong> : fichiers médias (photos, documents, etc.)</li> IndividusUnions</strong> : mariages / unions</li> </ol> Spécificités d'Heredis</h3> Quelques particularités à prendre en compte :</p> Prénoms multiples</strong> : table Prenoms</code> avec notion de "prénom usuel"</li> Professions multiples</strong> : table Professions</code> avec hiérarchie</li> Témoins d'événements</strong> : gérés via LienIndividuEvenement</code></li> Qualité des sources</strong> : plusieurs niveaux (Source, Information, Preuve)</li> Numérotation Sosa</strong> : table dédiée à la numérotation d'Aboville</li> </ul> Différences structurelles</h3> Certaines notions n'ont pas d'équivalent direct dans Gramps :</p> professions multiples → transformées en attributs multiples</li> prénoms multiples → stockés dans name.first_name</code></li> témoins d'événements → non pris en charge nativement (peuvent devenir des notes)</li> subdivisions géographiques → converties en Place</code> avec coordonnées</li> </ul> Création d'objets via l'API</h3> Le projet contient des modèles pour représenter les objets Gramps côté client. Exemple simplifié pour créer une personne :</p> class GrampsPeople(GrampsObject): def init(self, prenoms: str = "", nom: str = ""): self.name = f"{prenoms} {nom}".strip() self.primary_name = GrampsName() self.primary_name.first_name = prenoms self.primary_name.surname_list = [GrampsSurname(nom, primary=True)] self.primary_name.type = "Birth Name" self.gender = 2 # Inconnu par défaut def set_gender(self, heredis_gender: int): # Heredis : 109 = Masculin, 102 = Féminin self.gender = 1 if heredis_gender == 109 else 0 if heredis_gender == 102 else 2 def to_dict(self): return { "primary_name": self.primary_name.to_dict(), "gender": self.gender, } </code></pre> Utilisation du script</h2> Le script principal propose plusieurs modes d'utilisation :</p> Statistiques de la base Heredis</h3> Parce que c'est toujours intéressant de connaître la taille de sa base avant de lancer un import !</p> </blockquote> python3 main.py --stats # Exemple de sortie Nombre d'individus : 1245 Nombre d'événements : 3892 </code></pre> Rechercher un individu</h3> Le programme permet de rechercher des individus par nom et d'afficher leurs dates et relations :</p> python3 main.py --search "Dupont" --show-dates --show-parents </code></pre> Exemple d'affichage :</p> 👤 Jean DUPONT (ID : 42) Sexe : Masculin 📅 Naissance : 1890-03-15 à Paris 📅 Décès : 1965-07-22 à Lyon 👨‍👩‍👧 Parents : - Pierre DUPONT (ID : 21) - Marie MARTIN (ID : 22) 👤 Sophie DUPONT (ID : 156) Sexe : Féminin 📅 Naissance : 1920-05-10 à Marseille </code></pre> On peut aussi interroger un individu par son identifiant :</p> python3 main.py --individual --id 42 --show-dates --show-parents </code></pre> Format d'affichage (exemple) :</p> 42 DUPONT Jean (1890-03-15 - 1965-07-22) [M] </code></pre> Opérations d'import</h3> Le programme supporte l'import individuel et l'import en lot (expérimental) :</p> # Importer un individu python3 main.py --import-individual --id 42 -y # Importer avec parents et enfants python3 main.py --import-individual --id 42 --import-parents --import-children -y # Importer tous les individus (avec limite) python3 main.py --import-all --limit 100 -y </code></pre> L'option -y</code> confirme automatiquement les opérations sans demander de saisie.</p> Géocodage des lieux</h2> Gramps peut stocker des coordonnées GPS pour les lieux. J'ai ajouté un géocodage automatique :</p> import requests from functools import lru_cache @lru_cache(maxsize=1000) def geocode_place(place_name): """Géocode un lieu et met le résultat en cache.""" response = requests.get( "https://nominatim.openstreetmap.org/search", params={ "q": place_name, "format": "json", "limit": 1 } ) if response.json(): result = response.json()[0] return { "lat": result["lat"], "lon": result["lon"] } return None </code></pre> Un cache mémoire permet d'éviter les requêtes répétées pour les mêmes lieux, améliorant ainsi les performances (et en limitant les appels à l'API de Nominatim).</p> Gestion des médias</h2> Les médias dans Heredis sont référencés par des chemins absolus : il faut copier les fichiers et adapter les chemins pour Gramps.</p> def get_media_for_individual(self, individual_id): """ Récupère tous les médias liés à un individu. Retourne une liste de dictionnaires contenant : - media_id (int) - file_path (str) - file_name (str) - media_principal (bool) """ query = """ SELECT m.CodeID as media_id, m.FilePath as file_path, m.FileName as file_name, lmi.MediaPrincipal as media_principal FROM Medias m JOIN LiensMediaIndividu lmi ON m.CodeID = lmi.XrefMedia WHERE lmi.XrefIndividu = ? ORDER BY lmi.Ordre """ # Exécuter la requête et retourner les résultats </code></pre> Import par lots — expérimentations</h2> J'ai initialement développé un import par lots via l'endpoint /objects</code> de l'API Gramps pour améliorer les performances (réduire les 4–5 appels API par personne à 1–2 appels pour plusieurs personnes).</p> Cependant, cette approche par lots a été abandonnée</strong> à cause d'instabilités : échecs de transaction et comportements incohérents avec certains jeux de données.</p> La méthode stable actuelle importe les individus un par un — plus fiable, mais plus lent.</p> Limitations actuelles et améliorations futures</h2> Limitations actuelles</h3> Témoins d'événements</strong> : non transférés (pas d'équivalent natif dans Gramps)</li> Hiérarchie des professions</strong> : aplatie en liste simple</li> Recadrage des photos</strong> : informations perdues</li> Tâches Heredis</strong> : non exportées</li> Vitesse d'import</strong> : l'import unitaire est plus lent mais plus stable</li> </ol> Améliorations envisagées</h3> Exporter les témoins comme notes textuelles</li> Détection et fusion des doublons</li> Export incrémental</li> Interface web de suivi de l'import</li> Validation des données avant import</li> Rapport détaillé des éléments non convertis</li> Implémentation stable d'un import par lots</li> </ul> Conclusion</h2> Ce projet m'a permis de :</p> Comprendre en profondeur les deux modèles (Heredis et Gramps)</li> Progresser en Python (singletons, décorateurs, optimisation SQLite)</li> Rédiger une documentation utile</li> Construire un convertisseur fonctionnel malgré les différences structurelles</li> </ol> Ressources utiles</h2> Documentation Gramps Web API</a></li> Gramps.js (Gramps Web)</a></li> DBDiagram.io</a> — pour visualiser les schémas SQL</li> Documentation SQLite</a></li> Forum Geneanet</a></li> </ul>