Lecture et écriture de la configuration depuis un fichier INI

[laurent-laporte-pro]

Rappel du contexte

Glossaire

Voici un glossaire des termes couramment utilisés dans cette documentation :

• Attribut : attribut d'une classe, pour un modèle Pydantic, on utilise aussi le mot "champ".
• Champ : attribut d'un modèle Pydantic de type Field.
• Classe FieldInfo : Classe qui contient des informations supplémentaires sur chaque champ, telles que le chemin relatif au fichier INI, la valeur par défaut, la version de l'étude, etc. Cette classe est dépréciée.
• Classe de base FormFieldsBaseModel : Classe personnalisée qui hérite de la classe de base BaseModel de Pydantic et qui est utilisée pour gérer les champs d'un formulaire.
• Commande UpdateConfig : Commande utilisée pour spécifier les modifications apportées à l'étude.
• Conversion de données : Processus de conversion d'une donnée d'un type à un autre, par exemple, convertir une chaîne de caractères en un type énuméré.
• Exception TypeError : Exception qui est levée lorsqu'un type de donnée est incompatible.
• Exception ValueError : Exception qui est levée lorsque la valeur d'une donnée est invalide.
• Fichiers INI : Fichiers de configuration utilisés pour stocker des paramètres de l'étude.
• Mapping : Association entre les noms des attributs du modèle Pydantic et les noms des paramètres dans le fichier INI.
• Modèles Pydantic : Classes Python utilisées pour définir et valider la structure des données. Cette classe hérite (directement ou indirectement) de la classe BaseModel de Pydantic.
• Paramètre : paramètre de type "clef = valeur" issu soit d'un JSON, soit d'un fichier INI.
• Propriété : propriété d'un champ : paramètre de la classe Field, tel que le type, la description, les contraintes et les propriétés supplémentaires (user defined), ce terme est aussi utilisé pour décrire les propriétés de la configuration d'un modèle Pydantic (attributs de la classe Config).
• Propriété extra = Extra.forbid : Propriété utilisée dans la configuration du modèle Pydantic pour interdire l'utilisation de paramètres inconnus.
• Propriété ini_path : Propriété utilisée lors de la description des champs du modèle Pydantic avec la classe Field pour associer les noms des attributs aux noms des paramètres dans le fichier INI.
• Propriétés start_version et end_version : Propriétés utilisées lors de la description des champs du modèle Pydantic avec la classe Field pour spécifier la version de l'étude à partir de laquelle un attribut a été introduit et la dernière version où il existe encore.
• Validation des données : Processus de vérification et de validation des données entrées pour s'assurer qu'elles sont correctes et conformes aux contraintes spécifiées.
• Version : version de l'étude en cours (ou selon le contexte, version d'une application). La version d'une étude est un nombre entier, par exemple 860 (pour v8.6).

Présentation

La spécification fonctionnelle suivante résume les cas d'utilisation liés à la gestion de la configuration d'une étude à l'aide de fichiers INI et aux modèles Pydantic :

Lors de la gestion de la configuration d'une étude, il est courant d'utiliser des fichiers INI. Cela s'applique notamment aux clusters thermiques et renouvelables, et sera également le cas pour les stockages à court terme introduits dans la version v8.6 d'Antares Solver. Les données contenues dans ces fichiers INI évoluent en fonction des versions, avec l'ajout de certains paramètres et la suppression d'autres. Cette évolution est typiquement observée dans le fichier generaldata.ini.

Dans notre application web, nous utilisons des modèles Pydantic pour gérer ces paramètres. Les modèles Pydantic permettent de spécifier les noms des paramètres, leurs types et les contraintes sur les valeurs. Pour cela, nous utilisons la classe de base FormFieldsBaseModel, qui est configurée pour convertir automatiquement les noms des champs au format "camelCase" pour TypeScript en utilisant des alias.

Dans la version actuelle d'Antares Web, nous utilisons une table d'association pour fournir des informations supplémentaires sur chaque champ. Cette implémentation repose sur la classe FieldInfo, qui contient les champs suivants :

• path: un chemin relatif au fichier INI, indiquant la section et le nom du paramètre dans ce fichier. Ce chemin est relatif à la racine de l'étude lorsqu'elle est stockée sur disque, et il utilise la notation Posix.
• default_value: la valeur par défaut du paramètre.
• start_version: la version de l'étude à partir de laquelle ce paramètre a été introduit (facultatif).
• end_version: la dernière version de l'étude où le paramètre existe encore (facultatif).

Nous souhaitons améliorer la spécification des attributs des modèles Pydantic en utilisant la classe Field de Pydantic. Cette évolution nous permettra d'intégrer les attributs de la classe FieldInfo directement dans les modèles Pydantic et de nous passer de cette dernière. De plus, les managers devront être mis à jour et simplifiés en conséquence.

Affichage et soumission du formulaire

Du côté de l'interface utilisateur, tous les paramètres renseignés sont affichés. Si un paramètre est manquant, la zone de saisie correspondante est masquée. Cette fonctionnalité permet de cacher automatiquement les paramètres qui ne sont pas inclus dans la version de l'étude en cours.

Concernant le back office, l'option response_model_exclude_none=True est utilisée. Cela signifie que, dans un modèle Pydantic, les attributs ayant la valeur None sont exclus de la réponse JSON envoyée au front office.

Lorsque l'utilisateur apporte des modifications aux données du formulaire et les soumet, l'interface utilisateur prépare une requête JSON qui inclut uniquement les paramètres modifiés. En d'autres termes, l'objet JSON ne contient pas nécessairement toutes les données du modèle Pydantic.

Le modèle Pydantic doit donc avoir des attributs optionnels pour permettre la valeur None.

Lecture des paramètres de configuration

Par convention, les paramètres dont la valeur correspond à la valeur par défaut ne sont pas enregistrés dans le fichier INI. Généralement, cela concerne les valeurs nulles (comme 0.0 ou False pour un booléen), mais cela peut également s'appliquer à d'autres valeurs. Par exemple, le paramètre unit_count a une valeur par défaut de 1, ce qui signifie qu'il ne sera pas stocké dans le fichier INI s'il est égal à 1.

Le modèle Pydantic est construit à partir des paramètres du fichier INI. Cette construction implique la conversion et la validation des données, par exemple, la conversion d'une chaîne de caractères en un type énuméré. Il est possible que la validation des données échoue, ce qui peut entraîner le déclenchement d'une exception de type ValueError ou TypeError. Afin de fournir un contexte d'erreur plus précis, la fonction de lecture doit intercepter ces exceptions et lever une exception plus appropriée.

La construction du modèle doit également prendre en compte la version de l'étude. Si une étude est dans une version antérieure, les attributs du modèle qui appartiennent à la nouvelle version doivent être initialisés à None. Cependant, si un paramètre est manquant, la valeur par défaut de l'attribut doit être utilisée. Il convient de rappeler que certains paramètres sont obligatoires et n'ont donc pas de valeur par défaut. Si une valeur manque, la fonction de lecture doit lever une exception précisant le nom du paramètre.

Un mapping doit être défini pour associer les noms des attributs du modèle Pydantic aux noms des paramètres dans le fichier INI. Cela peut être réalisé en utilisant une propriété ini_path lors de la description des champs du modèle avec la fonction Field. Dans certain cas, par exemple dans le cas des paramètres avancé de General Data, l'accès aux paramètres doit se faire en profondeur, car il y a plusieurs sections dans le fichier INI. Dans ce cas, le nom du paramètre dans le fichier INI est représenté sous la forme d'un chemin (au format Posix).

De même, les propriétés start_version (et end_version) peuvent être ajoutées lors de l'appel à la fonction Field pour déterminer si un attribut existe dans une version spécifique de l'étude.

En fin de compte, le modèle Pydantic est construit à partir des paramètres du fichier INI et des valeurs par défaut des attributs en fonction de la version actuelle de l'étude.

Mise à jour des paramètres de configuration

La mise à jour des paramètres de configuration d'une étude Antares se déroule en deux étapes distinctes. La première étape consiste à créer une commande de type UpdateConfig pour spécifier les modifications apportées à l'étude. Cette commande contient uniquement les paramètres qui ont été modifiés.

La seconde étape est l'application effective des changements et la mise à jour du fichier INI de l'étude, qui est stocké sur le disque, dans le cas des études RAW. Dans le cas des variants d'études, la commande est simplement ajoutée à l'historique des commandes. La seconde étape est implémentée avec la fonction utilitaire execute_or_add_commands.

Lorsque le formulaire envoie les données JSON, seules les données modifiées sont renseignées. Le modèle Pydantic est construit à partir de ces données. Les attributs du modèle Pydantic sont facultatifs, ce qui permet d'assigner la valeur None aux paramètres manquants. La construction du modèle implique la conversion et la validation des données. FastAPI gère automatiquement cette validation et renvoie une erreur HTTP 422 "Unprocessable Entity" (Entité non traitable) en cas de problème.

Si les données proviennent d'un appel à l'API Swagger, des contrôles de validation supplémentaires sont nécessaires. Une erreur de validation doit être générée si un paramètre JSON n'existe pas dans le modèle Pydantic. Dans la configuration du modèle Pydantic, la propriété extra = Extra.forbid est utilisé pour interdire l'utilisation de paramètres inconnus. Il est également important de prendre en compte la version actuelle de l'étude et de vérifier la disponibilité de chaque attribut. Chaque attribut du modèle Pydantic possède les propriétés start_version et end_version, indiquant dans quelle version de l'étude l'attribut est disponible. Si un attribut n'est pas disponible dans la version de l'étude, une exception doit être levée, fournissant un message clair sur l'incompatibilité de version.

Pour mettre à jour la configuration de l'étude, nous utilisons un mapping qui associe les noms des attributs du modèle Pydantic aux noms des paramètres dans le fichier INI. Ce mapping est utilisé pour construire un dictionnaire Python qui sera utilisé par la commande UpdateConfig afin de mettre à jour le fichier INI de l'étude. Les paramètres ayant la valeur None sont exclus, car cela signifie qu'ils n'ont pas été modifiés et ne doivent pas être mis à jour.

[laurent-laporte-pro]

Configuration de la classe FormFieldsBaseModel

On se propose de configurer la classe FormFieldsBaseModel comme suit :

class FormFieldsBaseModel(BaseModel):
    """
    Pydantic Model for webapp form
    """

    class Config:
        alias_generator = to_camel_case
        extra = Extra.forbid
        allow_population_by_field_name = True

Cette configuration apporte les ajustement suivant :

• permettre la conversion des noms d'attributs au format "camelCase" pour la conversion JSON.
• interdire les attributs inconns lors de l'initialisation et la validation du modèle. Attention, cette vérification n'est pas faite lorsque l'objet est construit avec BaseModel.construct().
• permettre l'initialisation du modèle en utilisant des noms d'attributs au format "snake_case". Cela rend notamment les tests unitaires plus agréable à implémenter.

[laurent-laporte-pro]

Prise en compte des versions d'étude au niveau du modèle

Pour simplifier la spécification des valeurs start_version et end_version lorsque le modèle lui-même est disponible dans un intervalle de versions donné, les développeurs peuvent spécifier ces propriétés directement dans la classe Config de leur modèle Pydantic. Cela permet d'éviter de répéter les mêmes valeurs pour chaque champ du modèle.

Voici un exemple de classe Config pour la classe Product :

class Product(FormFieldsBaseModel):
    name: str
    price: float

    class Config:
        start_version = 800
        end_version = 820

[laurent-laporte-pro]

Implémentation d'un model Pydantic

Un modèle Pydantic (ou formulaire) est une sous-classe de la classe de base FormFieldsBaseModel qui est utilisée pour définir la structure et les contraintes des champs d'un formulaire. Pour spécifier les champs du formulaire, on utilise la classe Field de Pydantic. Cette classe offre plusieurs fonctionnalités, telles que la définition de valeurs par défaut, la description du champ (utilisée dans la génération du schéma JSON pour l'API Swagger) et la possibilité de définir des contraintes de validation. Pour spécifier le type d'un attribut, on utilisera les annotations de type classique du module typing.

Lors de la création d'un champ dans le formulaire, on peut ajouter les propriétés suivantes :

• ini_path : Il s'agit du nom du paramètre dans le fichier INI. Dans le cas où il y a une seule section, ini_path peut simplement être le nom du paramètre. Dans le cas où il y a plusieurs sections distinctes, ini_path peut être spécifié sous la forme {section}/{paramètre}. Si ce paramètre n'est pas renseigné, la valeur par défaut sera le nom de l'attribut au format "snake_case".

• start_version : Cette propriété représente la première version d'étude pour laquelle l'attribut est disponible. Il s'agit d'un nombre entier. Si ce paramètre n'est pas renseigné, sa valeur par défaut est zéro, ce qui indique que l'attribut est disponible depuis la première version d'étude.

• end_version : Cette propriété représente la dernière version d'étude pour laquelle l'attribut est disponible. Il s'agit également d'un nombre entier. Si ce paramètre n'est pas renseigné, sa valeur par défaut est zéro, ce qui signifie que l'attribut est toujours disponible. Ce paramètre doit être utilisé lorsque le paramètre correspondant est supprimé après une version d'étude spécifique.

Un attribut est disponible pour une étude en version study_version si le prédicat suivant est respecté :

is_available = (
    start_version <= study_version <= end_version
    if end_version
    else start_version <= study_version
)

L'exemple suivant montre comment définir un formulaire pour un "produit" (factice).

Dans cet exemple, on définit les champs suivants :

• name: exemple de champ obligatoire (sans valeur par défaut),

  • type: str (chaîne de caractères)
  • ini_path: non défini, on utilise le même nom que l'attribut pour lire/écrire dans le fichier INI
  • start_version: non définie, on utilisera la valeur 0.
  • end_version: non définie, on utilisera la valeur 0.

• price: exemple d'attribut numérique obligatoire avec une contrainte,

  • type: float (numérique)
  • ini_path: "product-price",
  • start_version: non définie, on utilisera la valeur 0.
  • end_version: non définie, on utilisera la valeur 0.

• quantity: exemple d'attribut numérique avec une contrainte,

  • type: int (entier)
  • default: 1,
  • ini_path: "qty",
  • start_version: 810.
  • end_version: non définie, on utilisera la valeur 0.

• product_size: exemple d'attribut de type énuméré,

  • type: SizeEnum (enuméré:)
  • default: SizeEnum.SMALL,
  • ini_path: "product-size",
  • start_version: 810.
  • end_version: 820.

Attention : dans cet exemple, on n'utilise pas le typage avec Optional[...], donc les valeurs None ne sont pas autorisées.

product_model.py

[laurent-laporte-pro]

Rendre les champs optionnels avec une Métaclasse

Lorsque nous implémentons un modèle Pydantic, nous définissons généralement les champs en spécifiant leurs valeurs par défaut et d'autres propriétés (description, contraintes, etc.). Cependant, nous souhaitons rendre tous les champs optionnels, ce qui nécessiterait d'ajouter Optional[...] à chaque champ.

Pour éviter cette répétition fastidieuse, une solution consiste à utiliser une métaclasse spéciale appelée AllOptionalMetaclass. Cette métaclasse permet de rendre automatiquement tous les champs d'un modèle Pydantic optionnels, sans avoir à modifier individuellement chaque champ.

all_optional_metaclass.py

Lorsque vous utilisez la métaclasse AllOptionalMetaclass, vous pouvez définir votre modèle de manière classique, en spécifiant les valeurs par défaut et les autres propriétés des champs. La métaclasse se chargera ensuite de transformer tous les champs en champs optionnels en enveloppant leurs types avec Optional[...].

L'exemple ci-dessous montre quelques cas d'utilisation d'un model Pydantic avec tous les champs optionnels :

product_model_optionals.py

REMARQUES :

• Si un paramètre est manquant et que le champ est initialement requis, alors le champ aura la valeur None.
• Si un paramètre est manquant et que le champ possède une valeur par défaut, alors le champ aura la valeur par défaut.
• Si un paramètre est fourni avec la valeur None, alors le champ aura la valeur None.
• Si un paramètre est fourni avec une valeur non vide (différente de None), alors la validation du champ est effectuée. Cela peut entraîner la levée de l'exception pydantic.error_wrappers.ValidationError, qui est une sous-classe de ValueError.

[laurent-laporte-pro]

Spécification détaillée

Conversion du modèle en paramètres INI

La méthode de classe to_ini a pour but d'extraire les champs d'un modèle Pydantic et de les utiliser pour mettre à jour la configuration d'une étude Antares.

Remarque : En général, seuls certains paramètres sont mis à jour, et non tous. Cela signifie que la plupart des attributs du modèle auront la valeur None, indiquant que le paramètre ne doit pas être mis à jour.

Un mapping est utilisé pour faire correspondre les noms des attributs du modèle avec les noms des paramètres du fichier INI. Ce mapping est créé en récupérant la propriété ini_path de l'objet Field de chaque champ. Cette propriété permet de construire un dictionnaire imbriqué des valeurs à enregistrer dans le fichier INI.

En ce qui concerne les valeurs, le format de données supporté par le fichier INI est très proche du format JSON. Par conséquent, nous utiliserons une conversion au format JSON pour convertir les valeurs en amont.

L'objet Field de chaque champ peut également contenir les propriétés start_version et end_version, qui spécifient un intervalle de disponibilité de l'attribut pour une version donnée de l'étude. Si le champ est renseigné (c'est-à-dire différent de None), une exception de type ValidationError doit être levée pour indiquer que le paramètre n'est pas disponible pour la version de l'étude.

Il n'est pas nécessaire de vérifier si un attribut donné existe dans le modèle, ni même si la valeur fournie est valide, car cela est déjà vérifié au niveau de l'endpoint FastAPI lors de la construction du modèle Pydantic.