docs(docs): 📝 update documentation files
update ruff and pyproject.toml. Sync or reinstall the package
This commit is contained in:
+87
-28
@@ -9,7 +9,9 @@ génère des rapports texte.
|
||||
Le traitement suit un pipeline linéaire :
|
||||
|
||||
```text
|
||||
fichiers de logs
|
||||
Flux fichiers fichiers de logs
|
||||
|
||||
fichiers de logs
|
||||
│
|
||||
▼
|
||||
parser.py lit et parse les fichiers en LogEntry
|
||||
@@ -24,6 +26,29 @@ fichiers de logs
|
||||
rapports .log
|
||||
```
|
||||
|
||||
```text
|
||||
Flux mail
|
||||
|
||||
boîte Exchange (dossier Logs)
|
||||
│
|
||||
▼
|
||||
read_mail.py
|
||||
│
|
||||
▼
|
||||
perser.py
|
||||
│
|
||||
▼
|
||||
classifier.py
|
||||
│
|
||||
▼
|
||||
reporter.py
|
||||
│
|
||||
▼
|
||||
notifier.py
|
||||
```
|
||||
|
||||
L'envoi du mail précède le déplacement des mails vers `Analyzed`. Si l'envoi échoue, les mails restent dans `Logs` et le rapport est régénéré au prochain passage : un rapport peut être envoyé deux fois en cas d'échec après envoi, mais jamais perdu.
|
||||
|
||||
## Structure du package
|
||||
|
||||
```text
|
||||
@@ -31,25 +56,68 @@ src/logwatcher/
|
||||
├── __init__.py # expose __version__
|
||||
├── __main__.py # point d'entrée : python -m logwatcher
|
||||
├── cli.py # interface en ligne de commande (Typer)
|
||||
├── config.py # constantes : chemins, formats
|
||||
├── config.py # constantes : chemins, formats, source type
|
||||
├── logging_config.py # configuration du logging
|
||||
├── models.py # LogEntry : structure de données
|
||||
├── parser.py # lecture et parsing des fichiers
|
||||
├── mail_reader.py # lecture de la boîte mail (EWS)
|
||||
├── mail_utils.py # utilitaires boîte mail (dossiers, constantes)
|
||||
├── notifier.py # envoi du rapport n2 par mail
|
||||
├── parser.py # lecture et parsing des logs
|
||||
├── classifier.py # classification N2 / hors N2
|
||||
└── reporter.py # génération des rapports texte
|
||||
```
|
||||
|
||||
### Modules
|
||||
#### cli.py — point d'entrée
|
||||
|
||||
#### [`classifier.py`](../src/logwatcher/classifier.py) — classification
|
||||
|
||||
* `N2_PATTERNS` : dictionnaire des motifs d'erreurs pertinents pour le N2, fournis par les techniciens.
|
||||
* `classify_log_entries()` : sépare les entrées en deux listes (relevant, irrelevant) et remplit entry.error_name pour les entrées pertinentes.
|
||||
|
||||
|
||||
#### [`cli.py`](../src/logwatcher/cli.py) — point d'entrée
|
||||
|
||||
* Définit `app = typer.Typer()` et la commande principale.
|
||||
* Valide les arguments (`--input-files` / `--input-dir` mutuellement exclusifs).
|
||||
* Orchestre le pipeline : parsing → classification → rapports.
|
||||
* Gère les erreurs utilisateur (`BadParameter`, code de sortie 2) et
|
||||
* les erreurs d'exécution (code de sortie 1).
|
||||
* Gère les erreurs utilisateur (`BadParameter`, code de sortie 2) et les erreurs d'exécution (code de sortie 1).
|
||||
* Expose `--version` (eager, affiche et quitte).
|
||||
|
||||
#### models.py — LogEntry
|
||||
|
||||
#### [`config.py`](../src/logwatcher/config.py) — constantes
|
||||
|
||||
* Chemins : `OUTPUT_PATH`, `RESULT_PATH`, `LOGGING_PATH`, `TEST_PATH`, `FIXTURE_PATH`
|
||||
* Date et fuseau : `DATETIME_FORMAT`, `FRENCH_TIMEZONE`
|
||||
* Types : `SourceType` (`FILE`, `MAIL`)
|
||||
|
||||
|
||||
#### [`logging_config.py`](../src/logwatcher/logging_config.py) — logging
|
||||
|
||||
* `setup_logging()` : configure le logger racine.
|
||||
* Handler console (`INFO`, ou `DEBUG` si verbose) + handler fichier.
|
||||
* Le fichier de log `logwatcher.log` est horodaté et écrit dans le dossier de sortie.
|
||||
* Les loggers verbeux des dépendances (exchangelib) sont ramenés au niveau WARNING, afin de ne pas polluer `logwatcher.log`.
|
||||
|
||||
|
||||
#### [`mail_reader.py`](../src/logwatcher/mail_reader.py) — lecture de la boîte mail
|
||||
|
||||
Accès à la boîte via EWS (exchangelib), en authentification NTLM.
|
||||
|
||||
* `connect_to_mailbox()` : lit `EMAIL`, `PASSWORD` et `EWS_URL` dans l'environnement, construit le compte et vérifie la connexion par un aller-retour serveur (accès à `account.protocol.version`).
|
||||
* `fetch_log_messages()` : retourne les mails du dossier Logs.
|
||||
* `extract_logs_from_mails()` : pour chaque mail, extrait les logs du corps ou de la pièce jointe `CR_*`, et les normalise en une liste de lignes. Ignore les lignes non conformes et avertit si le corps annonce une pièce jointe introuvable.
|
||||
* `move_analyzed_mails()` : déplace les mails traités vers le dossier `Analyzed`.
|
||||
|
||||
|
||||
#### [`mail_utils.py`](../src/logwatcher/mails_utils.py) — utilitaires boîte mail
|
||||
* `get_or_create_folder(account, folder_name)` retourne un dossier du compte, et le crée s'il n'existe pas. Utilisé pour les dossiers `Analyzed` et `Sent`.
|
||||
* Constantes : `LOG_DIR`, `ANALYZED_FOLDER`, `SENT_FOLDER`, `LOG_IN_ATTACHMENT_PATTERN`.
|
||||
|
||||
#### [`notifier.py`](../src/logwatcher/notifier.py) — envoi du rapport
|
||||
* `send_n2_report(account, summary, n2_log_file)` : construit un message Exchange avec `MAIL_TEMPLATE` comme corps, attache `n2_log_file`, et l'envoie aux destinataires de `N2_REPORT_RECIPIENTS`. Une copie du message envoyé est conservée dans `Logs/Sent` (copy_to_folder). L'envoi passe par les services Exchange (message.send) : aucun serveur SMTP externe n'est requis.
|
||||
|
||||
|
||||
#### [`models.py`](../src/logwatcher/models.py) — LogEntry
|
||||
|
||||
Dataclass immuable (par convention) représentant une ligne de log parsée.
|
||||
|
||||
@@ -65,41 +133,32 @@ Champs principaux :
|
||||
|
||||
LogEntry est créée uniquement par le parser. Le classifier l'enrichit
|
||||
(remplit `error_name`). Le modèle lui-même ne contient pas de logique métier.
|
||||
[`parser.py`]() — lecture et parsing
|
||||
|
||||
* `LOG_PATTERN` : expression régulière du format d'une ligne LAME MDC.
|
||||
* `parse_log_file()` : lit un fichier, retourne list[LogEntry].
|
||||
* Les lignes non conformes (système, en-têtes, corrompues) sont ignorées silencieusement.
|
||||
|
||||
#### classifier.py — classification
|
||||
#### [`parser.py`](../src/logwatcher/parser.py) — lecture et parsing
|
||||
|
||||
* N2_PATTERNS : dictionnaire des motifs d'erreurs pertinents pour le N2, fournis par les techniciens.
|
||||
* classify_log_entries() : sépare les entrées en deux listes (relevant, irrelevant) et remplit entry.error_name pour les entrées pertinentes.
|
||||
* Patterns réutilisables : `SERVER_IP_PATTERN`, `MDC_SERVER_NAME_PATTERN`, `DATE_TIME_PATTERN`, `STORE_NAME_PATTERN`, `ERROR_MESSAGE_PATTERN`.
|
||||
* `LOG_PATTERN` : expression régulière compilée du format d'une ligne LAME MDC.
|
||||
* `parse_line()` : parse une ligne, retourne `LogEntry | None`.
|
||||
* `parse_lines()` : parse un itérable de lignes, ignore les lignes non conformes.
|
||||
* `parse_file()` : lit un fichier (encodage windows-1252) et délègue à `parse_lines()`.
|
||||
|
||||
#### reporter.py — rapports
|
||||
|
||||
#### [`reporter.py`](../src/logwatcher/reporter.py) — rapports
|
||||
|
||||
* Templates texte (`string.Template`) : `BASE_TEMPLATE`, `N2_SUPPORT_TEMPLATE`, `OTHER_TEMPLATE`, `ERROR_TEMPLATE`.
|
||||
* `build_reports()` : construit les trois rapports (`dict n2, other, all`).
|
||||
* `write_log_report()` : écrit les rapports sur disque en Windows-1252.
|
||||
* `write_log_report()` : prend un SourceType (`FILE` ou `MAIL`) pour adapter le libellé de l'en-tête ("Fichier(s) lu(s)" ou "Mail(s) lu(s)"). Les fichiers générés s'appellent `all.log`, `n2.log` et `other.log`.
|
||||
* `_get_period()` : calcule les bornes min/max des error_time.
|
||||
|
||||
#### logging_config.py — logging
|
||||
|
||||
* `setup_logging()` : configure le logger racine.
|
||||
* Handler console (`INFO`, ou `DEBUG` si verbose) + handler fichier.
|
||||
* Le fichier de log `logwatcher.log` est horodaté et écrit dans le dossier de sortie.
|
||||
|
||||
#### config.py — constantes
|
||||
|
||||
* Chemins (`OUTPUT_PATH`, `FIXTURE_PATH` ...).
|
||||
* Formats de date (`DATETIME_FORMAT`).
|
||||
|
||||
## Dépendances
|
||||
|
||||
| Package | Rôle |
|
||||
|---------|------|
|
||||
| `typer` | Interface en ligne de commande |
|
||||
| `exchangelib` | Accès EWS à la boîte mail et envoi des rapports |
|
||||
| `mypy` | Typage statique (dev) |
|
||||
| `pytest` | Tests (dev) |
|
||||
| `pytest-cov` | Couverture (dev) |
|
||||
| `ruff` | Linting/formatage (dev) |
|
||||
| `mypy` | Typage statique (dev) |
|
||||
| `typer` | Interface en ligne de commande |
|
||||
Reference in New Issue
Block a user