argparse
--- Parser for command-line options, arguments and subcommands¶
Ajouté dans la version 3.2.
Code source: Lib/argparse.py
The argparse
module makes it easy to write user-friendly command-line
interfaces. The program defines what arguments it requires, and argparse
will figure out how to parse those out of sys.argv
. The argparse
module also automatically generates help and usage messages. The module
will also issue errors when users give the program invalid arguments.
The argparse
module's support for command-line interfaces is built
around an instance of argparse.ArgumentParser
. It is a container for
argument specifications and has options that apply to the parser as whole:
parser = argparse.ArgumentParser(
prog='ProgramName',
description='What the program does',
epilog='Text at the bottom of help')
La méthode ArgumentParser.add_argument()
permet de définir les arguments de l'analyseur. Ceux-ci peuvent être des arguments positionnels, des arguments optionnels ou des drapeaux (qui sont alors traduits en valeurs booléennes). Les arguments ont la possibilité d'être complétés par des valeurs :
parser.add_argument('filename') # positional argument
parser.add_argument('-c', '--count') # option that takes a value
parser.add_argument('-v', '--verbose',
action='store_true') # on/off flag
La méthode ArgumentParser.parse_args()
lance l'analyseur et stocke les résultats dans un objet argparse.Namespace
:
args = parser.parse_args()
print(args.filename, args.count, args.verbose)
Note
If you're looking for a guide about how to upgrade optparse
code
to argparse
, see Upgrading Optparse Code.
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, exit_on_error=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 – Nom du programme (par défaut :
os.path.basename(sys.argv[0])
) ;usage – 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 au dessus de l'aide pour les arguments (vide par défaut) ;
epilog – Texte à afficher après l'aide des arguments (vide par défaut) ;
parents – Liste d'objets
ArgumentParser
contenant des arguments qui devraient aussi être inclus ;formatter_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
) ;exit_on_error - Determines whether or not
ArgumentParser
exits with error info when an error occurs. (default: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
.Modifié dans la version 3.9: Le paramètre exit_on_error est ajouté.
Les sections suivantes décrivent comment chacune de ces options sont utilisées.
Le paramètre prog¶
By default, ArgumentParser
calculates the name of the program
to display in help messages depending on the way the Python interpreter was run:
The
base name
ofsys.argv[0]
if a file was passed as argument.The Python interpreter name followed by
sys.argv[0]
if a directory or a zipfile was passed as argument.The Python interpreter name followed by
-m
followed by the module or package name if the-m
option was used.
This default is almost always desirable because it will make the help messages
match the string that was used to invoke the program on the command line.
However, to change this default behavior, another value can be supplied using
the prog=
argument to ArgumentParser
:
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]
options:
-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]
options:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
Le paramètre usage¶
By default, ArgumentParser
calculates the usage message from the
arguments it contains. The default message can be overridden with the
usage=
keyword argument:
>>> 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
options:
-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¶
Most calls to the ArgumentParser
constructor will use the
description=
keyword argument. This argument gives a brief description of
what the program does and how it works. In help messages, the description is
displayed between the command-line usage string and the help messages for the
various arguments.
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
options:
-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 définir 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 sont 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
options:
-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
options:
-h, --help show this help message and exit
RawTextHelpFormatter
maintains whitespace for all sorts of help text,
including argument descriptions. However, multiple newlines are replaced with
one. If you wish to preserve multiple blank lines, add spaces between the
newlines.
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 ...]
positional arguments:
bar BAR! (default: [1, 2, 3])
options:
-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
options:
-h, --help show this help message and exit
--foo int
Le paramètre prefix_chars¶
Most command-line options will use -
as the prefix, e.g. -f/--foo
.
Parsers that need to support different or additional prefix
characters, e.g. for options
like +f
or /foo
, may specify them using the prefix_chars=
argument
to the ArgumentParser
constructor:
>>> 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 sont traités comme des fichiers et sont remplacés par les arguments contenus dans ces fichiers. Par exemple :
>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) 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']
.
ArgumentParser
uses filesystem encoding and error handler
to read the file containing arguments.
Par défaut, l'argument fromfile_prefix_chars=
est None
, ce qui signifie que les arguments ne sont pas traités en tant que références à des fichiers.
Modifié dans la version 3.12: ArgumentParser
changed encoding and errors to read arguments files
from default (e.g. locale.getpreferredencoding(False)
and "strict"
) to the filesystem encoding and error handler.
Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.
Le paramètre argument_default¶
Généralement, les valeurs par défaut des arguments sont définies 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
Ajouté 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]
options:
-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¶
By default, ArgumentParser
objects add an option which simply displays
the parser's help message. If -h
or --help
is supplied at the command
line, the ArgumentParser
help will be printed.
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]
options:
--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]
options:
+h, ++help show this help message and exit
Le paramètre exit_on_error¶
Normally, when you pass an invalid argument list to the parse_args()
method of an ArgumentParser
, it will print a message to sys.stderr
and exit with a status
code of 2.
Si vous souhaitez intercepter les erreurs manuellement, la fonctionnalité peut être activée en assignant False
à exit_on_error
:
>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
... parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
... print('Catching an argumentError')
...
Catching an argumentError
Ajouté dans la version 3.9.
La méthode add_argument()¶
- ArgumentParser.add_argument(name or flags..., *[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])¶
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 - Either a name or a list of option strings, e.g.
'foo'
or'-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 et absent de l'objet
namespace
;type – Type vers lequel l'argument sur la ligne de commande doit être converti ;
choices – La séquence de valeurs autorisées 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 est ajouté à l'objet retourné par
parse_args()
.deprecated - Whether or not use of the argument is deprecated.
Les sections suivantes décrivent comment chacune de ces options sont utilisées.
Le paramètre name_or_flags¶
La méthode add_argument()
doit savoir s'il s'agit d'un argument optionnel (tel que -f
ou --foo
) ou d'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 drapeaux, soit le nom de l'argument.
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 est traité. Les actions natives sont :
'store'
- This just stores the argument's value. This is the default action.'store_const'
– Stocke la valeur passée à l'argument nommé const. La valeur par défaut de const estNone
. L'action'store_const'
est généralement utilisée avec des arguments optionnels représentant 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'
and'store_false'
- These are special cases of'store_const'
used for storing the valuesTrue
andFalse
respectively. In addition, they create default values ofFalse
andTrue
respectively:>>> 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 son argument à cette liste. Il est donc généralement utile d'accepter la répétition de cet argument. Si une valeur par défaut est précisée, alors cette valeur est également présente dans la liste et précède les valeurs passé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 de son argument const à cette liste. Notez que la valeur par défaut de l'argument const estNone
. L'action'append_const'
est pratique quand plusieurs arguments ont besoin de stocker des constantes dans une seule 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'>])
'extend'
- This stores a list and appends each item from the multi-value argument list to it. The'extend'
action is typically used with the nargs keyword argument value'+'
or'*'
. Note that when nargs isNone
(the default) or'?'
, each character of the argument string will be appended to the list. Example usage:>>> 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'])
Ajouté dans la version 3.8.
'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 est
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
Only actions that consume command-line arguments (e.g. 'store'
,
'append'
or 'extend'
) can be used with positional arguments.
- class argparse.BooleanOptionalAction¶
You may also specify an arbitrary action by passing an
Action
subclass or other object that implements the same interface. TheBooleanOptionalAction
is available inargparse
and adds support for boolean actions such as--foo
and--no-foo
:>>> import argparse >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction) >>> parser.parse_args(['--no-foo']) Namespace(foo=False)
Ajouté dans la version 3.9.
The recommended way to create a custom action is to extend Action
,
overriding the __call__()
method and optionally the __init__()
and
format_usage()
methods.
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¶
ArgumentParser
objects usually associate a single command-line argument with a
single action to be taken. The nargs
keyword argument associates a
different number of command-line arguments with a single action.
See also Specifying ambiguous arguments. The supported values are:
N
(un entier).N
arguments de la ligne de commande sont 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 de la ligne de commande est capturé 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
If the nargs
keyword argument is not provided, the number of arguments consumed
is determined by the action. Generally this means a single command-line argument
will be consumed and a single item (not a list) will be produced.
Actions that do not consume command-line arguments (e.g.
'store_const'
) set nargs=0
.
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. La valeur deconst
estNone
par défaut pouradd_argument()
;appeler la méthode
add_argument()
avec des chaînes d'options (telles-f
,--foo
ou avecnargs='?'
) crée un argument optionnel auquel peut être attribué une valeur. Si celle-ci est omise, l'analyseur prendNone
comme la valeur deconst
. La description de nargs offre quelques exemples.
Modifié dans la version 3.11: const=None
par défaut, y compris avec action='append_const'
ou action='store_const'
.
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 est utilisée 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)
If the target namespace already has an attribute set, the action default will not overwrite it:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)
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 définie 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)
For required arguments, the default
value is ignored. For example, this
applies to positional arguments with nargs values other than ?
or *
,
or optional arguments marked as required=True
.
Si vous passez default=argparse.SUPPRESS
, aucun attribut n'est 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, l'analyseur capture 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.
Si l'argument nommé type est utilisé en conjonction avec l'argument nommé default, le convertisseur de type n'est appliqué que si la valeur par défaut est une chaîne.
La valeur de l'argument type
peut être n'importe quel appelable qui accepte une seule chaîne. Si la fonction lève ArgumentTypeError
, TypeError
ou ValueError
, l'exception est traitée et un message d'erreur agréablement formaté est affiché. Aucun autre type d'exception n'est géré.
Les types et les fonctions natives peuvent être utilisés comme convertisseurs de types :
import argparse
import pathlib
parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)
Des fonctions définies par l'utilisateur peuvent aussi être utilisées :
>>> def hyphenated(string):
... return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')
La fonction bool()
est déconseillée comme convertisseur de type. Son comportement se limite à convertir les chaînes vides à False
et les chaînes non-vides à True
. Ce n'est généralement pas le résultat désiré.
En général, l'argument nommé type
est un raccourci qui ne devrait être utilisé que pour les conversions simples qui ne peuvent lever qu'une des trois exceptions gérées. Les conversions qui demandent un traitement d'erreurs plus intéressant ou une gestion de ressources devraient être effectuées plus tard dans l’exécution suivant l'analyse des arguments.
Par exemple, les conversions de documents JSON ou YAML ont des cas d'erreurs complexes qui requièrent un meilleur signalement que ce qui est fourni par l'argument nommé type
. Une exception JSONDecodeError
ne serait pas adéquatement formatée et une exception FileNotFoundError
ne serait pas du tout traitée.
Even FileType
has its limitations for use with the type
keyword. If one argument uses FileType
and then a
subsequent argument fails, an error is reported but the file is not
automatically closed. In this case, it would be better to wait until after
the parser has run and then use the with
-statement to manage the
files.
Pour les vérificateurs de types qui ne font que tester l'appartenance à un ensemble de valeurs, pensez plutôt à utiliser l'argument nommé choices.
Le paramètre choices¶
Certains arguments de la ligne de commande doivent être choisis parmi un ensemble prédéfini de valeurs. Celles-ci doivent être déclarées dans la séquence passée à l'argument choices de la méthode add_argument()
. Un message d'erreur est alors affiché si l'utilisateur passe un argument qui 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')
Note that inclusion in the choices sequence is checked after any type conversions have been performed, so the type of the objects in the choices sequence should match the type specified.
N'importe quel séquence peut être utilisée comme valeur de choices, dont les objets de type list
, set
ou des conteneurs personnalisés.
L'utilisation d'enum.Enum
est déconseillée, car il est difficile de contrôler son apparence dans les messages d'usage, d'aide et d'erreur.
Les choix formatés écrasent la valeur par défaut de metavar qui est normalement dérivée de dest. C'est en général le comportement recherché car l'utilisateur ne voit jamais le paramètre dest. Si cet affichage n'est pas souhaité (comme lorsque les choix sont trop nombreux) spécifiez simplement metavar de façon explicite.
Le paramètre required¶
In general, the argparse
module assumes that flags like -f
and --bar
indicate optional arguments, which can always be omitted at the command line.
To make an option required, True
can be specified for the required=
keyword argument to 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 à ce que les options soient optionnelles. Elles devraient donc être évitées si possible.
Le paramètre help¶
The help
value is a string containing a brief description of the argument.
When a user requests help (usually by using -h
or --help
at the
command line), these help
descriptions will be displayed with each
argument.
La chaîne help
peut contenir des définitions de formatage permettant 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 définitions disponibles comprennent 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)
options:
-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
supports silencing the help entry for certain options, by
setting the help
value to argparse.SUPPRESS
:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]
options:
-h, --help show this help message and exit
Le paramètre metavar¶
When ArgumentParser
generates help messages, it needs some way to refer
to each expected argument. By default, ArgumentParser
objects use the dest
value as the "name" of each object. By default, for positional argument
actions, the dest value is used directly, and for optional argument actions,
the dest value is uppercased. So, a single positional argument with
dest='bar'
will be referred to as bar
. A single
optional argument --foo
that should be followed by a single command-line argument
will be referred to as FOO
. An example:
>>> 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
options:
-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
options:
-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]
options:
-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 des chaînes d'options. ArgumentParser
génère la valeur de dest
en retirant le préfixe --
de la première chaîne d'options longues. Si aucune n'est fournie, dest
est alors dérivée de la première chaîne d'options courtes sans le préfixe -
. Tous les -
suivants sont convertis en _
pour s'assurer que la 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')
deprecated¶
During a project's lifetime, some arguments may need to be removed from the
command line. Before removing them, you should inform
your users that the arguments are deprecated and will be removed.
The deprecated
keyword argument of
add_argument()
, which defaults to False
,
specifies if the argument is deprecated and will be removed
in the future.
For arguments, if deprecated
is True
, then a warning will be
printed to sys.stderr
when the argument is used:
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='snake.py')
>>> parser.add_argument('--legs', default=0, type=int, deprecated=True)
>>> parser.parse_args([])
Namespace(legs=0)
>>> parser.parse_args(['--legs', '4'])
snake.py: warning: option '--legs' is deprecated
Namespace(legs=4)
Ajouté dans la version 3.13.
Classes Action¶
Action
classes implement the Action API, a callable which returns a callable
which processes arguments from the command-line. Any object which follows
this API may be passed as the action
parameter to
add_argument()
.
- class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)¶
Action
objects are used by anArgumentParser
to represent the information needed to parse a single argument from one or more strings from the command line. TheAction
class must accept the two positional arguments plus any keyword arguments passed toArgumentParser.add_argument()
except for theaction
itself.Instances of
Action
(or return value of any callable to theaction
parameter) should have attributesdest
,option_strings
,default
,type
,required
,help
, etc. defined. The easiest way to ensure these attributes are defined is to callAction.__init__()
.- __call__(parser, namespace, values, option_string=None)¶
Action
instances should be callable, so subclasses must override the__call__()
method, which should accept four parameters:parser - The
ArgumentParser
object which contains this action.namespace - The
Namespace
object that will be returned byparse_args()
. Most actions add an attribute to this object usingsetattr()
.values - The associated command-line arguments, with any type conversions applied. Type conversions are specified with the type keyword argument to
add_argument()
.option_string - The option string that was used to invoke this action. The
option_string
argument is optional, and will be absent if the action is associated with a positional argument.
The
__call__()
method may perform arbitrary actions, but will typically set attributes on thenamespace
based ondest
andvalues
.
- format_usage()¶
Action
subclasses can define aformat_usage()
method that takes no argument and return a string which will be used when printing the usage of the program. If such method is not provided, a sensible default will be used.
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'espace de nommage
namespace
. Renvoie un objetnamespace
rempli.Previous calls to
add_argument()
determine exactly what objects are created and how they are assigned. See the documentation foradd_argument()
for details.
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 de plus d'un 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 (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, au maximum, ne 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)
See also the argparse howto on ambiguous arguments for more details.
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 à aucune autre 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
¶
Sometimes it may be useful to have an ArgumentParser
parse arguments other than those
of sys.argv
. This can be accomplished by passing a list of strings to
parse_args()
. This is useful for testing at the
interactive prompt:
>>> 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 utilisée par défaut par
parse_args()
pour créer un objet qui stocke 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 utiliservars()
(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 objetNamespace
. 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][, dest][, required][, help][, metavar])¶
Many programs split up their functionality into a number of subcommands, for example, the
svn
program can invoke subcommands likesvn checkout
,svn update
, andsvn commit
. Splitting up functionality this way can be a particularly good idea when a program performs several different functions which require different kinds of command-line arguments.ArgumentParser
supports the creation of such subcommands with theadd_subparsers()
method. Theadd_subparsers()
method is normally called with no arguments and returns a special action object. This object has a single method,add_parser()
, which takes a command name and anyArgumentParser
constructor arguments, and returns anArgumentParser
object that can be modified as usual.Description des paramètres :
title - title for the sub-parser group in help output; by default "subcommands" if description is provided, otherwise uses title for positional arguments
description - description for the sub-parser group in help output, by default
None
prog - usage information that will be displayed with sub-command help, by default the name of the program and any positional arguments before the subparser argument
parser_class - class which will be used to create sub-parser instances, by default the class of the current parser (e.g.
ArgumentParser
)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 - string presenting available subcommands in help; by default it is
None
and presents subcommands in form {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='subcommand 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=('X', 'Y', 'Z'), 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 donnée, seuls les attributsfoo
etbar
sont présents alors que la commandeb
présente les attributsfoo
etbaz
.Similarly, when a help message is requested from a subparser, only the help for that particular parser will be printed. The help message will not include parent parser or sibling parser messages. (A help message for each subparser command, however, can be given by supplying the
help=
argument toadd_parser()
as above.)>>> parser.parse_args(['--help']) usage: PROG [-h] [--foo] {a,b} ... positional arguments: {a,b} subcommand help a a help b b help options: -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 options: -h, --help show this help message and exit >>> parser.parse_args(['b', '--help']) usage: PROG b [-h] [--baz {X,Y,Z}] options: -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} ... options: -h, --help show this help message and exit subcommands: valid subcommands {foo,bar} additional help
Furthermore,
add_parser()
supports an additional aliases argument, which allows multiple strings to refer to the same subparser. This example, likesvn
, aliasesco
as a shorthand forcheckout
:>>> 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')
add_parser()
supports also an additional deprecated argument, which allows to deprecate the subparser.>>> import argparse >>> parser = argparse.ArgumentParser(prog='chicken.py') >>> subparsers = parser.add_subparsers() >>> run = subparsers.add_parser('run') >>> fly = subparsers.add_parser('fly', deprecated=True) >>> parser.parse_args(['fly']) chicken.py: warning: command 'fly' is deprecated Namespace()
Ajouté dans la version 3.13.
One particularly effective way of handling subcommands is to combine the use of the
add_subparsers()
method with calls toset_defaults()
so that each subparser knows which Python function it should execute. For example:>>> # subcommand 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(required=True) >>> >>> # 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 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 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: New required keyword-only parameter.
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 le convertissent automatiquement 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'>)
Modifié dans la version 3.4: Added the encodings and errors parameters.
Groupes d'arguments¶
- ArgumentParser.add_argument_group(title=None, description=None, *[, argument_default][, conflict_handler])¶
By default,
ArgumentParser
groups command-line arguments into "positional arguments" and "options" when displaying help messages. When there is a better conceptual grouping of arguments than this default one, appropriate groups can be created using theadd_argument_group()
method:>>> 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
The
add_argument_group()
method returns an argument group object which has anadd_argument()
method just like a regularArgumentParser
. When an argument is added to the group, the parser treats it just like a normal argument, but displays the argument in a separate group for help messages. Theadd_argument_group()
method accepts title and description arguments which can be used to customize this display:>>> 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
The optional, keyword-only parameters argument_default and conflict_handler allow for finer-grained control of the behavior of the argument group. These parameters have the same meaning as in the
ArgumentParser
constructor, but apply specifically to the argument group rather than the entire parser.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.
Modifié dans la version 3.11: Appeler
add_argument_group()
sur un groupe d'arguments est obsolète. Cet emploi n'a jamais été pris en charge et ne fonctionne pas dans tous les cas. La présence de cette fonction dans l'API est purement accidentelle et celle-ci disparaîtra.
Exclusion mutuelle¶
- ArgumentParser.add_mutually_exclusive_group(required=False)¶
Create a mutually exclusive group.
argparse
will make sure that only one of the arguments in the mutually exclusive group was present on the command line:>>> 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
Note that currently mutually exclusive argument groups do not support the title and description arguments of
add_argument_group()
. However, a mutually exclusive group can be added to an argument group that has a title and description. For example:>>> parser = argparse.ArgumentParser(prog='PROG') >>> group = parser.add_argument_group('Group title', 'Group description') >>> exclusive_group = group.add_mutually_exclusive_group(required=True) >>> exclusive_group.add_argument('--foo', help='foo help') >>> exclusive_group.add_argument('--bar', help='bar help') >>> parser.print_help() usage: PROG [-h] (--foo FOO | --bar BAR) options: -h, --help show this help message and exit Group title: Group description --foo FOO foo help --bar BAR bar help
Modifié dans la version 3.11: Appeler
add_argument_group()
ouadd_mutually_exclusive_group()
sur un groupe mutuellement exclusif est obsolète. Cet emploi n'a jamais été pris en charge et ne fonctionne pas dans tous les cas. La présence de cette fonction dans l'API est purement accidentelle et celle-ci disparaîtra.
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
.
Analyse partielle¶
- ArgumentParser.parse_known_args(args=None, namespace=None)¶
Parfois, un script n'analyse que quelques-uns des arguments de la ligne de commande avant de passer les arguments non-traités à un autre script ou 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'objetNamespace
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)¶
This method terminates the program, exiting with the specified status and, if given, it prints a message to
sys.stderr
before that. The user can override this method to handle these steps differently: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)¶
This method prints a usage message, including the message, to
sys.stderr
and terminates the program with a status code of 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()
etparse_known_intermixed_args()
permettent ce style d'analyse.These parsers do not support all the
argparse
features, and will raise exceptions if unsupported features are used. In particular, subparsers, and mutually exclusive groups that include both optionals and positionals are not supported.L'exemple suivant illustre la différence entre
parse_known_args()
etparse_intermixed_args()
: le premier renvoie['2', '3']
comme arguments non-traités alors que le second capture tous les arguments positionnels dansrest
>>> 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'objetNamespace
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.Ajouté dans la version 3.7.
Exceptions¶
- exception argparse.ArgumentError¶
An error from creating or using an argument (optional or positional).
The string value of this exception is the message, augmented with information about the argument that caused it.
- exception argparse.ArgumentTypeError¶
Raised when something goes wrong converting a command line string to a type.
Guides et tutoriels