Créer un module --help en Python

Lorsque vous développez un script Python, il est essentiel de fournir une aide pour connaître les arguments et les options disponibles pour votre script et également mieux comprendre son fonctionnement.
Dans cet article, nous allons voir comment mettre en place un module --help et -h pour une section d'aide intégrée dans vos scripts Python.

Contexte

Prenons le cas d'un script Python qui effectue des simples requêtes API. Nous souhaitons positionner l'URL que nous allons requêter en argument du script Python ainsi que de manière optionnelle, préciser la méthode HTTP utilisée. Un exemple d'exécution du script donnerait cela au final :

python3 script.py --url https://mon-domaine.com/mon-url --method POST

Ce qui nous intéresse le plus c'est comment afficher une brève description de ce script, ses arguments et options possibles.

L'exécution de l'argument --help ou -h  comme ceci :

python3 script.py --help

Devrait donner cela :

usage: script.py [-h] [--url URL] [--method METHOD]

Simples requêtes API

optional arguments:
  -h, --help            show this help message and exit
  --url URL, -u URL     URL au format https://domaine.com/endpoint à requêter.
  --method METHOD, -m METHOD
                        Méthode HTTP (GET,POST etc...)

Passons à la suite et regardons comment créer un module --help en Python !

Les arguments et options

Afin d'utiliser les arguments et les options en langage Python, il faut utiliser le module argparse.
Commençons par créer un script nommé script.py et importons les modules nécessaire en ajoutant les lignes suivantes :

#!/usr/bin/env python3
import argparse
import requests

Nous allons ensuite créer une première fonction Python nommée make_api_requests afin d'effectuer la requête API comme ceci :

def make_api_request(url, method):
    response = requests.request(method, url)
    print(response.json())

Jusqu'ici, rien de compliqué, la fonction utilise le module Python requests et utilise deux variables en paramètres : method qui précise la méthode HTTP ainsi que la variable url.

La seconde fonction nommée arguments correspond à ceci :

def arguments():
    parser = argparse.ArgumentParser(description='Simples requêtes API')
    parser.add_argument('--url', '-u', type=str, required=True, help='URL au format https://domaine.com/endpoint à requêter.')
    parser.add_argument('--method', '-m', type=str, default='GET', required=False, help='Méthode HTTP (GET, POST, etc...)')
    args = parser.parse_args()
    make_api_request(args.url, args.method)

arguments()

Décomposons notre fonction Python :

• parser = argparse.ArgumentParser(description='Simples requêtes API') : Correspond à la description du script.
• parser.add_argument('--url', '-u', type=str, required=True, help='URL au format https://domaine.com/endpoint à requêter.') : Nous précisons ici les arguments, nous forçons leur type, si les arguments sont requis ou non, puis une description des arguments.
• parser.add_argument('--method', '-m', type=str, default='GET', required=False, help='Méthode HTTP (GET, POST, etc...)') : Même chose que l'argument précédent sauf que nous ajoutons default afin d'avoir une valeur par défaut si l'argument n'est pas précisé !
• args = parser.parse_args() : Analyse les arguments fournis
• make_api_request(args.url, args.method) : Appelle la fonction précédente avec les deux arguments.

Utilisation

Pour afficher l'aide, il suffit d’exécuter le script avec l'argument --help ou -h comme ceci :

python3 script.py --help
# OU
python3 script.py -h

Et pour utiliser le script Python en fournissant les arguments :

python script.py --url https://mon-domaine.com/endpoint --method GET

Le code Python final donne ceci :

#!/usr/bin/env python3
import argparse
import requests

def make_api_request(url, method):
    response = requests.request(method, url)
    print(response.json())

def arguments():
    parser = argparse.ArgumentParser(description='Simples requêtes API')
    parser.add_argument('--url', '-u', type=str, required=True, help='URL au format https://domaine.com/endpoint à requêter.')
    parser.add_argument('--method', '-m', type=str, default='GET', required=False, help='Méthode HTTP (GET, POST, etc...)')
    args = parser.parse_args()
    make_api_request(args.url, args.method)

arguments()