ToolsParametersXml librairy
===========================
Généralités
-----------
Cette librairie permet de stocker des données dans le même format qu'un fichier XML, ce qui permet de lire et d'écrire facilement dans ce type de format. De plus, le format est optimisé pour des variables autre que des chaines de caractère, et en particulier les nombres avec unités.
Lorsqu'une donnée sera sauvegardé, son type sera également sauvegardé, en tant qu'attribut au paramètre xml. Si un objet `pint` est enregistré, son unité sera également sauvegardé en tant qu'attribut. Lors de la récupération de la donnée, on récupérera la varaible en fonction de son type.
Certains attributs sont parfaitement codifiés :
+------------------+------------------------+----------------------------------------------+
| Attributes names | Description | Possibility |
+==================+========================+==============================================+
+ type | type of the variable | string, int, float, bool, path, relativepath |
+------------------+------------------------+----------------------------------------------+
+ unit + Unit of the variable + pint format (exemple: m, km**2, K**-1) +
+------------------+------------------------+----------------------------------------------+
+ separator + Separator of variables + +
+------------------+------------------------+----------------------------------------------+
Cette librairie contient 1 classe et 2 fonctions :
* classe `ParametersFromXml`: classe principale, qui permet de lire et d'écrire dans un fichier xml
* la fonction `to_bool` : elle permet de transformer une chaine de caractère en booléun
* la fonction `xml_deep_copy` : permet de copier un objet de la classe `ParametersFromXml`
La classe ParametersFromXml
----------------------------
Cette classe contient 3 attributs :
* `_parameter_filename`: nom du fichier paramètre
* `_xml_root`: ET root, objet de base où sont stockées toutes les données du fichier xml
* `_xml_tree`: ET tree, permettant de créer un nouveau fichier xml
L'appel de cette fonction peut se faire de 3 façons différentes :
* Sans input: les 3 attributs seront alors vide, et les fonctions de lecture ne seront pas disponibles
* avec un nom de fichier xml à lire : à la création de l'objet, le fichier xml est lu et les données disponibles dans l'attribut `_xml_root`
* avec un objet de type `ET.Element`: une nouvelle classe est créée à partir de d'élement ET
L'import de cette classe se fait de la façon suivante :
.. code-block:: python
from SignalCreation.Utils.ToolsParametersXml import ParametersFromXml
Ajouter une variable
--------------------
Ajouter une chaine de caractère
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pour ajouter une variable, on utilise la fonction set_param_xml. Cette commande nécessite deux entrées : une clé et une valeur. La clé représente le chemin d'accès dans le fichier XML, et la valeur correspond à la variable qu'on va ajouter.
Exemple de création d'une variable chaine de caractère et de la création du fichier xml associé :
.. code-block:: python
param = ParametersFromXml()
param.set_param_xml('example', 'value_A')
param.write('test.xml')
Le fichier xml ainsi créé sera le suivant :
.. code-block:: xml
value_A
De base, le premier attribut du fichier xml est "Lidar", mais il peut facilement être changé en utilisant l'input `name_of_init_element` :
.. code-block:: python
param = ParametersFromXml()
param.set_param_xml('example', 'value_A', name_of_init_element='dalek')
param.write('test.xml')
Alors, le fichier ainsi créé sera :
.. code-block:: xml
value_A
Si on veut écrire une variable dans des sous-élements du fichier xml, il suffit d'utiliser la lettre "/" comme séparateur. Exemple :
.. code-block:: python
param = ParametersFromXml()
param.set_param_xml('example/sub_exemple_1', 'value_A')
param.set_param_xml('example/sub_exemple_2', 'value_B')
param.set_param_xml('dalek', 'blue')
param.set_param_xml('dalek/red', 'True')
param.write('test.xml')
Le fichier ainsi créé aura la forme suivante :
.. code-block:: xml
value_A
value_B
blue
True
Ajouter une variable numérique
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Cette fois ci, avec ajoutant une variable au format float, l'attribut de la variable sera écrit automatiquement dans le fichier xml.
.. code-block:: python
param = ParametersFromXml()
param.set_param_xml('example', 3.25)
param.write('test.xml')
Alors, dans le fichier créé, on verra apparaitre le type de la variable :
.. code-block:: xml
3.25
Ajouter un objet pint
^^^^^^^^^^^^^^^^^^^^^
Un objet pint est un objet qui a une valeur et une unité. On utilise pour cela la librairie Pint :
.. code-block:: python
import pint
La fonction suivante va sauvegarder la valeur de 6.78 GHz.
.. code-block:: python
unit_registry = pint.UnitRegistry()
param = ParametersFromXml()
param.set_param_xml('example', 6.78 * unit_registry('GHz'))
param.write('test.xml')
Alors, dans le fichier créé, on verra apparaitre le type de la variable et son unité :
.. code-block:: xml
6.78
Ajouter une variable avec des attributs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On peut ajouter des attributs à chaque variable qu'on ajoute, en utilisant l'entrée 'attrs' de la fonction. Cette entrée nécessite un dictionnaire. On peut ajouter un attribut utilisé par la classe (exemple : type, ou unité), mais également utiliser n'importe quel nom d'attribut. Exemple :
.. code-block:: python
param = ParametersFromXml()
param.set_param_xml('variable', 3.25, attrs={'unit':'km', 'other_attribute': 'class'})
param.write('test.xml')
Le fichier xml ainsi créé sera de la forme :
.. code-block:: xml
3.25
Lire une variable
-----------------
Pour lire une variable, on va utiliser
Classe ParametersFromXml
------------------------
.. autoclass:: SignalCreation.Utils.ToolsParametersXml.ParametersFromXml
:members: