Comment construire des interfaces de ligne de commande en Python avec argparse – Real Python

By | juin 12, 2019

Expert Python

L'un des points forts de Python est qu'il est livré avec des piles: il dispose d'une bibliothèque standard riche et polyvalente qui en fait l'un des meilleurs langages de programmation pour l'écriture de scripts pour la ligne de commande.
Mais si vous écrivez des scripts pour la ligne de commande, vous devez également fournir une bonne interface de ligne de commande, que vous pouvez créer avec Python. argparse bibliothèque.

Dans cet article, vous apprendrez:

  • Qu'est-ce que le python argparse C'est pourquoi il est important de l'utiliser si vous devez écrire des scripts de ligne de commande en Python
  • Comment utiliser le Python argparse bibliothèque pour créer rapidement une CLI simple en Python
  • Qu'est-ce que l'utilisation avancée du Python argparse la bibliothèque est

Cet article est destiné aux pythonistes débutants qui écrivent probablement des scripts en Python pour leur travail quotidien, mais n’ont jamais implémenté d’interface de ligne de commande pour leurs scripts.

Si cela vous ressemble, et que vous êtes habitué à définir des valeurs de variable au début de vos scripts ou à analyser manuellement le sys.argv liste système au lieu d’utiliser un outil de développement CLI plus robuste, cet article s’adresse à vous.

Qu'est-ce qu'une interface de ligne de commande?

L’interface de ligne de commande (également appelée CLI) est un moyen d'interagir avec un script en ligne de commande. Python est livré avec plusieurs bibliothèques différentes qui vous permettent d'écrire une interface de ligne de commande pour vos scripts, mais la méthode standard pour créer une CLI en Python est actuellement le Python. argparse bibliothèque.

Le python argparse La bibliothèque a été publiée dans la bibliothèque standard avec Python 3.2 le 20 février 2011. Elle a été introduite avec Python Enhancement Proposal 389 et constitue désormais le moyen standard de créer une interface de ligne de commande en Python, à la fois pour les versions 2.7 et 3.2+.

Ce nouveau module a été publié en remplacement de l’ancien getopt et optparse modules car il leur manquait certaines caractéristiques importantes.

Le python argparse bibliothèque:

  • Permet l'utilisation d'arguments de position
  • Permet la personnalisation des caractères préfixés
  • Prend en charge un nombre variable de paramètres pour une seule option
  • Prend en charge les sous-commandes (un analyseur principal de ligne de commande peut utiliser d'autres analyseurs de ligne de commande, en fonction de certains arguments).

Avant de commencer, vous devez savoir comment fonctionne une interface de ligne de commande. Ouvrez donc un terminal sur votre ordinateur et exécutez la commande. ls pour obtenir la liste des fichiers contenus dans le répertoire actuel comme ceci:

$ ls
dcdb_20180201.sg4 mastro35.sg4 opening.sg4
dcdb_20180201.si4 mastro35.si4 ouvertures.si4
dcdb_20180201.sn4 mastro35.sn4 opening.sn4

Comme vous pouvez le constater, de nombreux fichiers se trouvent dans le répertoire en cours, mais la commande n’a pas renvoyé beaucoup d’informations sur ces fichiers.

La bonne nouvelle est qu’il n’est pas nécessaire de rechercher un autre programme pour obtenir une liste plus riche des fichiers contenus dans le répertoire en cours. Vous n'avez pas non plus besoin de modifier le ls commande vous-même, car il adopte une interface de ligne de commande, c’est-à-dire un ensemble de jetons (appelé arguments) que vous pouvez utiliser pour configurer le comportement de cette commande.

Maintenant, essayez d'exécuter la commande ls encore une fois, mais en ajoutant le -l option sur la ligne de commande comme dans l'exemple ci-dessous:

$ ls -l
total 641824
-rw ------- 1 dave staff 204558286 5 mars 2018 dcdb_20180201.sg4
-rw ------- 1 dave staff 110588409 5 mars 2018 dcdb_20180201.si4
-rw ------- 1 dave staff 2937516 5 mars 2018 dcdb_20180201.sn4
-rw ------- 1 dave staff 550127 27 mars 2018 mastro35.sg4
-rw ------- 1 dave staff 15974 11 Gen 17:01 mastro35.si4
-rw ------- 1 dave staff 3636 27 mars 2018 mastro35.sn4
-rw ------- 1 dave staff 29128 17 avr. 2018 ouvertures.sg4
-rw ------- 1 dave staff 276 17 avr 2018 ouvertures.si4
-rw ------- 1 dave staff 86 18 avril 2018 ouvertures.sn4

La sortie est très différente maintenant. La commande a renvoyé de nombreuses informations sur les autorisations, le propriétaire, le groupe et la taille de chaque fichier, ainsi que sur l'occupation totale du répertoire sur le disque.

C’est parce que vous avez utilisé l’interface de ligne de commande du ls commande et spécifié le -l option qui active le format long, un format spécial qui renvoie beaucoup plus d'informations pour chaque fichier répertorié.

Afin de vous familiariser avec ce sujet, vous allez en apprendre beaucoup sur les arguments, les options et les paramètres. Nous allons donc clarifier la terminologie tout de suite:

  • Un argument est une seule partie d'une ligne de commande, délimitée par des blancs.
  • Un option est un type particulier d'argument (ou une partie d'un argument) pouvant modifier le comportement de la ligne de commande.
  • UNE paramètre est un type d'argument particulier qui fournit des informations supplémentaires à une seule option ou commande.

Considérez la commande suivante:

Dans cet exemple, vous avez cinq arguments différents:

  1. ls: le nom de la commande que vous exécutez
  2. -l: une option pour activer le format de liste longue
  3. -s: une option pour imprimer la taille allouée de chaque fichier
  4. -k: une option pour avoir la taille en kilo-octets
  5. / var / log: un paramètre fournissant des informations supplémentaires (le chemin d'accès à la liste) à la commande

Notez que si vous avez plusieurs options sur une même ligne de commande, vous pouvez les combiner en un seul argument, comme ceci:

Ici vous avez seulement trois arguments:

  1. ls : le nom de la commande que vous exécutez
  2. -lsk: les trois options que vous souhaitez activer (une combinaison de -l, -s, et -k)
  3. / var / log: un paramètre fournissant des informations supplémentaires (le chemin d'accès à la liste) à la commande

Quand utiliser une interface de ligne de commande

Maintenant que vous savez ce qu’est une interface de ligne de commande, vous vous demandez peut-être quand il est judicieux d’en implémenter une dans vos programmes. En règle générale, si vous souhaitez fournir une approche conviviale de la configuration de votre programme, vous devez envisager une interface de ligne de commande et la méthode standard pour le faire consiste à utiliser le langage Python. argparse bibliothèque.

Même si vous créez un programme de ligne de commande complexe nécessitant le fonctionnement d’un fichier de configuration, si vous souhaitez laisser votre utilisateur spécifier le fichier de configuration à utiliser, il est judicieux d’accepter cette valeur en créant une interface de ligne de commande avec Python. argparse bibliothèque.

Comment utiliser le python argparse Bibliothèque pour créer une interface de ligne de commande

Utiliser le Python argparse La bibliothèque comporte quatre étapes:

  1. Importer le Python argparse bibliothèque
  2. Créer l'analyseur
  3. Ajouter des arguments optionnels et positionnels à l'analyseur
  4. Exécuter .parse_args ()

Après avoir exécuté .parse_args (), ce que vous obtenez est un Espace de noms objet contenant une propriété simple pour chaque argument d'entrée reçu de la ligne de commande.

Pour voir ces quatre étapes en détail avec un exemple, supposons que vous créez un programme nommé myls.py qui répertorie les fichiers contenus dans le répertoire en cours.
Voici une implémentation possible de votre interface de ligne de commande sans utiliser Python. argparse bibliothèque:

# myls.py
importation os
importation sys

si len(sys.argv) > 2:
    impression('Vous avez spécifié trop d'arguments')
    sys.sortie()

si len(sys.argv) < 2:
    impression('Vous devez spécifier le chemin à répertorier')
    sys.sortie()

chemin_entrée = sys.argv[[[[1]

si ne pas os.chemin.Isdir(chemin_entrée):
    impression('Le chemin spécifié n'existe pas')
    sys.sortie()

impression(' n'.joindre(os.listdir(chemin_entrée)))

Ceci est une implémentation possible de l’interface de ligne de commande de votre programme qui n’utilise pas le langage Python. argparse bibliothèque, mais si vous essayez de l’exécuter, vous verrez que cela fonctionne:

$ python myls.py
Vous devez spécifier le chemin à lister

$ python myls.py / mnt / proc / dev
Vous avez spécifié trop d'arguments

$ python myls.py / mnt
dir1
dir2

Comme vous pouvez le constater, le script fonctionne, mais la sortie est assez différente de celle attendue d’une commande intégrée standard.

Voyons maintenant comment le Python argparse La bibliothèque peut améliorer ce code:

# myls.py
# Importer la bibliothèque argparse
importation argparse

importation os
importation sys

# Créer l'analyseur
mon_parser = argparse.ArgumentParser(la description='Liste le contenu d'un dossier')

# Ajouter les arguments
mon_parser.add_argument('Chemin',
                       metavar='chemin',
                       type=str,
                       Aidez-moi='le chemin de la liste')

# Exécute la méthode parse_args ()
args = mon_parser.parse_args()

chemin_entrée = args.Chemin

si ne pas os.chemin.Isdir(chemin_entrée):
    impression('Le chemin spécifié n'existe pas')
    sys.sortie()

impression(' n'.joindre(os.listdir(chemin_entrée)))

Le code a beaucoup changé avec l'introduction du Python argparse bibliothèque.

La première grande différence par rapport à la version précédente est que le si les instructions pour vérifier les arguments fournis par l'utilisateur ont disparu, car la bibliothèque vérifiera la présence des arguments pour nous.

Nous avons importé le Python argparse bibliothèque, a créé un analyseur syntaxique simple avec une brève description de l’objectif du programme et a défini l’argument de position que nous souhaitons obtenir de la part de l’utilisateur.
Enfin, nous avons exécuté .parse_args () pour analyser les arguments d'entrée et obtenir un Espace de noms objet qui contient l'entrée utilisateur.

Maintenant, si vous exécutez ce code, vous le verrez avec seulement quatre lignes de code. Vous avez une sortie très différente:

$ python myls.py
utilisation: myls.py [-h] chemin
myls.py: erreur: les arguments suivants sont requis: chemin

Comme vous pouvez le constater, le programme a détecté qu’il vous fallait au moins un argument de position (chemin), l'exécution du programme a donc été interrompue avec un message d'erreur spécifique.

Vous avez peut-être aussi remarqué que votre programme accepte maintenant une option -h flag, comme dans l'exemple ci-dessous:

$ python myls.py -h
utilisation: myls.py [-h] chemin

Lister le contenu d'un dossier

arguments de position:
chemin le chemin de la liste

arguments optionnels:
-h, --help affiche ce message d'aide et quitte

Bien, maintenant le programme répond à la -h indicateur, affichant un message d’aide qui indique à l’utilisateur comment utiliser le programme. N'est-ce pas intéressant, vu que vous n'avez même pas eu besoin de demander cette fonctionnalité?

Enfin, avec seulement quatre lignes de code, maintenant le args la variable est un Espace de noms object, qui a une propriété pour chaque argument collecté à partir de la ligne de commande. C'est super pratique.

L'utilisation avancée du python argparse Bibliothèque

Dans la section précédente, vous avez appris l’utilisation de base du langage Python. argparse bibliothèque, et maintenant vous pouvez implémenter une simple interface de ligne de commande pour tous vos programmes. Cependant, vous pouvez obtenir beaucoup plus de choses avec cette bibliothèque. Dans cette section, vous verrez presque tout ce que cette bibliothèque peut vous offrir.

Définition du nom du programme

Par défaut, la bibliothèque utilise la valeur du sys.argv[0] élément pour définir le nom du programme, qui, comme vous le savez probablement déjà, est le nom du script Python que vous avez exécuté. Cependant, vous pouvez spécifier le nom de votre programme simplement en utilisant le programme mot-clé:

# Créer l'analyseur
mon_parser = argparse.ArgumentParser(programme='myls',
                                    la description='Liste le contenu d'un dossier')

Avec le programme mot-clé, vous spécifiez le nom du programme qui sera utilisé dans le texte d'aide:

$ python myls.py
utilisation: myls [-h] chemin
myls.py: erreur: les arguments suivants sont requis: chemin

Comme vous pouvez le constater, le nom du programme est maintenant myls au lieu de myls.py.

Affichage d'une aide sur l'utilisation du programme personnalisé

Par défaut, l’aide à l’utilisation du programme a un format standard défini par Python. argparse bibliothèque.
Cependant, vous pouvez le personnaliser avec le usage mot clé comme ceci:

# Créer l'analyseur
mon_parser = argparse.ArgumentParser(programme='myls',
                                    usage='% (prog) s [options]    chemin',
                                    la description='Liste le contenu d'un dossier')

Notez que, à l'exécution, le % (prog) s Le jeton est automatiquement remplacé par le nom de votre programme:

$ python myls.py
utilisation: myls [options] chemin
myls: erreur: trop peu d'arguments

Comme vous pouvez le constater, l’aide du programme affiche maintenant une chaîne d’utilisation différente, où [-h] l'option a été remplacée par un générique [options] jeton.

Affichage du texte avant et après l'aide des arguments

Pour personnaliser le texte affiché avant et après le texte d'aide des arguments, vous pouvez utiliser deux mots-clés différents:

  1. la description: pour le texte affiché avant le texte d'aide
  2. épilogue: pour le texte affiché après le texte d'aide

Vous avez déjà vu le la description dans le chapitre précédent, voyons un exemple de la façon dont le épilogue mot clé fonctionne:

# Créer l'analyseur
mon_parser = argparse.ArgumentParser(la description='Liste le contenu d'un dossier',
                                    épilogue='Profitez du programme! :) ')

le épilogue mot-clé ici a personnalisé le texte qui sera affiché après le texte d'aide standard:

$ python myls.py -h
utilisation: myls.py [-h] chemin

Lister le contenu d'un dossier

arguments de position:
chemin le chemin de la liste

arguments optionnels:
-h, --help affiche ce message d'aide et quitte

Profitez du programme! :)

Maintenant, la sortie montre le texte supplémentaire qui a été personnalisé par le épilogue mot-clé.

Personnalisation des caractères de préfixe autorisés

Une autre caractéristique que le Python argparse bibliothèque vous offre la possibilité de personnaliser le caractères préfixe, quels sont les caractères que vous pouvez utiliser pour passer des arguments facultatifs à l’interface de ligne de commande.

Par défaut, le préfixe standard est le tiret (-), mais si vous souhaitez utiliser un autre caractère, vous pouvez le personnaliser en utilisant le prefix_chars mot-clé en définissant l'analyseur comme ceci:

# Créer l'analyseur
mon_parser = argparse.ArgumentParser(la description='Liste le contenu d'un dossier',
                                    épilogue='Profitez du programme! :) ',
                                    prefix_chars='/')

Après la redéfinition, le programme prend désormais en charge un préfixe complètement différent, et le texte d'aide a été modifié en conséquence:

$ python myls.py
utilisation: myls.py [/h] chemin
myls.py: erreur: trop peu d'arguments

Comme vous pouvez le constater, votre programme ne prend plus en charge la -h drapeau mais le / h drapeau. C’est particulièrement utile lorsque vous codez pour Microsoft Windows, car les utilisateurs de Windows sont habitués à ces caractères préfixés lorsqu'ils travaillent avec la ligne de commande.

Définition de caractères de préfixe pour les fichiers contenant des arguments à inclure

Lorsque vous utilisez une ligne de commande très longue ou compliquée, il peut être judicieux de sauvegarder les arguments dans un fichier externe et de demander à votre programme de charger des arguments à partir de celui-ci. Le python argparse bibliothèque peut faire ce travail pour vous hors de la boîte.

Pour tester cette fonctionnalité, créez le programme Python suivant:

# fromfile_example.py
importation argparse

mon_parser = argparse.ArgumentParser(fromfile_prefix_chars='@')

mon_parser.add_argument('une',
                       Aidez-moi='un premier argument')

mon_parser.add_argument('b',
                       Aidez-moi='un deuxième argument')

mon_parser.add_argument('c',
                       Aidez-moi='un troisième argument')

mon_parser.add_argument('ré',
                       Aidez-moi='un quatrième argument')

mon_parser.add_argument('e',
                       Aidez-moi='un cinquième argument')

mon_parser.add_argument('-v',
                       '--verbeux',
                       action='store_true',
                       Aidez-moi='un argument optionnel')

# Execute parse_args ()
args = mon_parser.parse_args()

impression("Si vous lisez cette ligne, cela signifie que vous avez fourni"
      'tous les paramètres')

Notez que nous avons utilisé le fromfile_prefix_chars mot-clé lors de la création de l'analyseur.

Maintenant, si vous essayez d’exécuter votre programme sans passer d’argument, un message d’erreur apparaîtra:

$ python fromfile_example.py
utilisation: fromfile_example.py [-h] [-v]    a b c d e
fromfile_example.py: error: les arguments suivants sont requis: a, b, c, d, e

Ici vous pouvez voir que le Python argparse La bibliothèque se plaint parce que vous n'avez pas fourni suffisamment d'arguments.

Alors, créons un fichier nommé args.txt qui contient tous les paramètres nécessaires, avec un argument sur chaque ligne comme ceci:

premier
seconde
troisième
Quatrième
cinquième

Maintenant que vous avez spécifié un caractère de préfixe pour obtenir les arguments d'un fichier externe, ouvrez un terminal et essayez d'exécuter le programme précédent:

$ python fromfile_example.py @ args.txt
Si vous lisez cette ligne, cela signifie que vous avez fourni tous les paramètres

Dans cet exemple, vous pouvez voir que argparse a lu les arguments du args.txt fichier.

Autoriser ou refuser les abréviations

Une des fonctionnalités que le Python argparse La bibliothèque fournit hors de la boîte est la capacité de gérer les abréviations. Considérez le programme suivant, qui affiche la valeur que vous spécifiez sur l’interface de ligne de commande pour le --contribution argument:

# abbrev_example.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('--contribution', action='le magasin', type=int, Champs obligatoires=Vrai)
mon_parser.add_argument('--id', action='le magasin', type=int)

args = mon_parser.parse_args()

impression(args.contribution)

Ce programme imprime la valeur que vous spécifiez pour le --contribution argument. Nous n’avons pas encore examiné les arguments optionnels, mais ne vous inquiétez pas, nous les discuterons en profondeur dans un instant. Pour l'instant, considérez cet argument comme tout autre argument de position que nous avons déjà vu, à la différence que le nom commence par deux tirets.

Voyons maintenant comment le Python argparse bibliothèque peut gérer les abréviations, en appelant notre programme plusieurs fois, en spécifiant une abréviation différente du contribution argument à chaque exécution:

$ python abbrev_example.py --input 42
42

$ python abbrev_example.py --inpu 42
42

$ python abbrev_example.py --inp 42
42

$ python abbrev_example.py --in 42
42

Comme vous pouvez le constater, les paramètres facultatifs peuvent toujours être raccourcis, à moins que l’abréviation ne conduise à une interprétation incorrecte.
Mais qu’arrivera-t-il si vous essayez d’exécuter le programme en spécifiant simplement --i 42?
Dans ce cas, argparse ne sais pas si vous voulez transmettre la valeur 42 au --contribution argument ou à la --id argument, donc il sort du programme avec un message d'erreur spécifique:

$ python abbrev_example.py --i 42
utilisation: abbrev_example.py [-h] - entrée INPUT [--id ID]
abbrev_example.py: error: option ambiguë: --i pourrait correspondre à --input, --id

Cependant, si vous n'aimez pas ce comportement et que vous voulez obliger vos utilisateurs à spécifier le nom complet des options qu'ils utilisent, vous pouvez simplement désactiver cette fonctionnalité avec le mot clé allow_abbrev mis à Faux lors de la création de l'analyseur:

# abbrev_example.py
importation argparse

mon_parser = argparse.ArgumentParser(allow_abbrev=Faux)
mon_parser.add_argument('--contribution', action='le magasin', type=int, Champs obligatoires=Vrai)

args = mon_parser.parse_args()

impression(args.contribution)

Maintenant, si vous essayez le code ci-dessus, vous verrez que les abréviations ne sont plus autorisées:

$ python abbrev_example.py --inp 42
utilisation: abbrev_example.py [-h] - entrée INPUT
abbrev_example.py: erreur: les arguments suivants sont requis: --input

Le message d'erreur indique à l'utilisateur que le --contribution paramètre n'a pas été spécifié parce que le --inp L'abréviation n'a pas été reconnue.

Utilisation de l'aide automatique

Dans certains des exemples précédents, vous avez utilisé le -h flag pour obtenir un texte d'aide.
C’est une fonctionnalité très pratique que le Python argparse bibliothèque vous permet d’utiliser sans rien coder. Cependant, vous souhaiterez parfois désactiver cette fonctionnalité.
Pour ce faire, utilisez simplement le add_help mot-clé lors de la création de l'analyseur:

# Créer l'analyseur
mon_parser = argparse.ArgumentParser(la description='Liste le contenu d'un dossier',
                                    add_help=Faux)

Le code dans l'exemple ci-dessus spécifie le add_help mot clé défini sur FauxAlors maintenant, si vous exécutez le code, vous verrez que le -h le drapeau n'est plus accepté:

$ myls.py
utilisation: chemin myls.py
myls.py: erreur: les arguments suivants sont requis: chemin

Comme vous pouvez le voir, le -h le drapeau n'est plus affiché ou accepté.

Définition du nom ou des drapeaux des arguments

Il existe fondamentalement deux types d'arguments différents que vous pouvez ajouter à votre interface de ligne de commande:

  1. Arguments de position
  2. Arguments optionnels

Les arguments positionnels sont ceux que votre commande doit utiliser.

Dans l'exemple précédent, l'argument chemin était un argument de position, et notre programme ne pourrait pas fonctionner sans cela. Ils s'appellent positionnel parce que leur position définit leur fonction.

Par exemple, considérons le cp commande sous Linux (ou le copie commande sous Windows). Voici l’utilisation standard:

$ cp [[[[OPTION]... [[[[-T] SOURCE DEST

Le premier argument de position après la cp commande est la source du fichier que vous allez copier. Le second est la destination où vous voulez le copier.

Optionnel les arguments ne sont pas obligatoires et, lorsqu'ils sont utilisés, ils peuvent modifier le comportement de la commande au moment de l'exécution. dans le cp Par exemple, un argument optionnel est, par exemple, le -r flag, qui fait que la commande copie les répertoires de manière récursive.

Syntaxiquement, la différence entre les arguments positionnels et les arguments optionnels réside dans le fait que les arguments optionnels commencent par - ou -, tandis que les arguments de position ne le sont pas.

Pour ajouter un argument optionnel, il vous suffit d'appeler .add_argument () à nouveau et nommer le nouvel argument avec un départ -.

Par exemple, essayez de modifier le myls.py comme ça:

# myls.py
# Importer la bibliothèque argparse
importation argparse

importation os
importation sys

# Créer l'analyseur
mon_parser = argparse.ArgumentParser(la description='Liste le contenu d'un dossier')

# Ajouter les arguments
mon_parser.add_argument('Chemin',
                       metavar='chemin',
                       type=str,
                       Aidez-moi='le chemin de la liste')
mon_parser.add_argument('-l',
                       '--longue',
                       action='store_true',
                       Aidez-moi='activer le format de liste longue')

# Execute parse_args ()
args = mon_parser.parse_args()

chemin_entrée = args.Chemin

si ne pas os.chemin.Isdir(chemin_entrée):
    impression('Le chemin spécifié n'existe pas')
    sys.sortie()

impression(' n'.joindre(os.listdir(chemin_entrée)))

Maintenant, essayez d’exécuter ce programme pour voir si le nouveau -l l'option est acceptée:

$ python myls.py -h
utilisation: myls.py [-h] [-l]    chemin

Lister le contenu d'un dossier

arguments de position:
chemin le chemin de la liste

arguments optionnels:
-h, --help affiche ce message d'aide et quitte
-l, --long activer le format de liste longue

Comme vous pouvez le constater, le programme accepte maintenant (mais ne nécessite pas) la -l Cette option permet à l’utilisateur d’obtenir un long format de liste pour le contenu du répertoire.

Définition de l'action à entreprendre pour un argument

Lorsque vous ajoutez un argument facultatif à votre interface de ligne de commande, vous pouvez également définir le type d'action à exécuter lorsque l'argument est spécifié. Cela signifie que vous devez généralement spécifier comment stocker la valeur dans le répertoire. Espace de noms objet que vous obtiendrez quand .parse_args () est exécuté.

Plusieurs actions sont déjà définies et prêtes à être utilisées. Analysons-les en détail:

  • le magasin stocke la valeur d'entrée dans le Espace de noms objet. (C'est l'action par défaut.)
  • store_const stocke une valeur constante lorsque les arguments facultatifs correspondants sont spécifiés.
  • store_true stocke la valeur booléenne Vrai lorsque l’argument optionnel correspondant est spécifié et stocke un Faux autre part.
  • store_false stocke la valeur booléenne Faux lorsque l'argument optionnel correspondant est spécifié et stocké Vrai autre part.
  • ajouter stocke une liste, en ajoutant une valeur à la liste chaque fois que l'option est fournie.
  • append_const stocke une liste en ajoutant une valeur constante à la liste chaque fois que l'option est fournie.
  • compter stocke un int c'est égal aux fois où l'option a été fournie.
  • Aidez-moi affiche un texte d'aide et quitte.
  • version affiche la version du programme et quitte.

Créons un exemple pour tester toutes les actions que nous avons vues jusqu’à présent:

# actions_example.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.version = '1.0'
mon_parser.add_argument('-une', action='le magasin')
mon_parser.add_argument('-b', action='store_const', const=42)
mon_parser.add_argument('-c', action='store_true')
mon_parser.add_argument('-ré', action='store_false')
mon_parser.add_argument('-e', action='ajouter')
mon_parser.add_argument('-F', action='append_const', const=42)
mon_parser.add_argument('-g', action='compter')
mon_parser.add_argument('-je', action='Aidez-moi')
mon_parser.add_argument('-j', action='version')

args = mon_parser.parse_args()

impression(vars(args))

Ce script accepte un argument facultatif pour chaque type d'action décrit, puis affiche la valeur des arguments lus à partir de la ligne de commande. Testez-le en exécutant cet exemple:

$ python actions_example.py
'a': Aucun, 'b': Aucun, 'c': Faux, 'd': Vrai, 'e': Aucun, 'f': Aucun, 'g': Aucun

Comme vous pouvez le constater, si nous ne spécifions aucun argument, les valeurs par défaut sont généralement Aucun, du moins pour les actions qui ne stockent pas de valeur booléenne.

L'utilisation de la le magasin action stocke la valeur que nous transmettons sans autre considération:

$ python actions_example.py -a 42
'a': '42', 'b': Aucune, 'c': Faux, 'd': Vrai, 'e': Aucune, f ': Aucune,' g ': Aucune

$ python actions_example.py -a "tester"
'a': 'test', 'b': Aucune, 'c': Faux, 'd': Vrai, 'e': Aucune, 'f': Aucune, 'g': Aucune}

le store_const action, stocke le const défini lorsque les arguments sont fournis. Dans notre test, nous avons fourni uniquement les b argument et la valeur de args.b est maintenant 42:

$ python actions_example.py -b
'a': Aucune, 'b': 42, 'c': Faux, 'd': Vrai, 'e': Aucune, 'f': Aucune, 'g': Aucune}

le store_true action stocke un Vrai Boolean lorsque l'argument est passé et stocke un Faux Booléen ailleurs. Si vous avez besoin du comportement opposé, utilisez simplement le store_false action:

$ python actions_example.py
'a': Aucun, 'b': Aucun, 'c': Faux, 'd': Vrai, 'e': Aucun, 'f': Aucun, 'g': Aucun
$ python actions_example.py -c
'a': Aucun, 'b': Aucun, 'c': Vrai, 'd': Vrai, 'e': Aucun, 'f': Aucun, 'g': Aucun
$ python actions_example.py -d
'a': Aucun, 'b': Aucun, 'c': Faux, 'd': Faux, 'e': Aucun, 'f': Aucun, 'g': Aucun

le ajouter action vous permet de créer une liste de toutes les valeurs transmises à la CLI avec le même argument:

$ python actions_example.py -e-moi -e vous -eignez-nous
'a': Aucun, 'b': Aucun, 'c': Faux, 'd': Vrai, 'e': ['me', 'you', 'us'], 'f': aucun, 'g': aucun

le append_const l'action est similaire à la ajouter un, mais il ajoute toujours la même valeur constante:

$ python actions_example.py -f -f
'a': Aucun, 'b': Aucun, 'c': Faux, 'd': Vrai, 'e': Aucun, 'f': [42, 42], 'g': aucun

le compter action compte le nombre de fois qu'un argument est passé. C’est très utile lorsque vous voulez implémenter un niveau de verbosité pour votre programme, car vous pouvez définir un niveau où -v est moins verbeux que -vvv:

$ python actions_example.py -ggg
'a': Aucun, 'b': Aucun, 'c': Faux, 'd': Vrai, 'e': Aucun, 'f': Aucun, 'g': 3
$ python actions_example.py -ggggg
'a': Aucun, 'b': Aucun, 'c': Faux, 'd': Vrai, 'e': Aucun, 'f': Aucun, 'g': 5

le Aidez-moi action est celui que vous avez déjà vu au début de l'article. Il est activé pour le -h flag par défaut, mais vous pouvez l'utiliser pour un autre drapeau si vous voulez:

$ python actions_example.py -i
utilisation: actions_example.py [-h] [-a A] [-b] [-c] [-d] [-e E] [-f] [-g] [-i]
[-j]

arguments optionnels:
-h, --help affiche ce message d'aide et quitte
-a un
-b
-c
-ré
-e E
-F
-g
-je
-j afficher le numéro de version du programme et quitter

le version l'action est la dernière que vous pouvez utiliser. Il montre seulement la version du programme (définie en attribuant une valeur à la .version propriété de l’analyseur) et termine ensuite l’exécution du script:

$ python actions_example.py -j
1,0

Une autre possibilité est de créer une action personnalisée. Cela se fait en sous-classant les argparse.Action classe et la mise en œuvre d'un couple de méthodes.

Regardez l'exemple suivant, qui est une coutume le magasin action qui est juste un peu plus verbeuse que celle standard:

# custom_action.py
importation argparse

classe VerboseStore(argparse.action):
    def __init__(soi, option_strings, dest, nargues=Aucun, **Kwargs):
        si nargues est ne pas Aucun:
            élever ValueError('nargues non autorisées')
        super(VerboseStore, soi).__init__(option_strings, dest, **Kwargs)

    def __appel__(soi, analyseur, espace de noms, valeurs, chaîne_option=Aucun):
        impression('Je suis en train de poser le' 
              'valeurs % r    pour le % r    option...' % (valeurs, chaîne_option))
        setattr(espace de noms, soi.dest, valeurs)

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('-je', '--contribution', action=VerboseStore, type=int)

args = mon_parser.parse_args()

impression(vars(args))

Cet exemple définit une action personnalisée identique à la le magasin action mais un peu plus verbeux. Essayez de l'exécuter pour tester son fonctionnement:

$ python custom_action.py -i 42
Me voici, fixant les valeurs 42 pour l'option '-i' ...
'entrée': 42

Comme vous pouvez le constater, le programme a imprimé une ligne avant de définir la valeur 42 pour le -je paramètre.

Définition du nombre de valeurs devant être consommées par l'option

L’analyseur, par défaut, suppose que vous utiliserez un seul paramètre pour chaque argument, mais vous pouvez modifier ce comportement par défaut en spécifiant un nombre différent de valeurs avec le paramètre. nargues mot-clé.

Par exemple, si vous voulez créer un argument optionnel qui consomme exactement trois valeurs, vous pouvez spécifier le nombre 3 comme valeur pour le nargues mot-clé lors de l'ajout du paramètre à l'analyseur:

# nargs_example.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('--contribution', action='le magasin', type=int, nargues=3)

args = mon_parser.parse_args()

impression(args.contribution)

Maintenant, le programme accepte trois valeurs pour le --contribution paramètre:

$ python nargs_example.py --input 42
utilisation: nargs_example.py [-h] [--input INPUT INPUT INPUT]
nargs_example.py: error: argument --input: attendu 3 arguments

$ python nargs_example.py --input 42 42 42
[42, 42, 42]

Comme vous pouvez le voir, la valeur de la args.input variable est maintenant une liste qui contient trois valeurs.

Cependant, le nargues mot clé peut également accepter les éléments suivants:

  • ?: une seule valeur, qui peut être optionnelle
  • *: un nombre flexible de valeurs, qui seront rassemblées dans une liste
  • +: comme *, mais nécessitant au moins une valeur
  • argparse.REMAINDER: toutes les valeurs qui restent dans la ligne de commande

Ainsi, par exemple, dans le programme suivant, l'argument de position contribution prend une seule valeur lorsqu’elle est fournie, mais si la valeur n’est pas fournie, alors celle spécifiée par défaut le mot clé est utilisé:

# nargs_example.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('contribution',
                       action='le magasin',
                       nargues='?',
                       défaut='ma valeur par défaut')

args = mon_parser.parse_args()

impression(args.contribution)

Maintenant, vous pouvez choisir de définir une valeur spécifique pour le contribution argument ou pas. Dans ce cas, la valeur par défaut sera utilisée:

$ python nargs_example.py 'ma valeur personnalisée'
ma valeur personnalisée

$ python nargs_example.py
ma valeur par défaut

Pour prendre un nombre flexible de valeurs et les rassembler dans une seule liste, vous devez spécifier le * valeur pour le nargues mot clé comme ceci:

# nargs_example.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('contribution',
                       action='le magasin',
                       nargues='*',
                       défaut='ma valeur par défaut')

args = mon_parser.parse_args()

impression(args.contribution)

Découvrez comment ce code permet à l'utilisateur de définir un nombre flexible de valeurs pour l'argument attendu:

$ python nargs_example.py moi vous nous
['me', 'you', 'us']

$ python nargs_example.py
ma valeur par défaut

Si vous devez prendre un nombre variable de valeurs, mais que vous devez vous assurer qu'au moins une valeur est spécifiée, vous pouvez utiliser le + valeur pour le nargues mot clé comme ceci:

# nargs_example.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('contribution', action='le magasin', nargues='+')

args = mon_parser.parse_args()

impression(args.contribution)

Dans ce cas, si vous exécutez le programme sans argument de position, vous recevrez un message d'erreur explicite:

$ python nargs_example.py moi vous nous
['me', 'you', 'us']

$ python nargs_example.py
utilisation: nargs_example.py [-h] contribution [input ...]
nargs_example.py: erreur: les arguments suivants sont requis: entrée

Enfin, si vous devez récupérer tous les arguments restants spécifiés sur la ligne de commande et les mettre tous dans une liste, nargues le mot clé doit être défini sur argparse.REMAINDER comme ça:

# nargs_example.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('premier', action='le magasin')
mon_parser.add_argument('autres', action='le magasin', nargues=argparse.RESTE)

args = mon_parser.parse_args()

impression('premier = % r' % args.premier)
impression('autres = % r' % args.autres)

Maintenant, si vous exécutez ce programme, vous verrez que la première valeur sera associée aux premiers paramètres, tandis que toutes les autres valeurs fournies seront associées au second:

$ python nargs_example.py moi vous nous
premier = 'moi'
autres = ['you', 'us']

Notez que toutes les valeurs restantes sont placées dans une seule liste.

Définition d'une valeur par défaut produite si l'argument est manquant

Vous savez déjà que l'utilisateur peut décider de spécifier ou non des arguments facultatifs dans la ligne de commande. Lorsque les arguments ne sont pas spécifiés, la valeur correspondante est généralement définie sur Aucun.

Cependant, il est possible de définir une valeur par défaut pour un argument quand il n’est pas fourni:

# default_example.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('-une', action='le magasin', défaut='42')

args = mon_parser.parse_args()

impression(vars(args))

Si vous exécutez cet exemple sans passer le -une option, alors ceci est la sortie que vous obtenez:

$ python default_example.py
'a': '42'

Vous pouvez voir que maintenant l'option -une est réglé sur 42, même si vous n'avez pas explicitement défini la valeur sur la ligne de commande.

Définition du type de l'argument

Par défaut, toutes les valeurs d'argument d'entrée sont traitées comme s'il s'agissait de chaînes. Cependant, il est possible de définir le type de la propriété correspondante du Espace de noms objet que vous obtenez après .parse_args () est invoqué simplement en le définissant avec le type mot clé comme ceci:

# type_example.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('-une', action='le magasin', type=int)

args = mon_parser.parse_args()

impression(vars(args))

Spécifiant la valeur int pour l'argument, vous dites argparse que le .une propriété de votre Espace de noms l'objet doit être un int (au lieu d'une chaîne):

$ python type_example.py -a 42
'a': 42

De plus, la valeur de l’argument est vérifiée au moment de l’exécution, et s’il ya un problème avec le type de la valeur fournie sur la ligne de commande, l’exécution est interrompue avec un message d’erreur clair:

$ python type_example.py -a "c'est une ficelle"
utilisation: type_example.py [-h] [-a A]
type_example.py: error: argument -a: invalid int value: "c'est une chaîne"

Dans ce cas, le message d'erreur est très clair car il indique que vous deviez passer un test int au lieu d'une chaîne.

Définition d'un domaine de valeurs autorisées pour un argument spécifique

Une autre possibilité intéressante avec le Python argparse bibliothèque créant un domaine de valeurs autorisées pour des arguments spécifiques. Vous pouvez le faire en fournissant une liste des valeurs acceptées tout en ajoutant la nouvelle option:

# choices_ex.py
importation argparse

mon_parser = argparse.ArgumentParser()
mon_parser.add_argument('-une', action='le magasin', les choix=[[[['tête', 'queue'])

args = mon_parser.parse_args()

Please note that if you are accepting numeric values, then you can even use range() to specify a range of accepted values:

# choices_ex.py
importation argparse

my_parser = argparse.ArgumentParser()
my_parser.add_argument('-a', action='store', type=int, les choix=intervalle(1, 5))

args = my_parser.parse_args()

impression(vars(args))

In this case, the value provided on the command line will be automatically checked against the range defined:

$ python choices_ex.py -a 4
'a': 4

$ python choices_ex.py -a 40
usage: choices_ex.py [-h] [-a 1,2,3,4]
choices_ex.py: error: argument -a: invalid choice: 40 (choose from 1, 2, 3, 4)

If the input number is outside the defined range, then you’ll get an error message.

Setting Whether the Argument Is Required

If you want to force your user to specify the value for an optional argument, then you can use the Champs obligatoires keyword:

# required_example.py
importation argparse

my_parser = argparse.ArgumentParser()
my_parser.add_argument('-a',
                       action='store',
                       les choix=[[[['head', 'tail'],
                       Champs obligatoires=True)

args = my_parser.parse_args()

impression(vars(args))

If you use the Champs obligatoires keyword set to True for an optional argument, then the user will be forced to set a value for that argument:

$ python required_example.py
usage: required_example.py [-h] -a head,tail
required_example.py: error: the following arguments are required: -a

$ python required_example.py -a head
'a': 'head'

That said, please bear in mind that requiring an optional argument is usually considered bad practice since the user wouldn’t expect to have to set a value for an argument that should be optional.

Showing a Brief Description of What an Argument Does

A great feature of the Python argparse library is that, by default, you have the ability to ask for help just by adding the -h flag to your command line.

To make it even better, you can add help text to your arguments, so as to give the users even more help when they execute your program with the -h drapeau:

# help_example.py
importation argparse

my_parser = argparse.ArgumentParser()
my_parser.add_argument('-a',
                       action='store',
                       les choix=[[[['head', 'tail'],
                       Aidez-moi='set the user choice to head or tail')

args = my_parser.parse_args()

impression(vars(args))

This example shows you how to define a custom help text for the -a argument, and now the help text will be more clear for the user:

$ python help_example.py -h
usage: help_example.py [-h] [-a head,tail]

optional arguments:
-h, --help      show this help message and exit
-a head, tail  set the user choice to head or tail

Defining a help text for all the arguments is a really good idea because it makes the usage of your program more clear to the user.

Defining Mutually Exclusive Groups

Another interesting option you have when working with the Python argparse library is the ability to create a mutually exclusive group for options that cannot coexist in the same command line:

# groups.py
importation argparse

my_parser = argparse.ArgumentParser()
my_group = my_parser.add_mutually_exclusive_group(Champs obligatoires=True)

my_group.add_argument('-v', '--verbose', action='store_true')
my_group.add_argument('-s', '--silent', action='store_true')

args = my_parser.parse_args()

impression(vars(args))

You can specify the -v ou la -s flags, unless they aren’t on the same command line, and also the help text that argparse provides reflects this constraint:

$ python groups.py -h
usage: groups.py [-h] (-v | -s)

optional arguments:
        -h, --help     show this help message and exit
        -v, --verbose
        -s, --silent

$ python groups.py -v -s
usage: groups.py [-h] (-v | -s)
groups.py: error: argument -s/--silent: not allowed with argument -v/--verbose

If you specify all the options of a mutually exclusive group on the same command line you will get an error.

Setting the Argument Name in Usage Messages

If an argument accepts an input value, it can be useful to give this value a name that the parser can use to generate the help message, and this can be done by using the metavar keyword.
In the following example, you can see how you can use the metavar keyword to specify a name for the value of the -v drapeau:

# metavar_example.py
importation argparse

my_parser = argparse.ArgumentParser()
my_parser.add_argument('-v',
                       '--verbosity',
                       action='store',
                       type=int,
                       metavar='LEVEL')

args = my_parser.parse_args()

impression(vars(args))

Now, if you run your program with the -h flag, the help text assigns the name NIVEAU to the value of the -v drapeau:

$ python metavar_example.py -h
usage: metavar_example.py [-h] [-v LEVEL]

optional arguments:
        -h, --help            show this help message and exit
        -v LEVEL, --verbosity LEVEL

Please note that, in the help message, the value accepted for the -v flag is now named NIVEAU.

Setting the Name of the Attribute to Be Added to the Object Once Parsed

As you have already seen, when you add an argument to the parser, the value of this argument is stored in a property of the Namespace object. This property is named by default as the first argument passed to .add_argument() for the positional argument and as the long option string for optional arguments.

If an option uses dashes (as is fairly common), they will be converted to underscores in the property name:

importation argparse

my_parser = argparse.ArgumentParser()
my_parser.add_argument('-v',
                       '--verbosity-level',
                       action='store',
                       type=int)

args = my_parser.parse_args()
impression(args.verbosity_level)

However, it’s possible to specify the name of this property just by using the keyword dest when you’re adding an argument to the parser:

# dest_example.py
importation argparse

my_parser = argparse.ArgumentParser()
my_parser.add_argument('-v',
                       '--verbosity',
                       action='store',
                       type=int,
                       dest='my_verbosity_level')

args = my_parser.parse_args()

impression(vars(args))

By running this program, you’ll see that now the args variable contains a .my_verbosity_level property, even if by default the name of the property should have been .verbosity:

$ python dest_example.py -v 42
'my_verbosity_level': 42

The default name of this property would have been .verbosity, but since a different name has been specified by the dest keyword, .my_verbosity_level has been used.

Conclusion

Now you know what a command line interface is and how you can create one in Python by using the Python argparse library.

In this article, you’ve learned:

  • What the Python argparse library is, and why it’s important to use it if you need to write command line scripts in Python
  • How to use the Python argparse library to quickly create a simple CLI in Python
  • What the advanced usage of the Python argparse library is

Writing a good command line interface is a good way to create self-explanatory programs and give users a means of interacting with your application.

If you still have questions, don’t hesitate to reach out in the comment section below and take a look at the official documentation and the Tshepang Lekhonkhobe tutorial that is part of the official Python 3 HOWTO documentation.