diff --git a/actes-princiers/docs/source/pipeline_actes_princiers.rst b/actes-princiers/docs/source/pipeline_actes_princiers.rst new file mode 100644 index 0000000..4735a2e --- /dev/null +++ b/actes-princiers/docs/source/pipeline_actes_princiers.rst @@ -0,0 +1,100 @@ +La pipeline kedro des actes princiers +===================================== + +L'oritentation data science du projet a pour but principal de séparer en plusieurs étapes les différentes problématiques du traitement des données. + +La commande `kedro run` permet de lancer la pipeline, c'est-à-dire le script `pipelines.py` : +1. `pipelines.py` charge les `catalog.yml` et va chercher `nodes.py` +2. `nodes.py` va chercher `actesdataset.py` +3. `actesdataset.py` réalise les traitements de données. + +La pipeline du projet *Actes princiers* possède deux points d'entrée : +- Le premier charge les XML sources avec `xml.etree.ElementTree` de la librairie `lxml` et permet de générer un dictionnaire. +- Le deuxième charge les XML source avec la librairie `BeautifulSoup` et permet de générer un JSON. + +`catalog.yml` +------------- + +- Dans `/actes-princiers/conf/base/` + +- Ce fichier définit des catalogues de données (*data catalog*) : + - de type brut (*raw*) : ce sont les données d'origine qui sont immuables et en lecture seule (les XML et les CSV). + - elles se trouvent dans `/actes-princiers/data/01_raw/`. + - de type intermédiaire (*intermediate*) = ce sont les données créées après le traitement des données brutes. + - elles se trouvent dans `actes-princiers/data/02_intermediate/`. + +`pipeline.py` +------------- + +- Dans `actes-princiers/src/actes_princiers/pipelines/xml_processing/pipeline.py`. + +- Ce code commence par importer les fonctions du fichier `nodes.py`. Les `nodes` kedro sont des blocs de la pipeline qui prennent en paramètre des dataset (les XML), font des traitements et renvoient des outputs (un dictionnaire ou un JSON). + +- Il y a deux nodes, qui correspondent à chaque point d'entrée : + - `parse_xml_collection`, qui correspond au traitement sur le datacatalog `bourbon` vers le datacatlog `bourbon_xmlcontent`. + - La fonction appelée depuis `nodes.py` est `parse_xml_collection()`. + - `parse_json_collection`, qui correspond au traitement sur le datacatalog `bourbon_json` vers le datacatlog `bourbon_jsonoutput` + - La fonction appelée depuis `nodes.py` est `parse_json_collection()`. + +```py +def create_pipeline(**kwargs) -> Pipeline: + return pipeline( + [ + node( + func=parse_xml_collection, + inputs="bourbon", + outputs="bourbon_xmlcontent", + name="bourbon_ds_collection", + ), + node( + func=parse_json_collection, + inputs="bourbon_json", + outputs="bourbon_jsonoutput", + name="bourbon_json_ds_collection", + ), +``` + +`nodes.py` +-------- + +- Dans `actes-princiers/src/actes_princiers/pipelines/xml_processing/nodes.py`. + +- Ce fichier contient les fonctions qui permettent de traiter les données. Il est appelé dans `pipeline.py`. + +- `parse_xml_collection` lit les dataset (= les XML) avec la librairie lxml. + - elle commence par lister les fichiers XML d'un dossier donné (correspondant à une maison princière). + - les xml sont parsés avec lxml. + - la `
` du `` est récupérée grâce à la fonction `_xslt` de `actes-princiers/src/actesdataset.py`. + - le résultat est stocké dans un fichier avec l'extension `.pseudoxml` car il ne s'agit pas d'un fichier XML bien formé. Le but est d'envoyer ces "bouts" de XML dans un JSON. + - la fonction retourne un dictionnaire où le nom du fichier est la clef et le pseudoxml la valeur. + +- `make_json_collection` = + - elle commence par lister les fichiers XML d'un dossier donné (correspondant à une maison princière) + - ces fichiers sont parsés avec BeautifulSoup. + - BeautifulSoup recherche les metadonnées dans le XML + - Un dictionnaire est créé avec en clef le nom du fichier et en valeur les métadonnées récupérées par BeautifulSoup. + - quand c'est sérialisé (enregister dans le disque dur) c'est en json + + +`actesdataset.py` +----------------- + +- Dans `actes-princiers/src/actesdataset.py` + +- Il s'agit du fichier maître de la pipeline, où sont définies dans classes qui sont ensuite instanciées dans le `node.py`. + +les représentations des dataset, qui va chercher les fonctions précédentes + +- `_xslt(xsltstylesheet)` : va chercher la partie du XML (`
` du `` qui nous intéresse) + +- `class XMLDataSet` : classe abstraite qui n'est jamais instanciée = classe mère en héritage dans la classe suivante. + +- `class EtreeXMLDataSet` : va chercher les `
` contenant les actes et fait un dictionnaire, avec la fonction `parse_xml_collection` dans `nodes.py` + +- `class BsXMLDataSet` : va chercher les métadonnées des actes et les met dans un dictionnaire qui est ensuite transformé en json. + +- `class DataSetCollection` : collection abstraite de dataset. + +- `class XMLDataSetCollection` : construit un dictionnaire (= data set container) dans un attribut dataset qui liste les fichiers xml. + +- `class JSONDataSetCollection` : construit un dictionnaire (= data set container) dans un attribut dataset qui liste les fichiers xml. \ No newline at end of file