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
type	type of the variable	string, int, float, bool, path, relativepath
unit	Unit of the variable	pint format (exemple: m, km2, K-1)
unit	Unit of the variable	pint format (exemple: m, km2, K-1)
separator	Separator of variables
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 :

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

param = ParametersFromXml()
param.set_param_xml('example', 'value_A')
param.write('test.xml')

Le fichier xml ainsi créé sera le suivant :

<Lidar>
        <example>value_A</example>
</Lidar>

De base, le premier attribut du fichier xml est “Lidar”, mais il peut facilement être changé en utilisant l’input name_of_init_element :

param = ParametersFromXml()
param.set_param_xml('example', 'value_A', name_of_init_element='dalek')
param.write('test.xml')

Alors, le fichier ainsi créé sera :

<dalek>
        <example>value_A</example>
</dalek>

Si on veut écrire une variable dans des sous-élements du fichier xml, il suffit d’utiliser la lettre “/” comme séparateur. Exemple :

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 :

<Lidar>
        <example>
                <sub_exemple_1>value_A</sub_exemple_1>
                <sub_exemple_2>value_B</sub_exemple_2>
        </example>
        <dalek>blue
                <red>True</red>
        </dalek>
</Lidar>

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.

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 :

<Lidar>
        <example type="float">3.25</example>
</Lidar>

Ajouter un objet pint

Un objet pint est un objet qui a une valeur et une unité. On utilise pour cela la librairie Pint :

import pint

La fonction suivante va sauvegarder la valeur de 6.78 GHz.

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

<Lidar>
        <example type="float" unit="gigahertz">6.78</example>
</Lidar>

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 :

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 :

<Lidar>
        <variable unit="km" other_attribute="class" type="float">3.25</variable>
</Lidar>

Lire une variable

Pour lire une variable, on va utiliser

Classe ParametersFromXml

class SignalCreation.Utils.ToolsParametersXml.ParametersFromXml(parameter_filename=None, use_reference_parameter=False, parameter_filename_ref=None)

Parameters:

parameter_filename (str | Element | None)
use_reference_parameter (bool)
parameter_filename_ref (Element | str | None)

clean_variables(tag_to_clean, level_tag=None, recursive=False)

Clean all the parameters where the tag is “tag_name_to_clean”, with a begining to the element “main_tag”

Parameters:

tag_to_clean (str or None) – name of the tag where the text will be remove (default: filename)
level_tag (str or None) – level to begining the search (default: None => begin to the root)
recursive (bool) – True if the search is recursive within the various sub-elements (default: False)

exist(tag)

Search if the element exist (the variable can be empty)

Parameters:: tag (str) – tag to search
Returns:: true is the element exist, False else

get_element_attrs_from_xml(keys, attrs_name_to_find=None)

Get attribute of element from parameters

Parameters:

keys – key of the parameter
attrs_name_to_find (str | list | None) – get only the attributes listed here

Returns:

a dictionary contained the attribute of the element

Return type:

dict | None

get_filename_from_path(xml_element_name, super_xml_element_name=None, tag_dt='Read/date_to_process/date', dt=None, tag_hours='Read/date_to_process/hours', tag_acquisition_time='Read/date_to_process/acquisition_time')

Return the filename from parameters in xml file and in function of the date.

Parameters:

xml_element_name (str) – Name of the element repertory in the xml file
super_xml_element_name (: str or None) – String, super element, which can replace information in xml_element_name
tag_dt (str) – tag where data is saved (default: “Read/date_to_process/date”)
dt (str or date or datetime or None) – date to use for the filename (if necessary) (default: None)
tag_hours (str) – tag where hours is saved (default: “Read/date_to_process/hours”)
tag_acquisition_time (str) – tag where acquisition time is saved (default: “Read/date_to_process/acquisition_time”)

Returns:

String, name of the filename

Return type:

str or list or None

get_list_options(key, attrs_name_to_find='options')

Get the possibles options for an option in the xml parameter file. If no options, read the value of the parameter, and create the list of possible options

Parameters:

key (str) – key of the value in the xml file
attrs_name_to_find (str) – attribute name to search (default: options)

Returns:

the list of options

Return type:

list or None

get_param(keys, value_separator=',', clean=True, num_output=-1, value_unit=None, value_type='str', cond_keys=None, cond_value=None, default_value=None, default_attrs=None)

Get parameter from XML file with optional conditional filtering and default value insertion.

Parameters:

keys (str) – tag of the variable in the XML root file
value_separator (str | None) – separator for lists (default: ‘,’)
clean (bool) – clean string values (default: True)
num_output (int | None) – index of the value to return (default: -1 for auto)
value_unit (str | None) – unit of the value (optional)
value_type (str) – type of the value (default: ‘str’)
cond_keys (str | None) – conditional key for filtering (optional)
cond_value (str | int | float | bool | None) – value to match for conditional filtering (optional)
default_value (str | float | int | list | ndarray | Quantity | None) – default value if parameter not found (optional)
default_attrs (dict | None) – default attributes to set if parameter not found (optional)

Returns:

extracted value(s)

Return type:

list | str | None

get_param_xml(keys, value_separator=',', clean=True, num_output=-1, value_unit=None, value_type='str')

Get parameter value from XML file

Parameters:

keys (str) – tag of the variable in the xml root file
value_separator (str or None) – separator in case of list of value (default: None)
clean (bool) – apply of clean function of the variable (remove space and invalid characters) (default: True)
num_output (int or None) – index of the variable to return, None return all the list (default: 0)
value_unit (str or None) – unit of the value if not in the attribute of the parameter (default: )
value_type (str) – type of the value if not in the attribute of the parameter (default: str)

Returns:

A dictionary with the parameter and the attribute.

Return type:

list or str or None

get_param_xml_to_dict(keys, value_separator=',', clean=True, num_output=-1, value_unit=None, value_type='str')

List the variables in a xml element and return a dictionary with tag and values

Parameters:

keys (str) – tag of the variable in the xml root file
value_separator (str or None) – separator in case of list of value (default: None)
clean (bool) – apply of clean function of the variable (remove space and invalid characters) (default: False)
num_output (int | None)
value_unit (str | None)
value_type (str)

Return type:

dict

:type clean; bool :param num_output: index of the variable to return, None return all the list (default: 0) :type num_output: int or None :param value_unit: unit of the value if not in the attribute of the parameter (default: ) :type value_unit: str or None :param value_type: type of the value if not in the attribute of the parameter (default: str) :type value_type: str

Returns:

return dictionary with parameters of the xml

Return type:

dict

Parameters:

keys (str)
value_separator (str | None)
clean (bool)
num_output (int | None)
value_unit (str | None)
value_type (str)

get_param_xml_with_default_param(keys, value_separator=',', clean=True, num_output=-1, value_unit=None, value_type='str', default_value=None, default_attrs=None)

Get the value of a xml parameters file, and insert default data when there is no data

Parameters:

keys (str) – key of the parameter
value_separator (str | None) – separator if more than one term (default: ,)
clean (bool) – apply of clean function of the variable (remove space and invalid characters) (default: False)
num_output (int | None) – index of the variable to return, None return all the list (default: 0)
value_unit (str | None) – unit of the value if not in the attribute of the parameter (default: )
value_type (str) – type of the value if not in the attribute of the parameter (default: str)
default_value (str | float | int | list | ndarray | Quantity | None) – default value if get value is None (default: None)
default_attrs (dict | None) – default attributes if get value is None (default: None)

read_filename_from_path(xml_element_name, super_xml_element_name=None)

Read the filename from parameters in xml file and in function of the date, check if file(s) exists, and insert filename(s) into the xml file.

Parameters:

xml_element_name (str) – Name of the element repertory in the xml file
super_xml_element_name (: str | None) – String, super element, which can replace information in xml_element_name

Returns:

String, name of the filename

Return type:

str | list | None

read_xml_file(parameter_filename, ref=False)

Read the parameters file in XML format

Parameters:

parameter_filename (str) – full pathname of the parameters file
ref (bool) – False if there is not the reference parameter, else True

remove_with_condition(cond_keys, conds_to_remove)

Remove data where there is a condition :param cond_keys: :param cond_to_remove: :return:

Parameters:

cond_keys (str)
conds_to_remove (list | str | int | float | bool)

set_param_xml(keys, value=None, attrs=None, separator=',', name_of_init_element='Lidar', num_output=None)

Set parameters into the xml root

Parameters:

keys (str) – key of the parameter
value (str | float | int | list | bool | ndarray | Quantity | date | None) – value of the parameter
attrs (dict | None) – attributes to the parameter (default: None)
separator (str | None) – separator if more than one term (default: ,)
name_of_init_element (str) – name of the initial element, if creation of the parameter (default: Lidar)
num_output (int | None) – index of the variable to return, None return all the list (default: 0)

write(filename_out)

Write the parameter file into xml format

Parameters:: filename_out (str) – name of the filename
Returns: