Argomenti CLI con argparse senza dolore: flag, default e help

Come aggiungere flag, default e --help ai tuoi script Python con argparse — esempi chiari su Windows, macOS e Linux, senza dolore.

Se hai mai scaricato uno script Python e lo hai lanciato dal terminale, è probabile che tu abbia usato dei parametri per modificarne il comportamento: --length 16 per una password più lunga, oppure --verbose per vedere cosa stava facendo il programma.

Per chi usa il terminale, queste flag sono normali. Quando inizi a scrivere i tuoi script, però, compare subito la domanda: come faccio a far leggere al codice quelle parole extra dopo il nome del file?

In questo articolo ti mostro come gestire gli argomenti da riga di comando (CLI) in Python con la libreria standard argparse. Niente moduli esterni e niente configurazioni barocche: i pezzi minimi per un --help pulito, i default e le flag booleane.

Perché usare argparse (e non leggere i valori a mano)

Quando lanci uno script, Python mette ciò che hai digitato in una lista speciale: sys.argv. Potresti pensare di leggere gli argomenti direttamente da lì.

Nella mia esperienza, analizzare sys.argv a mano va bene solo per script minuscoli con un parametro fisso. Appena serve un parametro opzionale, un default, oppure lasciare all’utente libertà sull’ordine delle flag (--lunghezza 10 --simboli oppure il contrario), la gestione manuale diventa una catena di if e try/except fragili.

argparse è incluso in Python (niente pip). Fa per te il lavoro ripetitivo:

• associa i valori alle variabili, indipendentemente dall’ordine;
• controlla i tipi (es. un intero al posto di una parola);
• genera il menu di aiuto con -h / --help.

💡 Consiglio pratico — Standard della libreria
argparse è lo strumento standard. Esistono librerie esterne valide (Click, Typer), ma conoscere le basi di argparse ti aiuta a leggere e modificare molti script che trovi online o che un’IA ti propone — senza installare niente.

L’anatomia minima di un parser

Tre pezzi bastano per partire.

Laboratorio: il primo script con argparse

Crea una cartella e, al suo interno, un file saluta_cli.py.

import argparse


def main():
    # 1. Crea il parser
    parser = argparse.ArgumentParser(
        description="Uno script ai riparo per imparare a usare argparse."
    )

    # 2. Primo argomento opzionale
    parser.add_argument(
        "--nome",
        help="Il nome della persona da salutare",
    )

    # 3. Leggi gli argomenti dal terminale
    args = parser.parse_args()

    # 4. Usa i dati
    if args.nome:
        print(f"Ciao, {args.nome}!")
    else:
        print("Ciao, utente misterioso!")


if __name__ == "__main__":
    main()

Questa è l’ossatura tipica: logica in main(), ingresso protetto da if __name__ == "__main__":. Se la guardia non ti è chiara, la lettura opzionale è Capire if name == “main” con esempi.

Lancio su Windows / macOS / Linux

Nella cartella dello script:

Windows (Prompt / PowerShell):

python saluta_cli.py

macOS / Linux:

python3 saluta_cli.py

Output atteso: Ciao, utente misterioso!.

Con la flag:

Windows:

python saluta_cli.py --nome Alex

macOS / Linux:

python3 saluta_cli.py --nome Alex

Output: Ciao, Alex!.

Help automatico:

Windows:

python saluta_cli.py --help

macOS / Linux:

python3 saluta_cli.py --help

Esempio di output (generato da Python):

usage: saluta_cli.py [-h] [--nome NOME]

Uno script ai riparo per imparare a usare argparse.

options:
  -h, --help   show this help message and exit
  --nome NOME  Il nome della persona da salutare

Senza un solo print() dedicato all’help, hai già un’interfaccia CLI utilizzabile.

Flag, default e tipi: uno per uno

Quattro parametri di add_argument() coprono la maggior parte dei casi pratici. Li aggiungiamo a saluta_cli.py.

1. default

Se l’utente non passa una flag, senza default il valore è spesso None. Con un default esplicito lo script ha un comportamento prevedibile:

parser.add_argument(
    "--stile",
    default="formale",
    help="Lo stile del saluto (default: formale)",
)

• python saluta_cli.py → args.stile == "formale"
• python saluta_cli.py --stile amichevole → args.stile == "amichevole"

ℹ️ Nota / Prerequisito operativo
argparse non stampa da solo i default nel testo di --help. Se vuoi che l’utente li veda, scrivili nel help= (come sopra).

2. Posizionali vs flag opzionali

Le flag con -- sono opzionali: se mancano, lo script non va in crash (salvo controlli tuoi).

Se un valore deve essere obbligatorio (es. il file da analizzare), usa un argomento posizionale (senza trattini):

parser.add_argument(
    "file_input",
    help="Il file che deve essere letto",
)

Lanciare solo python saluta_cli.py produce un errore del tipo: error: the following arguments are required: file_input.

3. action="store_true" (interruttori)

A volte non serve un valore (--nome Alex), ma solo accendere un interruttore (--verbose, --maiuscolo):

parser.add_argument(
    "--maiuscolo",
    action="store_true",
    help="Stampa il saluto tutto in maiuscolo",
)

• senza flag → args.maiuscolo è False
• con --maiuscolo → diventa True
  Non scrivere --maiuscolo True: basta la presenza della flag.

4. type=int (e altri tipi)

Dal terminale arriva testo. Se ti serve un numero, dichiara il tipo così un errore dell’utente viene bloccato subito:

parser.add_argument(
    "--ripeti",
    type=int,
    default=1,
    help="Quante volte ripetere il saluto",
)

python saluta_cli.py --ripeti ciao → errore: invalid int value: 'ciao'.

Collegamento con gli script di ai riparo

Se hai già usato il generatore di password da terminale, questo schema ti è familiare: --length con type=int e un default, più interruttori tipo --no-symbols con action="store_true".

Lo standard utile è sempre lo stesso: leggi gli argomenti all’inizio, poi passa variabili pulite alla logica. Puoi riusare il blocco argparse e cambiare solo nomi e messaggi di help — allineato anche alla struttura minima di un progetto Python.

Errori tipici (e come evitarli)

1. Typo nella flag (unrecognized arguments)

Se lo script aspetta --length e digiti --lengh 12, Python si ferma con unrecognized arguments. È un blocco sicuro: meglio un errore chiaro che un’esecuzione a metà.

2. Valore scambiato con la flag successiva

Se una flag richiede un valore e scrivi --nome --maiuscolo, il parser può assegnare la stringa "--maiuscolo" a args.nome. Il valore deve seguire subito la sua flag.

3. Dimenticare parse_args()

Definisci il parser, aggiungi gli argomenti… e poi usi args.nome senza aver chiamato args = parser.parse_args(). Risultato tipico: NameError. Metti sempre parse_args() dopo l’ultimo add_argument().

🚨 Avviso critico — Percorsi di file
Se un argomento è un path (--input file.txt), argparse lo tratta come stringa. Non verifica esistenza né permessi. Controlli come Path(...).exists() vanno nella logica successiva dello script.

Domande Frequenti (FAQ)

Cos’è argparse in Python?

È un modulo della libreria standard. Serve a interpretare ciò che digiti dopo il nome dello script: variabili tipizzate, messaggi di errore chiari e menu --help automatico.

Qual è la differenza tra un argomento posizionale e una flag (--nome)?

Il posizionale è obbligatorio e dipende dall’ordine (es. python copia.py origine.txt dest.txt). La flag è opzionale, inizia con -/-- e può comparire in ordine libero (es. --verbose).

A cosa serve default in add_argument?

Assegna un valore automatico se l’utente non passa quella flag. Così lo script ha un comportamento prevedibile anche «a mani vuote».

Come ottengo il messaggio di help (-h / --help)?

Non lo programmi a mano. argparse lo genera dalle description / help che hai scritto. Lancia python tuo_script.py -h (su macOS/Linux: python3 … -h).

Cos’è action="store_true"?

Trasforma la flag in un interruttore booleano: presente → True, assente → False. Ideale per --verbose, --force, --maiuscolo.

Devo usare argparse anche negli script leggeri senza dipendenze?

Sì, se hai più di un parametro banale. Essendo nella libreria standard non richiede pip e rende lo script più chiaro su Windows, macOS e Linux.

Qual è la differenza tra argparse e sys.argv?

sys.argv è la lista grezza delle parole digitati. argparse legge quella lista, organizza flag e tipi, e segnala gli errori all’utente invece di lasciarti fare parsing a mano.

Letture opzionali

• Capire if name == “main” con esempi
• Generatore di password sicure da terminale
• Terminale: comandi minimi per usare gli script di ai riparo
• Struttura minima di un progetto Python «ai riparo»