From 115a3748f73fcef792d43ec66c688c67bb29911d Mon Sep 17 00:00:00 2001 From: David Castex Date: Mon, 30 Jun 2025 14:31:17 +0200 Subject: [PATCH] =?UTF-8?q?Mise=20=C3=A0=20jour=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 315 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 176 insertions(+), 139 deletions(-) diff --git a/README.md b/README.md index be10558..2f4e9aa 100644 --- a/README.md +++ b/README.md @@ -1,139 +1,176 @@ - -# NeoBanbou 🐼🐼 - -Script Python utilisé pour le controle qualité de dossiers de plan de -recollement de fibre optiques. - -## 🎍 Mise en place 📖 - -Lorsque vous débutez sur Banbou, la première fois. - -1. Sur le bureau, créez un dossier 📁 nommé *Banbou* (B majuscule). -2. Copiez/collez 📋 dans celui ci, les fichiers : - - `NEOBANBOU.py` 📄 - - `VISA_BANBOU.xlsx` 📄 - - `STYLE_SYMBOLOGIE.lyrx` 📄 - -Et voilà ! - -## 🎍 Utilisation 📖 - -A faire à chaque dossier à traiter. - -1. Copiez/collez 📋 l'archive 🗃 du dossier à traiter dans le dossier *Banbou*, et dézipper la 🤐. -2. A l'intérieur de ⮩ **chaque sous-dossier** ainsi dézippé (ou à défaut dans le dossier dézippé), copiez/collez-y 📋 le fichier `NEOBANBOU.py` 📄. -3. Exécutez ⚙ le script `NEOBANBOU.py` ainsi déposé. - -Vous pouvez fermer les fenêtres apparues une fois le script terminé. Bien joué ! 👍 - -## 🎍 Fonctionnement 📖 - -### ⛪ Historique ⛪ - -Après avoir lu et compris le contenu de l'ancien script, et avoir apporté quelques modifications, j'ai plutot décidé de repartir de zéro. -Ma première version était divisée en plusieurs modules et fichiers. -Mais pour une question d'ergonomie dans l'utilisation, j'ai tout regroupé sur un seul fichier. - -### 🧪 Tests unitaires 🧪 - -Dans l'optique de m'exercer, j'ai créé dans l'ancienne version des tests unitaires pour chaque fonction et classe. Malheuresement, je ne les ai pas mis a jour avec la dernière version, ils ne sont donc pour le moment plus fonctionnels. - -### 🔃 Déroulé du programme 🔃 - -Voici un explicatif du déroulé du programme : - -#### 1. Imports des bibliothèques et modules. - - - lignes 4-14 : Le script commence par vérifier la présence de la commande `pip` (commande qui permet d'installer des modules *PyPI* (Python Package Index, le dépot communautaire des modules Python) et l'installe si nécessaire. - - lignes 15-25 : Le script vérifie la présence des modules additionnels utilisés dans le script et les installe si nécessaire. - -> Note : Cette partie est en vérité à exécuter qu'une seule fois, lors de la première utilisation du script. Si vous souhaitez accélérer l'exécution du script pour les prochaines fois, effacez cette partie (lignes 4 à 25). - - - lignes 29-32 : Import des modules utilisés. - - #### 2. Constantes - - - lignes 39-162 : Vous trouverez une liste de variables constantes : - - Le nom de l'utilisateur Windows. - - Le chemin vers le modèle du Visa. - - Le nom du dossier qui receptionne les fichiers créés. - - Le caractère choisi comme séparateur d'élements d'un fichier CSV. - - L'expression régulière utilisée pour filtrer les fichiers nécessaires des fichiers inutiles. (VOir lien wiki sur les RegEx) - - Les masques binaires utilisés pour les opérations logiques de validation de point de controle. TODO Voir lien plus loin pour les explications. - - Une liste de projections polaires coniques utilisé en France Métropolitaine (TODO Voir lien réf IGN). Elles sont, chacunes, définies et contraintes par leurs plages des valeurs (les coordonnées géographiques). - - -> Note : Vous pouvez modifier facilement le comportement du programme en modifiant directement ces variables. - -#### 3. Classes et fonctions - -Il s'agit du regroupement des modules que j'avais externalisés dans l'ancienne version : - -- lignes 172-245 : Une représentation d'un fichier. -- lignes 251-256 : Une représentation d'une notification. -- lignes 266-328 : Une fonction importante qui controle la validité des coordonnées d'un point géographique. -- lignes 337-472 : Des fonctions *Input/Output* sur des chaines de caractères (ex: formater un nom suivant une nomenclature donné, etc) -- lignes 482-906 : Une représentation du projet. -- lignes 916-1081 : Une fonction qui génère le Visa de controle. - -#### 4. Exécution du programme - ->Note : Le programme principal parait donc très court car il va ensuite faire appel à toutes les autres fonctions vu plus haut. - -- lignes 1123-1134 : Le programme commence par créer un Projet et définie des valeurs utiles (date, chemin, etc) -- ligne 1136 : Le programme parcourt le dossier où se trouve le script et analyse tous les fichiers trouvés (quel est son nom, son extension, est-il est utile pour le projet ? ) et stocke toutes ces infos dans une liste pour être utiliser plus tard. - - ligne 1138 : calcule la taille **seulement** des fichiers qui vont être copiés dans le dossier de Travail. - - ligne 1142 : reprend la liste créée et décide des dossiers à créer puis y copie les fichiers attendus. Ajoute les préfixes et suffixes aux noms de fichiers si nécessaire. -- lignes 1151-1156 : le fichier CSV contenant les points est lu. Chaque ligne, contenant une coordonnée, est : - - analysée, on vérifie de sa projection. - - formatée, on corrige certains défauts de syntaxe. Les lignes vides, etc. - - ajoutée à une liste. Cette liste est ensuite écrite dans un fichier. - -- ligne 1161 : Le programme controle la longueur de tous les noms de fichiers. -- ligne 1166 : finalement le programme crée un visa à partir d'un modèle, et ajoute toutes les informations nécessaires, ainsi que toutes les notifications -sur des points de controles qui ne seraient pas passés. - -### 🛂🚧 Les points de controles réalisés 🚧🛂 - -#### 1. 🚦Intersection CC47 et Lambert93 🚦 - -Voir shémas (TODO) - -#### 2. 🧭 Longitude pas en métropole 🧭 -Si la projection polaire est correcte, je vérifie et avertie si la longitude du point ne se situe pas en métropole. - -#### 3. 📏 Longueur des noms de fichiers 📏 ->Note : Par nom de fichier je veux dire le nom du fichier sans son point ni son extension. Il faut cependant compter les préfixes et suffixes ajoutés. -Ex : pour le fichier `Plan_monfichierDWG.dwg`, le nom retenu sera *Plan_monfichierDWG* simplement. - -La règle retenu est : -- Pour le fichier DWG, longueur nom strictement inférieure à 31. -- Tous les autres noms de fichiers et dossiers, longueur nom strictement inférieure à 46. - -#### 4. 🛸 Fichier CSV imcomplet, inconnu 🛸 -Le formatage du fichier ne résout pas tout. Si il manque des données, des champs entiers, etc, je ne vais pas les créer. Dans ce cas, le programme s'arrete -en affichant un avertissement. - - -#### 5. 🚧 Controle la présence des fichiers nécessaires -Un projet doit necessairement comporter au moins ces 4 fichiers : -- un fichier PDF 📄 de plan de situation -- un fichier PDF 📄 (ou autres formats), la fiche de topographie -- un fichier DWG 📄, le fichier de couches AutoCad -- un **seul** fichier CSV 📄, le fichier contenant le relevé des coordonnées de chaque points. - ->Note: Si un de ces 4 fichiers est absent, le projet devrait être considéré comme **incomplet**. Des FAILs se notifieront dans la page FRONT. - -## 🎍 A l'attention des utilisateurs avancés 📖 - -J'ai considéré l'écriture de ce script comme un exercice d'algorithmie et de d'apprentissage du Python. -De ce point de vue, il y a certainement beaucoup d'optimisation. - -*C'est vrai ça : Pourquoi s'embêter à faire des classes pour des objets qui ont deja nativement dans le langage des classes et méthodes ( wtf une classe _Fichier ??), ou alors pourquoi implementer une variable binaire pour comptabiliser les controles ? (alors que de simples variables ou une liste de variables aurait pu aussi bien fait l'affaire...).* - -**Réponse :** pour la pratique et la curiosité ! - -Donc oui, ce script n'est pas optimal. Mais, il est robuste (plutot) et fonctionnel pour l'usage prévu en production. - -Notez également qu'il n'y a eu aucun recours à de l'IA. L'exercice consistait aussi à conceptualiser les besoins. -TODO Explication avancées. \ No newline at end of file + +# NeoBanbou 🐼🐼 + +Script Python utilisé pour le controle qualité de dossiers de plan de +recollement de fibre optiques. + +## 🎍 Mise en place 📖 + +Lorsque vous débutez sur Banbou, la première fois. + +1. Sur le bureau, créez un dossier 📁 nommé *Banbou* (B majuscule). +2. Copiez/collez 📋 dans celui ci, les fichiers : + - `NEOBANBOU.py` 📄 + - `VISA_BANBOU.xlsx` 📄 + - `STYLE_SYMBOLOGIE.lyrx` 📄 + +Et voilà ! + +## 🎍 Utilisation 📖 + +A faire à chaque dossier à traiter. + +1. Copiez/collez 📋 l'archive 🗃 du dossier à traiter dans le dossier *Banbou*, et dézipper la 🤐. +2. A l'intérieur de ⮩ **chaque sous-dossier** ainsi dézippé (ou à défaut dans le dossier dézippé), copiez/collez-y 📋 le fichier `NEOBANBOU.py` 📄. +3. Exécutez ⚙ le script `NEOBANBOU.py` ainsi déposé. + +Vous pouvez fermer les fenêtres apparues une fois le script terminé. Bien joué ! 👍 + +## 🎍 Fonctionnement 📖 + +### ⛪ Historique ⛪ + +Après avoir lu et compris le contenu de l'ancien script, et avoir apporté quelques modifications, j'ai plutot décidé de repartir de zéro. +Ma première version était divisé en plusieurs modules et fichiers. +Mais pour une question d'ergonomie dans l'utilisation, j'ai tout regroupé sur un seul fichier. + +### 🧪 Tests unitaires 🧪 + +Dans l'optique de m'exercer, j'ai créé dans l'ancienne version des tests unitaires pour chaque fonction et classe. Malheuresement, je ne les ai pas mis a jour avec la dernière version, ils ne sont donc pour le moment plus fonctionnels. [Voir détails](#-lancer-les-tests-) + +### 🔃 Déroulé du programme 🔃 + +Voici un explicatif du déroulé du programme : + +#### 1. Imports des bibliothèques et modules. + + - lignes 4-14 : Le script commence par vérifier la présence de la commande `pip` (commande qui permet d'installer des modules *PyPI* (Python Package Index, le dépot communautaire des modules Python) et l'installe si nécessaire. + - lignes 15-25 : Le script vérifie la présence des modules additionnels utilisés dans le script et les installe si nécessaire. + +> Note : Cette partie est en vérité à exécuter qu'une seule fois, lors de la première utilisation du script. Si vous souhaitez accélérer l'exécution du script pour les prochaines fois, effacez cette partie (lignes 4 à 25). + + - lignes 29-32 : Import des modules utilisés. + + #### 2. Constantes + + - lignes 39-162 : Vous trouverez une liste de variables constantes : + - Le nom de l'utilisateur Windows. + - Le chemin vers le modèle du Visa. + - Le nom du dossier qui receptionne les fichiers créés. + - Le caractère choisi comme séparateur d'élements d'un fichier CSV. + - L'expression régulière utilisée pour filtrer les fichiers nécessaires des fichiers inutiles. (VOir lien wiki sur les RegEx) + - Les masques binaires utilisés pour les opérations logiques de validation de point de controle. TODO Voir lien plus loin pour les explications. + - Une liste de projections polaires coniques utilisé en France Métropolitaine (TODO Voir lien réf IGN). Elles sont, chacunes, définies et contraintes par leurs plages des valeurs (les coordonnées géographiques). + + +> Note : Vous pouvez modifier facilement le comportement du programme en modifiant directement ces variables. + +#### 3. Classes et fonctions + +Il s'agit du regroupement des modules que j'avais externalisés dans l'ancienne version : + +- lignes 172-245 : Une représentation d'un fichier. +- lignes 251-256 : Une représentation d'une notification. +- lignes 266-328 : Une fonction importante qui controle la validité des coordonnées d'un point géographique. +- lignes 337-472 : Des fonctions *Input/Output* sur des chaines de caractères (ex: formater un nom suivant une nomenclature donné, etc) +- lignes 482-906 : Une représentation du projet. +- lignes 916-1081 : Une fonction qui génère le Visa de controle. + +#### 4. Exécution du programme + +>Note : Le programme principal parait donc très court car il va ensuite faire appel à toutes les autres fonctions vu plus haut. + +- lignes 1123-1134 : Le programme commence par créer un Projet et définie des valeurs utiles (date, chemin, etc) +- ligne 1136 : Le programme parcourt le dossier où se trouve le script et analyse tous les fichiers trouvés (quel est son nom, son extension, est-il est utile pour le projet ? ) et stocke toutes ces infos dans une liste pour être utiliser plus tard. + - ligne 1138 : calcule la taille **seulement** des fichiers qui vont être copiés dans le dossier de Travail. + - ligne 1142 : reprend la liste créée et décide des dossiers à créer puis y copie les fichiers attendus. Ajoute les préfixes et suffixes aux noms de fichiers si nécessaire. +- lignes 1151-1156 : le fichier CSV contenant les points est lu. Chaque ligne, contenant une coordonnée, est : + - analysée, on vérifie de sa projection. + - formatée, on corrige certains défauts de syntaxe. Les lignes vides, etc. + - ajoutée à une liste. Cette liste est ensuite écrite dans un fichier. + +- ligne 1161 : Le programme controle la longueur de tous les noms de fichiers. +- ligne 1166 : finalement le programme crée un visa à partir d'un modèle, et ajoute toutes les informations nécessaires, ainsi que toutes les notifications +sur des points de controles qui ne seraient pas passés. + +### 🛂🚧 Les points de controles réalisés 🚧🛂 + +La liste n'est pas exhaustive, le code est commenté + +#### 1. 🚦Intersection CC47 et Lambert93 🚦 + +Voir shémas (TODO) + +#### 2. 🧭 Longitude pas en métropole 🧭 +Si la projection polaire est correcte, je vérifie et avertie si la longitude du point ne se situe pas en métropole. + +#### 3. 📏 Longueur des noms de fichiers 📏 +>Note : Par nom de fichier je veux dire le nom du fichier sans son point ni son extension. Il faut cependant compter les préfixes et suffixes ajoutés. +Ex : pour le fichier `Plan_monfichierDWG.dwg`, le nom retenu sera *Plan_monfichierDWG* simplement. + +La règle retenu est : +- Pour le fichier DWG, longueur nom strictement inférieure à 31. +- Tous les autres noms de fichiers et dossiers, longueur nom strictement inférieure à 46. + +#### 4. 🛸 Fichier CSV imcomplet, inconnu 🛸 +Le formatage du fichier ne résout pas tout. Si il manque des données, des champs entiers, etc, je ne vais pas les créer. Dans ce cas, le programme s'arrete +en affichant un avertissement. + + +#### 5. 🚧 Controle la présence des fichiers nécessaires +Un projet doit necessairement comporter au moins ces 4 fichiers : +- un fichier PDF 📄 de plan de situation +- un fichier PDF 📄 (ou autres formats), la fiche de topographie +- un fichier DWG 📄, le fichier de couches AutoCad +- un **seul** fichier CSV 📄, le fichier contenant le relevé des coordonnées de chaque points. + +>Note: Si un de ces 4 fichiers est absent, le projet devrait être considéré comme **incomplet**. Des FAILs se notifieront dans la page FRONT. + +## 🎍 A l'attention des utilisateurs avancés 📖 + +J'ai considéré l'écriture de ce script comme un exercice d'algorithmie et de d'apprentissage du Python. +De ce point de vue, il y a certainement beaucoup d'optimisation. + +*C'est vrai ça : Pourquoi s'embêter à faire des classes pour des objets qui ont deja nativement dans le langage des classes et méthodes ( wtf une classe _Fichier ??), ou alors pourquoi implementer une variable binaire pour comptabiliser les controles ? (alors que de simples variables ou une liste de variables aurait pu aussi bien fait l'affaire...).* + +**Réponse :** pour la pratique et la curiosité ! + +Donc oui, ce script n'est pas optimal. Mais, il est robuste (plutot) et fonctionnel pour l'usage prévu en production. + +Notez également qu'il n'y a eu aucun recours à de l'IA. L'exercice consistait aussi à conceptualiser les besoins, les représentations de données et l'algorithme. + + + +### 🔧 Lancer les Tests 🔧 + +Pour lancer les tests, il faudra préalablement installer un environnement de travail isolé + +```bash + python -m venv venv +``` + +Puis basculer vers cet environnement (a faire à chaque fois qu'on ouvre un shell) +```bash + source venv/Scripts/activate +``` +Sous Windows ce sera `env\Scripts\activate.bat` + + +J'ai utiliser Pytest pour les tests et son module pytest-mock + +```bash + pip install pytest + pip install pytest-mock +``` + +Les tests sont situés dans le dossier `test/` pour les lancer tous, depuis la racine du projet : + +``` + pytest test/ +``` + + +## Auteurs + +- [@david.castex](https://gitea.digitanie.org/david.castex) +