getopt — C-stilsanalysator för kommandoradsalternativ

Källkod: Lib/getopt.py

Anteckning

Denna modul anses vara funktionsmässigt komplett. Ett mer deklarativt och utbyggbart alternativ till detta API finns i modulen optparse. Ytterligare funktionella förbättringar för bearbetning av kommandoradsparametrar tillhandahålls antingen som tredjepartsmoduler på PyPI eller som funktioner i modulen argparse.

Denna modul hjälper skript att tolka kommandoradsargumenten i sys.argv. Den stöder samma konventioner som Unix getopt()-funktionen (inklusive de speciella betydelserna av argument av formen ’-’ och ’--’). Långa alternativ liknande dem som stöds av GNU-programvara kan också användas via ett valfritt tredje argument.

Användare som inte är bekanta med Unix-funktionen getopt() bör överväga att använda modulen argparse i stället. Användare som är bekanta med Unix getopt()-funktionen, men som vill få motsvarande beteende samtidigt som de skriver mindre kod och får bättre hjälp- och felmeddelanden bör överväga att använda modulen optparse. Se Att välja ett bibliotek för argumentparsning för ytterligare detaljer.

Denna modul innehåller två funktioner och ett undantag:

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

Analyserar kommandoradsalternativ och parameterlista. args är den argumentlista som ska analyseras, utan den inledande referensen till det program som körs. Vanligtvis betyder detta sys.argv[1:]. shortopts är den sträng med alternativbokstäver som skriptet vill känna igen, med alternativ som kräver ett argument följt av ett kolon (':') och alternativ som accepterar ett valfritt argument följt av två kolon ('::'); dvs. samma format som Unix getopt() använder.

Anteckning

Till skillnad från GNU getopt(), efter ett argument som inte är ett alternativ, anses alla ytterligare argument också vara icke-alternativ. Detta liknar det sätt på vilket Unix-system som inte är GNU fungerar.

longopts, om det anges, måste vara en lista med strängar med namnen på de långa alternativ som ska stödjas. De inledande tecknen '--' skall inte ingå i alternativnamnet. Långa alternativ som kräver ett argument skall följas av ett likhetstecken ('='). Långa alternativ som accepterar ett valfritt argument bör följas av ett likhetstecken och ett frågetecken ('=?'). För att endast acceptera långa alternativ bör shortopts vara en tom sträng. Långa alternativ på kommandoraden kan identifieras så länge som de innehåller ett prefix för alternativnamnet som matchar exakt ett av de accepterade alternativen. Om longopts till exempel är ['foo', 'frob'], kommer alternativet --fo att matcha som --foo, men --f kommer inte att matcha unikt, så GetoptError kommer att uppstå.

Returvärdet består av två element: det första är en lista med paren (option, value); det andra är listan med programargument som finns kvar efter att optionslistan har rensats (detta är en efterföljande del av args). Varje alternativ- och värdepar som returneras har alternativet som sitt första element, med ett bindestreck som prefix för korta alternativ (t.ex. '-x') eller två bindestreck för långa alternativ (t.ex. '--long-option'), och alternativets argument som sitt andra element, eller en tom sträng om alternativet inte har något argument. Alternativen förekommer i listan i samma ordning som de hittades, vilket innebär att de kan förekomma flera gånger. Långa och korta alternativ kan blandas.

Ändrad i version 3.14: Valfria argument stöds.

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

Den här funktionen fungerar som getopt(), förutom att GNU-stilens skanningsläge används som standard. Detta innebär att alternativ- och icke-alternativargument kan blandas. Funktionen getopt() slutar att bearbeta alternativ så snart ett argument som inte är ett alternativ påträffas.

Om det första tecknet i alternativsträngen är '+', eller om miljövariabeln POSIXLY_CORRECT är inställd, stoppas alternativbehandlingen så snart ett argument som inte är ett alternativ påträffas.

Om det första tecknet i optionssträngen är '-' läggs icke-optionsargument som följs av optioner till i listan över options- och värdepar som ett par med None som första element och listan över icke-optionsargument som andra element. Det andra elementet i gnu_getopt()-resultatet är en lista över programargument efter det sista alternativet.

Ändrad i version 3.14: Stöd för att returnera blandade alternativ och icke-alternativargument i ordning.

exception getopt.GetoptError

Detta anges när ett okänt alternativ hittas i argumentlistan eller när ett alternativ som kräver ett argument inte anges. Argumentet till undantaget är en sträng som anger orsaken till felet. För långa alternativ kommer ett argument som ges till ett alternativ som inte kräver något argument också att leda till att detta undantag aktiveras. Attributen msg och opt ger felmeddelandet och det relaterade alternativet; om det inte finns något specifikt alternativ som undantaget relaterar till, är opt en tom sträng.

exception getopt.error

Alias för GetoptError; för bakåtkompatibilitet.

Ett exempel som endast använder Unix-alternativ:

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

Det är lika enkelt att använda långa optionsnamn:

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

Valfria argument bör anges explicit:

>>> s = '-Con -C --color=off --color a1 a2'
>>> args = s.split()
>>> args
['-Con', '-C', '--color=off', '--color', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])
>>> optlist
[('-C', 'on'), ('-C', ''), ('--color', 'off'), ('--color', '')]
>>> args
['a1', 'a2']

Ordningen på alternativ och icke-alternativargument kan bevaras:

>>> s = 'a1 -x a2 a3 a4 --long a5 a6'
>>> args = s.split()
>>> args
['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']
>>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])
>>> optlist
[(None, ['a1']), ('-x', 'a2'), (None, ['a3', 'a4']), ('--long', 'a5')]
>>> args
['a6']

I ett skript är den typiska användningen ungefär så här:

import getopt, sys

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    except getopt.getoptError as err:
        # skriv ut hjälpinformation och avsluta:
        print(err) # kommer att skriva ut något i stil med "option -a not recognized"
        användning()
        sys.exit(2)
    output = Ingen
    verbose = Falsk
    för o, a i opts:
        om o == "-v":
            verbose = Sann
        elif o i ("-h", "--help"):
            användning()
            sys.exit()
        elif o in ("-o", "--output"):
            utdata = a
        else:
            assert False, "obehandlat alternativ"
    process(args, output=output, verbose=verbose)

if __name__ == "__main__":
    main()

Observera att ett motsvarande kommandoradsgränssnitt kan produceras med mindre kod och mer informativa hjälp- och felmeddelanden genom att använda modulen optparse:

import optparse

if __name__ == '__main__':
    parser = optparse.OptionParser()
    parser.add_option('-o', '--output')
    parser.add_option('-v', dest='verbose', action='store_true')
    opts, args = parser.parse_args()
    process(args, output=opts.output, verbose=opts.verbose)

Ett ungefär motsvarande kommandoradsgränssnitt för detta fall kan också produceras genom att använda modulen argparse:

import argparse

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-o', '--output')
    parser.add_argument('-v', dest='verbose', action='store_true')
    parser.add_argument('rest', nargs='*')
    args = parser.parse_args()
    process(args.rest, output=args.output, verbose=args.verbose)

Se Att välja ett bibliotek för argumentparsning för detaljer om hur argparse-versionen av denna kod skiljer sig i beteende från optparse (och getopt)-versionen.

Se även

Modulen optparse

Deklarativ parsning av kommandoradsalternativ.

Modul argparse

Ett bibliotek som tolkar alternativ och argument på kommandoraden.