15.6. 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, options[, long_options])

Parses command line options and parameter list. args is the argument list to be parsed, without the leading reference to the running program. Typically, this means sys.argv[1:]. options is the string of option letters that the script wants to recognize, with options that require an argument followed by a colon (':'; i.e., the same format that Unix getopt() uses).

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.

long_options, if specified, must be a list of strings with the names of the long options which should be supported. The leading '--' characters should not be included in the option name. Long options which require an argument should be followed by an equal sign ('='). Optional arguments are not supported. To accept only long options, options should be an empty string. Long options on the command line can be recognized so long as they provide a prefix of the option name that matches exactly one of the accepted options. For example, if long_options is ['foo', 'frob'], the option --fo will match as --foo, but --f will not match uniquely, so GetoptError will be raised.

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, options[, long_options])

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

Nouveau dans la version 2.3.

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.

Modifié dans la version 1.6: Introduced GetoptError as a synonym for error.

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