Comment utiliser argparse pour analyser les paramètres des scripts python

Objectif

Apprenez à utiliser le module argparse pour analyser facilement les paramètres des scripts python

Exigences

Connaissance de base de python et des concepts orientés objet

Difficulté

FACILE

Conventions

# – nécessite que les commandes Linux données soient exécutées avec les privilèges root, soit
directement en tant qu’utilisateur root, soit en utilisant la commande sudo
$ – nécessite que des commandes Linux données soient exécutées en tant qu’utilisateur régulier non privilégié

Introduction

Dans un article précédent, nous avons vu comment analyser les arguments de ligne de commande à l’aide de getopts dans le contexte des scripts bash (vous pouvez trouver l’article ici). Nous allons maintenant voir comment accomplir la même tâche, de manière plus puissante, lors de l’écriture d’un script python.

Initialiser l’analyseur

Pour atteindre notre objectif, nous allons utiliser un module python appelé argparse. Il nous permettra de spécifier nos paramètres de ligne de commande et générera automatiquement le message d’aide du script basé sur ceux-ci. Alors commençons, nous appellerons notre script « printerscript.py » :

#!/usr/bin/env python
import argparse

if __name__ == '__main__':
    # Initialize the parser
    parser = argparse.ArgumentParser(
        description="simple script to demonstrate argparse usage"
    )

La première chose à faire est, évidemment, d’importer le module argparse. Après cela, nous procédons à l’initialisation de l’analyseur. Le mot-clé description, passé au constructeur de l’analyseur, est facultatif, mais nous permet d’ajouter une brève description du script lorsque le message d’aide est affiché.

Il y a d’autres mots-clés que nous pouvons utiliser pour personnaliser davantage le comportement de l’analyseur : par exemple, en fournissant le mot-clé epilog, nous pouvons fournir un texte à afficher après le message d’aide principal, ou en utilisant prog, nous pouvons spécifier le nom du programme à afficher dans le même contexte (par défaut sys.argv[0] est utilisé).

Ajout d’un paramètre positionnel

Il est maintenant temps d’ajouter notre premier paramètre de position au script. Dans ce cas, nous allons ajouter le paramètre « printme », c’est-à-dire la chaîne qui sera imprimée par notre script de test. Nous accomplissons cela en utilisant la méthode add_argument() de l’objet parser que nous avons initialisé ci-dessus :

parser.add_argument('printme', help="The string to be printed")

Le premier argument que nous avons fourni à la méthode est le nom du paramètre, et le second, facultatif, est help. À l’aide de ce mot-clé, nous pouvons spécifier la description du paramètre qui sera affiché dans le message d’aide généré par argparse.

Il est important de noter que par défaut les paramètres seront considérés comme des chaînes de caractères : pour spécifier un autre type de données, il faut utiliser le mot-clé type. Par exemple, si nous voulions que notre argument soit converti en entier, nous l’aurions spécifié de cette façon :

parser.add_argument('printme', type=int)

Une fois que nous avons ajouté notre paramètre, nous devons invoquer la méthode parse_args() de l’objet parser. Cette méthode renverra une instance de l’argument argparse. Classe d’espace de noms : les paramètres analysés seront stockés en tant qu’attributs de cette instance. Enfin, nous pouvons ajouter une ligne pour imprimer la variable. À ce stade, le script devrait ressembler à ceci :

#!/usr/bin/env python
import argparse

if __name__ == '__main__':
    # Initialize the parser
    parser = argparse.ArgumentParser(
        description="simple script to demonstrate argparse usage"
    )

    # Add the positional parameter
    parser.add_argument('printme', help="The string to be printed")

    # Parse the arguments
    arguments = parser.parse_args()

    # Finally print the passed string
    print(arguments.printme)

Exécutons-le :

./printerscript.py "hello world!"
hello world!

La corde que nous avons passée a été imprimée comme prévu. Mais que se passerait-il si nous ne le fournissions pas ? Le message d’aide aurait été affiché, décrivant l’utilisation correcte du script :

./printerscript.py
usage: printerscript.py [-h] printme
printerscript.py: error: too few arguments

Ajout d’un paramètre facultatif

Les paramètres optionnels ne sont pas obligatoires pour l’utilisation du script, mais ils sont utilisés pour modifier son comportement. Argparse les reconnaît lorsqu’il voit que des traits d’union sont fournis dans la description, par exemple :

parser.add_argument(
    '-r', '--repeat',
    help="number of times to print the string",
    type=int,
    default=1
)

Le nom du paramètre est précédé de traits d’union (nous pouvons spécifier à la fois la version courte et la version longue du paramètre). Dans ce cas, nous avons ajouté le paramètre optionnel --repeat qui spécifie combien de fois la chaîne doit être imprimée. Nous avons également utilisé le mot-clé par défaut. C’est vraiment important, car grâce à lui, nous pouvons spécifier la valeur que l’attribut prendra si le paramètre n’est pas explicitement fourni lors de l’appel du script.

À ce stade, pour vérifier que le paramètre fonctionne comme prévu, tout ce que nous avons à faire est de modifier notre script afin de répéter l’impression de la chaîne pour le nombre de fois spécifié, donc nous enfermons la fonction print() dans une petite boucle for :

for i in range(0, arguments.repeat):
    print(arguments.printme)

Essayons-le :

./printerscript.py --repeat=3 "hello world!"
hello world!
hello world!
hello world!

Tout s’est passé comme prévu. De plus, le message d’aide a également été mis à jour et comprend désormais une description du nouveau paramètre facultatif :

./printerscript.py --help
usage: printerscript.py [-h] [-r REPEAT] printme

simple script to demonstrate argparse usage

positional arguments:
  printme               The string to be printed

optional arguments:
  -h, --help            show this help message and exit
  -r REPEAT, --repeat REPEAT
                        number of times to print the string

Comme dit ci-dessus, lorsque argparse voit qu’un paramètre est préfixé par des traits d’union, il suppose qu’il est facultatif. Pour modifier ce comportement et le « déclarer » comme obligatoire, nous pouvons utiliser le mot-clé required lors de l’ajout du paramètre, sous la forme : required=True.

Le mot-clé « dest »

Normalement, la valeur fournie pour un paramètre sera stockée sous la forme d’un attribut nommé d’après le premier argument donné à la méthode add_argument() dans le cas de paramètres positionnels, ou la première option de chaîne longue (sans les traits d’union : la chaîne –repeat deviendra l’attribut 'repeat') dans le cas de paramètres optionnels. Dans ce dernier cas, si une option de chaîne longue n’est pas disponible, la courte est utilisée. Le mot-clé dest nous permet de spécifier un nom d’attribut personnalisé au lieu de nous fier à ce comportement.

Le mot-clé « action »

Lorsque vous utilisez la méthode add_argument(), nous pouvons spécifier le comportement à utiliser pour les options analysées en utilisant un autre mot-clé : action. L’action par défaut consiste à attribuer la valeur passée à l’attribut correspondant. Dans le cas de notre petit script, par exemple, la valeur fournie pour le paramètre --repeat sera attribuée à l’attribut 'repeat' de l’argparse. Namespace une fois que les arguments sont analysés. Cependant, ce comportement peut également être modifié. Décrivons brièvement les autres options principales :

store_true et store_false

En spécifiant cette action, nous disons essentiellement que le paramètre ne nécessite pas d’argument : True sera attribué comme valeur à l’attribut correspondant si l’option est fournie, ou False dans le cas contraire. store_true et store_false fourniront respectivement une valeur par défaut True et False.

magasin_const

Ceci est similaire à l’option ci-dessus, mais en l’utilisant comme valeur pour le mot-clé action, au lieu d’un booléen, une valeur constante sera attribuée à l’attribut si le paramètre est utilisé. Cette valeur est elle-même spécifiée à l’aide du mot-clé const :

parser.add_argument("--random-option", action="store_const", const=yourvalue)

ajouter

Si append est utilisé comme valeur du mot-clé action, une liste sera créée et référencée par l’attribut de paramètre correspondant : la valeur fournie y sera ajoutée. Ceci est utile dans le cas où le paramètre est fourni plus d’une fois :

parser.add_argument('--random-option', action="append")

ajouter_const

Tout comme lors de l’utilisation de append, une valeur sera ajoutée à la liste référencée par l’attribut parameter. La différence est que dans ce cas, la valeur n’est pas fournie par l’utilisateur, mais déclarée lors de l’ajout du paramètre, encore une fois, via le mot-clé const :

parser.add_argument(
    '--randomoption',
    action="append_const",
    const="the value to append"
)

Paramètres optionnels mutuellement exclusifs

Dans certaines situations, nous pouvons avoir besoin de faire en sorte que certaines options s’excluent mutuellement. Le module argparse nous permet d’accomplir cette tâche de manière plus ou moins simple. En gros, ce que nous allons faire, c’est créer un groupe séparé d’options en utilisant la méthode add_mutually_exclusive_group() de l’objet parser, et y ajouter nos arguments. Par exemple:

parser = argparse.ArgumentParser();

create our group of mutually exclusive arguments
mutually_exclusive = parser.add_mutually_exclusive_group()
mutually_exclusive.add_argument("--foo", help="foo excludes bar")
mutually_exclusive.add_argument("--bar", help="bar excludes foo")

Une chose à noter est que pour faire partie d’un mutually_exclusive_group arguments doivent être facultatifs, donc les arguments positionnels, ou les arguments que vous avez définis comme obligatoires (required=True) ne sont pas autorisés dans celui-ci.

À ce stade, vous devriez avoir une idée du fonctionnement d’argparse. Cependant, nous n’avons fait qu’effleurer la surface de ce que ce module a à offrir : pour une description complète de toutes ses fonctionnalités, n’hésitez pas à lire la documentation, vous ne le regretterez pas. Beau script !