Ajout de commentaires

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+### [v3.1] - 2020-06-08
+- Amélioration de la documentation
+
 ### [v3.0] - 2020-06-07
 - Réorganisation du code en modules
 - Ajout du script permettant de créer la base de donnée SQLite

README.md

@@ -1,31 +1,34 @@
 # Purge Registres Décès INSEE
 
-Ce programme s'adresse essentiellement aux greffiers des pieux, paroisse et
+Ce programme s'adresse essentiellement aux greffiers des pieux,
-branches de France, de l'Église de Jésus Christ des Saints des Derniers Jours.
+paroisse et branches de France, de l'Église de Jésus Christ des Saints
+des Derniers Jours.
 
 ## Objectif
 
-La tenue à jour des registres de l'Église n'est pas une tache aisée. Une des
+La tenue à jour des registres de l'Église n'est pas une tache
-difficultés est liée au fait que lorsqu'un membre s'éloigne de l'Église, ses
+aisée. Une des difficultés est liée au fait que lorsqu'un membre
-informations personnelles (adresse, téléphone, etc) ne sont plus mises à jour.
+s'éloigne de l'Église, ses informations personnelles (adresse,
+téléphone, etc) ne sont plus mises à jour.
 
 L'INSEE tient un fichier des personnes décédées en France de 1970 à
 aujourd'hui. Ce fichier est disponible en [données
-ouvertes](https://fr.wikipedia.org/wiki/Donn%C3%A9es_ouvertes) sur [le site du
+ouvertes](https://fr.wikipedia.org/wiki/Donn%C3%A9es_ouvertes) sur [le
+site du
 gouvernement](https://www.data.gouv.fr/fr/datasets/fichier-des-personnes-decedees/).
-Ce fichier est une aubaine, car il permet de savoir si un membre de l'Église
+Ce fichier est une aubaine, car il permet de savoir si un membre de
-est décédé sans que nous le sachions. Si une personne figure à la fois dans
+l'Église est décédé sans que nous le sachions. Si une personne figure
-les registres de l'Église et dans le fichier de l'INSEE, alors une mise à jour
+à la fois dans les registres de l'Église et dans le fichier de
-du registre de l'Église est nécessaire.
+l'INSEE, alors une mise à jour du registre de l'Église est nécessaire.
 
-Parcourir à la main le registre de membres de paroisse est une tache longue et
+Parcourir à la main le registre de membres de paroisse est une tache
-fastidieuse. Ce programme permet de comparer automatiquement le registre de
+longue et fastidieuse. Ce programme permet de comparer automatiquement
-paroisse avec le fichier de l'INSEE, et donne la liste des membres trouvés
+le registre de paroisse avec le fichier de l'INSEE, et donne la liste
-dans le fichier de l'INSEE.
+des membres trouvés dans le fichier de l'INSEE.
 
-Le fichier de l'INSEE est actualisé de façon mensuelle. Il semble intéressant
+Le fichier de l'INSEE est actualisé de façon mensuelle. Il semble
-d'utiliser ce programme régulièrement (une fois par an par exemple) pour
+intéressant d'utiliser ce programme régulièrement (une fois par an par
-s'assurer que les registres restent à jour.
+exemple) pour s'assurer que les registres restent à jour.
 
 ## Pré-requis
 
@@ -56,49 +59,67 @@ cd purge-registres-deces-insee
 
 ```bash
 python3 -m venv localenv
-. localenv/bin/activate
+source localenv/bin/activate
 pip install -r requirements.txt
 ```
 
 ## Utilisation
 
-Le début du fichier ```trouver_deces.py``` contient les paramètres à configurer :
+Le fichier ```purge-registres-deces-insee/settings.py``` contient les
+paramètres à configurer :
+
+- chemin_base_donnees : Le chemin vers le [fichier
+  téléchargé](https://git.roflcopter.fr/sdjgeek/purge-registres-deces-insee/-/wikis/home#t%C3%A9l%C3%A9charger-la-base-de-donn%C3%A9e)
+
+- numeros_unites : La liste des unités que le programme doit
+  tester. La liste commence par le caractère '['. Les numéros d'unités
+  sont séparés par des virgules. La liste se termine par le caractère
+  ']'. Par exemple [47823, 67745, 31456]
+
+- cookie : Les cookies de la session au compte SDJ. Pour obtenir ces
+  cookies il faut :
 
-- chemin_base_donnees : Le chemin vers le fichier téléchargé (me contacter)
-- numeros_unites : La liste des unités que le programme doit tester. La liste commence par le caractère '['. Les
-  numéros d'unités sont séparés par des virgules. La liste se termine par le caractère ']'. Par exemple
-  [47823, 67745, 31456]
-- cookie : Les cookies de la session au compte SDJ. Pour obtenir ces cookies il faut
 1- Ouvrir Firefox
+
 2- Ouvrir les outils de développement : CTRL + MAJ + E
+
 3- Aller sur le site des outils pour greffiers : https://lds.org/lcr
+
 4- Entrer identifiant et mot de passe SDJ
+
 5- Aller dans la liste des membres
+
 6- Dans l'outil de développement, cliquer sur la dernière ligne
-  7- Dans le panneau de droite, dans la section "En-tête de la requête", rechercher le champ "cookie"
+
+7- Dans le panneau de droite, dans la section "En-tête de la requête",
+rechercher le champ "cookie"
+
 8- Copier la valeur contenue dans ce champ
-- chemin_repertoire_sortie : Le chemin vers le répertoire qui contiendra la fichiers de sortie
+  
+- chemin_repertoire_sortie : Le chemin vers le répertoire qui
+  contiendra la fichiers de sortie
 
 Une fois la configuration effectuée, lancer le script :
 
 ```bash
 . localenv/bin/activate
-python trouver_deces.py
+python purge-registres-deces-insee/trouver_deces.py
 ```
 
-Le script mettra un peu de temps à s'exécuter. En fin d'exécution, le fichier
+Le script mettra un peu de temps à s'exécuter. En fin d'exécution, le
-liste_membres_decedes_unite_{unite}.txt contiendra la liste des membres
+fichier liste_membres_decedes_unite_{unite}.txt contiendra la liste
-trouvés dans le fichier de l'INSEE. Il est recommandé de contrôler les
+des membres trouvés dans le fichier de l'INSEE. Il est recommandé de
-informations du membres avant de le déclarer comme décédé dans les registres
+contrôler les informations du membres avant de le déclarer comme
-de l'Église.
+décédé dans les registres de l'Église.
 
 ## Licence
 
 Copyright (c) 2020 Sdj Geek
 
-Ce logiciel est sous licence MIT/X Consortium. Elle donne à toute personne
+Ce logiciel est sous licence MIT/X Consortium. Elle donne à toute
-recevant le logiciel (et ses fichiers) le droit illimité de l'utiliser, le
+personne recevant le logiciel (et ses fichiers) le droit illimité de
-copier, le modifier, le fusionner, le publier, le distribuer, le vendre et le
+l'utiliser, le copier, le modifier, le fusionner, le publier, le
-"sous-licencier" (l'incorporer dans une autre licence). La seule obligation
+distribuer, le vendre et le "sous-licencier" (l'incorporer dans une
-est d'incorporer la notice de licence et de copyright dans toutes les
+autre licence). La seule obligation est d'incorporer la notice de
-copies. Voir le fichier [LICENSE](LICENSE) pour le texte complet.
+licence et de copyright dans toutes les copies. Voir le fichier
+[LICENSE](LICENSE) pour le texte complet.

purge-registres-deces-insee/bdd_insee.py

@@ -1,19 +1,35 @@
+"""Classe d'accès aux données INSEE dans la base SQLite
+
+"""
+
 import os
 import peewee
 
 
+# Objet de connexion à la base
 database = peewee.SqliteDatabase(None)
 
 
 class BddInsee:
+    """Classe encapsulant les accès aux données.
+
+    """
 
     def __init__(self, chemin_base_donnees):
+        """Initialisation
+
+        :param chemin_base_donnees: chemin vers le fichier SQLite
+
+        """
         new = not os.path.isfile(chemin_base_donnees)        
         database.init(chemin_base_donnees)
         if new:
             database.create_tables([self.Person])
 
     class Person(peewee.Model):
+        """Classe représentant une personne dans la base
+
+        """
         last_name = peewee.CharField()
         first_name = peewee.CharField()
         is_woman = peewee.BooleanField()
@@ -33,6 +49,17 @@ class BddInsee:
             database = database
 
     def find_person(self, first_name, last_name, maiden_name, annee_naissance, mois_naissance, jour_naissance):
+        """Rechercher une personne dans la base
+
+        :param first_name: prénom de la personne à rechercher
+        :param last_name: nom de famille de la personne à rechercher
+        :param maiden_name: nom de jeune fille de la personne à rechercher (None si non défini)
+        :param annee_naissance: année de naissance de la personne à rechercher
+        :param mois_naissance: mois de naissance de la personne à rechercher
+        :param jour_naissance: jour de naissance de la personne à rechercher
+        :returns: liste contenant un dictionnaire par personne trouvée
+
+        """
         if maiden_name:
             return self.Person.select().where((self.Person.annee_naissance == int(annee_naissance))
                                          & (self.Person.mois_naissance == int(mois_naissance))
@@ -48,6 +75,12 @@ class BddInsee:
                                          & (self.Person.last_name.contains(last_name.upper())))
 
     def import_data_list(self, data_list):
+        """Insérer des données dans la base
+
+        :param data_list: liste de dictionnaires contenant les
+        informations à insérer
+
+        """
         with database.atomic():
             for batch in peewee.chunked(data_list, 70):
                 self.Person.insert_many(batch).execute()

purge-registres-deces-insee/completer_bdd_insee.py

@@ -29,6 +29,12 @@ from bdd_insee import BddInsee
 
 
 def parse_insee_file(data_file_path):
+    """Parse un fichier de l'INSEE
+
+    :param data_file_path: chemin vers le fichier à parser
+    :returns: liste de dictionnaires contenant les informations à insérer
+
+    """
     data_list = []
     with open(data_file_path, 'r', encoding='latin1') as data_file:
         for line in data_file.readlines():
@@ -56,6 +62,12 @@ def parse_insee_file(data_file_path):
 
 
 def completer_bdd_insee(chemin_base_donnees, chemin_repertoire_donnees):
+    """Ajouter des données dans la base
+
+    :param chemin_base_donnees: chemin vers le fichier SQLite
+    :param chemin_repertoire_donnees: chemin vers le répertoire contenant les fichiers de l'INSEE
+
+    """
     base_insee = BddInsee(chemin_base_donnees)
     for file_path in sorted(glob.glob(os.path.join(chemin_repertoire_donnees, "deces-*.txt"))):
         print(f"Import du fichier {file_path}")

purge-registres-deces-insee/site_eglise.py

@@ -1,9 +1,18 @@
+"""Classe d'accès aux données du site de l'Église
+
+"""
+
 import requests
 
 
-###
-# Registres de l'Église
 def get_member_list(unit_number, cookie):
+    """Recevoir la liste des membres
+
+    :param unit_number: numéro de l'unité (paroisse, branche)
+    :param cookie: le cookie de session pour l'accès au site
+    :returns: la liste des membres sous forme d'objet JSON
+
+    """
     r = requests.get('https://lcr.churchofjesuschrist.org/services/umlu/report/member-list',
                      params={'lang': "fra", 'unitNumber': unit_number},
                      headers={'Accept': "application/json",
@@ -13,6 +22,13 @@ def get_member_list(unit_number, cookie):
 
 
 def get_member_profile(member_id, cookie):
+    """Recevoir les informations sur un membre
+
+    :param member_id: ID du membre
+    :param cookie: le cookie de session pour l'accès au site
+    :returns: les informations sur le membre sous forme d'objet JSON
+
+    """
     r = requests.get(f'https://lcr.churchofjesuschrist.org/records/member-profile/service/{member_id}',
                      params={'lang': "fra"},
                      headers={'Accept': "application/json",

purge-registres-deces-insee/trouver_decedes.py

@@ -47,9 +47,15 @@ import site_eglise
 import settings as param
 
 
-###
-# Programme principal
 def trouver_decedes(chemin_base_donnees, numeros_unites, cookie, chemin_repertoire_sortie):
+    """Recherche les personnes décédées dans les registres
+
+    :param chemin_base_donnees: chemin vers le fichier SQLite
+    :param numeros_unites: liste des numéros d'unités à analyser
+    :param cookie: le cookie de session pour l'accès au site
+    :param chemin_repertoire_sortie: chemin vers le répertoire où inscrire les fichiers de sortie
+
+    """
     base_insee = BddInsee(chemin_base_donnees)
     # Boucler sur la liste des unités
     for unite in numeros_unites: