neobanbou/README.md

# 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 d'utilisation pour l'opérateur, j'ai tout regroupé sur un seul fichier (comme l'ancien script). 

### 🧪 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 : Représentation d'un fichier.
- 251-256 : Représentation d'une notification.
- 266-328 : Fonction importante qui controle la validité des coordonnées d'un point géographique.
- 333-502 : Fonctions E/S sur des chaines de caractères (ex: formater un nom suivant une nomenclature donné, etc)
- 511-595 : Représentation du projet.
- 608-663 : Fonctions pour obtenir des elements d'environnement pour le projet : date, nom du dossier, etc.
- 666-808 : Fonction importante qui crée les dossiers nécessaires et copie les fichiers de travail.
- 811-831 : Fonction qui controle la longueur des noms de fichier.
- 833-985 : Fonctions importantes qui formate le fichier CSV.
- 995-1060 : 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.

- 1200-1210 : Le programme commence par créer un Projet et définie des valeurs utiles (date, chemin, etc)
- 1213 : 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.
- 1216 : calcule la taille **seulement** des fichiers qui vont être copiés dans le dossier de Travail.
- 1220 : reprend la liste créée et décide des dossiers à créer puis y copie les fichiers attendus.
- 1232-1236 : 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 1240 : Le programme controle la longueur de tous les noms de fichiers.
- ligne 1245 : 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)