argparse - Parser della linea di comando

Nota

I contenuti che seguono prendono forte ispirazione dalla documentazione ufficiale relativa della versione 3.11 di Python

Link alla documentazione ufficiale: https://docs.python.org/3.11/library/argparse.html

Introduzione alla libreria

La libreria argparse in Python è utilizzata per analizzare gli argomenti della riga di comando passati a uno script Python. Essa semplifica la gestione degli argomenti forniti dall’utente, consentendo agli script di essere eseguiti con opzioni specifiche o argomenti obbligatori. L’utilizzo di argparse rende più facile per gli utenti interagire con lo script senza dover modificare il codice sorgente.

Ecco alcune delle principali funzionalità e scopi di argparse:

1. Definizione degli argomenti: argparse permette di definire quali argomenti e opzioni il tuo script può accettare. Puoi specificare argomenti obbligatori, opzionali, flag booleani e altro ancora.

2. Parsificazione degli argomenti: argparse analizza gli argomenti passati dalla riga di comando e li rende disponibili nel tuo programma come oggetti Python. Puoi accedere a questi argomenti e utilizzarli nel tuo codice.

3. Gestione degli errori e messaggi di aiuto: argparse fornisce un modo semplice per gestire errori, visualizzare messaggi di aiuto e documentazione sull’uso del tuo script. Gli utenti possono richiedere informazioni sull’uso degli argomenti attraverso l’opzione --help.

4. Validazione degli argomenti: argparse ti consente di definire regole di validazione per gli argomenti, come limiti di valore o scelte consentite.

5. Generazione automatica della documentazione: Può generare automaticamente la documentazione basata sugli argomenti specificati, facilitando la creazione di una guida utente per il tuo script.

Concetti base

Di seguito vengono spiegate con piccoli esempi applicativi le funzionalità che la libreria mette a disposizione del programmatore.

Partiamo con l’esempio più semplice di utilizzo di argparse. In questo non richiediamo alcuna funzione specifica, ma come vedremo, la libreria implementa automaticamente alcune funzionalità basilari.

prog.py

import argparse
parser = argparse.ArgumentParser()
parser.parse_args()

Tre righe di codice: la prima per importare la libreria, con la seconda si instanzia un oggetto di classe ArgumentParser, che mette a disposizione il metodo parse_args() richiamato nella terza riga.

Quindi alla fine questa semplice chiamata cosa fa?

Eseguimo il programma usando alcune combinazioni di parametri:

assenza di argomenti

$ python prog.py

Il programma esegue il parsing della linea di comando che non restituisce nulla.

Ora proviamo a passare un argomento nella linea di comando:

passando un argomento sconosciuto (foo)

$ python prog.py foo
usage: prog.py [-h]
prog.py: error: unrecognized arguments: foo

Ecco che entra in gioco il metodo parse_args() e non essendo istruito a riconoscere alcun argomento ci presenta un messaggio di errore e termina il programma.

Notare che il messaggio si compone di due parti:

• una spiegazione di utilizzo del programma con la presenza di una opzione -h

• il messaggio di errore specifico per il non riconoscimento dell’argomento passato

Ecco quindi un primo automatismo messo a disposizione da argparse.

Ma abbiamo appena iniziato. Ora proviamo l’opzione -h

passando l’opzione -h

$ python prog.py -h
usage: prog.py [-h]

options:
  -h, --help  show this help message and exit

In automatico argparse implementa la visualizzazione dell’help della linea di comando. Di seguito andremo a vedere come aggiungere informazioni, ma ora facciamo un ultimo esperimento e proviamo a utilizzare una opzione sconosciuta

passando un’opzione sconosciuta (–baz)

$ python prog.py --baz
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --baz

A questo punto c’era da aspettarselo, un bel messaggio di errore.

Con questi esempi abbiamo visto il comportamento della libreria in assenza di una configurazione specifica. Ma noi vogliato sfruttare la libreria per implementare la gestione di specifici argomenti della linea di comando.

Argomenti posizionali

Siamo studiando argparse quindi è molto probabile che abbiamo la necessità di gestire uno o più argomenti nella linea di comando.

Supponiamo di voler sviluppare un’applicazione che calcola il quadrato del numero passato come argomento.

Partendo dall’esempio precedente, creiamo un nuovo programma square.py in cui aggiungiamo la gestione del nuovo argomento:

square.py

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("number")
args = parser.parse_args()
# di seguito le funzioni dell'applicazione
print(int(args.number)**2)

Come evidenziato nel codice abbiamo aggiunto:

• chiamata la metodo add_argument() con cui aggiungiamo la gestione del nuovo argomento number

• il risultato del metodo parse_args() viene memorizzato localmente con nome args

• il codice specifico della nostra applicazione, che in questo caso si stampa il quadrato del valore passato come argomento number. Nota che l’argomento è una stringa e quindi è convertito in in intero prima di eseguire l’operazione.

Abbiamo istruito argparse che la nostra applicazione si aspetta di ricevere l’argomento number sulla linea di comando.

Proviamo come prima a lanciare la nostra app in tre condizioni: senza argomenti, con l’argomento corretto, con l’opzione -h per visualizzare l’help.

test con varie condizioni

$ python square.py
usage: square.py [-h] number
prog.py: error: the following arguments are required: number
$ python square.py 25
625
$ python square.py -h
usage: square.py [-h] number

positional arguments:
number

options:
  -h, --help  show this help message and exit

Nel primo caso il codice si interrompe con chiamata al metodo parse_args(), il codice che segue non è eseguito.

Passando correttamente l’argomento (nel nostro esempio 32), il codice prosegue e i valori passati come argomenti sono restituiti dal metodo parse_args(). Il programma stampa il risultato corretto.

Chiamando il programma con l’opzione -h notiamo come il messaggio di help relativo al parametro number non fornisce non presenta nessuna informazione particolare.

Ovviamente possiamo fornire tali informazioni. Il metodo add_argument permette di aggiungere sia un messaggio di help che indicare la tipologia di parametro. Nel nostro caso indichiamo di necessitare un numero intero.

square.py

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("number", help="number to be squared",
                    type=int)
args = parser.parse_args()
# di seguito le funzioni dell'applicazione
print(args.number**2)