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` :

#. `pipelines.py` charge les `catalog.yml` et va chercher `nodes.py`

#. `nodes.py` va chercher `actesdataset.py`

#. `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()`.

 .. code-block:: 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 `<div>` du `<body>` 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 (`<div>` du `<body>` 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 `<div>` 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.
