6.19 `getopt` -- Parser per le opzioni da riga di comando

Questo modulo consente agli script ad analizzare gli argomenti da riga di comando in sys.argv. Supporta le stesse convenzioni della funzione Unix getopt() (inclusi i significati speciali degli argomenti nella forma `-' e `--'). Le opzioni lunghe, analogamente a quelle supportate dai software GNU, possono venire usate anche tramite un terzo argomento facoltativo. Questo modulo fornisce una singola funzione ed una eccezione:

getopt( args, options[, long_options])

Analizza le opzioni da riga di comando e la lista dei parametri. args è l'argomento della lista da analizzare, senza il riferimento iniziale al programma in esecuzione. Tipicamente, questo significa "sys.argv[1:]". options è la stringa delle lettere-opzioni che lo script deve riconoscere, con le opzioni che richiedono un argomento, seguite da un segno di due punti (":"; per esempio, lo stesso formato che usa getopt() in Unix).

Note: Diversamente dal getopt() GNU, dopo un argomento non-opzione, anche i successivi argomenti vengono considerati come non-opzioni. Questo comportamento è simile al modo in cui operano i sistemi Unix non-GNU.

long_options, se specificato, deve essere una lista di stringhe con i nomi delle opzioni lunghe che dovrebbero venire supportate. I caratteri '--' iniziali non dovrebbero venire inclusi nel nome dell'opzione. Le opzioni lunghe che richiedono un argomento dovrebbero essere seguite dal segno di uguale ("="). Per accettare solo opzioni lunghe, options dovrebbe essere una stringa vuota. Le opzioni lunghe da riga di comando possono venire riconosciute come tali, purché contengano un prefisso del nome dell'opzione che corrisponda esattamente con una delle opzioni accettate. Per esempio, se long_options è ['foo', 'frob'], l'opzione --fo corrisponderà con --foo, ma --f non verrà considerata una corrispondenza univoca, così da sollevare un'eccezione GetoptError.

Il valore restituito consiste di due elementi: il primo è una lista di coppie (option, value); il secondo è la lista degli argomenti del programma rimasti a sinistra, dopo che la lista delle opzioni è stata tolta (questa è la suddivisione in fette di args (NdT: per mezzo di split())). Ogni coppia opzione-valore restituita ha l'opzione come primo elemento, avente come prefisso un trattino per le opzioni brevi (per es. '-x') o due trattini per le opzioni lunghe (per es. '--long-option'), e l'argomento dell'opzione come suo secondo argomento, o una stringa vuota se l'opzione non ha argomenti. Le opzioni compaiono nella lista nello stesso ordine nel quale sono state individuate, permettendo così occorrenze nultiple. Le opzioni lunghe e brevi si possono mescolare.

gnu_getopt( args, options[, long_options]): Questa funzione opera come getopt(), con la differenza che lo stile GNU di modalità di scansione viene usato in modo predefinito. Questo significa che gli argomenti di opzione e di non-opzione possono venire mescolati tra loro. La funzione getopt() ferma l'elaborazione delle opzioni non appena viene incontrato un argomento di non-opzione.
Se il primo carattere dell'opzione stringa è `+', o se la variabile d'ambiente POSIXLY_CORRECT è impostata, allora l'elaborazione delle opzioni si ferma non appena viene incontrato un argomento di non-opzione.

exception GetoptError: Viene sollevata quando viene trovata un'opzione sconosciuta nella lista degli argomenti, oppure quando non viene fornito nessun argomento ad una opzione che ne richieda. L'argomento dell'eccezione è una stringa indicante la causa dell'errore. Per le opzioni lunghe, un argomento fornito ad un'opzione che non ne richieda, provocherà il sollevamento dell'eccezione. Gli attributi msg e opt danno il messaggio d'errore e le opzioni connesse; se non esiste l'opzione specifica alla quale l'eccezione si riferisce, allora opt è una stringa vuota.
Modificato nella versione 1.6: Introdotto GetoptError come sinonimo di error.

exception error: Sinonimo per GetoptError; per retrocompatibilità.

Un esempio usando solamente lo stile delle opzioni 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'uso dei nomi lunghi delle opzioni è altrettanto facile:

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

In uno script, l'uso tipico è qualcosa di simile a questo:

import getopt, sys

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    except getopt.GetoptError:
        # stampa l'informazione di aiuto ed esce:
        usage()
        sys.exit(2)
    output = None
    verbose = False
    for o, a in opts:
        if o == "-v":
            verbose = True
        if o in ("-h", "--help"):
            usage()
            sys.exit()
        if o in ("-o", "--output"):
            output = a
    # ...

if __name__ == "__main__":
    main()

Vedete anche:

Modulo optparse:: Una riga di comando per l'analisi delle opzioni maggiormente orientata agli oggetti.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.

6.19 getopt -- Parser per le opzioni da riga di comando

6.19 `getopt` -- Parser per le opzioni da riga di comando