Forem: Kev Castor

Create easily a Python app with Streamlit

Kev Castor — Mon, 27 May 2024 19:54:29 +0000

🇫🇷 version here.

For some time now, I have been learning Vietnamese. To do this, like many people these days, I signed up for the Duolingo app. This app is really good; it makes learning quick and fun.

But here’s the thing, like many apps these days, Duolingo offers a Freemium model, and its full potential is only unlocked with a subscription. One of the interesting features offered by the subscription is the ability to take a simple Vietnamese/English translation quiz with all the words learned since the beginning of the lessons. So I wondered, "How can I try to reproduce this exercise, which is quite simple, to practice without having to pay for a Duolingo subscription?"

In this article, I will try to show you how to recreate this exercise with the Streamlit framework and a bit of code.

First, the data

First, I need a dataset to carry out this project. Fortunately, on its website, Duolingo lists all the words I've learned since the beginning of my lessons, along with their English translations (I can only learn Vietnamese from English in the app).

A quick copy/paste of the word list into a text file (sorry Duolingo...), and here I am with a small dataset of 131 Vietnamese words with their corresponding English translations. All that's left is to reformat everything with a quick Python script, and I have a JSON file that contains the basic data for my future game.

{
    "translations": [
        {
            "VN": "ga",
            "EN": "station, gas"
        },
        {
            "VN": "trạm",
            "EN": "station, stations"
        },
        {
            "VN": "đặt chỗ",
            "EN": "make a reservation, reservation"
        },
        ...

Streamlit

I had several options for creating my app. What I wanted was something relatively simple to implement, easily deployable so I could access it anywhere, and an opportunity to learn something while working on this project. So, what to do? Create a simple HTML/JS project, try to dive into a JS framework (React or Vue.js), or find another alternative?

The HTML/JS project? Yes, why not, but I'm not sure I would learn anything interesting.

Creating an app with a JS framework? Yes, that would be great, but I know these kinds of projects from having tried them several times before... They are great frameworks, but you still need to learn how to use them properly (I knew how to use React a few years ago, but it evolves so quickly that today I would have to start from scratch) to avoid doing things incorrectly, and you need to spend 2 weeks learning a framework to create an app with a few lines of code that takes 4 hours to implement.

Moreover, I'm no longer comfortable with JS...

So why not turn to something else? I'm a pythonista in my daily life, and I've heard about the Streamlit framework at work. It seems you can create cool apps with it. So, let's take a look 🕵️

Quick focus on the Framework

Go to the Streamlit website, and you'll see written in front of you: "A faster way to build and share data apps". That seems to be what we're looking for 😄. A few minutes browsing the documentation confirms it. It's simple to install, use, and deploy, and it's all in Python. Let's see if it fits the bill!

Installation

Installing the framework is quite simple and can be done in a few lines:

mkdir translation-exercise-app
cd translation-exercise-app
# make sure you have a version of python >= 3.8
python3 --version 
python3 -m venv .venv
source .venv/bin/activate
pip install streamlit

And that's it. Simple, right? For the rest of the article, the only Streamlit command we'll use is streamlit run app.py.

Let's get started with the implementation

With your favorite editor, open the translation-exercise-app folder. Your .venv folder should already be there. Add the JSON file containing the initially generated dataset, then create a file named app.py.

# app.py 
import streamlit as st

st.text("Hello World!")

Now, use the command streamlit run app.py, and a page in your browser should open displaying "Hello World!". First easy victory 💪 !

I won't explain each Streamlit component I'll use one by one. I prefer to provide you with links to the official documentation, which is much better than any explanations I could give. Instead, I'll show you how I use them to create my translation exercise app.

Some design first

What exactly do I want to do?

I thought that, for now, I would create a very simple app. Its purpose will be to display a word in Vietnamese taken from the base dataset, along with 4 English translations, one corresponding to the exact translation of the chosen Vietnamese word, and the other 3 being just random English words from the rest of the dataset. The player will have to find the correct English translation among the 4 options. We will display a score on the screen which will count the number of consecutive correct answers from the player. This score will reset to 0 in case of a mistake. We will also display the best score obtained.

Loading data into the app

For the app to function, we need to make the dataset available to it. So here we go:

import json

import streamlit as st

# We create a function that will read and load the data into a Python dictionary
def load_data() -> dict:
    data = {}
    with open("vn_en_words_translations.json") as fd:
        data = json.load(fd)
    return data

# We check if the data is in the Streamlit "session_state" (or cache)
# If it's not there, then we use the function to load the data
if "words_dict" not in st.session_state:
    st.session_state["words_dict"] = load_data()

With this piece of code, I can load my data and store it in the Streamlit session state (I'll explain later what the session state is). It's quite simple and allows me to access my dataset throughout my file via st.session_state["words_dict"], which is quite handy.

Creating the Quiz Dataset

We are tackling the most "difficult" part (in reality, it's very simple, don't panic) in terms of logic for our application. The idea here is to create a function that will randomly select a Vietnamese word and 4 English words, one of which will be the translation of our Vietnamese word. I decided to use a simple data structure for this: a dictionary with two keys. One of them is associated with a list that will contain the Vietnamese word (this list will always be of size 1). The other is associated with a list that will contain the 4 English translations, always placing the correct translation at the beginning of the list (index 0).

import random

def select_quiz_words(words_dict: dict) -> dict:
    # Create the dictionary
    selected_words = {
        "VN": [],
        "EN": []
    }
    # Randomly determine an index to use for selecting a Vietnamese word
    # and its English equivalent from our dataset to place at the start of the list.
    selected_word_index = random.randrange(0, len(words_dict["translations"]))
    selected_words["VN"].append(words_dict["translations"][selected_word_index]["VN"])
    selected_words["EN"].append(words_dict["translations"][selected_word_index]["EN"])
    # Thus, selected_words["EN"][0] will always be the correct translation of selected_words["VN"][0]

Next, we continue our function to randomly select the other three English words, ensuring these words meet the following two conditions:

They must not match selected_words["EN"][0], otherwise the correct answer will appear twice among our 4 options.
There must be no duplicates among our 4 options.

import random

def select_quiz_words(words_dict: dict) -> dict:
    selected_words = {
        "VN": [],
        "EN": []
    }
    selected_word_index = random.randrange(0, len(words_dict["translations"]))
    selected_words["VN"].append(words_dict["translations"][selected_word_index]["VN"])
    selected_words["EN"].append(words_dict["translations"][selected_word_index]["EN"])

    find_other_words = True
    # Loop until 3 other words have been chosen
    while find_other_words:
        # Randomly determine an index to use for selecting an English word from our dataset
        selected_en_word_index = random.randrange(0, len(words_dict["translations"]))
        # Of course, this word must not be the one chosen above
        if selected_en_word_index != selected_word_index:
            # Nor should it already be in our list
            if words_dict["translations"][selected_en_word_index]["EN"] not in selected_words["EN"]:
                # If both conditions are met, then add it to our list
                selected_words["EN"].append(words_dict["translations"][selected_en_word_index]["EN"])
        if len(selected_words["EN"]) == 4:
            find_other_words = False
    return selected_words

We now have the data for our quiz.

The Content of the App

Alright, all of this is nice, but at the moment, our app still looks like a blank page that says hello. It's time to add some content! Let's start by adding two or three sentences that will explain to the player what they are doing here.

selected_words_dict = select_quizz_words(words_dict=st.session_state["words_dict"])

st.title("Hello Learners :wave:!")
st.subheader("Let's make a small game. I give you a Vietnamese word, and you try to give me the correct English translation. Let's go?")

st.write(f"What is the English translation of the word **{selected_words_dict['VN'][0]}**?")

It's a start. First, we load our quiz data into a global variable called selected_words_dict using the function we wrote earlier. Then, we quickly explain the rules by displaying text very simply via st.title() and st.subheader(), and we present the Vietnamese word to be translated via st.write(). You can find all the details of the Streamlit functions that allow you to display text on the screen here.

Next, let's propose the 4 English translation options to the user. We need to find a way to allow the player to interact with our app by making a choice. I've decided to use the Streamlit component st.button(). I will display 4 buttons side by side horizontally, each displaying one of the 4 possible answers. The user will then have the choice to click on one of them to select the correct translation. Here is the code to implement these buttons:

# We 'copy' our list of English options and then shuffle it like a good cocktail
selected_en_words_dict_shuffled = selected_words_dict["EN"].copy()
random.shuffle(selected_en_words_dict_shuffled)
# We create a Streamlit layout composed of 4 columns.
col1, col2, col3, col4 = st.columns(4)
# And for each of them, we insert a clickable button containing the option
with col1:
    word = selected_en_words_dict_shuffled[0]
    st.button(label=word, key=word, on_click=check_result, args=[word], use_container_width=True)
with col2:
    word = selected_en_words_dict_shuffled[1]
    st.button(label=word, key=word, on_click=check_result, args=[word], use_container_width=True)
with col3:
    word = selected_en_words_dict_shuffled[2]
    st.button(label=word, key=word, on_click=check_result, args=[word], use_container_width=True)
with col4:
    word = selected_en_words_dict_shuffled[3]
    st.button(label=word, key=word, on_click=check_result, args=[word], use_container_width=True)

I decided to shuffle my array of answers because, remember, otherwise, we would end up with the correct answer always in the first position, which removes quite a bit of suspense from the exercise...

Next, we use the layout system of Streamlit to create 4 columns. For each of them, we add a clickable button representing one of the answers. Note that:

label is the text of the button.
key is a key used by Streamlit to have unique buttons.
on_click is a callback method that we will discuss shortly.
args is an array of parameters that will be given to the callback method. We pass the button's option to validate or not the click.
use_container_width is a simple boolean allowing the button to know that it can take the entire width of the container it is in, here the column (and I didn't need to spend 5 hours on CSS to achieve this, which is a miracle 🙏).

This part of the code can probably be refactored, but I haven't found a correct way to do it yet. It might be the subject of a future article.

Validate the result

Our application is starting to have content. Now we need to validate the quiz result. As mentioned earlier, we will allow the player to see a score. We will also enable them to see their best score. So let's start by defining these two variables:

#... 
if  "words_dict"  not  in  st.session_state:
    st.session_state["words_dict"] = load_data()

if "score" not in st.session_state:
    st.session_state["score"] = 0

if "best_score" not in st.session_state:
    st.session_state["best_score"] = 0
# ...

Next, let's focus on the check_result callback method that was passed to our buttons earlier:

def check_result(choice):
    if  choice == selected_words_dict["EN"][0]:
        st.session_state["score"] += 1
    else:
        if  st.session_state["score"] > st.session_state["best_score"]:
            st.session_state["best_score"] = st.session_state["score"]
        st.session_state["score"] =  0

This method is very simple. If the user's choice matches the first element of our list of English options, then it's a jackpot, and we increment their score. Otherwise, we update the best score if it is strictly less than the current score, and then we reset the current score to 0.

We just need to display our scores:

st.subheader(body=f"Your current score is: {st.session_state['score']}")
st.subheader(body=f"Your best score is: {st.session_state['best_score']}")

And there you have it!

It's Time to Test

By using streamlit run app.py, we can quickly launch and test our application.

So yes, it's not very pretty, but it's still presentable, and that without a single line of CSS. We end up with a little game that allows us to practice our Vietnamese. The goal we set seems to be achieved! Yay 🎉!

What's Happening Under the Hood?

At this point, it's important to emphasize a mechanism of Streamlit that everyone needs to keep in mind if you want to use this framework. Streamlit reloads this little Python script that we just implemented at EVERY interaction we have with the app. In our case, this means that every time the user clicks a button, the entire script is rerun. This explains several things...

It explains why some of my "variables," like the initial dataset, are loaded in this way:

if "words_dict" not in st.session_state:
    st.session_state["words_dict"] = load_data()

Here, I leverage Streamlit's "cache" system to avoid having these data reloaded at every interaction. This is also what allows me to retain my score despite successive reloads. Indeed, at each rerun of the script, Streamlit checks if the st.session_state dictionary contains an element associated with "words_dict" (which it does) and therefore does not reload it.

This also explains why most variables and Streamlit statements are executed at the global scope of the script. For example, the proposals used for each question are loaded in the global scope:

selected_words_dict = select_quizz_words(words_dict=st.session_state["words_dict"])

I do it this way because I need this dictionary to be recreated each time to change the proposals and make the game, let's say... interesting! The buttons are thus also recreated each time with new values, which is our goal.

In Conclusion

Thanks to Streamlit, I managed to implement this little app in less than 100 lines of code and in just a few hours. So yes, I didn't start from scratch with Python, and the app is far from perfect, both technically and visually, but I'm quite happy with the result. I am very pleasantly surprised by the ease of use of the framework and the result.

The fact that the script is fully reloaded each time makes me think that the framework must have limitations for more complex apps. Moreover, the available components, although numerous, do not cover all use cases of more sophisticated apps. But for small prototypes and simple apps like the one presented in this article, it works just fine.

Regarding my app, I would like to make a few improvements in the future:

Add a green message in case of a correct answer or a red one in case of an error, explaining the correct answer.
Allow the user to choose the direction of the exercise: from Vietnamese to English or from English to Vietnamese.
Allow the user to choose between a word translation exercise or a sentence translation exercise.
Deploy my app online.
Refactor some of the code.
Add other features that I hope will come to mind later 🤔. This will probably be the subject of future articles.

That being said, I will continue to explore this framework that addresses one of my issues: being able to create simple apps in Python without having to spend several days learning to use a complex framework.

See you soon for new adventures in the simple and efficient world of Streamlit. Feel free to check the Gitlab repository to find the code for the article.

Streamlit: Créer des apps en Python très simplement

Kev Castor — Mon, 27 May 2024 19:48:27 +0000

Depuis quelques temps, je me suis mis à l'apprentissage du vietnamien. Pour cela, comme beaucoup de monde en ce moment, je me suis inscrit sur l'application Duolingo. Cette application est vraiment pas mal, elle rend l'apprentissage rapide et ludique.

Oui mais voilà, comme beaucoup d'applications de nos jours, Duolingo propose une offre Freemium, et son plein potentiel n'est libéré qu'avec un abonnement. Notamment, une des fonctionnalités intéressantes qu'offre l'abonnement, c'est la possibilité de faire un simple quiz de traduction vietnamien / anglais avec tous les mots appris depuis le début des leçons. Je me suis alors demandé "Comment essayer de reproduire cet exercice, finalement assez simple, pour pouvoir pratiquer sans avoir à payer un abonnement Duolingo ?"

Dans cet article, je vais essayer de vous montrer comment recréer cet exercice avec le framework Streamlit et un peu de code.

D'abord, les données

Il me faut pour commencer un premier dataset pour réaliser ce projet. Ça tombe bien, sur son site internet, Duolingo me liste tous les mots que j'ai appris depuis le début de mes leçons, avec leurs traductions anglaises (je ne peux qu'apprendre le vietnamien à partir de l'anglais depuis l'application).

Un rapide copier/coller de la liste de mots dans un fichier texte (désolé Duolingo...), et me voilà avec un petit dataset de 131 mots vietnamiens avec la traduction anglaise correspondante. Reste encore à reformatter le tout avec un rapide script Python, et j'ai un JSON qui contient les données de base de mon futur jeu.

{
    "translations": [
        {
            "VN": "ga",
            "EN": "station, gas"
        },
        {
            "VN": "trạm",
            "EN": "station, stations"
        },
        {
            "VN": "đặt chỗ",
            "EN": "make a reservation, reservation"
        },
        ...

Streamlit

Plusieurs choix s'offraient à moi pour créer mon application. Ce que je voulais, c'était avoir quelque chose de relativement simple à implémenter, pouvant être facilement déployé pour pouvoir y accéder partout, et apprendre quelque chose en travaillant sur ce projet. Du coup, quoi faire ? Faire un projet HTML/JS simple, essayer de me plonger dans un framework JS (React ou Vue.js), ou trouver une autre alternative ?

Le projet HTML/JS ? Oui, pourquoi pas, mais pas sûr d'en apprendre quelque chose d'intéressant.

Faire une application via un framework JS ? Oui, ça serait super, mais je connais ce genre de projet pour y avoir déjà goûté plusieurs fois... Ce sont de supers frameworks, mais il faut quand même apprendre à s'en servir (j'ai su faire du React il y a quelques années, mais ça évolue tellement vite qu'aujourd'hui je dois repartir de zéro) pour ne pas faire n'importe quoi, et il faut passer 2 semaines à apprendre un framework pour faire une application de quelques lignes qui prend 4 heures à implémenter.

De plus, je ne suis plus super à l'aise avec JS...

Alors pourquoi ne pas me tourner vers autre chose ? Je suis un pythonista dans mon quotidien, et j'ai entendu parler du framework Streamlit au travail. Il paraît que l'on peut faire des applications sympas avec. Alors, y jeter un coup d'œil 🕵️

Rapide focus sur le Framework

Allez sur le site de Streamlit, et vous verrez s'afficher devant vous : "A faster way to build and share data apps". Ça semble être ce que l'on cherche 😄. Quelques minutes à parcourir la documentation me le confirment. C'est simple à installer, à utiliser, à déployer, et c'est du full Python. Voyons si ça peut faire l'affaire !

L'installation

L'installation du framework est assez simple et se réalise en quelques commandes :

mkdir translation-exercice-app
cd translation-exercice-app
# assurez vous d'avoir une version de python >= 3.8
python3 --version 
python3 -m venv .venv
source .venv/bin/activate
pip install streamlit

Et c'est tout. Simple, non ? Pour la suite de l'article, la seule commande Streamlit que l'on utilisera sera streamlit run app.py.

C'est parti pour l'implémentation

Avec votre éditeur favori, ouvrez le dossier translation-exercise-app. Normalement, votre dossier .venv devrait déjà s'y trouver. Ajoutez le fichier JSON contenant le dataset initialement généré, puis créez un fichier app.py.

# app.py 
import streamlit as st

st.text("Hello World!")

Maintenant, utilisez la commande streamlit run app.py, et une page de votre navigateur devrait s'ouvrir en affichant "Hello World!". Première victoire facile 💪 !

Je ne vais pas vous expliquer un par un tous les composants Streamlit que je vais utiliser. Je préfère vous mettre les liens vers la documentation officielle, qui est bien meilleure que toutes mes explications pourront l'être. Je vais plutôt vous montrer comment je les utilise pour créer mon app d'exercice de traduction.

Un peu de design d'abord

Qu'est-ce que je veux faire exactement ?

Je me suis dit que, pour le moment, j'allais faire une app très simple. Son but sera d'afficher un mot en vietnamien pris dans le dataset de base, ainsi que 4 traductions anglaises, une correspondant à l'exacte traduction du mot vietnamien choisie, les 3 autres étant juste des mots anglais pris au hasard dans le reste du dataset. Le joueur devra trouver la bonne traduction anglaise parmi les 4 proposées. On aura un score affiché à l'écran qui comptera le nombre de bonnes réponses d'affilée du joueur. Ce score retombera à 0 en cas d'erreur. On affichera également le meilleur score obtenu.

Charger les données dans l'app

Pour que l'app fonctionne, on doit lui mettre à disposition le dataset. Alors c'est parti:

import json

import streamlit as s

# On crée une fonction qui va lire et charger les données dans un dictionnaire Python
def load_data() -> dict:
    data  = {}
    with  open("vn_en_words_translations.json") as  fd:
        data = json.load(fd)
    return data

# On vérifie si les données sont dans le "session_state" (ou cache) de Streamlit
# Si ce n'est pas le cas, alors on utilise la fonction pour charger les données
if "words_dict" not in st.session_state:
    st.session_state["words_dict"] = load_data()

Grâce à ce bout de code, je peux charger mes données et les stocker dans le session state de Streamlit (j'expliquerai plus tard ce qu'est le session state). C'est assez simple et ça me permet d'accéder à mon dataset partout dans mon fichier via st.session_state["words_dict"], ce qui est assez pratique.

Création du dataset de quiz

Nous nous attaquons à la partie la plus "difficile" (en réalité, c'est très simple, ne paniquez pas) en termes de logique de notre application. L'idée ici est de créer une fonction qui va sélectionner au hasard un mot vietnamien et 4 mots anglais, dont un sera la traduction de notre mot vietnamien. Je décide pour cela d'utiliser une structure de données simple : un dictionnaire avec deux clés. L'une d'elles est associée à une liste qui contiendra le mot vietnamien (cette liste sera toujours de taille 1). L'autre est associée à une liste qui contiendra les 4 traductions anglaises, en prenant soin de toujours placer la bonne traduction au début de la liste (index 0).

import random

def  select_quizz_words(words_dict: dict) -> dict:
    # On créer le dictionnaire
    selected_words = {
        "VN": [],
        "EN": []
    }
    # On détermine au hasard un index que l'on utilise pour prendre un mot vietnamien
    # et son équivalent anglais dans notre dataset que l'on place en début de liste.
    selected_word_index = random.randrange(0, len(words_dict["translations"]))
    selected_words["VN"].append(words_dict["translations"][selected_word_index]["VN"])
    selected_words["EN"].append(words_dict["translations"][selected_word_index]["EN"])
    # Ainsi, selected_words["EN"][0] sera toujours la bonne traduction de selected_words["VN"][0]

Nous continuons ensuite notre fonction pour choisir les trois autres mots anglais au hasard, en nous assurant que ces mots remplissent les deux conditions suivantes :

Ils ne doivent pas correspondre à selected_words["EN"][0], sinon la bonne réponse apparaîtra en doublon dans nos 4 propositions.
Il ne doit pas y avoir de doublons dans nos 4 propositions.

import random

def  select_quizz_words(words_dict: dict) -> dict:
    selected_words = {
        "VN": [],
        "EN": []
    }
    selected_word_index = random.randrange(0, len(words_dict["translations"]))
    selected_words["VN"].append(words_dict["translations"][selected_word_index]["VN"])
    selected_words["EN"].append(words_dict["translations"][selected_word_index]["EN"])

    find_other_words = True
    # On boucle tant que 3 autres mots n'ont pas été choisis
    while find_other_words:
        # On détermine au hasard un index que l'on utilise pour prendre mot anglais dans notre dataset
        selected_en_word_index = random.randrange(0, len(words_dict["translations"]))
        # Bien sûr, ce mot ne doit pas être celui choisi plus haut
        if selected_en_word_index != selected_word_index:
            # Ni déjà être dans notre liste
            if words_dict["translations"][selected_en_word_index]["EN"] not in selected_words["EN"]:
                # Si les deux conditions sont remplies, alors on l'ajoute à notre liste
                selected_words["EN"].append(words_dict["translations"][selected_en_word_index]["EN"])
        if len(selected_words["EN"]) == 4:
            find_other_words = False
    return selected_words

Nous avons maintenant les données pour notre quiz.

Le contenue de l'app

Alors c'est bien joli tout ça, mais pour le moment notre application ressemble toujours à une page blanche qui dit bonjour. Il serait temps d'y mettre du contenu ! Commençons par y mettre deux ou trois phrases qui expliquent au joueur ce qu'il fait là.

selected_words_dict = select_quizz_words(words_dict=st.session_state["words_dict"])

st.title("Hello Learners :wave:!")
st.subheader("Let's make a small game. I give you vietnamese word, and you try to give me the good english translation. Let's go?")

st.write(f"What is the english translation of the word **{selected_words_dict['VN'][0]}**?")

C'est un début. D'abord, nous chargeons nos données de quiz dans une variable globale appelée selected_words_dict en utilisant la fonction écrite plus haut. Ensuite, nous expliquons rapidement les règles en affichant du texte très simplement via st.title() et st.subheader(), et nous proposons le mot vietnamien à traduire via st.write(). Vous pouvez trouver tous les détails des fonctions Streamlit qui permettent d'afficher du texte à l'écran ici.

Venons-en maintenant à proposer à l'utilisateur de l'application les 4 propositions de traduction en anglais. Il faut trouver un moyen de permettre au joueur d'interagir avec notre application en faisant un choix. J'ai décidé ici d'utiliser le composant Streamlit st.button(). Je vais afficher 4 boutons côte à côte horizontalement, chacun affichant une des 4 réponses possibles. L'utilisateur pourra alors choisir en cliquant sur l'un d'entre eux. Voici le code pour implémenter ces boutons :

# On 'copie' notre liste de propositions en anglais puis on la mélange comme un bon cocktail
selected_en_words_dict_shuffled = selected_words_dict["EN"].copy()
random.shuffle(selected_en_words_dict_shuffled)
# On crée un layout Streamlit composé de 4 colonnes.
col1, col2, col3, col4  =  st.columns(4)
# Et pour chacun d'entre eux, on y insère un bouton cliquable contenant la proposition
with col1:
    word = selected_en_words_dict_shuffled[0]
    st.button(label=word, key=word, on_click=check_result, args=[word], use_container_width=True)
with col2:
    word = selected_en_words_dict_shuffled[1]
    st.button(label=word, key=word, on_click=check_result, args=[word], use_container_width=True)
with col3:
    word = selected_en_words_dict_shuffled[2]
    st.button(label=word, key=word, on_click=check_result, args=[word], use_container_width=True)
with col4:
    word = selected_en_words_dict_shuffled[3]
    st.button(label=word, key=word, on_click=check_result, args=[word], use_container_width=True)

J'ai décidé de mélanger mon tableau de réponses, car sinon, rappelez-vous, nous nous retrouverions avec la bonne réponse toujours en première position, ce qui enlèverait pas mal de suspense à l'exercice...

Ensuite, nous utilisons le système de layout de Streamlit pour créer 4 colonnes. Pour chacune d'entre elles, nous ajoutons un bouton cliquable représentant une des réponses. À noter que :

label est le texte du bouton.
key est une clé utilisée par Streamlit pour avoir des boutons uniques.
on_click est une méthode de callback dont nous parlerons juste après.
args est un tableau de paramètres qui sera donné à la méthode de callback. Nous lui passons donc la proposition du bouton pour valider ou non le clic.
use_container_width est un simple booléen permettant au bouton de savoir qu'il peut prendre toute la largeur du conteneur dans lequel il est, ici la colonne (et je n'ai pas eu besoin de faire 5h de CSS pour réussir ça, ce qui est un miracle 🙏).

Cette partie du code peut sûrement être factorisée, mais je n'ai pas trouvé de moyen correct de le faire pour le moment. Ce sera peut-être l'objet d'un futur article.

Valider ou non le résultat

Notre application commence à avoir du contenu. Reste maintenant à valider le résultat du quiz. Comme énoncé plus haut, on va permettre au joueur de voir un score. On va aussi lui permettre de voir son meilleur score. Alors commençons par définir ces deux variables :

#... 
if  "words_dict"  not  in  st.session_state:
    st.session_state["words_dict"] = load_data()

if "score" not in st.session_state:
    st.session_state["score"] = 0

if "best_score" not in st.session_state:
    st.session_state["best_score"] = 0
# ...

Ensuite, attardons-nous sur la méthode de callback check_result passée plus haut à nos boutons :

def check_result(choice):
    if  choice == selected_words_dict["EN"][0]:
        st.session_state["score"] += 1
    else:
        if  st.session_state["score"] > st.session_state["best_score"]:
            st.session_state["best_score"] = st.session_state["score"]
        st.session_state["score"] =  0

Cette méthode est très simple. Si le choix de notre utilisateur correspond au premier élément de notre liste de propositions anglaises, alors c'est le jackpot, et on incrémente son score. Sinon, on met à jour le meilleur score si ce dernier est strictement inférieur au score actuel, puis on met ce dernier à 0.

Il ne nous reste plus qu'à afficher nos scores :

st.subheader(body=f"Your current score is: {st.session_state['score']}")
st.subheader(body=f"Your best score is: {st.session_state['best_score']}")

Et voila !

Il est temps de tester

En utilisant streamlit run app.py, on peut rapidement lancer et tester notre application.

Alors oui, ce n'est pas très joli, mais c'est quand même présentable, et cela sans une seule ligne de CSS. On se retrouve avec un petit jeu qui nous permet de travailler un peu notre vietnamien. L'objectif que l'on s'était fixé semble atteint ! Youpi 🎉!

Qu'est ce qu'il se passe sous le capeau ?

Il me semble important à ce niveau d'insister sur un mécanisme de Streamlit qu'il faut que tout le monde garde à l'esprit si vous voulez utiliser ce framework. Streamlit recharge ce petit script Python que nous venons d'implémenter à CHAQUE interaction que nous avons avec l'application. Dans notre cas, cela veut dire qu'à chaque fois que l'utilisateur clique sur un bouton, c'est tout le script qui est relancé. Cela explique plusieurs choses...

Cela explique pourquoi certaines de mes "variables", comme par exemple le dataset initial, sont chargées de cette manière :

if "words_dict" not in st.session_state:
    st.session_state["words_dict"] = load_data()

Ici, je joue avec le système de "cache" de Streamlit pour éviter d'avoir ces données rechargées à chaque interaction. C'est aussi ce qui me permet de conserver mon score malgré les rechargements successifs. En effet, à chaque re-run du script, Streamlit teste si le dictionnaire st.session_state contient un élément associé à "words_dict" (ce qui est le cas) et donc ne le recharge pas.

Cela explique enfin pourquoi la plupart des variables et instructions Streamlit sont réalisées au niveau du scope global du script. Par exemple, les propositions utilisées à chaque question sont chargées dans le scope global :

selected_words_dict = select_quizz_words(words_dict=st.session_state["words_dict"])

Je procède de cette manière car j'ai besoin que ce dictionnaire soit recréé à chaque fois, histoire de changer les propositions et de rendre le jeu, disons... intéressant ! Les boutons sont ainsi recréés aussi à chaque fois avec de nouvelles valeurs, ce qui est notre objectif.

En conclusion

Grâce à Streamlit, j'ai réussi à implémenter cette petite application en moins de 100 lignes de code et en une poignée d'heures. Alors certes, je ne pars pas de rien en Python, et l'application est loin d'être parfaite, tant sur le plan technique que visuel, mais je suis assez content du résultat. Je suis très agréablement surpris de la facilité d'utilisation du framework et du résultat.

Le fait que le script soit entièrement rechargé à chaque fois me fait penser que le framework doit avoir des limitations pour des applications plus complexes. De plus, les composants disponibles, bien que nombreux, ne couvrent pas tous les cas d'utilisation d'applications plus sophistiquées. Mais pour des petits prototypes et des applications simples comme celle présentée dans cet article, ça fait largement l'affaire.

Concernant mon application, j'aimerais apporter quelques améliorations dans le futur :

Ajouter un message vert en cas de bon résultat ou rouge en cas d'erreur, expliquant la bonne réponse.
Permettre à l'utilisateur de choisir le sens de l'exercice : du vietnamien à l'anglais ou de l'anglais au vietnamien.
Permettre à l'utilisateur de choisir entre un exercice de traduction de mots ou de phrases.
Déployer mon application en ligne.
Faire quelques factorisations du code.
Ajouter d'autres fonctionnalités qui me viendront en tête plus tard, je l'espère 🤔.

Cela fera sûrement l'objet de futurs articles.

Ceci étant dit, je vais continuer à explorer ce framework qui répond à l'une de mes problématiques : réussir à créer des applications simples en Python sans avoir besoin de passer plusieurs jours à apprendre à utiliser un framework complexe.

À bientôt pour de nouvelles aventures dans le monde simple et efficace de Streamlit. N'hésitez pas à consulter le repo Gitlab pour retrouver le code de l'article.

PS: Cet article a été corrigé grâce à L'IA.