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 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)

Modifié dans la version 3.5: Le paramètre allow_abbrev est ajouté.

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.

  • requiredTrue 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 est True et False, respectivement. Aussi, ces actions ont comme valeur par défaut False et True, 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 est None. 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)
    

    Note, the default will be None unless explicitly set to 0.

  • 'help' – Affiche le message d'aide complet pour toutes les options de l'analyseur puis termine l'exécution. Une action help est automatiquement ajoutée à l'analyseur par défaut. Consultez ArgumentParser 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
    

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(FooAction, self).__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 avec nargs='*', mais il est par contre possible d'avoir plusieurs arguments optionnels qui spécifient nargs='*'. 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 avec action='store_const' ou action='append_const'. Ces actions ajoutent la valeur de const à l'un des attributs de l'objet renvoyé par parse_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) et nargs='?'. 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 de const 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)

Any object that supports the in operator can be passed as the choices value, so dict objects, set objects, custom containers, etc. are all supported.

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: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required

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'objet ArgumentParser qui contient cette action.

  • namespace – L'objet Namespace qui sera renvoyé par parse_args(). La majorité des actions ajoutent un attribut à cet objet avec setattr().

  • 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'argument option_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'objet namespace 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.

  • args – Liste de chaînes à analyser. La valeur par défaut est récupérée dans : sys.argv.

  • namespace – Un objet pour recevoir les attributs. Par défaut : une nouvelle instance (vide) de Namespace.

Option value syntax

The parse_args() method supports several ways of specifying the value of an option (if it takes one). In the simplest case, the option and its value are passed as two separate arguments:

>>> 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)

For long options (options with names longer than a single character), the option and value can also be passed as a single command-line argument, using = to separate them:

>>> 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

While parsing the command line, parse_args() checks for a variety of errors, including ambiguous options, invalid types, invalid options, wrong number of positional arguments, etc. When it encounters such an error, it exits and prints the error along with a usage message:

>>> 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 -

The parse_args() method attempts to give errors whenever the user has clearly made a mistake, but some situations are inherently ambiguous. For example, the command-line argument -1 could either be an attempt to specify an option or an attempt to provide a positional argument. The parse_args() method is cautious here: positional arguments may only begin with - if they look like negative numbers and there are no options in the parser that look like negative numbers:

>>> 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

If you have positional arguments that must begin with - and don't look like negative numbers, you can insert the pseudo-argument '--' which tells parse_args() that everything after that is a positional argument:

>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)

Arguments abrégés (Par comparaison de leurs préfixes)

The parse_args() method by default allows long options to be abbreviated to a prefix, if the abbreviation is unambiguous (the prefix matches a unique 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 qui est utilisé par défaut par parse_args() pour créer un objet qui stock les attributs. Cet objet est renvoyé par ArgumentParser.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])

Many programs split up their functionality into a number of sub-commands, for example, the svn program can invoke sub-commands like svn checkout, svn update, and svn 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 sub-commands with the add_subparsers() method. The add_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 any ArgumentParser constructor arguments, and returns an ArgumentParser 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 - the basic type of action to be taken when this argument is encountered at the command line

  • dest - name of the attribute under which sub-command name will be stored; by default None and no value is stored

  • required - Whether or not a subcommand must be provided, by default False (added in 3.7)

  • help - help for sub-parser group in help output, by default None

  • metavar - string presenting available sub-commands in help; by default it is None and presents sub-commands 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='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)

Note that the object returned by parse_args() will only contain attributes for the main parser and the subparser that was selected by the command line (and not any other subparsers). So in the example above, when the a command is specified, only the foo and bar attributes are present, and when the b command is specified, only the foo and baz attributes are present.

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 to add_parser() as above.)

>>> 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

The add_subparsers() method also supports title and description keyword arguments. When either is present, the subparser's commands will appear in their own group in the help output. For example:

>>> 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

Furthermore, add_parser supports an additional aliases argument, which allows multiple strings to refer to the same subparser. This example, like svn, aliases co as a shorthand for checkout:

>>> 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')

One particularly effective way of handling sub-commands is to combine the use of the add_subparsers() method with calls to set_defaults() so that each subparser knows which Python function it should execute. For example:

>>> # 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))

This way, you can let parse_args() do the job of calling the appropriate function after argument parsing is complete. Associating functions with actions like this is typically the easiest way to handle the different actions for each of your subparsers. However, if it is necessary to check the name of the subparser that was invoked, the dest keyword argument to the add_subparsers() call will work:

>>> 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 argument.

Objets FileType

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)

The FileType factory creates objects that can be passed to the type argument of ArgumentParser.add_argument(). Arguments that have FileType objects as their type will open command-line arguments as files with the requested modes, buffer sizes, encodings and error handling (see the open() function for more details):

>>> 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'>)

FileType objects understand the pseudo-argument '-' and automatically convert this into sys.stdin for readable FileType objects and sys.stdout for writable FileType objects:

>>> 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 et errors.

Groupes d'arguments

ArgumentParser.add_argument_group(title=None, description=None)

By default, ArgumentParser groups command-line arguments into "positional arguments" and "optional arguments" when displaying help messages. When there is a better conceptual grouping of arguments than this default one, appropriate groups can be created using the add_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 an add_argument() method just like a regular ArgumentParser. 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. The add_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

Note that any arguments not in your user-defined groups will end up back in the usual "positional arguments" and "optional arguments" sections.

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

The add_mutually_exclusive_group() method also accepts a required argument, to indicate that at least one of the mutually exclusive arguments is required:

>>> 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().

Valeurs par défaut de l'analyseur

ArgumentParser.set_defaults(**kwargs)

Most of the time, the attributes of the object returned by parse_args() will be fully determined by inspecting the command-line arguments and the argument actions. set_defaults() allows some additional attributes that are determined without any inspection of the command line to be added:

>>> 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)

Note that parser-level defaults always override argument-level defaults:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')

Parser-level defaults can be particularly useful when working with multiple parsers. See the add_subparsers() method for an example of this type.

ArgumentParser.get_default(dest)

Get the default value for a namespace attribute, as set by either add_argument() or by set_defaults():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'

Afficher l'aide

In most typical applications, parse_args() will take care of formatting and printing any usage or error messages. However, several formatting methods are available:

ArgumentParser.print_usage(file=None)

Print a brief description of how the ArgumentParser should be invoked on the command line. If file is None, sys.stdout is assumed.

ArgumentParser.print_help(file=None)

Print a help message, including the program usage and information about the arguments registered with the ArgumentParser. If file is None, sys.stdout is assumed.

There are also variants of these methods that simply return a string instead of printing it:

ArgumentParser.format_usage()

Return a string containing a brief description of how the ArgumentParser should be invoked on the command line.

ArgumentParser.format_help()

Return a string containing a help message, including the program usage and information about the arguments registered with the ArgumentParser.

Parsing partiel

ArgumentParser.parse_known_args(args=None, namespace=None)

Sometimes a script may only parse a few of the command-line arguments, passing the remaining arguments on to another script or program. In these cases, the parse_known_args() method can be useful. It works much like parse_args() except that it does not produce an error when extra arguments are present. Instead, it returns a two item tuple containing the populated namespace and the list of remaining argument strings.

>>> 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

Prefix matching rules apply to parse_known_args(). The parser may consume an option even if it's just a prefix of one of its known options, instead of leaving it in the remaining arguments list.

Personnaliser le parsing de fichiers

ArgumentParser.convert_arg_line_to_args(arg_line)

Arguments that are read from a file (see the fromfile_prefix_chars keyword argument to the ArgumentParser constructor) are read one argument per line. convert_arg_line_to_args() can be overridden for fancier reading.

This method takes a single argument arg_line which is a string read from the argument file. It returns a list of arguments parsed from this string. The method is called once per line read from the argument file, in order.

A useful override of this method is one that treats each space-separated word as an argument. The following example demonstrates how to do this:

class MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()

Exiting methods

ArgumentParser.exit(status=0, message=None)

This method terminates the program, exiting with the specified status and, if given, it prints a message before that.

ArgumentParser.error(message)

This method prints a usage message including the message to the standard error 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)

A number of Unix commands allow the user to intermix optional arguments with positional arguments. The parse_intermixed_args() and parse_known_intermixed_args() methods support this parsing style.

These parsers do not support all the argparse features, and will raise exceptions if unsupported features are used. In particular, subparsers, argparse.REMAINDER, and mutually exclusive groups that include both optionals and positionals are not supported.

The following example shows the difference between parse_known_args() and parse_intermixed_args(): the former returns ['2', '3'] as unparsed arguments, while the latter collects all the positionals into 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() returns a two item tuple containing the populated namespace and the list of remaining argument strings. parse_intermixed_args() raises an error if there are any remaining unparsed argument strings.

Nouveau dans la version 3.7.

Mettre à jour du code optparse

Originally, the argparse module had attempted to maintain compatibility with optparse. However, optparse was difficult to extend transparently, particularly with the changes required to support the new nargs= specifiers and better usage messages. When most everything in optparse had either been copy-pasted over or monkey-patched, it no longer seemed practical to try to maintain the backwards compatibility.

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() par args = parser.parse_args() et ajouter des appels à ArgumentParser.add_argument() pour les arguments positionnels. Prenez note que les valeurs précédemment appelées options sont appelées args dans le contexte d'argparse.

  • Remplacer optparse.OptionParser.disable_interspersed_args() en appelant parse_intermixed_args() plutôt que parse_args().

  • Remplacer les actions de rappel (callback actions en anglais) et les arguments nommés callback_* par des arguments type et actions.

  • 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 par Namespace ; et optparse.OptionError et optparse.OptionValueError par ArgumentError.

  • 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>').