"argparse" --- Parser for command-line options, arguments and sub-commands
**************************************************************************

Ajouté dans la version 3.2.

**Code source:** Lib/argparse.py

======================================================================


Tutoriel
^^^^^^^^

Cette page est la référence de l'API. Pour une introduction plus en
douceur à l'analyse des arguments de la ligne de commande, regardez le
tutoriel argparse.

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 des arguments invalides.


Fonctionnalité principale
=========================

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)


Référence pour "add_argument()"
===============================

+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| Nom                          | Description                                                 | Valeurs                                                                                                                    |
|==============================|=============================================================|============================================================================================================================|
| action                       | Précise la gestion d'un argument                            | "'store'", "'store_const'", "'store_true'", "'append'", "'append_const'", "'count'", "'help'", "'version'"                 |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| choices                      | Limite le choix à certaines valeurs                         | "['foo', 'bar']", "range(1, 10)"  ou une instance de  "Container"                                                          |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| const                        | Utilise une valeur constante                                |                                                                                                                            |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| default                      | Valeur à utiliser en l'absence d'un argument                | "None" par défaut                                                                                                          |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| dest                         | Définit le nom de l'attribut à utiliser dans l'espace de    |                                                                                                                            |
|                              | nommage résultant                                           |                                                                                                                            |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| help                         | Message d'aide pour l'argument                              |                                                                                                                            |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| metavar                      | Autre nom possible pour l'argument, est affiché dans l'aide |                                                                                                                            |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| nargs                        | Précise le nombre de répétitions de l'argument              | "int", "'?'", "'*'" ou "'+'"                                                                                               |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| required                     | Précise si l'argument est obligatoire ou optionnel          | "True" ou "False"                                                                                                          |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| type                         | Conversion automatique vers le type fourni                  | "int", "float", "argparse.FileType('w')" ou une fonction                                                                   |
+------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+


Exemple
=======

Le code suivant est un programme Python acceptant une liste de nombres
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))

Après avoir sauvegardé le code Python ci-dessus dans un fichier nommé
"prog.py", il peut être lancé en ligne de commande et fournit le
message d'aide suivant :

   $ python prog.py -h
   usage: prog.py [-h] [--sum] N [N ...]

   Process some integers.

   positional arguments:
    N           an integer for the accumulator

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

   $ 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 affiche 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, 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 – Détermine si l'objet "ArgumentParser" termine
     l'exécution avec un message d'erreur quand une erreur est
     rencontrée (par défaut : "True").

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

   Modifié dans la version 3.8: Dans les versions précédentes,
   *allow_abbrev* désactivait aussi le regroupement de plusieurs
   options courtes telles que "-vv" pour signifier "-v -v".

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

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]

   options:
    -h, --help  show this help message and exit
    --foo FOO   foo help
   $ cd ..
   $ python subdir/myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   options:
    -h, --help  show this help message and exit
    --foo FOO   foo help

Pour changer ce comportement, 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]

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

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

   options:
    -h, --help   show this help message and exit
    --foo [FOO]  foo help

Le message par défaut peut être remplacé en utilisant 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

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

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

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

   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" 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 ...]

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

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 préciser 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 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 *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*
-----------------------

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" est affiché :

   $ python myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   options:
    -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]

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

En général, quand vous passez une liste d'arguments dont au moins un
est invalide à la méthode "parse_args()" d'une instance
d'"ArgumentParser", l'exécution se termine avec un message d'erreur.

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

   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 – Nom ou 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 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()".

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'" – 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.
  La valeur par défaut de const est "None". 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'" 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 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 est "None". 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'>])

* "'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 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

* "'extend'" – Stocke une liste et ajoute à la liste chacune des
  valeurs de l'argument reçues. Voici un exemple de son utilisation :

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
     >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
     Namespace(foo=['f1', 'f2', 'f3', 'f4'])

  Ajouté dans la version 3.8.

Vous pouvez aussi spécifier une action arbitraire en passant une sous-
classe d'"Action" ou un objet qui implémente la même interface. La
classe "BooleanOptionalAction" est disponible dans "argparse" et elle
ajoute la gestion des options booléennes telles que "--foo" et "--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.

La façon recommandée pour créer une action personnalisée est d'hériter
d'"Action" en surchargeant la méthode "__call__". Vous avez également
l'option de surcharger les méthodes "__init__" et "format_usage".

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

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. La valeur de
  "const" est "None" par défaut pour "add_argument()" ;

* appeler la méthode "add_argument()" avec des chaînes d'options
  (telles "-f", "--foo" ou avec "nargs='?'") crée un argument
  optionnel auquel peut être attribué une valeur. Si celle-ci est
  omise, l'analyseur prend "None" comme la valeur de "const". 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)

Si l'objet "namespace" cible a déjà un attribut assigné, l'action
*default* ne l'écrase pas :

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

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('source_file', type=open)
   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.

Même la classe "FileType" a ses limitations quand elle est utilisée
pour l'argument nommé "type". Si un argument utilise *FileType* et
qu'un argument ultérieur échoue, une erreur est annoncée mais le
fichier n'est pas automatiquement fermé. Dans ce cas, il serait mieux
d'attendre la fin de l'exécution de l'analyseur puis de gérer les
fichiers à l'aide d'un bloc "with".

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

Prenez note que le test d'inclusion dans le conteneur *choices* est
fait après la conversion de type. Le type des objets dans le conteneur
*choices* doit donc correspondre au type spécifié :

   >>> parser = argparse.ArgumentParser(prog='doors.py')
   >>> parser.add_argument('door', type=int, choices=range(1, 4))
   >>> print(parser.parse_args(['3']))
   Namespace(door=3)
   >>> parser.parse_args(['4'])
   usage: doors.py [-h] {1,2,3}
   doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

N'importe quel 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*
-----------------------

En général, le module "argparse" prend pour acquis que les drapeaux
comme "-f" et "--bar" annoncent un argument *optionnel* qui peut
toujours être omis de la ligne de commande. Pour rendre une option
*obligatoire*, "True" peut être passé à l'argument nommé "required="
d'"add_argument()" :

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', required=True)
   >>> parser.parse_args(['--foo', 'BAR'])
   Namespace(foo='BAR')
   >>> parser.parse_args([])
   usage: [-h] --foo FOO
   : error: the following arguments are required: --foo

Tel qu'illustré dans l'exemple, quand l'option est marquée comme
"required", "parse_args()" mentionne une erreur si l'option est
absente de la ligne de commande.

Note:

  En général, les options obligatoires manifestent un style boiteux,
  car les utilisateurs s'attendent à ce 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 sont 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

   options:
    -h, --help  show this help message and exit
    --foo   foo the bars before frobbling

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

   options:
     -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. La valeur de dest est alors 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'" est affiché comme "bar" et un
argument optionnel unique "--foo" qui prend un seul argument sur la
ligne de commande est 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

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


Classes Action
--------------

Les classes "Action" implémentent l'API Action, un appelable qui
renvoie 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 est 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 affecte des attributs sur le "namespace" en fonction de
"dest" et de "values".

Les classes dérivées d'"Action" peuvent définir une méthode
"format_usage" qui ne prend aucun argument et qui renvoie une chaîne
utilisée lors de l'affichage du message d'utilisation du programme. Si
cette méthode n'est pas fournie, une valeur raisonnable est utilisée
par défaut.


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


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

Il est parfois désirable de demander à un objet "ArgumentParser" de
faire l'analyse d'arguments autres que ceux de "sys.argv". On peut
faire ce traitement en passant une liste de chaînes à "parse_args()".
Cette approche est pratique pour faire des tests depuis l'invite de
commande :

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument(
   ...     'integers', metavar='int', type=int, choices=range(10),
   ...     nargs='+', help='an integer in the range 0..9')
   >>> parser.add_argument(
   ...     '--sum', dest='accumulate', action='store_const', const=sum,
   ...     default=max, help='sum the integers (default: find the max)')
   >>> parser.parse_args(['1', '2', '3', '4'])
   Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
   >>> parser.parse_args(['1', '2', '3', '4', '--sum'])
   Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])


L'objet "Namespace"
-------------------

class argparse.Namespace

   Classe rudimentaire utilisée par défaut par "parse_args()" pour
   créer un objet qui stocke 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_strings][, dest][, required][, help][, metavar])

   Certains programmes organisent leurs fonctionnalités grâce à des
   sous-commandes. Par exemple : le programme "svn" peut être invoqué
   comme "svn checkout", "svn update" et "svn commit". Cette manière
   d'organiser les fonctionnalités est judicieuse quand le programme
   effectue plusieurs fonctions différentes qui requièrent différents
   types de lignes de commandes. "ArgumentParser" prend en charge la
   création de ce genre de sous-commandes grâce à la méthode
   "add_subparsers()". La méthode "add_subparsers()" est généralement
   appelée sans argument et elle renvoie un objet "Action" spécial.
   Cet objet possède une seule méthode, "add_parser()", qui prend le
   nom d'une commande et n'importe quels arguments du constructeur
   d'"ArgumentParser" ; elle renvoie un objet "ArgumentParser" qui
   peut être modifié normalement.

   Description des paramètres :

   * "title" – titre du groupe de ce sous-analyseur dans la sortie
     d'aide ; par défaut : ""subcommands"" si "description" est
     fournie, sinon utilise la valeur de "title" de la section sur les
     arguments positionnels ;

   * "description" – description du groupe de ce sous-analyseur dans
     la sortie d'aide ; par défaut : "None" ;

   * "prog" – nom du programme dans le message d'utilisation de l'aide
     des sous-commandes ; par défaut : le nom du programme et les
     arguments positionnels qui arrivent avant l'argument de ce sous-
     analyseur ;

   * "parser_class" – classe utilisée pour créer les instances de
     sous-analyseurs ; par défaut : la classe de l'analyseur courant
     (par exemple "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 – chaîne qui représente les sous-commandes disponibles
     dans les messages d'aide ; par défaut : "None", ce qui entraine
     la génération d'une chaîne suivant le format "'{cmd1, cmd2, …}'".

   Quelques exemples d'utilisation :

      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--foo', action='store_true', help='foo help')
      >>> subparsers = parser.add_subparsers(help='sub-command help')
      >>>
      >>> # create the parser for the "a" command
      >>> parser_a = subparsers.add_parser('a', help='a help')
      >>> parser_a.add_argument('bar', type=int, help='bar help')
      >>>
      >>> # create the parser for the "b" command
      >>> parser_b = subparsers.add_parser('b', help='b help')
      >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
      >>>
      >>> # parse some argument lists
      >>> parser.parse_args(['a', '12'])
      Namespace(bar=12, foo=False)
      >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
      Namespace(baz='Z', foo=True)

   Prenez note que l'objet renvoyé par "parse_args()" ne contient que
   les attributs reconnus par l'analyseur principal et le sous-
   analyseur sélectionné par la ligne de commande. Les autres sous-
   analyseurs n'ont pas d'influence sur l'objet renvoyé. Ainsi dans
   l'exemple précédent, quand la commande "a" est donnée, seuls les
   attributs "foo" et "bar" sont présents alors que la commande "b"
   présente les attributs "foo" et "baz".

   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

      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és "title"
   et "description". 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

   De plus, "add_parser" accepte l'argument additionnel "aliases" qui
   permet à plusieurs chaînes de faire référence au même sous-
   analyseur. L'exemple suivant, à la manière de "svn",  utilise "co"
   comme une abréviation de "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')

   Une façon efficace de traiter les sous-commandes est de combiner
   l'utilisation de la méthode "add_subparsers()" avec des appels à
   "set_defaults()" pour que chaque sous-analyseur sache quelle
   fonction Python doit être exécutée. Par exemple :

      >>> # sub-command functions
      >>> def foo(args):
      ...     print(args.x * args.y)
      ...
      >>> def bar(args):
      ...     print('((%s))' % args.z)
      ...
      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(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: Introduction des arguments nommés
   obligatoires.


Objets "FileType"
-----------------

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

   Le type fabrique "FileType" crée des objets qui peuvent être passés
   à l'argument "type" d'"ArgumentParser.add_argument()". Les
   arguments qui ont comme "type" un objet "FileType" 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 fonction "open()" 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 vers "sys.stdin" pour les objets
   "FileType" ouverts en lecture, et vers "sys.stdout" pour les objets
   "FileType" 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)

   Par défaut, "ArgumentParser" regroupe les arguments de la ligne de
   commande entre « arguments positionnels » et « arguments optionnels
   » dans l'affichage de l'aide. Lorsqu'un meilleur regroupement
   conceptuel est possible, celui-ci peut être créé avec la méthode
   "add_argument_group()" :

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group = parser.add_argument_group('group')
      >>> group.add_argument('--foo', help='foo help')
      >>> group.add_argument('bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--foo FOO] bar

      group:
        bar    bar help
        --foo FOO  foo help

   La méthode "add_argument_group()" renvoie un objet représentant le
   groupe d'arguments. Cet objet possède une méthode "add_argument()"
   semblable à celle d'"ArgumentParser". Quand un argument est ajouté
   au groupe, l'analyseur le traite comme un argument normal, mais il
   affiche le nouvel argument dans un groupe séparé dans les messages
   d'aide. Afin de personnaliser l'affichage, la méthode
   "add_argument_group()" accepte les arguments "title" et
   "description" :

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group1 = parser.add_argument_group('group1', 'group1 description')
      >>> group1.add_argument('foo', help='foo help')
      >>> group2 = parser.add_argument_group('group2', 'group2 description')
      >>> group2.add_argument('--bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--bar BAR] foo

      group1:
        group1 description

        foo    foo help

      group2:
        group2 description

        --bar BAR  bar help

   Prenez note que tout argument qui n'est pas dans l'un de vos
   groupes est affiché dans l'une des sections usuelles *positional
   arguments* et *optional arguments*.

   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)

   Crée un groupe mutuellement exclusif. Le module "argparse" vérifie
   qu'au plus un des arguments du groupe mutuellement exclusif est
   présent sur la ligne de commande :

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group()
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args(['--foo'])
      Namespace(bar=True, foo=True)
      >>> parser.parse_args(['--bar'])
      Namespace(bar=False, foo=False)
      >>> parser.parse_args(['--foo', '--bar'])
      usage: PROG [-h] [--foo | --bar]
      PROG: error: argument --bar: not allowed with argument --foo

   La méthode "add_mutually_exclusive_group()" accepte aussi
   l'argument "required" 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()" ou
   "add_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éthode "set_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 par "add_argument()" ou par
   "set_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. Si "file" est
   "None", utilise "sys.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". Si "file" est "None", utilise "sys.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'objet "Namespace" rempli
et la liste des arguments non-traités.

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action='store_true')
   >>> parser.add_argument('bar')
   >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
   (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

Avertissement:

  Les règles d'acceptation des abréviations sont applicables à
  "parse_known_args()". L'analyseur peut ainsi capturer une option
  même si elle n'est que le préfixe d'une option reconnue plutôt que
  de la laisser dans la liste des arguments non-traités.


Personnaliser le *parsing* de fichiers
--------------------------------------

ArgumentParser.convert_arg_line_to_args(arg_line)

   Les arguments qui proviennent d'un fichier sont lus un par ligne.
   La méthode "convert_arg_line_to_args()" peut être surchargée pour
   accomplir un traitement plus élaboré. Voir aussi l'argument nommé
   "fromfile_prefix_chars" du constructeur d'"ArgumentParser".

   La méthode "convert_arg_line_to_args" accepte un seul argument,
   "arg_line", qui est une chaîne lue dans le fichier d'arguments.
   Elle renvoie une liste d'arguments analysés dans cette chaîne. La
   méthode est appelée une fois pour chaque ligne lue du fichier
   d'arguments. L'ordre est préservé.

   Une surcharge utile de cette méthode est de permettre à chaque mot
   délimité par des espaces d'être traité comme un argument. L'exemple
   suivant illustre comment réaliser ceci :

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


Méthodes d'interruptions
------------------------

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

   Cette méthode interrompt l'exécution du programme et renvoie
   "status" comme valeur de retour du processus. Si "message" est
   fourni, la chaîne est affichée avant la fin de l'exécution. Vous
   pouvez surcharger cette méthode pour traiter ces étapes
   différemment :

      class ErrorCatchingArgumentParser(argparse.ArgumentParser):
          def exit(self, status=0, message=None):
              if status:
                  raise Exception(f'Exiting because of an error: {message}')
              exit(status)

ArgumentParser.error(message)

   Cette méthode affiche un message d'utilisation qui inclut la chaîne
   "message" sur la sortie d'erreur standard puis termine l'exécution
   avec le code de fin d'exécution 2.


Analyse entremêlée
------------------

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

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

De nombreuses commandes Unix permettent à l'utilisateur d'entremêler
les arguments optionnels et les arguments positionnels. Les méthodes
"parse_intermixed_args()" et "parse_known_intermixed_args()"
permettent ce style d'analyse.

Ces analyseurs n'offrent pas toutes les fonctionnalités d'"argparse"
et ils lèvent une exception si une fonctionnalité non prise en charge
est utilisée. En particulier, les sous-analyseurs et les groupes
mutuellement exclusifs qui contiennent à la fois des arguments
optionnels et des arguments positionnels ne sont pas pris en charge.

L'exemple suivant illustre la différence entre "parse_known_args()" et
"parse_intermixed_args()" : le premier renvoie "['2', '3']" comme
arguments non-traités alors que le second capture tous les arguments
positionnels dans "rest"

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('cmd')
   >>> parser.add_argument('rest', nargs='*', type=int)
   >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
   (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
   >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
   Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

"parse_known_intermixed_args()" renvoie une paire de valeurs : l'objet
"Namespace" rempli et une liste de chaînes d'arguments non-traités.
"parse_intermixed_args()" lève une erreur s'il reste des chaînes
d'arguments non-traités.

Ajouté dans la version 3.7.


Mettre à jour du code "optparse"
================================

Initialement, le module "argparse" tentait de rester compatible avec
"optparse". Hélas, il était difficile de faire des améliorations à
"optparse" de façon transparente, en particulier pour les changements
requis pour gérer les nouveaux spécificateurs de "nargs=" et les
messages d'utilisation améliorés. Après avoir porté ou surchargé tout
le code d'"optparse", la rétro-compatibilité pouvait difficilement
être conservée.

Le module "argparse" fournit plusieurs améliorations par rapport au
module "optparse" de la bibliothèque standard :

* gère les arguments positionnels ;

* prise en charge des sous commandes ;

* permet d'utiliser les alternatives "+" ou "/" comme préfixes
  d'option ;

* prend en charge la répétition de valeurs (zéro ou plus, un ou plus)
  ;

* fournit des messages d'aide plus complets ;

* fournit une interface plus simple pour les types et les 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>')".


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.
