**Python 3.11.1 is now out (as of 6 December 2022) and with it comes, as usual, a number of changes and improvements. If you want to know what is new with 3.11.1, you can go to https://docs.python.org/3/whatsnew/3.11.html to find out all the information.

One of the new things that did come along with 3.11.1 is a new standard library module called tomllib, which has "support" for parsing TOML style documents. Notice that I said "support". It's not complete support, but it is support. I'll talk more about that in a few moments.

What is TOML?

TOML stands for Tom's Obvious Minimal Language and from what I understand, was created mainly as a means of storing configuration data. Many other ways of storing configuration data don't provide a means of saving comments inline.

To get started, let's assume that I created a Python program that used PAGE to create the GUI front end. Let's further assume that I want to give the user the ability to select the Theme for the program (since it uses ttk Widgets). I want the program to remember what that user decided for their theme of choice. To do this, I will use a configuration file to keep all the customization information.**

Python 3.11.1 est maintenant disponible (à partir du 6 décembre 2022) et, comme d'habitude, il apporte un certain nombre de changements et d'améliorations. Si vous voulez savoir ce qu'il y a de nouveau dans la version 3.11.1, vous pouvez vous rendre sur le site https://docs.python.org/3/whatsnew/3.11.html pour trouver toutes les informations.

L'une des nouveautés de la version 3.11.1 est un nouveau module de la bibliothèque standard appelé tomllib, qui offre un « support » pour l'analyse des documents de style TOML. Remarquez que j'ai dit « support ». Ce n'est pas un support complet, mais c'est un support. Je vais en parler davantage dans quelques instants.

Qu'est-ce que TOML ?

TOML est l'acronyme de Tom's Obvious Minimal Language et, d'après ce que j'ai compris, il a été créé principalement comme un moyen de stocker des données de configuration. Beaucoup d'autres moyens de stocker des données de configuration ne permettent pas d'enregistrer des commentaires en ligne.

Pour commencer, supposons que j'ai créé un programme Python qui utilise PAGE pour créer l'interface utilisateur graphique. Supposons également que je veuille donner à l'utilisateur la possibilité de sélectionner le thème du programme (puisqu'il utilise des Widgets ttk). Je veux que le programme se souvienne de ce que l'utilisateur a décidé pour le thème choisi. Pour ce faire, je vais utiliser un fichier de configuration pour conserver toutes les informations de personnalisation.


**Shown top right is a simplified version of the hypothetical configuration file.

At this point, it looks like a standard configuration file that you would find just about anywhere. However, if this were a "standard" configparser type config file, the first entry under the [Themes] section would not be possible directly, since configparser doesn’t support lists without manipulation. In TOML, sections are called tables. The available_themes key has the value of an array. Once it's ported into Python, it becomes a list.

Now let's look at how to get the data into a program.

Of course, we have to import the tomllib library. Remember this is supported directly only under Python 3.11.

import tomllib
import pprint

Next, we open the configuration file and use the load method of the library.

with open("config.toml", "rb") as f:
   
data = tomllib.load(f)

Using pretty print, we can now look at the data that was brought in from the config file (next page, top right).**

En haut à droite, vous voyez une version simplifiée du fichier de configuration hypothétique.

À ce stade, il ressemble à un fichier de configuration standard que l'on peut trouver à peu près partout. Cependant, s'il s'agissait d'un fichier de configuration « standard » de type configparser, la première entrée de la section [Themes] ne serait pas possible directement, puisque configparser ne supporte pas les listes sans manipulation. En TOML, les sections sont appelées tables. La clé available_themes a la valeur d'un tableau. Une fois portée en Python, elle devient une liste.

Voyons maintenant comment introduire les données dans un programme.

Bien sûr, nous devons importer la bibliothèque tomllib. Rappelez-vous que celle-ci n'est prise en charge directement que sous Python 3.11.

import tomllib
import pprint

Ensuite, nous ouvrons le fichier de configuration et utilisons la méthode load de la bibliothèque.

with open("config.toml", "rb") as f:
   
data = tomllib.load(f)

En utilisant pretty print, nous pouvons maintenant regarder les données qui ont été apportées par le fichier de configuration (page suivante, en haut à droite).

**You can see that it is simply just a dictionary. To access the data, we do it just like any other dictionary (next page, bottom left).

The output of our little program will look like this…

Available Themes: ['notsodark', 'plastik', 'waldorf', 'page_wheat', 'clearlooks', 'forest-light', 'forest-dark', 'default', 'clam', 'classic', 'alt']
Your default Theme is: waldorf
Your current Theme is: notsodark
Program version 0.7.1

The Python tomllib library provides only two functions, tomllib.loads which loads a TOML string and returns a dictionary, and tomllib.load which reads a TOML file and returns again, a dictionary. See https://docs.python.org/3/library/tomllib.html.**

Vous pouvez voir qu'il s'agit simplement d'un dictionnaire. Pour accéder aux données, nous procédons comme pour tout autre dictionnaire (page suivante, en bas à gauche).

Le résultat de notre petit programme ressemblera à ceci :

Available Themes: ['notsodark', 'plastik', 'waldorf', 'page_wheat', 'clearlooks', 'forest-light', 'forest-dark', 'default', 'clam', 'classic', 'alt']
Your default Theme is: waldorf
Your current Theme is: notsodark
Program version 0.7.1

La bibliothèque Python tomllib ne fournit que deux fonctions, tomllib.loads qui charge une chaîne TOML et retourne un dictionnaire, et tomllib.load qui lit un fichier TOML et retourne à nouveau un dictionnaire. Voir https://docs.python.org/3/library/tomllib.html.


**Unfortunately, Python does not provide any way to properly write out the TOML data. The good news is that there is a third party library called tomli_w which will allow you to write the TOML data back to a file. So if the user decides to change his current theme from 'notsodark' to 'clam', it's a simple chore to make the change and write it back. You can install it via pip.

pip install tomli-w

Once it’s installed, you can simply write it pretty much as it’s a normal, but binary file.

Remember the tomllib (bottom right) comes with only Python 3.11. So what do you do if you are running Python 3.8.10 and you aren't ready to upgrade quite yet? Never fear. The tomli-w library is currently supported in versions 3.7 all the way up to 3.11. To get the parser analog to tomllib, you can install tomli. Again, just use pip.

pip install tomli

Of course, if you are using tomli rather than tomllib, you need to do the import a bit differently.

#import tomllib
import tomli
import tomli_w
import pprint

The home pages for tomli-w and tomli can be found at https://github.com/hukkin/tomli-w**

Malheureusement, Python ne fournit aucun moyen d'écrire correctement les données TOML. La bonne nouvelle est qu'il existe une bibliothèque tierce appelée tomli_w qui vous permet de réécrire les données TOML dans un fichier. Ainsi, si l'utilisateur décide de changer son thème actuel de « notsodark » à « clam », il lui suffira d'effectuer le changement et de le réécrire. Vous pouvez l'installer via pip.

pip install tomli-w

Une fois qu'il est installé, vous pouvez simplement l'écrire comme un fichier normal, mais binaire.

Rappelez-vous que le tomllib (en bas à droite) n'est livré qu'avec Python 3.11. Alors que faire si vous utilisez Python 3.8.10 et que vous n'êtes pas encore prêt à faire la mise à niveau ? N'ayez crainte. La bibliothèque tomli-w est actuellement supportée dans les versions 3.7 jusqu'à 3.11. Pour obtenir l'analyseur analogue à tomllib, vous pouvez installer tomli. Encore une fois, il suffit d'utiliser pip.

pip install tomli

Bien sûr, si vous utilisez tomli plutôt que tomllib, vous devez faire l'importation un peu différemment.

#import tomllib
import tomli
import tomli_w
import pprint

Les pages d'accueil de tomli-w et de tomli se trouvent aux adresses :
https://github.com/hukkin/tomli-w

et

**https://github.com/hukkin/tomli

If you want to take a look at the complete information on TOML, you can visit the home page at https://toml.io/en/ 

There is another TOML third-party package for Python at https://github.com/sdispater/tomlkit . It’s documentation can be found at https://github.com/sdispater/tomlkit/blob/master/docs/quickstart.rst. I haven’t had much of a chance to play with it, but it looks promising.

I’ve put the config.toml file and the Python file (toml1.py) in my repository at https://github.com/gregwa1953/FCM-189.

That’s it for this month. Happy New Year!!!

Until next time, as always; stay safe, healthy, positive and creative!**

https://github.com/hukkin/tomli

Si vous souhaitez consulter les informations complètes sur TOML, vous pouvez visiter la page d'accueil à l'adresse https://toml.io/en/. 

Il existe un autre paquet tiers TOML pour Python à l'adresse https://github.com/sdispater/tomlkit . Sa documentation se trouve à l'adresse https://github.com/sdispater/tomlkit/blob/master/docs/quickstart.rst. Je n'ai pas encore eu l'occasion de jouer avec, mais il semble prometteur.

J'ai placé le fichier config.toml et le fichier Python (toml1.py) dans mon dépôt à https://github.com/gregwa1953/FCM-189.

C'est tout pour ce mois-ci. Bonne année ! !!

Jusqu'à la prochaine fois, comme toujours, restez en sécurité, en bonne santé, positif et créatif !