Programmation CGI en Python : Un guide complet pour créer des interfaces web

Dans le monde du développement web moderne, dominé par des frameworks sophistiqués comme Django, Flask et FastAPI, le terme CGI (Common Gateway Interface) peut sonner comme un écho d'une époque révolue. Cependant, ignorer le CGI serait négliger une technologie fondamentale qui non seulement a alimenté les débuts du web dynamique, mais qui continue également d'offrir des leçons précieuses et des applications pratiques aujourd'hui. Comprendre le CGI, c'est comme comprendre le fonctionnement d'un moteur avant d'apprendre à conduire une voiture ; cela fournit une connaissance profonde et fondamentale de l'interaction client-serveur qui sous-tend toutes les applications web.

Ce guide complet démystifiera la programmation CGI en Python. Nous l'explorerons à partir des principes de base, vous montrant comment construire des interfaces web dynamiques et interactives en utilisant uniquement les bibliothèques standard de Python. Que vous soyez un étudiant apprenant les fondements du web, un développeur travaillant avec des systèmes existants, ou quelqu'un opérant dans un environnement contraint, ce guide vous dotera des compétences nécessaires pour tirer parti de cette technologie puissante et simple.

Qu'est-ce que le CGI et pourquoi est-il toujours pertinent ?

L'Common Gateway Interface (CGI) est un protocole standard qui définit comment un serveur web peut interagir avec des programmes externes, souvent appelés scripts CGI. Lorsqu'un client (comme un navigateur web) demande une URL spécifique associée à un script CGI, le serveur web ne se contente pas de servir un fichier statique. Au lieu de cela, il exécute le script et renvoie la sortie du script au client. Cela permet de générer du contenu dynamique basé sur les entrées de l'utilisateur, les requêtes de base de données, ou toute autre logique que le script contient.

Imaginez-le comme une conversation :

• Client au Serveur : "J'aimerais voir la ressource à `/cgi-bin/process-form.py` et voici quelques données d'un formulaire que j'ai rempli."
• Serveur au Script CGI : "Une requête est arrivée pour toi. Voici les données du client et des informations sur la requête (comme son adresse IP, son navigateur, etc.). S'il te plaît, exécute-toi et donne-moi la réponse à renvoyer."
• Script CGI au Serveur : "J'ai traité les données. Voici les en-têtes HTTP et le contenu HTML à retourner."
• Serveur au Client : "Voici la page dynamique que vous avez demandée."

Bien que les frameworks modernes aient abstrait cette interaction brute, les principes sous-jacents restent les mêmes. Alors, pourquoi apprendre le CGI à l'ère des frameworks de haut niveau ?

• Compréhension fondamentale : Cela vous oblige à apprendre les mécanismes de base des requêtes et réponses HTTP, y compris les en-têtes, les variables d'environnement et les flux de données, sans aucune magie. Cette connaissance est inestimable pour le débogage et l'optimisation des performances de n'importe quelle application web.
• Simplicité : Pour une tâche unique et isolée, écrire un petit script CGI peut être beaucoup plus rapide et simple que de mettre en place un projet de framework entier avec son routage, ses modèles et ses contrôleurs.
• Indépendant du langage : Le CGI est un protocole, pas une bibliothèque. Vous pouvez écrire des scripts CGI en Python, Perl, C++, Rust, ou tout autre langage capable de lire depuis l'entrée standard et d'écrire sur la sortie standard.
• Systèmes existants et environnements contraints : De nombreuses applications web plus anciennes et certains environnements d'hébergement mutualisé dépendent du CGI ou ne fournissent que son support. Savoir comment travailler avec peut être une compétence essentielle. C'est aussi courant dans les systèmes embarqués avec des serveurs web simples.

Configurer votre environnement CGI

Avant de pouvoir exécuter un script CGI Python, vous avez besoin d'un serveur web configuré pour l'exécuter. C'est l'obstacle le plus courant pour les débutants. Pour le développement et l'apprentissage, vous pouvez utiliser des serveurs populaires comme Apache ou même le serveur intégré de Python.

Prérequis : Un serveur web

La clé est de dire à votre serveur web que les fichiers dans un répertoire spécifique (traditionnellement nommé `cgi-bin`) ne doivent pas être servis comme du texte mais doivent être exécutés, leur sortie étant envoyée au navigateur. Bien que les étapes de configuration spécifiques varient, les principes généraux sont universels.

• Apache : Vous devez généralement activer `mod_cgi` et utiliser une directive `ScriptAlias` dans votre fichier de configuration pour mapper un chemin d'URL à un répertoire du système de fichiers. Vous avez également besoin d'une directive `Options +ExecCGI` pour ce répertoire afin de permettre l'exécution.
• Nginx : Nginx n'a pas de module CGI direct comme Apache. Il utilise généralement un pont comme FCGIWrap pour exécuter les scripts CGI.
• `http.server` de Python : Pour des tests locaux simples, vous pouvez utiliser le serveur web intégré de Python, qui prend en charge le CGI d'origine. Vous pouvez le démarrer depuis votre ligne de commande avec : `python3 -m http.server --cgi 8000`. Cela démarrera un serveur sur le port 8000 et traitera tous les scripts dans un sous-répertoire `cgi-bin/` comme étant exécutables.

Votre premier "Hello, World!" en CGI Python

Un script CGI a un format de sortie très spécifique. Il doit d'abord imprimer tous les en-têtes HTTP nécessaires, suivis d'une seule ligne vide, puis du corps du contenu (par exemple, du HTML).

Créons notre premier script. Enregistrez le code suivant sous le nom `hello.py` dans votre répertoire `cgi-bin`.

            
#!/usr/bin/env python3
# -*- coding: UTF-8 -*-

# 1. L'en-tête HTTP
# L'en-tête le plus important est Content-Type, qui indique au navigateur quel type de données attendre.
print("Content-Type: text/html;charset=utf-8")

# 2. La ligne vide
# Une seule ligne vide est cruciale. Elle sépare les en-têtes du corps du contenu.
print()

# 3. Le corps du contenu
# C'est le contenu HTML réel qui sera affiché dans le navigateur.
print("<h1>Bonjour, le monde !</h1>")
print("<p>Ceci est mon premier script CGI en Python.</p>")
print("<p>Il fonctionne sur un serveur web global, accessible à tous !</p>")

            

              
                Copy
              
            
          

Décortiquons cela :

• #!/usr/bin/env python3 : C'est la ligne "shebang". Sur les systèmes de type Unix (Linux, macOS), elle indique au système d'exploitation d'exécuter ce fichier en utilisant l'interpréteur Python 3.
• print("Content-Type: text/html;charset=utf-8") : C'est l'en-tête HTTP. Il informe le navigateur que le contenu suivant est du HTML et est encodé en UTF-8, ce qui est essentiel pour prendre en charge les caractères internationaux.
• print() : Ceci imprime la ligne vide obligatoire qui sépare les en-têtes du corps. L'oublier est une erreur très courante.
• Les dernières instructions `print` produisent le HTML que l'utilisateur verra.

Enfin, vous devez rendre le script exécutable. Sur Linux ou macOS, vous exécuteriez cette commande dans votre terminal : `chmod +x cgi-bin/hello.py`. Maintenant, lorsque vous accédez à `http://votre-adresse-serveur/cgi-bin/hello.py` dans votre navigateur, vous devriez voir votre message "Bonjour, le monde !".

Le cœur du CGI : les variables d'environnement

Comment le serveur web communique-t-il les informations sur la requête à notre script ? Il utilise les variables d'environnement. Ce sont des variables définies par le serveur dans l'environnement d'exécution du script, fournissant une mine d'informations sur la requête entrante et le serveur lui-même. C'est la "Gateway" (passerelle) dans Common Gateway Interface.

Variables d'environnement clés du CGI

Le module `os` de Python nous permet d'accéder à ces variables. Voici quelques-unes des plus importantes :

• REQUEST_METHOD : La méthode HTTP utilisée pour la requête (par ex., 'GET', 'POST').
• QUERY_STRING : Contient les données envoyées après le '?' dans une URL. C'est ainsi que les données sont passées dans une requête GET.
• CONTENT_LENGTH : La longueur des données envoyées dans le corps de la requête, utilisée pour les requêtes POST.
• CONTENT_TYPE : Le type MIME des données dans le corps de la requête (par ex., 'application/x-www-form-urlencoded').
• REMOTE_ADDR : L'adresse IP du client qui effectue la requête.
• HTTP_USER_AGENT : La chaîne user-agent du navigateur du client (par ex., 'Mozilla/5.0...').
• SERVER_NAME : Le nom d'hôte ou l'adresse IP du serveur.
• SERVER_PROTOCOL : Le protocole utilisé, tel que 'HTTP/1.1'.
• SCRIPT_NAME : Le chemin vers le script en cours d'exécution.

Exemple pratique : Un script de diagnostic

Créons un script qui affiche toutes les variables d'environnement disponibles. C'est un outil incroyablement utile pour le débogage. Enregistrez-le sous `diagnostics.py` dans votre répertoire `cgi-bin` et rendez-le exécutable.

            
#!/usr/bin/env python3
import os

print("Content-Type: text/html\n")

print("<h1>Variables d'environnement CGI</h1>")
print("<p>Ce script affiche toutes les variables d'environnement transmises par le serveur web.</p>")

print("<table border='1' style='border-collapse: collapse; width: 80%;'>")
print("<tr><th>Variable</th><th>Valeur</th></tr>")

# Itérer à travers toutes les variables d'environnement et les imprimer dans un tableau
for key, value in sorted(os.environ.items()):
    print(f"<tr><td>{key}</td><td>{value}</td></tr>")

print("</table>")

            

              
                Copy
              
            
          

Lorsque vous exécutez ce script, vous verrez un tableau détaillé répertoriant chaque information que le serveur a transmise à votre script. Essayez d'ajouter une chaîne de requête à l'URL (par ex., `.../diagnostics.py?name=test&value=123`) et observez comment la variable `QUERY_STRING` change.

Gérer les entrées utilisateur : Formulaires et données

L'objectif principal du CGI est de traiter les entrées des utilisateurs, généralement à partir de formulaires HTML. La bibliothèque standard de Python fournit des outils robustes pour cela. Voyons comment gérer les deux principales méthodes HTTP : GET et POST.

Tout d'abord, créons un formulaire HTML simple. Enregistrez ce fichier sous `feedback_form.html` dans votre répertoire web principal (pas le répertoire cgi-bin).

            
<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <title>Formulaire de feedback global</title>
</head>
<body>
    <h1>Envoyez vos commentaires</h1>
    <p>Ce formulaire démontre les méthodes GET et POST.</p>

    <h2>Exemple de méthode GET</h2>
    <form action="/cgi-bin/form_handler.py" method="GET">
        <label for="get_name">Votre nom :</label>
        <input type="text" id="get_name" name="username">
        <br/><br/>
        <label for="get_topic">Sujet :</label>
        <input type="text" id="get_topic" name="topic">
        <br/><br/>
        <input type="submit" value="Envoyer avec GET">
    </form>

    <hr>

    <h2>Exemple de méthode POST (Plus de fonctionnalités)</h2>
    <form action="/cgi-bin/form_handler.py" method="POST">
        <label for="post_name">Votre nom :</label>
        <input type="text" id="post_name" name="username">
        <br/><br/>

        <label for="email">Votre email :</label>
        <input type="email" id="email" name="email">
        <br/><br/>

        <p>Êtes-vous satisfait de notre service ?</p>
        <input type="radio" id="happy_yes" name="satisfaction" value="yes">
        <label for="happy_yes">Oui</label><br>
        <input type="radio" id="happy_no" name="satisfaction" value="no">
        <label for="happy_no">Non</label><br>
        <input type="radio" id="happy_neutral" name="satisfaction" value="neutral">
        <label for="happy_neutral">Neutre</label>
        <br/><br/>

        <p>Quels produits vous intéressent ?</p>
        <input type="checkbox" id="prod_a" name="products" value="Product A">
        <label for="prod_a">Produit A</label><br>
        <input type="checkbox" id="prod_b" name="products" value="Product B">
        <label for="prod_b">Produit B</label><br>
        <input type="checkbox" id="prod_c" name="products" value="Product C">
        <label for="prod_c">Produit C</label>
        <br/><br/>

        <label for="comments">Commentaires :</label><br>
        <textarea id="comments" name="comments" rows="4" cols="50"></textarea>
        <br/><br/>

        <input type="submit" value="Envoyer avec POST">
    </form>
</body>
</html>

            

              
                Copy
              
            
          

Ce formulaire soumet ses données à un script nommé `form_handler.py`. Maintenant, nous devons écrire ce script. Bien que vous puissiez analyser manuellement la `QUERY_STRING` pour les requêtes GET et lire depuis l'entrée standard pour les requêtes POST, c'est sujet aux erreurs et complexe. À la place, nous devrions utiliser le module `cgi` intégré de Python, qui est conçu exactement pour cela.

La classe `cgi.FieldStorage` est l'héroïne ici. Elle analyse la requête entrante et fournit une interface de type dictionnaire pour les données du formulaire, qu'elles aient été envoyées via GET ou POST.

Voici le code pour `form_handler.py`. Enregistrez-le dans votre répertoire `cgi-bin` et rendez-le exécutable.

            
#!/usr/bin/env python3
import cgi
import html

# Créer une instance de FieldStorage
# Cet unique objet gère les requêtes GET et POST de manière transparente
form = cgi.FieldStorage()

# Commencer à imprimer la réponse
print("Content-Type: text/html\n")

print("<h1>Soumission de formulaire reçue</h1>")
print("<p>Merci pour vos commentaires. Voici les données que nous avons reçues :</p>")

# Vérifier si des données de formulaire ont été soumises
if not form:
    print("<p><em>Aucune donnée de formulaire n'a été soumise.</em></p>")
else:
    print("<table border='1' style='border-collapse: collapse;'>")
    print("<tr><th>Nom du champ</th><th>Valeur(s)</th></tr>")

    # Itérer à travers toutes les clés des données du formulaire
    for key in form.keys():
        # IMPORTANT : Assainir les entrées utilisateur avant de les afficher pour prévenir les attaques XSS.
        # html.escape() convertit les caractères comme <, >, & en leurs entités HTML.
        sanitized_key = html.escape(key)
        
        # La méthode .getlist() est utilisée pour gérer les champs qui peuvent avoir plusieurs valeurs,
        # comme les cases à cocher. Elle retourne toujours une liste.
        values = form.getlist(key)
        
        # Assainir chaque valeur dans la liste
        sanitized_values = [html.escape(v) for v in values]
        
        # Joindre la liste des valeurs en une chaîne séparée par des virgules pour l'affichage
        display_value = ", ".join(sanitized_values)
        
        print(f"<tr><td><strong>{sanitized_key}</strong></td><td>{display_value}</td></tr>")

    print("</table>")

# Exemple d'accès direct à une seule valeur
# Utilisez form.getvalue('key') pour les champs dont vous attendez une seule valeur.
# Il retourne None si la clé n'existe pas.
username = form.getvalue("username")
if username:
    print(f"<h2>Bienvenue, {html.escape(username)} !</h2>")


            

              
                Copy
              
            
          

Points clés à retenir de ce script :

1. `import cgi` et `import html` : Nous importons les modules nécessaires. `cgi` pour l'analyse du formulaire et `html` pour la sécurité.
2. `form = cgi.FieldStorage()` : Cette seule ligne fait tout le gros du travail. Elle vérifie les variables d'environnement (`REQUEST_METHOD`, `CONTENT_LENGTH`, etc.), lit le flux d'entrée approprié et analyse les données dans un objet facile à utiliser.
3. La sécurité d'abord (`html.escape`) : Nous n'imprimons jamais les données soumises par l'utilisateur directement dans notre HTML. Le faire crée une vulnérabilité de type Cross-Site Scripting (XSS). La fonction `html.escape()` est utilisée pour neutraliser tout HTML ou JavaScript malveillant qu'un attaquant pourrait soumettre.
4. `form.keys()` : Nous pouvons itérer sur tous les noms de champs soumis.
5. `form.getlist(key)` : C'est le moyen le plus sûr de récupérer les valeurs. Comme un formulaire peut soumettre plusieurs valeurs pour le même nom (par ex., des cases à cocher), `getlist()` retourne toujours une liste. Si le champ n'avait qu'une seule valeur, ce sera une liste avec un seul élément.
6. `form.getvalue(key)` : C'est un raccourci pratique lorsque vous n'attendez qu'une seule valeur. Il retourne la valeur unique directement, ou s'il y a plusieurs valeurs, il retourne une liste. Il retourne `None` si la clé n'est pas trouvée.

Maintenant, ouvrez `feedback_form.html` dans votre navigateur, remplissez les deux formulaires et voyez comment le script gère les données différemment mais efficacement à chaque fois.

Techniques CGI avancées et meilleures pratiques

Gestion de l'état : les cookies

HTTP est un protocole sans état. Chaque requête est indépendante, et le serveur n'a aucune mémoire des requêtes précédentes du même client. Pour créer une expérience persistante (comme un panier d'achat ou une session connectée), nous devons gérer l'état. La manière la plus courante de le faire est avec les cookies.

Un cookie est un petit morceau de données que le serveur envoie au navigateur du client. Le navigateur renvoie ensuite ce cookie avec chaque requête ultérieure au même serveur. Un script CGI peut définir un cookie en imprimant un en-tête `Set-Cookie` et peut lire les cookies entrants à partir de la variable d'environnement `HTTP_COOKIE`.

Créons un simple script de compteur de visiteurs. Enregistrez-le sous `cookie_counter.py`.

            
#!/usr/bin/env python3
import os
import http.cookies

# Charger les cookies existants depuis la variable d'environnement
cookie = http.cookies.SimpleCookie(os.environ.get("HTTP_COOKIE"))

visit_count = 0
# Essayer d'obtenir la valeur de notre cookie 'visit_count'
if 'visit_count' in cookie:
    try:
        # La valeur du cookie est une chaîne, donc nous devons la convertir en entier
        visit_count = int(cookie['visit_count'].value)
    except ValueError:
        # Gérer les cas où la valeur du cookie n'est pas un nombre valide
        visit_count = 0

# Incrémenter le compteur de visites
visit_count += 1

# Définir le cookie pour la réponse. Cela sera envoyé comme un en-tête 'Set-Cookie'.
# Nous définissons la nouvelle valeur pour 'visit_count'.
cookie['visit_count'] = visit_count

# Vous pouvez également définir des attributs de cookie comme la date d'expiration, le chemin, etc.
# cookie['visit_count']['expires'] = '...'
# cookie['visit_count']['path'] = '/' 

# Imprimer d'abord l'en-tête Set-Cookie
print(cookie.output())

# Puis imprimer l'en-tête Content-Type normal
print("Content-Type: text/html\n")

# Et enfin le corps HTML
print("<h1>Compteur de visiteurs basé sur les cookies</h1>")
print(f"<p>Bienvenue ! C'est votre visite numéro : <strong>{visit_count}</strong>.</p>")
print("<p>Actualisez cette page pour voir le compteur augmenter.</p>")
print("<p><em>(Votre navigateur doit avoir les cookies activés pour que cela fonctionne.)</em></p>")


            

              
                Copy
              
            
          

Ici, le module `http.cookies` de Python simplifie l'analyse de la chaîne `HTTP_COOKIE` et la génération de l'en-tête `Set-Cookie`. Chaque fois que vous visitez cette page, le script lit l'ancien compte, l'incrémente et renvoie la nouvelle valeur pour qu'elle soit stockée dans votre navigateur.

Débogage des scripts CGI : le module `cgitb`

Quand un script CGI échoue, le serveur renvoie souvent un message générique "500 Internal Server Error", ce qui n'est pas utile pour le débogage. Le module `cgitb` (CGI Traceback) de Python est une véritable bouée de sauvetage. En l'activant en haut de votre script, toute exception non gérée générera un rapport détaillé et formaté directement dans le navigateur.

Pour l'utiliser, ajoutez simplement ces deux lignes au début de votre script :

            
import cgitb
cgitb.enable()

            

              
                Copy
              
            
          

Avertissement : Bien que `cgitb` soit inestimable pour le développement, vous devriez le désactiver ou le configurer pour journaliser dans un fichier dans un environnement de production. Exposer des traces d'exécution détaillées au public peut révéler des informations sensibles sur la configuration et le code de votre serveur.

Téléchargements de fichiers avec CGI

L'objet `cgi.FieldStorage` gère également de manière transparente les téléchargements de fichiers. Le formulaire HTML doit être configuré avec `method="POST"` et, de manière cruciale, `enctype="multipart/form-data"`.

Créons un formulaire de téléchargement de fichiers, `upload.html` :

            
<!DOCTYPE html>
<html lang="fr">
<head>
    <title>Téléchargement de fichier</title>
</head>
<body>
    <h1>Télécharger un fichier</h1>
    <form action="/cgi-bin/upload_handler.py" method="POST" enctype="multipart/form-data">
        <label for="userfile">Sélectionnez un fichier à télécharger :</label>
        <input type="file" id="userfile" name="userfile">
        <br/><br/>
        <input type="submit" value="Télécharger le fichier">
    </form>
</body>
</html>

            

              
                Copy
              
            
          

Et maintenant le gestionnaire, `upload_handler.py`. Note : Ce script nécessite un répertoire nommé `uploads` au même emplacement que le script, et le serveur web doit avoir la permission d'y écrire.

            
#!/usr/bin/env python3
import cgi
import os
import html

# Activer le rapport d'erreurs détaillé pour le débogage
import cgitb
cgitb.enable()

print("Content-Type: text/html\n")

print("<h1>Gestionnaire de téléchargement de fichiers</h1>")

# Répertoire où les fichiers seront sauvegardés. SÉCURITÉ : Ce devrait être un répertoire sécurisé et non accessible via le web.
upload_dir = './uploads/'

# Créer le répertoire s'il n'existe pas
if not os.path.exists(upload_dir):
    os.makedirs(upload_dir, exist_ok=True)
    # IMPORTANT : Définir les bonnes permissions. Dans un scénario réel, ce serait plus restrictif.
    # os.chmod(upload_dir, 0o755) 

form = cgi.FieldStorage()

# Obtenir l'élément fichier du formulaire. 'userfile' est le 'name' du champ de saisie.
file_item = form['userfile']

# Vérifier si un fichier a bien été téléchargé
if file_item.filename:
    # SÉCURITÉ : Ne jamais faire confiance au nom de fichier fourni par l'utilisateur.
    # Il pourrait contenir des caractères de chemin comme '../' (attaque par traversée de répertoire).
    # Nous utilisons os.path.basename pour supprimer toute information de répertoire.
    fn = os.path.basename(file_item.filename)
    
    # Créer le chemin complet pour sauvegarder le fichier
    file_path = os.path.join(upload_dir, fn)
    
    try:
        # Ouvrir le fichier en mode écriture binaire et écrire les données téléchargées
        with open(file_path, 'wb') as f:
            f.write(file_item.file.read())
        message = f"Le fichier '{html.escape(fn)}' a été téléchargé avec succès !"
        print(f"<p style='color: green;'>{message}</p>")
    except IOError as e:
        message = f"Erreur lors de la sauvegarde du fichier : {e}. Vérifiez les permissions du serveur pour le répertoire '{upload_dir}'."
        print(f"<p style='color: red;'>{message}</p>")
else:
    message = 'Aucun fichier n\'a été téléchargé.'
    print(f"<p style='color: orange;'>{message}</p>")

print("<a href='/upload.html'>Télécharger un autre fichier</a>")

            

              
                Copy
              
            
          

Sécurité : la préoccupation primordiale

Parce que les scripts CGI sont des programmes exécutables directement exposés à Internet, la sécurité n'est pas une option, c'est une exigence. Une seule erreur peut conduire à la compromission du serveur.

Validation et assainissement des entrées (Prévention du XSS)

Comme nous l'avons déjà vu, vous ne devez jamais faire confiance aux entrées de l'utilisateur. Supposez toujours qu'elles sont malveillantes. Lorsque vous affichez des données fournies par l'utilisateur dans une page HTML, échappez-les toujours avec `html.escape()` pour prévenir les attaques de type Cross-Site Scripting (XSS). Un attaquant pourrait sinon injecter des balises `