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.