documentation/source/pipeline_actes_princiers.rst

Le 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.
reorganisation de la documentation 3 years ago			`Le pipeline kedro des actes princiers`
first revision 3 years ago			`=====================================`

			`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).`
typo rst 3 years ago			- elles se trouvent dans `/actes-princiers/data/01_raw/`.
first revision 3 years ago			`- de type intermédiaire (intermediate) = ce sont les données créées après le traitement des données brutes.`
typo rst 3 years ago			- elles se trouvent dans `actes-princiers/data/02_intermediate/`.
first revision 3 years ago
			`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`.
typo rst 3 years ago			- La fonction appelée depuis `nodes.py` est `parse_xml_collection()`.
first revision 3 years ago			- `parse_json_collection`, qui correspond au traitement sur le datacatalog `bourbon_json` vers le datacatlog `bourbon_jsonoutput`
typo rst 3 years ago			- La fonction appelée depuis `nodes.py` est `parse_json_collection()`.
first revision 3 years ago
			`.. 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`
typo rst 3 years ago			`------------`
first revision 3 years ago
			- 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.`

typo rst 3 years ago			- `make_json_collection` =
first revision 3 years ago			`- 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.