iragi 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
iragi-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Yannick Magayane
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,14 @@
1
+ include README.md
2
+ include LICENSE
3
+ include pyproject.toml
4
+
5
+ recursive-include iragi *.py
6
+
7
+ # Exclude private, virtualenv and local files
8
+ global-exclude *.py[cod] __pycache__ *.so
9
+ prune .env
10
+ prune bin
11
+ prune docs
12
+ prune tests
13
+ prune dist
14
+ prune build
iragi-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,435 @@
1
+ Metadata-Version: 2.4
2
+ Name: iragi
3
+ Version: 0.1.0
4
+ Summary: Toolkit Python modulaire pour l'inspection de qualite de donnees et l'extraction documentaire.
5
+ Author-email: Yannick Magayane <yannickmagayaneyan@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Documentation, https://pypi.org/project/iragi/#description
8
+ Keywords: data-quality,pdf-extraction,profiling,analytics,data-cleaning
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Programming Language :: Python :: 3.14
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
17
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: pandas>=2.0.0
22
+ Requires-Dist: openpyxl>=3.1.0
23
+ Requires-Dist: typer>=0.9.0
24
+ Requires-Dist: rich>=13.0.0
25
+ Requires-Dist: jinja2>=3.1.0
26
+ Provides-Extra: pdf
27
+ Requires-Dist: pypdf>=4.0.0; extra == "pdf"
28
+ Requires-Dist: pdfplumber>=0.10.0; extra == "pdf"
29
+ Provides-Extra: ocr
30
+ Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
31
+ Requires-Dist: pillow>=10.0.0; extra == "ocr"
32
+ Provides-Extra: all
33
+ Requires-Dist: pypdf>=4.0.0; extra == "all"
34
+ Requires-Dist: pdfplumber>=0.10.0; extra == "all"
35
+ Requires-Dist: pytesseract>=0.3.10; extra == "all"
36
+ Requires-Dist: pillow>=10.0.0; extra == "all"
37
+ Provides-Extra: docs
38
+ Requires-Dist: sphinx>=8.0.0; extra == "docs"
39
+ Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "docs"
40
+ Requires-Dist: myst-parser>=4.0.0; extra == "docs"
41
+ Provides-Extra: test
42
+ Requires-Dist: pytest>=8.0.0; extra == "test"
43
+ Dynamic: license-file
44
+
45
+ # Iragi
46
+
47
+ <p align="center">
48
+ <strong>Inspecter. Extraire. Analyser.</strong><br>
49
+ <em>Toolkit Python modulaire pour l'inspection de qualité de données et l'extraction de documents.</em>
50
+ </p>
51
+
52
+ <p align="center">
53
+ <a href="#objectifs"><img src="https://img.shields.io/badge/Python-3.14%2B-blue.svg" alt="Python 3.14+"></a>
54
+ <a href="#installation"><img src="https://img.shields.io/badge/Version-0.1.0-green.svg" alt="Version 0.1.0"></a>
55
+ <a href="#licence"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="Licence MIT"></a>
56
+ <a href="#documentation"><img src="https://img.shields.io/badge/Docs-Sphinx-orange.svg" alt="Documentation Sphinx"></a>
57
+ <a href="#architecture-modulaire"><img src="https://img.shields.io/badge/Architecture-Modular-purple.svg" alt="Architecture modulaire"></a>
58
+ </p>
59
+
60
+ ---
61
+
62
+ **Iragi** est un package Python modulaire dédié à l'inspection, à l'extraction et à l'analyse de fichiers. Il réunit deux moteurs indépendants — **Scan** et **PDF** — et propose un troisième module, **All**, qui orchestre leur fonctionnement dans un pipeline unifié.
63
+
64
+ L'objectif est de fournir une bibliothèque réutilisable dans des scripts Python, des applications Django ou FastAPI, des outils Data et des workflows d'automatisation, tout en offrant une interface en ligne de commande (CLI) simple et puissante.
65
+
66
+ > **Principe de conception clé :** chaque moteur doit pouvoir être utilisé seul. Le module `iragi.all` coordonne les moteurs existants sans recopier leur logique métier.
67
+
68
+ ---
69
+
70
+ ## Sommaire
71
+
72
+ - [Objectifs](#objectifs)
73
+ - [Fonctionnalités](#fonctionnalités)
74
+ - [1. iragi.scan — Inspection et qualité](#1-iragiscan--inspection-et-qualité-des-fichiers)
75
+ - [2. iragi.pdf — Extraction de documents PDF](#2-iragipdf--extraction-de-documents-pdf)
76
+ - [3. iragi.all — Orchestration et pipeline](#3-iragiall--orchestration-des-moteurs)
77
+ - [Architecture modulaire](#architecture-modulaire)
78
+ - [Installation](#installation)
79
+ - [Utilisation en Python](#utilisation-en-python)
80
+ - [Inspection avec Scan](#inspection-dun-fichier-avec-scan)
81
+ - [Extraction PDF](#extraction-dun-pdf)
82
+ - [Pipeline unifié avec All](#analyse-combinée-avec-all)
83
+ - [Interface CLI](#interface-cli)
84
+ - [Rapports](#rapports)
85
+ - [Documentation Sphinx](#documentation-sphinx)
86
+ - [Architecture du projet](#architecture-du-projet)
87
+ - [Technologies](#technologies-envisagées)
88
+ - [Principes de conception](#principes-de-conception)
89
+ - [Feuille de route](#feuille-de-route)
90
+ - [Contribution](#contribution)
91
+ - [Licence](#licence)
92
+
93
+ ---
94
+
95
+ ## Objectifs
96
+
97
+ Iragi vise à simplifier trois opérations fréquentes dans les projets logiciels et Data :
98
+
99
+ 1. **Inspecter des fichiers** pour comprendre leur structure, leur contenu et leur qualité.
100
+ 2. **Extraire des informations de documents PDF**, notamment le texte, les tableaux et les métadonnées.
101
+ 3. **Enchaîner extraction et contrôle qualité** afin de produire un résultat exploitable et un rapport cohérent.
102
+
103
+ Iragi n'est pas conçu comme une application web autonome. C'est d'abord un **package Python**, avec une CLI intégrée. Il doit pouvoir être incorporé à d'autres applications sans imposer un framework particulier (Django, FastAPI, Flask, notebooks ou scripts autonomes).
104
+
105
+ ---
106
+
107
+ ## Fonctionnalités
108
+
109
+ ### 1. `iragi.scan` — Inspection et qualité des fichiers
110
+
111
+ Le moteur Scan analyse les fichiers structurés ou textuels afin d'en comprendre le contenu et de détecter les anomalies et problèmes courants de qualité.
112
+
113
+ **Formats ciblés :**
114
+ - **CSV** (séparateurs automatiques, encodages variés)
115
+ - **Excel** (`.xlsx`, `.xls` selon dépendances)
116
+ - **JSON** (objets, tableaux tabulaires, JSON Lines)
117
+ - **TXT** et logs techniques
118
+ - Autres formats tabulaires ajoutés progressivement
119
+
120
+ **Capacités principales :**
121
+ - **Détection de format** et lecture intelligente du fichier.
122
+ - **Inspection structurelle :** comptage des lignes, colonnes, feuilles et types de données.
123
+ - **Profilage des colonnes :** détection des types inférés, unicité, cardinalité.
124
+ - **Contrôle de complétude :** valeurs manquantes, vides ou nulles.
125
+ - **Détection des doublons :** lignes redondantes ou quasi-doublons.
126
+ - **Détection des types incohérents :** formats de dates invalides, anomalies numériques.
127
+ - **Repérage d'anomalies statistiques :** outliers via méthode IQR configurable.
128
+ - **Statistiques descriptives :** moyennes, médianes, min/max, percentiles.
129
+ - **Score indicatif de qualité :** score pondéré et explicable sur 100 avec détail des pénalités.
130
+ - **Recommandations exploitables :** conseils de nettoyage et d'assainissement ciblés.
131
+ - **Nettoyage explicite :** aucune mutation destructive du fichier source ; production de nouveaux artefacts nettoyés.
132
+
133
+ ### 2. `iragi.pdf` — Extraction de documents PDF
134
+
135
+ Le moteur PDF se concentre sur l'extraction, la structuration et la numérisation du contenu des documents PDF.
136
+
137
+ **Capacités principales :**
138
+ - **Extraction textuelle :** flux de texte structuré par page, paragraphe et bloc.
139
+ - **Extraction tabulaire :** extraction et conversion directe des grilles de données tabulaires vers des DataFrames / CSV.
140
+ - **Métadonnées :** titre, auteur, date de création, producteur, nombre de pages.
141
+ - **Traitement par lots (Batch) :** traitement efficace de répertoires de PDF entiers.
142
+ - **Détection des pages scannées :** identification automatique des pages nécessitant une reconnaissance optique.
143
+ - **OCR facultatif :** reconnaissance optique de caractères pour documents numérisés via Tesseract.
144
+ - **Exports multi-formats :** exports directs en JSON, CSV, Excel ou Markdown.
145
+
146
+ ### 3. `iragi.all` — Orchestration des moteurs
147
+
148
+ Le module All combine les moteurs Scan et PDF dans un pipeline unifié et cohérent.
149
+
150
+ **Workflow type :**
151
+ 1. Réception d'un document PDF (e.g. facture, relevé, rapport d'audit).
152
+ 2. Extraction du texte, des métadonnées et des tableaux via `iragi.pdf`.
153
+ 3. Structuration des données tabulaires extraites en objets intermédiaires.
154
+ 4. Transmission automatique de ces données au moteur `iragi.scan`.
155
+ 5. Audit de conformité et calcul du score de qualité des données extraites.
156
+ 6. Génération d'un rapport consolidé traçable (JSON, HTML ou console).
157
+
158
+ ---
159
+
160
+ ## Architecture modulaire
161
+
162
+ Les trois modules sont conçus pour être importés et exécutés en toute indépendance.
163
+
164
+ | Module | Responsabilité | Utilisation autonome | Dépendances spécifiques |
165
+ |---|---|---|---|
166
+ | `iragi.scan` | Inspection et qualité des fichiers | **Oui** | `pandas`, `openpyxl` |
167
+ | `iragi.pdf` | Extraction de texte, tables et OCR | **Oui** | `pypdf`, `pdfplumber`, `pytesseract` (opt) |
168
+ | `iragi.all` | Orchestration et pipeline combiné | **Oui** | scan + pdf |
169
+
170
+ Cette séparation offre des avantages concrets :
171
+ - Intégrer `iragi.scan` dans un projet Django existant sans installer les dépendances PDF lourdes.
172
+ - Employer `iragi.pdf` dans un simple script de conversion documentaire.
173
+ - Tirer parti de `iragi.all` pour bâtir des pipelines de données bout-en-bout.
174
+ - Tester et faire évoluer chaque moteur de manière isolée.
175
+
176
+ ---
177
+
178
+ ## Installation
179
+
180
+ Iragi propose une installation minimale ultra-légère complétée par des extras optionnels :
181
+
182
+ ```bash
183
+ # Installation minimale (moteur Scan seul)
184
+ pip install iragi
185
+
186
+ # Installation avec le moteur PDF
187
+ pip install "iragi[pdf]"
188
+
189
+ # Installation avec le support OCR pour documents scannés
190
+ pip install "iragi[ocr]"
191
+
192
+ # Installation complète (Scan + PDF + OCR + CLI complète)
193
+ pip install "iragi[all]"
194
+ ```
195
+
196
+ ---
197
+
198
+ ## Utilisation en Python
199
+
200
+ ### Inspection d'un fichier avec Scan
201
+
202
+ ```python
203
+ from iragi.core.models import DataInspectionResult
204
+ from iragi import scan
205
+
206
+ # Inspection d'un fichier tabulaire
207
+ result: DataInspectionResult = scan("clients.csv")
208
+
209
+ # Affichage des métriques clés
210
+ print(f"Lignes : {result.row_count}, Colonnes : {result.column_count}")
211
+ print(f"Score de qualité : {result.quality_score.total_score}/100")
212
+ print("Recommandations :", result.recommendations)
213
+
214
+ # Parcours des colonnes profilées
215
+ for col in result.column_profiles:
216
+ print(f"- {col.name} ({col.inferred_type}) : {col.missing_count} valeurs manquantes")
217
+ ```
218
+
219
+ ### Extraction d'un PDF
220
+
221
+ ```python
222
+ from iragi.pdf import extract, extract_tables
223
+
224
+ # Extraction du document et de ses métadonnées
225
+ document = extract("rapport_annuel.pdf")
226
+ print("Titre :", document.metadata.get("title"))
227
+ print("Pages :", len(document.pages))
228
+
229
+ # Extraction des tableaux sous forme tabulaire
230
+ tables = extract_tables("rapport_annuel.pdf")
231
+ for idx, table in enumerate(tables):
232
+ print(f"Tableau #{idx + 1} ({len(table.rows)} lignes)")
233
+ ```
234
+
235
+ ### Analyse combinée avec All
236
+
237
+ ```python
238
+ from iragi import analyze
239
+
240
+ # Pipeline unifié extraction + audit de qualité
241
+ result = analyze("factures_q3.pdf")
242
+
243
+ print("Score de qualité global :", result.quality_report.quality_score.total_score)
244
+ print("Données tabulaires extraites :", len(result.extracted_data.tables))
245
+ print("Anomalies détectées :", result.quality_report.potential_outliers_count)
246
+ ```
247
+
248
+ ---
249
+
250
+ ## Interface CLI
251
+
252
+ Iragi dispose d'une interface en ligne de commande moderne et intuitive construite avec `typer` et mise en forme avec `rich`.
253
+
254
+ ```bash
255
+ # Inspection de fichiers tabulaires
256
+ iragi scan data.csv
257
+ iragi scan data.xlsx --sheet "Ventes"
258
+ iragi scan data.json --output report.json
259
+
260
+ # Extraction PDF
261
+ iragi pdf text document.pdf
262
+ iragi pdf tables document.pdf --format csv --output ./tables/
263
+ iragi pdf metadata document.pdf
264
+
265
+ # Pipeline complet
266
+ iragi all document.pdf
267
+ iragi all document.pdf --report html --output ./reports/audit.html
268
+ ```
269
+
270
+ ---
271
+
272
+ ## Rapports
273
+
274
+ Iragi permet d'exporter les résultats dans différents formats pour convenir à tous les usages :
275
+
276
+ - **JSON :** Structure complète sérialisable pour pipelines CI/CD, APIs REST ou Django/FastAPI.
277
+ - **HTML :** Rapports interactifs lisibles dans un navigateur, avec graphiques et tableaux clairs.
278
+ - **CSV / Excel :** Export direct des données extraites ou nettoyées.
279
+
280
+ Chaque rapport garantit une traçabilité rigoureuse : empreinte du fichier source, date et heure d'analyse, paramètres de configuration appliqués et détail des pénalités du score de qualité.
281
+
282
+ ---
283
+
284
+ ## Documentation Sphinx
285
+
286
+ La documentation technique est générée automatiquement à partir des docstrings au format Sphinx.
287
+
288
+ ### Génération locale
289
+
290
+ Pour générer la documentation HTML du projet :
291
+
292
+ ```bash
293
+ # Génération standard
294
+ bin/docs
295
+
296
+ # Nettoyage et régénération complète
297
+ bin/docs --clean -E -a
298
+ ```
299
+
300
+ La documentation compilée est générée dans `docs/build/html/index.html`.
301
+
302
+ ---
303
+
304
+ ## Architecture du projet
305
+
306
+ ```text
307
+ iragi/
308
+ ├── bin/
309
+ │ ├── _common.sh # Configuration commune de l'environnement
310
+ │ └── docs # Script de génération de la documentation Sphinx
311
+ ├── docs/
312
+ │ ├── source/
313
+ │ │ ├── conf.py # Configuration Sphinx & extensions
314
+ │ │ ├── index.rst # Point d'entrée de la documentation
315
+ │ │ └── api/ # Documentation automatique des modules
316
+ │ └── build/ # Documentation HTML compilée
317
+ ├── iragi/
318
+ │ ├── __init__.py # Point d'entrée du package
319
+ │ ├── core/ # Modèles de données, configuration et exceptions
320
+ │ │ ├── __init__.py
321
+ │ │ ├── config.py
322
+ │ │ ├── exceptions.py
323
+ │ │ └── models.py
324
+ │ ├── scan/ # Moteur d'inspection et de qualité
325
+ │ │ ├── __init__.py
326
+ │ │ ├── engine.py
327
+ │ │ └── profiler.py
328
+ │ ├── pdf/ # Moteur d'extraction PDF
329
+ │ │ ├── __init__.py
330
+ │ │ ├── extractor.py
331
+ │ │ └── tables.py
332
+ │ ├── all/ # Orchestration du pipeline
333
+ │ │ ├── __init__.py
334
+ │ │ └── pipeline.py
335
+ │ ├── reports/ # Générateurs de rapports (HTML, JSON)
336
+ │ └── cli/ # Commandes CLI Typer
337
+ ├── tests/ # Tests unitaires et d'intégration
338
+ ├── examples/ # Exemples d'utilisation
339
+ ├── pyproject.toml # Métadonnées et dépendances du projet
340
+ └── README.md
341
+ ```
342
+
343
+ ---
344
+
345
+ ## Technologies envisagées
346
+
347
+ | Composant | Outils / Bibliothèques |
348
+ |---|---|
349
+ | **Langage** | Python 3.14+ |
350
+ | **Analyse tabulaire** | Pandas, NumPy |
351
+ | **Fichiers Excel** | OpenPyXL |
352
+ | **Extraction PDF** | PyMuPDF, pdfplumber |
353
+ | **OCR** | Tesseract & pytesseract *(optionnel)* |
354
+ | **CLI & Terminal** | Typer, Rich |
355
+ | **Rapports** | Jinja2 |
356
+ | **Documentation** | Sphinx, sphinx-rtd-theme, myst-parser, sphinxcontrib-django |
357
+ | **Tests** | pytest |
358
+
359
+ ---
360
+
361
+ ## Principes de conception
362
+
363
+ 1. **Modularité stricte :** Scan, PDF et All ont des responsabilités distinctes et des cycles de vie indépendants.
364
+ 2. **Priorité à l'API Python :** La CLI n'est qu'un client léger consommant les modules Python publics.
365
+ 3. **Indépendance vis-à-vis des frameworks :** Utilisable nativement dans un script, Django, FastAPI ou Jupyter.
366
+ 4. **Immuabilité des données sources :** Aucune modification destructive par défaut.
367
+ 5. **Score explicable et traçable :** Tout score de qualité expose la formule et les pénalités appliquées.
368
+ 6. **Gestion explicite des erreurs :** Aucune exception masquée silencieusement.
369
+ 7. **Dépendances optionnelles :** Un utilisateur de `iragi.scan` ne télécharge pas les dépendances de rendu PDF ou OCR.
370
+ 8. **Documentation exhaustive :** Chaque fonction, classe et module est documenté selon le standard Sphinx avec exemples.
371
+
372
+ ---
373
+
374
+ ## Feuille de route
375
+
376
+ ### Phase 1 — Fondations
377
+ - [x] Initialiser le dépôt et `pyproject.toml`.
378
+ - [x] Définir les exceptions et les objets de résultat communs (`iragi.core`).
379
+ - [x] Mettre en place les tests unitaires et l'intégration continue (`.github/workflows/ci.yml`).
380
+ - [x] Configurer la génération de documentation Sphinx (`bin/docs`).
381
+ - [ ] Créer une première CLI de base.
382
+
383
+ ### Phase 2 — Moteur Scan
384
+ - [x] Lire les fichiers CSV.
385
+ - [x] Lire les fichiers Excel.
386
+ - [x] Lire les fichiers JSON.
387
+ - [x] Ajouter le profilage des colonnes.
388
+ - [x] Détecter les valeurs manquantes et les doublons.
389
+ - [x] Ajouter les validations de types et de formats.
390
+ - [x] Produire un premier rapport JSON.
391
+
392
+ ### Phase 3 — Moteur PDF
393
+ - [ ] Extraire le texte avec PyMuPDF.
394
+ - [ ] Lire les métadonnées.
395
+ - [ ] Extraire les tableaux avec pdfplumber.
396
+ - [ ] Ajouter la détection des PDF nécessitant un OCR.
397
+ - [ ] Ajouter l'OCR comme dépendance optionnelle.
398
+ - [ ] Ajouter les exports structurés.
399
+
400
+ ### Phase 4 — Orchestration All
401
+ - [ ] Définir le pipeline commun.
402
+ - [ ] Connecter les résultats du moteur PDF au moteur Scan.
403
+ - [ ] Produire un rapport global.
404
+ - [ ] Ajouter le traitement par lots.
405
+
406
+ ### Phase 5 — Stabilisation et publication
407
+ - [x] Vérifier la disponibilité du nom `iragi` sur PyPI (disponible).
408
+ - [ ] Compléter les tests unitaires et d'intégration.
409
+ - [ ] Documenter les API publiques au fur et à mesure.
410
+ - [ ] Ajouter des exemples d'intégration Django et FastAPI.
411
+ - [ ] Vérifier les dépendances et les métadonnées du package.
412
+ - [ ] Publier la version v0.1.0 sur PyPI.
413
+
414
+ ---
415
+
416
+ ## Contribution
417
+
418
+ Les contributions sont les bienvenues ! Pour proposer une fonctionnalité ou un correctif :
419
+
420
+ 1. Ouvrez une issue pour échanger sur la conception et l'intérêt de la modification.
421
+ 2. Respectez l'isolation stricte entre moteurs et les conventions de docstrings Sphinx.
422
+ 3. Ajoutez les tests correspondants sous `tests/`.
423
+ 4. Vérifiez que la documentation se génère sans avertissement (`bin/docs`).
424
+
425
+ ---
426
+
427
+ ## Licence
428
+
429
+ Ce projet est distribué sous licence [MIT](LICENSE).
430
+
431
+ ---
432
+
433
+ <p align="center">
434
+ <strong>Iragi — Inspecter. Extraire. Analyser.</strong>
435
+ </p>