"getopt" – Analyseur de style C pour les options de ligne de commande
*********************************************************************

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

Note:

  Le module "getopt" est un analyseur pour les options de ligne de
  commande dont l’API est conçue pour être familière aux utilisateurs
  de la fonction C "getopt()". Les utilisateurs qui ne connaissent pas
  la fonction "getopt()" ou qui aimeraient écrire moins de code,
  obtenir une meilleure aide et de meilleurs messages d’erreur
  devraient utiliser le module "argparse".

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

Ce module aide les scripts à analyser les arguments de ligne de
commande contenus dans "sys.argv". Il prend en charge les mêmes
conventions que la fonction UNIX "getopt()" (y compris les
significations spéciales des arguments de la forme "-" et "--"). De
longues options similaires à celles prises en charge par le logiciel
GNU peuvent également être utilisées via un troisième argument
facultatif.

Ce module fournit deux fonctions et une exception :

getopt.getopt(args, shortopts, longopts=[])

   Analyse les options de ligne de commande et la liste des
   paramètres. *args* est la liste d’arguments à analyser, sans la
   référence principale au programme en cours d’exécution. En général,
   cela signifie "sys.argv[1:]" (donc que le premier argument
   contenant le nom du programme n’est pas dans la liste). *shortopts*
   est la chaîne de lettres d’options que le script doit reconnaître,
   avec des options qui requièrent un argument suivi d’un signe deux-
   points (":", donc le même format que la version Unix de "getopt()"
   utilise).

   Note:

     Contrairement au "getopt()" GNU, après un argument n'appartenant
     pas à une option, aucun argument ne sera considéré comme
     appartenant à une option. Ceci est similaire à la façon dont les
     systèmes UNIX non-GNU fonctionnent.

   *longopts*, si spécifié, doit être une liste de chaînes avec les
   noms des options longues qui doivent être prises en charge. Le
   premier "'--'" ne dois pas figurer dans le nom de l’option. Les
   options longues qui requièrent un argument doivent être suivies
   d’un signe égal ("'='"). Les arguments facultatifs ne sont pas pris
   en charge. Pour accepter uniquement les options longues,
   *shortopts* doit être une chaîne vide. Les options longues sur la
   ligne de commande peuvent être reconnues tant qu’elles fournissent
   un préfixe du nom de l’option qui correspond exactement à l’une des
   options acceptées. Par exemple, si *longopts* est "['foo',
   'frob']", l’option "--fo" correspondra à "--foo", mais "--f" ne
   correspondra pas de façon unique, donc "GetoptError" sera levé.

   La valeur de retour se compose de deux éléments : le premier est
   une liste de paires "(option, value)", la deuxième est la liste des
   arguments de programme laissés après que la liste d’options est été
   dépouillée (il s’agit d’une tranche de fin de *args*). Chaque paire
   option-valeur retournée a l’option comme premier élément, préfixée
   avec un trait d'union pour les options courtes (par exemple,
   "'-x'") ou deux tirets pour les options longues (par exemple, "'--
   long-option'"), et l’argument option comme deuxième élément, ou une
   chaîne vide si le option n’a aucun argument. Les options se
   trouvent dans la liste dans l’ordre dans lequel elles ont été
   trouvées, permettant ainsi plusieurs occurrences. Les options
   longues et courtes peuvent être mélangées.

getopt.gnu_getopt(args, shortopts, longopts=[])

   Cette fonction fonctionne comme "getopt()", sauf que le mode de
   *scan* GNU est utilisé par défaut. Cela signifie que les arguments
   option et non-option peuvent être **intermixés**. La fonction
   "getopt()" arrête le traitement des options dès qu’un argument de
   non-option est rencontré.

   Si le premier caractère de la chaîne d’options est "+", ou si la
   variable d’environnement "POSIXLY_CORRECT" est définie, le
   traitement des options s’arrête dès qu’un argument non-option est
   rencontré.

exception getopt.GetoptError

   Cette exception est levée lorsqu’une option non reconnue est
   trouvée dans la liste d’arguments ou lorsqu’une option nécessitant
   un argument n’en a pas reçu. L’argument de l’exception est une
   chaîne de caractères indiquant la cause de l’erreur. Pour les
   options longues, un argument donné à une option qui n’en exige pas
   un entraîne également le levage de cette exception. Les attributs
   "msg" et "opt" donnent le message d’erreur et l’option connexe.
   S’il n’existe aucune option spécifique à laquelle l’exception se
   rapporte, "opt" est une chaîne vide.

exception getopt.error

   Alias pour "GetoptError" ; pour la rétrocompatibilité.

Un exemple utilisant uniquement les options de style UNIX :

>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']

L’utilisation de noms d’options longs est tout aussi simple :

>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
...     'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']

Dans un script, l’utilisation typique ressemble à ceci :

   import getopt, sys

   def main():
       try:
           opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
       except getopt.GetoptError as err:
           # print help information and exit:
           print(err)  # will print something like "option -a not recognized"
           usage()
           sys.exit(2)
       output = None
       verbose = False
       for o, a in opts:
           if o == "-v":
               verbose = True
           elif o in ("-h", "--help"):
               usage()
               sys.exit()
           elif o in ("-o", "--output"):
               output = a
           else:
               assert False, "unhandled option"
       # ...

   if __name__ == "__main__":
       main()

Notez qu’une interface de ligne de commande équivalente peut être
produite avec moins de code et des messages d’erreur et d’aide plus
informatifs à l’aide du module "argparse" module :

   import argparse

   if __name__ == '__main__':
       parser = argparse.ArgumentParser()
       parser.add_argument('-o', '--output')
       parser.add_argument('-v', dest='verbose', action='store_true')
       args = parser.parse_args()
       # ... do something with args.output ...
       # ... do something with args.verbose ..

Voir aussi:

  Module "argparse"
     Option de ligne de commande alternative et bibliothèque d’analyse
     d’arguments.
