argparse
-- Parseur d'arguments, d'options, et de sous-commandes de ligne de commande¶
Nouveau dans la version 3.2.
Code source: Lib/argparse.py
Le module argparse
facilite l'écriture d'interfaces en ligne de commande agréables à l'emploi. Le programme définit les arguments requis et argparse
s'arrange pour analyser ceux provenant de sys.argv
. Le module argparse
génère aussi automatiquement les messages d'aide, le mode d'emploi, et lève des erreurs lorsque les utilisateurs fournissent au programme des arguments invalides.
Exemple¶
Le code suivant est un programme Python acceptant une liste de nombre entiers et en donnant soit la somme, soit le maximum :
import argparse
parser = argparse.ArgumentParser(description='Process some integers.')
parser.add_argument('integers', metavar='N', type=int, nargs='+',
help='an integer for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
const=sum, default=max,
help='sum the integers (default: find the max)')
args = parser.parse_args()
print(args.accumulate(args.integers))
En supposant que le code Python ci-dessus est sauvegardé dans un fichier nommé prog.py
, il peut être lancé en ligne de commande et fournit des messages d'aide utiles :
$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]
Process some integers.
positional arguments:
N an integer for the accumulator
optional arguments:
-h, --help show this help message and exit
--sum sum the integers (default: find the max)
Lorsqu'il est lancé avec les arguments appropriés, il affiche la somme ou le maximum des entiers fournis en ligne de commande :
$ python prog.py 1 2 3 4
4
$ python prog.py 1 2 3 4 --sum
10
Si des arguments invalides sont passés, il lève une erreur :
$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'
Les sections suivantes vous guident au travers de cet exemple.
Créer un analyseur (parser en anglais)¶
La première étape dans l'utilisation de argparse
est de créer un objet ArgumentParser
:
>>> parser = argparse.ArgumentParser(description='Process some integers.')
L'objet ArgumentParser
contiendra toutes les informations nécessaires pour interpréter la ligne de commande comme des types de données de Python.
Ajouter des arguments¶
Alimenter un ArgumentParser
avec des informations sur les arguments du programme s'effectue en faisant des appels à la méthode add_argument()
. En général ces appels disent à l'ArgumentParser
comment prendre les chaînes de caractères de la ligne de commande et les transformer en objets. Cette information est stockée et utilisée lorsque parse_args()
est appelée. Par exemple :
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
... help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
... const=sum, default=max,
... help='sum the integers (default: find the max)')
Ensuite, appeler parse_args()
va renvoyer un objet avec deux attributs, integers
et accumulate
. L'attribut integers
est une liste d'un ou plusieurs entiers, et l'attribut accumulate
est soit la fonction sum()
, si --sum
était fourni à la ligne de commande, soit la fonction max()
dans le cas contraire.
Analyse des arguments¶
ArgumentParser
analyse les arguments avec la méthode parse_args()
. Cette méthode inspecte la ligne de commande, convertit chaque argument au type approprié et invoque l'action requise. Dans la plupart des cas, le résultat est la construction d'un objet Namespace
à partir des attributs analysés dans la ligne de commande :
>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
Dans un script, parse_args()
est généralement appelée sans arguments et l'objet ArgumentParser
détermine automatiquement les arguments de la ligne de commande à partir de sys.argv
.
Objets ArgumentParser
¶
-
class
argparse.
ArgumentParser
(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)¶ Crée un nouvel objet
ArgumentParser
. Tous les paramètres doivent être passés en arguments nommés. Chaque paramètre a sa propre description détaillée ci-dessous, mais en résumé ils sont :prog – Le nom du programme (par défaut :
sys.argv[0]
)usage – La chaîne décrivant l'utilisation du programme (par défaut : générée à partir des arguments ajoutés à l'analyseur)
description – Texte à afficher avant l'aide des arguments (par défaut : vide)
epilog – Texte à afficher après l'aide des arguments (par défaut : vide)
parents – Liste d'objets
ArgumentParser
contenant des arguments qui devraient aussi être inclusformatter_class – Classe pour personnaliser la sortie du message d'aide
prefix_chars – Jeu de caractères qui précède les arguments optionnels (par défaut :
'-'
)fromfile_prefix_chars – Jeu de caractères qui précède les fichiers d'où des arguments additionnels doivent être lus (par défaut :
None
)argument_default – Valeur globale par défaut pour les arguments (par défaut :
None
)conflict_handler – Stratégie pour résoudre les conflits entre les arguments optionnels (non-nécessaire en général)
add_help – Ajoute une option d'aide
-h/--help
à l'analyseur (par défaut :True
)allow_abbrev – Permet l'acceptation d'abréviations non-ambigües pour les options longues (par défaut :
True
)
Modifié dans la version 3.5: Le paramètre allow_abbrev est ajouté.
Modifié dans la version 3.8: Dans les versions précédentes, allow_abbrev désactivait aussi le regroupement de plusieurs options courtes telles que
-vv
pour signifier-v -v
.
Les sections suivantes décrivent comment chacune de ces options sont utilisées.
Le paramètre prog¶
Par défaut, l'objet ArgumentParser
utilise sys.argv[0]
pour déterminer comment afficher le nom du programme dans les messages d'aide. Cette valeur par défaut est presque toujours souhaitable, car elle produit un message d'aide qui correspond à la méthode utilisée pour lancer le programme sur la ligne de commande. Par exemple, si on a un fichier nommé myprogram.py
avec le code suivant :
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
Le message d'aide pour ce programme affiche myprogram.py
pour le nom du programme (peu importe d'où le programme est lancé) :
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
Pour changer ce comportement par défaut, une valeur alternative est passée par l'argument prog=
du constructeur d'ArgumentParser
:
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]
optional arguments:
-h, --help show this help message and exit
Prenez note que le nom du programme, peu importe s'il provient de sys.argv[0]
ou de l'argument prog=
, est accessible aux messages d'aide grâce au spécificateur de formatage %(prog)s
.
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
Le paramètre usage¶
Par défaut, l'objet ArgumentParser
construit le message relatif à l'utilisation à partir des arguments qu'il contient :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
Le message par défaut peut être remplacé grâce à l'argument nommé usage=
:
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
Le spécificateur de formatage %(prog)s
est disponible pour insérer le nom du programme dans vos messages d'utilisation.
Le paramètre description¶
La plupart des appels au constructeur d'ArgumentParser
utilisent l'argument nommé description=
. Cet argument donne une brève description de ce que fait le programme et de comment il fonctionne. Dans les messages d'aide, cette description est affichée entre le prototype de ligne de commande et les messages d'aide des arguments :
>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
optional arguments:
-h, --help show this help message and exit
Par défaut, la description est sujette au retour à la ligne automatique pour se conformer à l'espace disponible. Pour changer ce comportement, voyez l'argument formatter_class.
Le paramètre epilog¶
Certains programmes aiment afficher un texte supplémentaire après la description des arguments. Un tel texte peut être spécifié grâce à l'argument epilog=
du constructeur d'ArgumentParser
:
>>> parser = argparse.ArgumentParser(
... description='A foo that bars',
... epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
optional arguments:
-h, --help show this help message and exit
And that's how you'd foo a bar
De même que pour l'argument description, le texte passé à epilog=
est sujet au retour à la ligne automatique. Ce comportement peut être ajusté grâce à l'argument formatter_class du constructeur d'ArgumentParser
.
Le paramètre parents¶
Parfois, plusieurs analyseurs partagent un jeu commun d'arguments. Plutôt que de répéter les définitions de ces arguments, un analyseur commun qui contient tous les arguments partagés peut être utilisé, puis passé à l'argument parents=
du constructeur d'ArgumentParser
. L'argument parents=
accepte une liste d'objets ArgumentParser
, accumule toutes les actions positionnelles et optionnelles de ces objets, puis les ajoute à l'instance d'ArgumentParser
en cours de création :
>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)
>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)
>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)
Prenez note que la majorité des analyseurs parents doivent spécifier add_help=False
. Autrement, le constructeur d'ArgumentParser
va voir plus d'une option -h/--help
(une pour le parent et une pour l'instance en cours de création) et va lever une erreur.
Note
Vous devez initialiser complètement les analyseurs avant de les passer à parents=
. Si vous changez les analyseurs parents après la création de l'analyseur enfant, ces changements ne seront pas répercutés sur l'enfant.
Le paramètre formatter_class¶
Les objets ArgumentParser
permettent la personnalisation de la mise en page des messages d'aide en spécifiant une classe de formatage alternative. Il y a actuellement quatre classes de formatage :
-
class
argparse.
RawDescriptionHelpFormatter
¶ -
class
argparse.
RawTextHelpFormatter
¶ -
class
argparse.
ArgumentDefaultsHelpFormatter
¶ -
class
argparse.
MetavarTypeHelpFormatter
¶
RawDescriptionHelpFormatter
et RawTextHelpFormatter
vous donnent plus de contrôle sur comment les descriptions textuelles sont affichées. Par défaut, les contenus de description et epilog des objets ArgumentParser
font l'objet du retour à la ligne automatique dans les messages d'aide :
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... description='''this description
... was indented weird
... but that is okay''',
... epilog='''
... likewise for this epilog whose whitespace will
... be cleaned up and whose words will be wrapped
... across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]
this description was indented weird but that is okay
optional arguments:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
Passer RawDescriptionHelpFormatter
à formatter_class=
indique que les textes de description et d'epilog ont déjà été formatés correctement et qu'ils ne doivent pas faire l'objet d'un retour à la ligne automatique :
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.RawDescriptionHelpFormatter,
... description=textwrap.dedent('''\
... Please do not mess up this text!
... --------------------------------
... I have indented it
... exactly the way
... I want it
... '''))
>>> parser.print_help()
usage: PROG [-h]
Please do not mess up this text!
--------------------------------
I have indented it
exactly the way
I want it
optional arguments:
-h, --help show this help message and exit
RawTextHelpFormatter
conserve les espaces pour toutes les catégories de textes d'aide, y compris les descriptions des arguments. Notez bien que plusieurs retours à la ligne consécutifs sont remplacés par un seul. Si vous voulez garder plusieurs sauts de ligne, ajoutez des espaces entre les caractères de changement de ligne.
ArgumentDefaultsHelpFormatter
ajoute automatiquement l'information sur les valeurs par défaut aux messages d'aide de tous les arguments :
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar [bar ...]]
positional arguments:
bar BAR! (default: [1, 2, 3])
optional arguments:
-h, --help show this help message and exit
--foo FOO FOO! (default: 42)
MetavarTypeHelpFormatter
utilise le nom du type de l'argument pour chacun des arguments comme nom d'affichage pour leurs valeurs (contrairement au formateur standard qui utilise dest) :
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float
positional arguments:
float
optional arguments:
-h, --help show this help message and exit
--foo int
Le paramètre prefix_chars¶
La majorité des options sur la ligne de commande utilisent -
comme préfixe (par exemple : -f/--foo
). Pour les analyseurs qui doivent accepter des caractères préfixes autres ou additionnels (par exemple pour les options +f
ou /foo
), vous devez les spécifier en utilisant l'argument prefix_chars=
du constructeur d'ArgumentParser
:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')
La valeur par défaut de prefix_chars=
est '-'
. Passer un jeu de caractères qui n'inclut pas -
provoquera le refus des options comme -f/--foo
.
Le paramètre fromfile_prefix_chars¶
Parfois, par exemple quand on traite une liste d'arguments particulièrement longue, il est logique de stocker la liste d'arguments dans un fichier plutôt que de la saisir sur la ligne de commande. Si un jeu de caractères est passé à l'argument fromfile_prefix_chars=
du constructeur de ArgumentParser
, alors les arguments qui commencent par l'un des caractères spécifiés seront traités comme des fichiers et seront remplacés par les arguments contenus dans ces fichiers. Par exemple :
>>> with open('args.txt', 'w') as fp:
... fp.write('-f\nbar')
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')
Par défaut, les arguments lus à partir d'un fichier doivent être chacun sur une nouvelle ligne (voir aussi convert_arg_line_to_args()
) et ils sont traités comme s'ils étaient au même emplacement que le fichier original référençant les arguments de la ligne de commande. Ainsi dans l'exemple ci-dessus, l'expression ['-f', 'foo', '@args.txt']
est équivalente à l'expression ['-f', 'foo', '-f', 'bar']
.
Par défaut, l'argument fromfile_prefix_chars=
est None
, ce qui signifie que les arguments ne seront pas traités en tant que références à des fichiers.
Le paramètre argument_default¶
Généralement, les valeurs par défaut des arguments sont spécifiées soit en passant la valeur désirée à add_argument()
soit par un appel à la méthode set_defaults()
. Cette méthode accepte un ensemble de paires nom-valeur. Il est parfois pertinent de configurer une valeur par défaut pour tous les arguments d'un analyseur. On peut activer ce comportement en passant la valeur désirée à l'argument nommé argument_default=
du constructeur de ArgumentParser
. Par exemple, pour supprimer globalement la création d'attributs pendant l'appel de parse_args()
, on fournit argument_default=SUPPRESS
:
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()
Le paramètre allow_abbrev¶
En temps normal, lorsque vous passez une liste d'arguments à la méthode parse_args()
d'ArgumentParser
elle accepte les abréviations des options longues.
Cette fonctionnalité peut être désactivée en passant False
à allow_abbrev
:
>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
>>> parser.add_argument('--foobar', action='store_true')
>>> parser.add_argument('--foonley', action='store_false')
>>> parser.parse_args(['--foon'])
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon
Nouveau dans la version 3.5.
Le paramètre conflict_handler¶
Les objets ArgumentParser
ne peuvent pas avoir plus d'une option avec la même chaîne d'option. Par défaut, les objets ArgumentParser
lèvent une exception si on essaie de créer un argument avec une chaîne d'option qui est déjà utilisée :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
..
ArgumentError: argument --foo: conflicting option string(s): --foo
Parfois, par exemple si on utilise des analyseurs parents, il est souhaitable de surcharger les anciens arguments qui partagent la même chaîne d'option. Pour obtenir ce comportement, vous devez passer 'resolve'
à l'argument conflict_handler=
du constructeur d'ArgumentParser
:
>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
Prenez note que les objets ArgumentParser
n'enlèvent une action que si toutes ses chaînes d'options sont surchargées. Ainsi dans l'exemple ci-dessus, l'action -f/--foo
du parent est conservée comme l'action -f
puisque --foo
est la seule chaîne d'options qui a été surchargée.
Le paramètre add_help¶
Par défaut, les objets ArgumentParser
ajoutent une option qui offre l'affichage du message d'aide de l'analyseur. Par exemple, prenons le fichier myprogram.py
qui contient le code suivant :
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
Si -h
ou --help
est passé sur la ligne de commande, le message d'aide de l'ArgumentParser
sera affiché :
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
Il est parfois utile de désactiver l'ajout de cette option d'aide. Pour ce faire, vous devez passer False
à l'argument add_help=
du constructeur d'ArgumentParser
:
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]
optional arguments:
--foo FOO foo help
En général, l'option d'aide est -h/--help
. L'exception à cette règle est quand une valeur est passée à prefix_chars=
et qu'elle n'inclue pas -
, auquel cas, -h
et --help
ne sont pas des options valides. Dans ce cas, le premier caractère de prefix_chars
est utilisé comme préfixe des options d'aide :
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]
optional arguments:
+h, ++help show this help message and exit
La méthode add_argument()¶
-
ArgumentParser.
add_argument
(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])¶ Définie comment une option de ligne de commande doit être analysée. Chacun des paramètres est décrit plus en détails ci-bas, mais en résumé ils sont :
name_or_flags – un nom ou une liste de chaînes d'options. Par exemple :
foo
ou-f, --foo
.action – Type élémentaire de l'action à entreprendre quand cet argument est reconnu sur la ligne de commande.
nargs – Nombre d'arguments de la ligne de commande à capturer.
const – Valeur constante requise par certains choix d'action et de nargs.
default – Valeur produite si l'argument est absent de la ligne de commande.
type – Type vers lequel l'argument sur la ligne de commande doit être converti.
choices – Conteneur qui contient toutes les valeurs permises pour cet argument.
required –
True
si l'option sur la ligne de commande est obligatoire (ne s'applique qu'aux arguments optionnels).help – Brève description de ce que fait l'argument.
metavar – Nom de l'argument dans les messages d'utilisations.
dest – Nom de l'attribut qui sera ajouté à l'objet retourné par
parse_args()
.
Les sections suivantes décrivent comment chacune de ces options sont utilisées.
Les paramètres name et flags¶
La méthode add_argument()
doit savoir si c'est un argument optionnel (tel que -f
ou --foo
) ou plutôt un argument positionnel (tel qu'une liste de noms de fichiers) qui est attendu. Le premier argument passé à add_argument()
doit donc être soit une série de noms d'options tels qu'ils apparaissent sur la ligne de commande, soit simplement un nom si on désire un argument positionnel. Par exemple, un argument optionnel est créé comme suit :
>>> parser.add_argument('-f', '--foo')
alors qu'un argument positionnel est créé comme suit :
>>> parser.add_argument('bar')
Lors le l'appel de parse_args()
, les arguments qui commencent par le préfixe -
sont présumés optionnels et tous les autres sont présumés positionnels :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar
Le paramètre action¶
Les objets ArgumentParser
associent les arguments de la ligne de commande avec des actions. Ces actions peuvent soumettre les arguments de la ligne de commande auxquels elles sont associées à un traitement arbitraire, mais la majorité des actions se contentent d'ajouter un attribut à l'objet renvoyé par parse_args()
. L'argument nommé action
indique comment l'argument de la ligne de commande sera traité. Les actions natives sont :
'store'
– Stocke la valeur de l'argument sans autre traitement. Ceci est l'action par défaut. Par exemple :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo') >>> parser.parse_args('--foo 1'.split()) Namespace(foo='1')
'store_const'
– Stocke la valeur passée à l'argument nommé const. L'action'store_const'
est typiquement utilisée avec des arguments optionnels qui représentent un drapeau ou une condition similaire. Par exemple :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='store_const', const=42) >>> parser.parse_args(['--foo']) Namespace(foo=42)
'store_true'
et'store_false'
– Ces actions sont des cas particuliers de'store_const'
pour lesquelles la valeur stockée estTrue
etFalse
, respectivement. Aussi, ces actions ont comme valeur par défautFalse
etTrue
, respectivement. Par exemple :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='store_true') >>> parser.add_argument('--bar', action='store_false') >>> parser.add_argument('--baz', action='store_false') >>> parser.parse_args('--foo --bar'.split()) Namespace(foo=True, bar=False, baz=True)
'append'
– Stocke une liste et ajoute la valeur de l'argument à la liste. Ceci est pratique pour les options qui peuvent être répétées sur la ligne de commande :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='append') >>> parser.parse_args('--foo 1 --foo 2'.split()) Namespace(foo=['1', '2'])
'append_const'
– Stocke une liste et ajoute la valeur passée à l'argument nommé const à la fin de la liste. Notez que la valeur par défaut de l'argument nommé const estNone
. L'action'append_const'
est pratique quand plusieurs arguments ont besoin de stocker des constantes dans la même liste. Par exemple :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--str', dest='types', action='append_const', const=str) >>> parser.add_argument('--int', dest='types', action='append_const', const=int) >>> parser.parse_args('--str --int'.split()) Namespace(types=[<class 'str'>, <class 'int'>])
'count'
– Compte le nombre d'occurrences de l'argument nommé. Ceci est pratique, par exemple, pour augmenter le niveau de verbosité :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--verbose', '-v', action='count', default=0) >>> parser.parse_args(['-vvv']) Namespace(verbose=3)
Prenez note que la valeur de default sera
None
à moins qu'elle soit explicitement définie à0
.'help'
– Affiche le message d'aide complet pour toutes les options de l'analyseur puis termine l'exécution. Une actionhelp
est automatiquement ajoutée à l'analyseur par défaut. ConsultezArgumentParser
pour les détails de la création du contenu de l'aide.'version'
– Affiche la version du programme puis termine l'exécution. Cette action requiert l'argument nomméversion=
dans l'appel àadd_argument()
:>>> import argparse >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0') >>> parser.parse_args(['--version']) PROG 2.0
'extend'
– Stock une liste et ajoute à la liste chacune des valeurs de l'argument reçues. Voici un exemple de son utilisation :>>> parser = argparse.ArgumentParser() >>> parser.add_argument("--foo", action="extend", nargs="+", type=str) >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"]) Namespace(foo=['f1', 'f2', 'f3', 'f4'])
Nouveau dans la version 3.8.
You may also specify an arbitrary action by passing an Action subclass or
other object that implements the same interface. The recommended way to do
this is to extend Action
, overriding the __call__
method
and optionally the __init__
method.
Un exemple d'action personnalisée :
>>> class FooAction(argparse.Action):
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
... if nargs is not None:
... raise ValueError("nargs not allowed")
... super().__init__(option_strings, dest, **kwargs)
... def __call__(self, parser, namespace, values, option_string=None):
... print('%r %r %r' % (namespace, values, option_string))
... setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')
Pour plus d'information, voir Action
.
Le paramètre nargs¶
En général, les objets ArgumentParser
associent un seul argument de la ligne de commande à une seule action à entreprendre. L'argument nommé nargs
associe un nombre différent d'arguments de la ligne de commande à une action. Les valeurs reconnues sont :
N
(un entier).N
arguments de la ligne de commande seront capturés ensemble et stockés dans une liste. Par exemple :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', nargs=2) >>> parser.add_argument('bar', nargs=1) >>> parser.parse_args('c --foo a b'.split()) Namespace(bar=['c'], foo=['a', 'b'])
Prenez note que
nargs=1
produit une liste avec un seul élément. Ceci est différent du comportement par défaut qui produit l'élément directement (comme un scalaire).
'?'
. Un argument sera capturé de la ligne de commande et produit directement. Si aucun argument n'est présent sur la ligne de commande, la valeur de default est produite. Prenez note que pour les arguments optionnels, il est aussi possible que la chaîne d'option soit présente mais qu'elle ne soit pas suivie d'un argument. Dans ce cas, la valeur de const est produite. Voici quelques exemples pour illustrer ceci :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', nargs='?', const='c', default='d') >>> parser.add_argument('bar', nargs='?', default='d') >>> parser.parse_args(['XX', '--foo', 'YY']) Namespace(bar='XX', foo='YY') >>> parser.parse_args(['XX', '--foo']) Namespace(bar='XX', foo='c') >>> parser.parse_args([]) Namespace(bar='d', foo='d')
nargs='?'
est fréquemment utilisé pour accepter des fichiers d'entrée et de sortie optionnels :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'), ... default=sys.stdin) >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'), ... default=sys.stdout) >>> parser.parse_args(['input.txt', 'output.txt']) Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>, outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>) >>> parser.parse_args([]) Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>, outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
'*'
. Tous les arguments présents sur la ligne de commande sont capturés dans une liste. Prenez note qu'il n'est pas logique d'avoir plus d'un argument positionnel avecnargs='*'
, mais il est par contre possible d'avoir plusieurs arguments optionnels qui spécifientnargs='*'
. Par exemple :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', nargs='*') >>> parser.add_argument('--bar', nargs='*') >>> parser.add_argument('baz', nargs='*') >>> parser.parse_args('a b --foo x y --bar 1 2'.split()) Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
'+'
. Comme pour'*'
, tous les arguments présents sur la ligne de commande sont capturés dans une liste. De plus, un message d'erreur est produit s'il n'y a pas au moins un argument présent sur la ligne de commande. Par exemple :>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('foo', nargs='+') >>> parser.parse_args(['a', 'b']) Namespace(foo=['a', 'b']) >>> parser.parse_args([]) usage: PROG [-h] foo [foo ...] PROG: error: the following arguments are required: foo
argparse.REMAINDER
. All the remaining command-line arguments are gathered into a list. This is commonly useful for command line utilities that dispatch to other command line utilities:>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--foo') >>> parser.add_argument('command') >>> parser.add_argument('args', nargs=argparse.REMAINDER) >>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())) Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
Si l'argument nommé nargs
n'est pas fourni, le nombre d'arguments capturés est déterminé par l'action. En général, c'est un seul argument de la ligne de commande qui est capturé et il est produit directement.
Le paramètre const¶
L'argument const
d'add_argument()
est utilisé pour stocker une constante qui n'est pas lue depuis la ligne de commande mais qui est requise par certaines actions d'ArgumentParser
. Les deux utilisations les plus communes sont :
quand
add_argument()
est appelée avecaction='store_const'
ouaction='append_const'
. Ces actions ajoutent la valeur deconst
à l'un des attributs de l'objet renvoyé parparse_args()
. Consultez la description d'action pour voir quelques exemples ;quand la méthode
add_argument()
est appelée avec des chaînes d'options (telles que-f
ou--foo
) etnargs='?'
. Ceci crée un argument optionnel qui peut être suivi de zéro ou un argument de ligne de commande. Quand la ligne de commande est analysée, si la chaîne d'option est trouvée mais qu'elle n'est pas suivie par un argument, la valeur deconst
est utilisée. Consultez la description de nargs pour voir quelques exemples.
Pour les actions 'store_const'
et 'append_const'
, l'argument nommé const
doit être spécifié. Pour toutes les autres actions, il est optionnel et sa valeur par défaut est None
.
Le paramètre default¶
Tous les arguments optionnels et certains arguments positionnels peuvent être omis à la ligne de commande. L'argument nommé default
de la méthode add_argument()
(qui vaut None
par défaut), indique quelle valeur sera utilisé si l'argument est absent de la ligne de commande. Pour les arguments optionnels, la valeur de default
est utilisée si la chaîne d'option n'est pas présente sur la ligne de commande :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)
Si la valeur de default
est une chaîne, l'analyseur analyse cette valeur comme si c'était un argument de la ligne de commande. En particulier, l'analyseur applique la conversion spécifiée par l'argument type (si elle est fournie) avant d'affecter l'attribut à l'objet Namespace
renvoyé. Autrement, l'analyseur utilise la valeur telle qu'elle :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)
Pour les arguments positionnels pour lesquels nargs est ?
ou *
, la valeur de default
est utilisée quand l'argument est absent de la ligne de commande :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)
Si vous passez default=argparse.SUPPRESS
, aucun attribut ne sera ajouté à l'objet Namespace
quand l'argument est absent de la ligne de commande :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')
Le paramètre type¶
Par défaut, les objets ArgumentParser
capturent les arguments de la ligne de commande comme des chaînes. Très souvent par contre, on désire interpréter les chaînes de la ligne de commande comme un autre type, tel que float
ou int
. L'argument nommé type
d'add_argument()
nous permet de faire les vérifications et les conversions de type nécessaires. Les types et les fonctions natives peuvent être utilisés directement pour la valeur de l'argument type
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
Consultez la rubrique de l'argument nommé default pour plus d'information sur quand l'argument type
est appliqué aux arguments par défaut.
Pour faciliter l'utilisation de types de fichiers variés, le module argparse
fournit le type fabrique FileType
qui accepte les arguments mode=
, bufsize=
, encoding=
et errors=
de la fonction open()
. Par exemple, FileType('w')
peut être utilisé pour créer un fichier en mode écriture :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
type=
peut prendre n'importe quelle fonction ou objet appelable qui prend une seule chaîne de caractère comme argument et qui renvoie la valeur convertie :
>>> def perfect_square(string):
... value = int(string)
... sqrt = math.sqrt(value)
... if sqrt != int(sqrt):
... msg = "%r is not a perfect square" % string
... raise argparse.ArgumentTypeError(msg)
... return value
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square
L'argument nommé choices est parfois plus facile d'utilisation pour les vérificateurs de type qui comparent la valeur à une gamme prédéfinie :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=range(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
Voir le chapitre choices pour plus de détails.
Le paramètre choices¶
Certains arguments de la ligne de commande doivent être choisis parmi un ensemble fermé de valeurs. Ceux-ci peuvent être gérés en passant un conteneur à l'argument nommé choices de la méthode add_argument()
. Quand la ligne de commande est analysée, les valeurs de l'argument sont comparées et un message d'erreur est affiché si l'argument n'est pas parmi les valeurs acceptables :
>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')
Prenez note que le test d'inclusion dans le conteur choices est fait après la conversion de type. Le type des objets dans le conteneur choices doivent donc correspondre au type spécifié :
>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)
N'importe quel conteneur peut être fourni pour la valeur de choices, donc les objets list
, les objets set
et les conteneurs personnalisés sont tous acceptés.
Le paramètre required¶
En général, le module argparse
prend pour acquis que les drapeaux comme -f
et --bar
annoncent un argument optionnel qui peut toujours être omis de la ligne de commande. Pour rendre une option obligatoire, True
peut être passé à l'argument nommé required=
d'add_argument()
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-h] --foo FOO
: error: the following arguments are required: --foo
Tel qu'illustré' dans l'exemple, quand l'option est marquée comme required
, parse_args()
mentionne une erreur si l'option est absente de la ligne de commande.
Note
En général, les options obligatoires manifestent un style boiteux, car les utilisateurs s'attendent que les options soient optionnelles. Elles devraient donc être évitées si possible.
Le paramètre help¶
La valeur de help
est une chaîne qui contient une brève description de l'argument. Quand un utilisateur demande de l'aide (en général par l'utilisation de -h
ou --help
sur la ligne de commande), ces descriptions d'aide seront affichées pour chacun des arguments :
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
... help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
... help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]
positional arguments:
bar one of the bars to be frobbled
optional arguments:
-h, --help show this help message and exit
--foo foo the bars before frobbling
La chaîne help
peut contenir des spécificateurs de formatage afin d'éviter la répétition de contenu tel que le nom du programme et la valeur par défaut de l'argument (voir default). Les spécificateurs de formatage disponibles incluent entre autres le nom du programme, %(prog)s
, et la plupart des arguments nommés d'add_argument()
, tels que %(default)s
, %(type)s
, etc. :
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
... help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]
positional arguments:
bar the bar to frobble (default: 42)
optional arguments:
-h, --help show this help message and exit
Comme la chaîne d'aide utilise le caractère %
pour le formatage, si vous désirez afficher un %
littéral dans la chaîne d'aide, vous devez en faire l’échappement avec %%
.
argparse
peut supprimer la rubrique d'aide de certaines options. Pour ce faire, passez argparse.SUPPRESS
à help
:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]
optional arguments:
-h, --help show this help message and exit
Le paramètre metavar¶
Quand un objet ArgumentParser
construit le message d'aide, il doit pouvoir faire référence à chacun des arguments attendus. Par défaut, les objets ArgumentParser
utilisent la valeur de dest pour le nom de chaque objet. Par défaut, la valeur de dest est utilisée telle quelle pour les actions d'arguments positionnels et elle (dest) est convertie en majuscules pour les actions d'arguments optionnels. Ainsi, un argument positionnel unique avec dest='bar'
sera affiché comme bar
et un argument positionnel unique --foo
qui prend un seul argument sur la ligne de commande sera affiché comme FOO
. Par exemple :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage: [-h] [--foo FOO] bar
positional arguments:
bar
optional arguments:
-h, --help show this help message and exit
--foo FOO
Un nom alternatif peut être fourni à metavar
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage: [-h] [--foo YYY] XXX
positional arguments:
XXX
optional arguments:
-h, --help show this help message and exit
--foo YYY
Prenez note que metavar
ne change que le nom affiché. Le nom de l'attribut ajouté à l'objet renvoyé par parse_args()
est toujours déterminé par la valeur de dest.
Certaines valeurs de nargs
peuvent provoquer l'affichage de metavar
plus d'une fois. Passer un n-uplet à metavar
indique les différents noms à afficher pour chacun des arguments :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]
optional arguments:
-h, --help show this help message and exit
-x X X
--foo bar baz
Le paramètre dest¶
La plupart des actions d'ArgumentParser
ajoutent une valeur dans un attribut de l'objet renvoyé par parse_args()
. Le nom de l'attribut est déterminé par l'argument nommé dest
d'add_argument()
. Pour les arguments positionnels, dest
est généralement le premier argument d'add_argument()
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')
Pour les actions d'arguments optionnels, la valeur de dest
est généralement inférée à partir des chaînes d'option. ArgumentParser
génère la valeur de dest
en prenant la première chaîne d'option longue et en retirant le préfixe --
. Si une chaîne d'option longue n'est pas fournie, dest
sera dérivée de la première chaîne d'option courte sans le préfixe -
. Tous les -
subséquents seront convertis en _
pour s'assurer que le chaîne est un nom d'attribut valide. Les exemples suivants illustrent ce comportement :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')
dest
vous permet de fournir un nom d'attribut personnalisé :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')
Classes Action¶
Les classes Action
implémentent l'API Action, un appelable qui retourne un appelable qui traite les arguments de la ligne de commande. Tout objet qui suit cette API peut être passé comme paramètre action
d'add_argument()
.
-
class
argparse.
Action
(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)¶
Les objets Action
sont utilisés par un ArgumentParser
pour représenter l'information nécessaire à l'analyse d'un seul argument à partir d'une ou plusieurs chaînes de la ligne de commande. La classe Action
doit accepter les deux arguments positionnels d'ArgumentParser.add_argument()
ainsi que tous ses arguments nommés, sauf action
.
Les instances d'Action
(ou la valeur de retour de l'appelable passé au paramètre action
) doivent définir les attributs nécessaires : dest, option_strings, default, type, required, help, etc. La façon la plus simple de s'assurer que ces attributs sont définis est d'appeler Action.__init__
.
Les instances d'Action
doivent être appelables et donc les sous-classes doivent surcharger la méthode __call__
. Cette méthode doit accepter quatre paramètres :
parser
– L'objetArgumentParser
qui contient cette action.namespace
– L'objetNamespace
qui sera renvoyé parparse_args()
. La majorité des actions ajoutent un attribut à cet objet avecsetattr()
.values
– Les arguments de la ligne de commande associés à l'action après les avoir soumis à la conversion de type. Les conversions de types sont spécifiées grâce à l’argument nommé type d'add_argument()
.option_string
– La chaîne d'option utilisée pour invoquer cette action. L'argumentoption_string
est optionnel et est absent si l'action est associée à un argument positionnel.
La méthode __call__
peut réaliser un traitement arbitraire, mais en général elle affect des attributs sur namespace
en fonction de dest
et de values
.
La méthode parse_args()¶
-
ArgumentParser.
parse_args
(args=None, namespace=None)¶ Convertie les chaînes d'arguments en objets et les assigne comme attributs de l'objet
namespace
. Retourne l'objetnamespace
rempli.Les appels à
add_argument()
qui ont été faits déterminent exactement quels objets sont créés et comment ils sont affectés. Consultez la rubrique d'add_argument()
pour les détails.
Syntaxe de la valeur des options¶
La méthode parse_args()
offre plusieurs façons d'indiquer la valeur d'une option si elle en prend une. Dans le cas le plus simple, l'option et sa valeur sont passées en tant que deux arguments distincts :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)
Pour les options longues (les options qui ont un nom plus long qu'un seul caractère), l'option et sa valeur peuvent être passées comme un seul argument de la ligne de commande en utilisant =
comme séparateur :
>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)
Pour les options courtes (les options qui utilisent un seul caractère), l'option et sa valeur peuvent être concaténées :
>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')
Plusieurs options courtes peuvent être groupées ensemble après un seul préfixe -
pour autant que seule la dernière (ou aucune) nécessite une valeur :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')
Arguments invalides¶
Quand elle fait l'analyse de la ligne de commande, la méthode parse_args()
vérifie plusieurs erreurs possibles : entre autres, options ambigües, types invalides, options invalides, nombre incorrect d'arguments positionnels, etc. Quand une erreur est rencontrée, elle affiche l'erreur accompagnée du message d'aide puis termine l'exécution :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')
>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'
>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar
>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger
Arguments contenant -
¶
La méthode parse_args()
tente de signaler une erreur quand l'utilisateur s'est clairement trompé. Par contre, certaines situations sont intrinsèquement ambigües. Par exemple, l'argument de la ligne de commande -1
peut aussi bien être une tentative de spécifier une option qu'une tentative de passer un argument positionnel. La méthode parse_args()
est prudente : les arguments positionnels ne peuvent commencer par -
que s'ils ont l'apparence d'un nombre négatif et que l'analyseur ne contient aucune option qui a l'apparence d'un nombre négatif :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')
>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')
>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')
>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')
>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2
>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument
Si l'utilisateur a des arguments positionnels qui commencent par -
et qui n'ont pas l'apparence d'un nombre négatif, il peut insérer le pseudo-argument '--'
qui indique à parse_args()
de traiter tout ce qui suit comme un argument positionnel :
>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)
Arguments abrégés (Par comparaison de leurs préfixes)¶
Par défaut, la méthode parse_args()
accepte que les options longues soient abrégées par un préfixe pour autant que l’abréviation soit non-ambigüe, c'est-à-dire qu'elle ne corresponde qu'à une seule option :
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon
Une erreur est générée pour les arguments qui peuvent produire plus d'une option. Ce comportement peut être désactivé en passant False
à Le paramètre allow_abbrev.
Au-delà de sys.argv
¶
Il est parfois désirable de demander à un objet ArgumentParser
de faire l'analyse d'arguments autres que ceux de sys.argv
. On peut faire ce traitement en passant une liste de chaînes à parse_args()
. Cette approche est pratique pour faire des tests depuis l'invite de commande :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
... 'integers', metavar='int', type=int, choices=range(10),
... nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
... '--sum', dest='accumulate', action='store_const', const=sum,
... default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
L'objet namespace¶
-
class
argparse.
Namespace
¶ Classe rudimentaire qui est utilisé par défaut par
parse_args()
pour créer un objet qui stock les attributs. Cet objet est renvoyé parArgumentParser.parse_args
.
Cette classe est délibérément rudimentaire : une sous-classe d'object
avec une représentation textuelle intelligible. Si vous préférez une vue dict-compatible, vous devez utiliser vars()
(un idiome Python classique) :
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}
Il est parfois utile de demander à ArgumentParser
de faire l'affectation des attributs sur un objet existant plutôt que de faire la création d'un nouvel objet Namespace
. Ceci peut être réalisé avec l'argument nommé namespace=
:
>>> class C:
... pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'
Autres outils¶
Sous commandes¶
-
ArgumentParser.
add_subparsers
([title][, description][, prog][, parser_class][, action][, option_string][, dest][, required][, help][, metavar])¶ Certains programmes divisent leurs fonctionnalités entre un nombre de sous-commandes. Par exemple : le programme
svn
peut être invoqué commesvn checkout
,svn update
etsvn commit
. Séparer les fonctionnalités de cette façon est judicieux quand le programme effectue plusieurs fonctions différentes qui requièrent différents types de lignes de commandes.ArgumentParser
prend en charge la création de ce genre de sous-commandes grâce à la méthodeadd_subparsers()
. La méthodeadd_subparsers()
est généralement appelée sans argument et elle renvoie un objetAction
spécial. Cet objet possède une seule méthode,add_parser()
, qui prend le nom d'une commande et n'importe quels arguments du constructeur d'ArgumentParser
; elle renvoie un objetArgumentParser
qui peut être modifié normalement.Description des paramètres
title
– titre du groupe de ce sous-analyseur dans la sortie d'aide ; par défaut :"subcommands"
sidescription
est fournie, sinon utilise la valeur detitle
de la section sur les arguments positionnels ;description
– description du groupe de ce sous-analyseur dans la sortie d'aide ; par défaut :None
;prog
– nom du programme dans le message d'utilisation de l'aide des sous-commandes ; par défaut : le nom du programme et les arguments positionnels qui arrivent avant l'argument de ce sous-analyseur ;parser_class
– classe utilisée pour créer les instances de sous-analyseurs ; par défaut : la classe de l'analyseur courant (par exempleArgumentParser
) ;action – action à entreprendre quand cet argument est reconnu sur la ligne de commande ;
dest – nom de l'attribut sous lequel la sous-commande est stockée ; par défaut :
None
et aucune valeur n'est stockée ;required –
True
si la sous-commande est obligatoire ; par défaut :False
(ajouté dans 3.7) ;help – message d'aide pour le groupe du sous-analyseur dans la sortie d'aide ; par défaut :
None
;metavar – chaîne qui représente les sous-commandes disponibles dans les messages d'aide ; par défaut :
None
, ce qui entraine la génération d'une chaîne suivant le format'{cmd1, cmd2, …}'
.
Quelques exemples d'utilisation :
>>> # create the top-level parser >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--foo', action='store_true', help='foo help') >>> subparsers = parser.add_subparsers(help='sub-command help') >>> >>> # create the parser for the "a" command >>> parser_a = subparsers.add_parser('a', help='a help') >>> parser_a.add_argument('bar', type=int, help='bar help') >>> >>> # create the parser for the "b" command >>> parser_b = subparsers.add_parser('b', help='b help') >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help') >>> >>> # parse some argument lists >>> parser.parse_args(['a', '12']) Namespace(bar=12, foo=False) >>> parser.parse_args(['--foo', 'b', '--baz', 'Z']) Namespace(baz='Z', foo=True)
Prenez note que l'objet renvoyé par
parse_args()
ne contient que les attributs reconnus par l'analyseur principal et le sous-analyseur sélectionné par la ligne de commande. Les autres sous-analyseurs n'ont pas d'influence sur l'objet renvoyé. Ainsi dans l'exemple précédent, quand la commandea
est spécifiée, seuls les attributsfoo
etbar
sont présents ; quand la commandeb
est spécifiée, seuls les attributsfoo
etbaz
sont présents.De même, quand le message d'aide est demandé depuis l'un des sous-analyseurs, seul le message d'aide de cet analyseur est affiché. Le message d'aide n'inclut pas le message de l'analyseur parent ni celui des sous-analyseurs au même niveau. Il est toutefois possible de fournir un message d'aide pour chacun des sous-analyseurs grâce à l'argument
help=
d'add_parser()
tel qu'illustré ci-dessus.>>> parser.parse_args(['--help']) usage: PROG [-h] [--foo] {a,b} ... positional arguments: {a,b} sub-command help a a help b b help optional arguments: -h, --help show this help message and exit --foo foo help >>> parser.parse_args(['a', '--help']) usage: PROG a [-h] bar positional arguments: bar bar help optional arguments: -h, --help show this help message and exit >>> parser.parse_args(['b', '--help']) usage: PROG b [-h] [--baz {X,Y,Z}] optional arguments: -h, --help show this help message and exit --baz {X,Y,Z} baz help
La méthode
add_subparsers()
accepte les arguments nomméstitle
etdescription
. Quand au moins l'un des deux est présent, les commandes du sous-analyseur sont affichées dans leur propre groupe dans la sortie d'aide. Par exemple :>>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers(title='subcommands', ... description='valid subcommands', ... help='additional help') >>> subparsers.add_parser('foo') >>> subparsers.add_parser('bar') >>> parser.parse_args(['-h']) usage: [-h] {foo,bar} ... optional arguments: -h, --help show this help message and exit subcommands: valid subcommands {foo,bar} additional help
De plus,
add_parser
accepte l'argument additionnelaliases
qui permet à plusieurs chaînes de faire référence au même sous-analyseur. L'exemple suivant, à la manière desvn
, utiliseco
comme une abréviation decheckout
:>>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers() >>> checkout = subparsers.add_parser('checkout', aliases=['co']) >>> checkout.add_argument('foo') >>> parser.parse_args(['co', 'bar']) Namespace(foo='bar')
Une façon efficace de traiter les sous-commandes est de combiner l'utilisation de la méthode
add_subparsers()
avec des appels àset_defaults()
pour que chaque sous-analyseur sache quelle fonction Python doit être exécutée. Par exemple :>>> # sub-command functions >>> def foo(args): ... print(args.x * args.y) ... >>> def bar(args): ... print('((%s))' % args.z) ... >>> # create the top-level parser >>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers() >>> >>> # create the parser for the "foo" command >>> parser_foo = subparsers.add_parser('foo') >>> parser_foo.add_argument('-x', type=int, default=1) >>> parser_foo.add_argument('y', type=float) >>> parser_foo.set_defaults(func=foo) >>> >>> # create the parser for the "bar" command >>> parser_bar = subparsers.add_parser('bar') >>> parser_bar.add_argument('z') >>> parser_bar.set_defaults(func=bar) >>> >>> # parse the args and call whatever function was selected >>> args = parser.parse_args('foo 1 -x 2'.split()) >>> args.func(args) 2.0 >>> >>> # parse the args and call whatever function was selected >>> args = parser.parse_args('bar XYZYX'.split()) >>> args.func(args) ((XYZYX))
Ainsi, vous pouvez laisser à
parse_args()
la responsabilité de faire l'appel à la bonne fonction après avoir analysé les arguments. Associer fonctions et actions est en général la façon la plus facile de gérer des actions différentes pour chacun de vos sous-analyseurs. Par contre, si vous avez besoin de consulter le nom de du sous-analyseur qui a été invoqué, vous pouvez utiliser l'argument nommédest
d'add_subparsers()
:>>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers(dest='subparser_name') >>> subparser1 = subparsers.add_parser('1') >>> subparser1.add_argument('-x') >>> subparser2 = subparsers.add_parser('2') >>> subparser2.add_argument('y') >>> parser.parse_args(['2', 'frobble']) Namespace(subparser_name='2', y='frobble')
Modifié dans la version 3.7: Introduction des arguments nommés obligatoires.
Objets FileType
¶
-
class
argparse.
FileType
(mode='r', bufsize=-1, encoding=None, errors=None)¶ Le type fabrique
FileType
crée des objets qui peuvent être passés à l'argumenttype
d'ArgumentParser.add_argument()
. Les arguments qui ont commetype
un objetFileType
ouvrent les arguments de la ligne de commande en tant que fichiers avec les options spécifiées : mode, taille du tampon, encodage et gestion des erreurs (voir la fonctionopen()
pour plus de détails) :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0)) >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8')) >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt']) Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)
Les objets
FileType
reconnaissent le pseudo-argument'-'
et en font automatiquement la conversion verssys.stdin
pour les objetsFileType
ouverts en lecture et verssys.stdout
pour les objetsFileType
ouverts en écriture :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('infile', type=argparse.FileType('r')) >>> parser.parse_args(['-']) Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)
Nouveau dans la version 3.4: Les arguments nommés
encodings
eterrors
.
Groupes d'arguments¶
-
ArgumentParser.
add_argument_group
(title=None, description=None)¶ Par défaut,
ArgumentParser
sépare les arguments de la ligne de commande entre les groupes « arguments positionnels » et « arguments optionnels » au moment d'afficher les messages d'aide. S'il existe un meilleur regroupement conceptuel des arguments, les groupes adéquats peuvent être créés avec la méthodeadd_argument_group()
:>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) >>> group = parser.add_argument_group('group') >>> group.add_argument('--foo', help='foo help') >>> group.add_argument('bar', help='bar help') >>> parser.print_help() usage: PROG [--foo FOO] bar group: bar bar help --foo FOO foo help
La méthode
add_argument_group()
renvoie un objet représentant le groupe d'arguments. Cet objet possède une méthodeadd_argument()
semblable à celle d'ArgumentParser
. Quand un argument est ajouté au groupe, l'analyseur le traite comme un argument normal, mais il affiche le nouvel argument dans un groupe séparé dans les messages d'aide. Afin de personnaliser l'affichage, la méthodeadd_argument_group()
accepte les argumentstitle
etdescription
:>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) >>> group1 = parser.add_argument_group('group1', 'group1 description') >>> group1.add_argument('foo', help='foo help') >>> group2 = parser.add_argument_group('group2', 'group2 description') >>> group2.add_argument('--bar', help='bar help') >>> parser.print_help() usage: PROG [--bar BAR] foo group1: group1 description foo foo help group2: group2 description --bar BAR bar help
Prenez note que tout argument qui n'est pas dans l'un de vos groupes est affiché dans l'une des sections usuelles positional arguments et optional arguments.
Exclusion mutuelle¶
-
ArgumentParser.
add_mutually_exclusive_group
(required=False)¶ Crée un groupe mutuellement exclusif. Le module
argparse
vérifie qu'au plus un des arguments du groupe mutuellement exclusif est présent sur la ligne de commande :>>> parser = argparse.ArgumentParser(prog='PROG') >>> group = parser.add_mutually_exclusive_group() >>> group.add_argument('--foo', action='store_true') >>> group.add_argument('--bar', action='store_false') >>> parser.parse_args(['--foo']) Namespace(bar=True, foo=True) >>> parser.parse_args(['--bar']) Namespace(bar=False, foo=False) >>> parser.parse_args(['--foo', '--bar']) usage: PROG [-h] [--foo | --bar] PROG: error: argument --bar: not allowed with argument --foo
La méthode
add_mutually_exclusive_group()
accepte aussi l'argumentrequired
pour indiquer qu'au moins un des arguments mutuellement exclusifs est nécessaire :>>> parser = argparse.ArgumentParser(prog='PROG') >>> group = parser.add_mutually_exclusive_group(required=True) >>> group.add_argument('--foo', action='store_true') >>> group.add_argument('--bar', action='store_false') >>> parser.parse_args([]) usage: PROG [-h] (--foo | --bar) PROG: error: one of the arguments --foo --bar is required
Prenez note que présentement les groupes d'arguments mutuellement exclusifs n'acceptent pas les arguments
title
etdescription
d'add_argument_group()
.
Valeurs par défaut de l'analyseur¶
-
ArgumentParser.
set_defaults
(**kwargs)¶ Dans la majorité des cas, les attributs de l'objet renvoyé par
parse_args()
sont entièrement définis par l'inspection des arguments de la ligne de commande et par les actions des arguments. La méthodeset_defaults()
permet l'ajout d'attributs additionnels qui sont définis sans nécessiter l'inspection de la ligne de commande :>>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', type=int) >>> parser.set_defaults(bar=42, baz='badger') >>> parser.parse_args(['736']) Namespace(bar=42, baz='badger', foo=736)
Prenez note que les valeurs par défaut au niveau de l'analyseur ont précédence sur les valeurs par défaut au niveau de l'argument :
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default='bar') >>> parser.set_defaults(foo='spam') >>> parser.parse_args([]) Namespace(foo='spam')
Les valeurs par défaut au niveau de l'analyseur sont particulièrement utiles quand on travaille avec plusieurs analyseurs. Voir la méthode
add_subparsers()
pour un exemple de cette utilisation.
-
ArgumentParser.
get_default
(dest)¶ Renvoie la valeur par défaut d'un attribut de l'objet
Namespace
tel qu'il a été défini soit paradd_argument()
ou parset_defaults()
:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default='badger') >>> parser.get_default('foo') 'badger'
Afficher l'aide¶
Pour la majorité des applications, parse_args()
se charge du formatage et de l'affichage des messages d'erreur et d'utilisation. Plusieurs méthodes de formatage sont toutefois disponibles :
-
ArgumentParser.
print_usage
(file=None)¶ Affiche une brève description sur la façon d'invoquer l'
ArgumentParser
depuis la ligne de commande. Sifile
estNone
, utilisesys.stdout
.
-
ArgumentParser.
print_help
(file=None)¶ Affiche un message d'aide qui inclut l'utilisation du programme et l'information sur les arguments répertoriés dans l'
ArgumentParser
. Sifile
estNone
, utilisesys.stdout
.
Des variantes de ces méthodes sont fournies pour renvoyer la chaîne plutôt que de l'afficher :
-
ArgumentParser.
format_usage
()¶ Renvoie une chaîne contenant une brève description sur la façon d'invoquer l'
ArgumentParser
depuis la ligne de commande.
-
ArgumentParser.
format_help
()¶ Renvoie une chaîne représentant un message d'aide qui inclut des informations sur l'utilisation du programme et sur les arguments définis dans l'
ArgumentParser
.
Parsing partiel¶
-
ArgumentParser.
parse_known_args
(args=None, namespace=None)¶
Parfois, un script n'analyse que de quelques-uns des arguments de la ligne de commande avant de passer les arguments non-traités à un autre script ou un autre programme. La méthode parse_known_args()
est utile dans ces cas. Elle fonctionne similairement à parse_args()
, mais elle ne lève pas d'erreur quand des arguments non-reconnus sont présents. Au lieu, elle renvoie une paire de valeurs : l'objet Namespace
rempli et la liste des arguments non-traités.
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])
Avertissement
Les règles d'acceptation des abréviations sont applicables à parse_known_args()
. L'analyseur peut ainsi capturer une option même si elle n'est que le préfixe d'une option reconnue plutôt que de la laisser dans la liste des arguments non-traités.
Personnaliser le parsing de fichiers¶
-
ArgumentParser.
convert_arg_line_to_args
(arg_line)¶ Les arguments qui proviennent d'un fichier sont lus un par ligne. La méthode
convert_arg_line_to_args()
peut être surchargée pour accomplir un traitement plus élaboré. Voir aussi l'argument nomméfromfile_prefix_chars
du constructeur d'ArgumentParser
.La méthode
convert_arg_line_to_args
accepte un seul argument,arg_line
, qui est une chaîne lue dans le fichier d'arguments. Elle renvoie une liste d'arguments analysés dans cette chaîne. La méthode est appelée une fois pour chaque ligne lue du fichier d'arguments. L'ordre est préservé.Une surcharge utile de cette méthode est de permettre à chaque mot délimité par des espaces d'être traité comme un argument. L'exemple suivant illustre comment réaliser ceci :
class MyArgumentParser(argparse.ArgumentParser): def convert_arg_line_to_args(self, arg_line): return arg_line.split()
Méthodes d'interruptions¶
-
ArgumentParser.
exit
(status=0, message=None)¶ Cette méthode interrompt l'exécution du programme et renvoie
status
comme valeur de retour du processus. Simessage
est fourni, la chaîne est affichée avant la fin de l'exécution. Vous pouvez surcharger cette méthode pour traiter ces étapes différemment :class ErrorCatchingArgumentParser(argparse.ArgumentParser): def exit(self, status=0, message=None): if status: raise Exception(f'Exiting because of an error: {message}') exit(status)
-
ArgumentParser.
error
(message)¶ Cette méthode affiche un message d'utilisation qui inclut la chaîne
message
sur la sortie d'erreur standard puis termine l'exécution avec le code de fin d'exécution 2.
Analyse entremêlée¶
-
ArgumentParser.
parse_intermixed_args
(args=None, namespace=None)¶
-
ArgumentParser.
parse_known_intermixed_args
(args=None, namespace=None)¶
De nombreuses commandes Unix permettent à l'utilisateur d'entremêler les arguments optionnels et les arguments positionnels. Les méthodes parse_intermixed_args()
et parse_known_intermixed_args()
permettent ce style d'analyse.
Ces analyseurs n'offrent pas toutes les fonctionnalités d'argparse
et ils lèvent une exception si une fonctionnalité non prise en charge est utilisée. En particulier, les sous-analyseurs, argparse.REMAINDER
et les groupes mutuellement exclusifs qui contiennent à la fois des arguments optionnels et des arguments positionnels ne sont pas pris en charge.
L'exemple suivant illustre la différence entre parse_known_args()
et parse_intermixed_args()
: le premier renvoie ['2', '3']
comme arguments non-traités alors que le second capture tous les arguments positionnels dans rest
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])
parse_known_intermixed_args()
renvoie une paire de valeurs : l'objet Namespace
rempli et une liste de chaînes d'arguments non-traités. parse_intermixed_args()
lève une erreur s'il reste des chaînes d'arguments non-traités.
Nouveau dans la version 3.7.
Mettre à jour du code optparse
¶
Initialement, le module argparse
tentait de rester compatible avec optparse
. Hélas, il était difficile de faire des améliorations à optparse
de façon transparente, en particulier pour les changements requis pour gérer les nouveaux spécificateurs de nargs=
et les messages d'utilisation améliorés. Après avoir porté ou surchargé tout le code d'optparse
, la rétro-compatibilité pouvait difficilement être conservée.
Le module argparse
fournit plusieurs améliorations par rapport au module optparse
de la bibliothèque standard :
Gère les arguments positionnels.
Prise en charge des sous commandes.
Permet d'utiliser les alternatives
+
ou/
comme préfixes d'option.Prend en charge la répétition de valeurs (zéro ou plus, un ou plus).
Fournit des messages d'aide plus complets.
Fournit une interface plus simple pour les types et actions personnalisés
Le portage partiel d'optparse
à argparse
:
Remplacer tous les appels à
optparse.OptionParser.add_option()
par des appels àArgumentParser.add_argument()
.Remplacer
(options, args) = parser.parse_args()
parargs = parser.parse_args()
et ajouter des appels àArgumentParser.add_argument()
pour les arguments positionnels. Prenez note que les valeurs précédemment appeléesoptions
sont appeléesargs
dans le contexte d'argparse
.Remplacer
optparse.OptionParser.disable_interspersed_args()
en appelantparse_intermixed_args()
plutôt queparse_args()
.Remplacer les actions de rappel (callback actions en anglais) et les arguments nommés
callback_*
par des argumentstype
etactions
.Remplacer les chaînes représentant le nom des types pour l'argument nommé
type
par les objets types correspondants (par exemple :int
,float
,complex
, etc).Remplacer
optparse.Values
parNamespace
; etoptparse.OptionError
etoptparse.OptionValueError
parArgumentError
.Remplacer les chaînes avec des arguments de formatage implicite (tels que
%default
ou%prog
) par la syntaxe standard de Python pour l'interpolation d'un dictionnaire dans les chaînes de formatage (c'est-à-dire%(default)s
et%(prog)s
).Remplacer l'argument
version
du constructeur d'OptionParser
par un appel àparser.add_argument('--version', action='version', version='<la version>')
.