Python Argparse Avanzato: Padroneggiare i Sottocomandi e le Classi di Azione Personalizzate

Il modulo argparse di Python è uno strumento potente per la creazione di interfacce a riga di comando (CLI). Mentre l'utilizzo di base è relativamente semplice, argparse offre funzionalità avanzate che consentono la creazione di CLI sofisticate e user-friendly. Questo post del blog approfondisce due di queste funzionalità avanzate: i sottocomandi e le classi di azione personalizzate.

Perché Argparse Avanzato?

Per script semplici con solo poche opzioni, la funzionalità di base di argparse potrebbe essere sufficiente. Tuttavia, man mano che i tuoi script crescono in complessità e funzionalità, una CLI più strutturata e organizzata diventa essenziale. Le funzionalità avanzate di argparse aiutano a:

• Migliorare l'Esperienza Utente: Fornire un'interfaccia chiara e intuitiva per gli utenti.
• Migliorare la Manutenibilità del Codice: Organizzare il codice in moduli logici, rendendolo più facile da comprendere e mantenere.
• Aumentare la Funzionalità: Supportare flussi di lavoro complessi e operazioni multiple all'interno di un singolo script.
• Promuovere la Riutilizzabilità: Creare componenti riutilizzabili che possono essere applicati a diverse parti della tua applicazione.

Sottocomandi: Organizzare CLI Complesse

I sottocomandi sono un modo per raggruppare comandi correlati sotto un unico comando principale. Questo è particolarmente utile per applicazioni che eseguono una varietà di compiti distinti. Si pensi a Git, per esempio. Utilizza ampiamente i sottocomandi: git commit, git push, git pull, e così via. Ogni sottocomando ha il proprio set di argomenti e opzioni.

Implementazione dei Sottocomandi con argparse

Per implementare i sottocomandi con argparse, si usa il metodo add_subparsers(). Ecco un esempio di base:

            
import argparse

# Create the main parser
parser = argparse.ArgumentParser(description='A simple example with subcommands')

# Create the subparser
subparsers = parser.add_subparsers(dest='command', help='Available commands')

# Create the 'add' subcommand
add_parser = subparsers.add_parser('add', help='Add two numbers')
add_parser.add_argument('x', type=int, help='First number')
add_parser.add_argument('y', type=int, help='Second number')

# Create the 'subtract' subcommand
subtract_parser = subparsers.add_parser('subtract', help='Subtract two numbers')
subtract_parser.add_argument('x', type=int, help='First number')
subtract_parser.add_argument('y', type=int, help='Second number')

# Parse the arguments
args = parser.parse_args()

# Perform the action based on the subcommand
if args.command == 'add':
    result = args.x + args.y
    print(f'The sum is: {result}')
elif args.command == 'subtract':
    result = args.x - args.y
    print(f'The difference is: {result}')
else:
    parser.print_help()

            

              
                Copy
              
            
          

In questo esempio:

• Creiamo un parser principale usando argparse.ArgumentParser().
• Aggiungiamo un sottocomando usando parser.add_subparsers(dest='command', help='Available commands'). L'argomento dest specifica l'attributo che memorizzerà il nome del sottocomando scelto.
• Creiamo due sottocomandi, 'add' e 'subtract', usando subparsers.add_parser().
• Ogni sottocomando ha il proprio set di argomenti (x e y).
• Analizziamo gli argomenti usando parser.parse_args().
• Controlliamo il valore di args.command per determinare quale sottocomando è stato scelto e quindi eseguiamo l'azione corrispondente.

Per eseguire questo script, si userebbero comandi come:

python your_script.py add 5 3
python your_script.py subtract 10 2

Tecniche Avanzate per i Sottocomandi

1. Utilizzo di Funzioni per Gestire i Sottocomandi

Un approccio più organizzato consiste nel definire funzioni separate per gestire ogni sottocomando. Questo migliora la leggibilità e la manutenibilità del codice.

            
import argparse

def add(args):
    result = args.x + args.y
    print(f'The sum is: {result}')

def subtract(args):
    result = args.x - args.y
    print(f'The difference is: {result}')

# Create the main parser
parser = argparse.ArgumentParser(description='A simple example with subcommands')

# Create the subparser
subparsers = parser.add_subparsers(dest='command', help='Available commands')

# Create the 'add' subcommand
add_parser = subparsers.add_parser('add', help='Add two numbers')
add_parser.add_argument('x', type=int, help='First number')
add_parser.add_argument('y', type=int, help='Second number')
add_parser.set_defaults(func=add)

# Create the 'subtract' subcommand
subtract_parser = subparsers.add_parser('subtract', help='Subtract two numbers')
subtract_parser.add_argument('x', type=int, help='First number')
subtract_parser.add_argument('y', type=int, help='Second number')
subtract_parser.set_defaults(func=subtract)

# Parse the arguments
args = parser.parse_args()

# Call the function associated with the subcommand
if hasattr(args, 'func'):
    args.func(args)
else:
    parser.print_help()

            

              
                Copy
              
            
          

Qui, usiamo set_defaults(func=...) per associare una funzione a ogni sottocomando. Quindi, dopo il parsing, chiamiamo la funzione appropriata se esiste.

2. Sottocomandi Annidati

È possibile annidare i sottocomandi per creare CLI ancora più complesse e gerarchiche. Ad esempio, si consideri una CLI per la gestione delle risorse cloud:

cloud compute instance create --name my-instance --region us-east-1
cloud storage bucket list --project my-project

In questo esempio, cloud è il comando principale, compute e storage sono sottocomandi, e instance e bucket sono sottocomandi annidati.

3. Esempio Reale: Strumento di Internazionalizzazione

Immaginate uno strumento per la gestione delle traduzioni in un'applicazione multilingue. Potreste usare i sottocomandi per organizzare le diverse operazioni:

translation tool add-language --code fr_FR --name "French (France)"
translation tool extract-strings --source-dir src
translation tool translate --target-language es_ES --source-file strings.pot

Questo approccio consente una chiara separazione delle responsabilità e rende lo strumento più facile da usare e mantenere, soprattutto quando si ha a che fare con numerose lingue e flussi di lavoro di traduzione applicabili in diversi paesi.

Classi di Azione Personalizzate: Adattare il Parsing degli Argomenti

argparse consente di definire classi di azione personalizzate per personalizzare il modo in cui gli argomenti vengono elaborati. Questo è utile per scenari in cui il comportamento predefinito di elaborazione degli argomenti non è sufficiente. Una classe di azione è una classe che eredita da argparse.Action e sovrascrive il metodo __call__.

Creazione di una Classe di Azione Personalizzata

Ecco un esempio di una classe di azione personalizzata che converte un argomento in maiuscolo:

            
import argparse

class ToUpper(argparse.Action):
    def __call__(self, parser, namespace, values, option_string=None):
        if isinstance(values, list):
            setattr(namespace, self.dest, [v.upper() for v in values])
        else:
            setattr(namespace, self.dest, values.upper())

# Create the parser
parser = argparse.ArgumentParser(description='Example with custom action')

# Add an argument with the custom action
parser.add_argument('--name', action=ToUpper, help='Name to convert to uppercase')
parser.add_argument('--cities', action=ToUpper, nargs='+', help='List of cities to convert to uppercase')

# Parse the arguments
args = parser.parse_args()

# Print the result
if args.name:
    print(f'Name: {args.name}')
if args.cities:
    print(f'Cities: {args.cities}')

            

              
                Copy
              
            
          

In questo esempio:

• Definiamo una classe ToUpper che eredita da argparse.Action.
• Il metodo __call__ viene richiamato quando l'argomento viene incontrato. Accetta i seguenti argomenti:
  • parser: L'oggetto ArgumentParser.
  • namespace: L'oggetto namespace dove sono memorizzati gli argomenti analizzati.
  • values: Il/i valore/i dell'argomento.
  • option_string: La stringa di opzione utilizzata per invocare questa azione (ad es. --name).
• All'interno del metodo __call__, convertiamo il valore in maiuscolo usando values.upper() e lo memorizziamo nel namespace usando setattr(namespace, self.dest, values.upper()).
• Aggiungiamo un argomento al parser usando parser.add_argument('--name', action=ToUpper, help='Name to convert to uppercase'). Specifichiamo l'argomento action come la nostra classe di azione personalizzata.

Per eseguire questo script, si userebbero comandi come:

python your_script.py --name john
python your_script.py --cities london paris tokyo

Casi d'Uso per le Classi di Azione Personalizzate

1. Validazione dell'Input

È possibile utilizzare classi di azione personalizzate per validare l'input e generare un errore se l'input non è valido. Ad esempio, si potrebbe creare una classe di azione che verifica se un file esiste o se un numero rientra in un intervallo specifico.

            
import argparse
import os

class FileMustExist(argparse.Action):
    def __call__(self, parser, namespace, values, option_string=None):
        if not os.path.exists(values):
            raise argparse.ArgumentTypeError(f'File not found: {values}')
        setattr(namespace, self.dest, values)

parser = argparse.ArgumentParser(description='Example validating file existence.')
parser.add_argument('--input-file', action=FileMustExist, help='Path to input file.')

args = parser.parse_args()

print(f'Input file: {args.input_file}')

            

              
                Copy
              
            
          

2. Conversione di Unità

È possibile utilizzare classi di azione personalizzate per convertire le unità. Ad esempio, si potrebbe creare una classe di azione che converte le temperature da Celsius a Fahrenheit.

3. Gestione di Strutture Dati Complesse

Se è necessario analizzare gli argomenti in strutture dati complesse (ad esempio, dizionari, liste di oggetti), è possibile utilizzare classi di azione personalizzate per gestire la logica di parsing.

4. Esempio: Gestione dei Fusi Orari

Considera un'applicazione che necessita di gestire date e orari in diversi fusi orari. Una classe di azione personalizzata potrebbe essere utilizzata per analizzare una stringa di data e convertirla in un fuso orario specifico utilizzando librerie come pytz.

            
import argparse
import datetime
import pytz

class TimeZoneConverter(argparse.Action):
    def __init__(self, option_strings, dest, timezone=None, **kwargs):
        super().__init__(option_strings, dest, **kwargs)
        self.timezone = timezone

    def __call__(self, parser, namespace, values, option_string=None):
        try:
            dt = datetime.datetime.fromisoformat(values)
            if self.timezone:
                tz = pytz.timezone(self.timezone)
                dt = tz.localize(dt)
            setattr(namespace, self.dest, dt)
        except ValueError:
            raise argparse.ArgumentTypeError(f\"Invalid date/time format.  Use ISO format (YYYY-MM-DDTHH:MM:SS): {values}\")
        except pytz.exceptions.UnknownTimeZoneError:
            raise argparse.ArgumentTypeError(f\"Invalid Timezone: {self.timezone}\")

parser = argparse.ArgumentParser(description='Example with timezone conversion.')
parser.add_argument('--event-time', action=TimeZoneConverter, timezone='America/Los_Angeles', help='Event time in ISO format (YYYY-MM-DDTHH:MM:SS). Converts to America/Los_Angeles timezone.')

args = parser.parse_args(['--event-time', '2024-10-27T10:00:00'])

print(f'Event Time (Los Angeles): {args.event_time}')

            

              
                Copy
              
            
          

Questo esempio mostra come le azioni personalizzate possano gestire le conversioni di fuso orario usando la libreria pytz, dimostrando un utilizzo più sofisticato e rilevante a livello globale.

Migliori Pratiche per l'Uso Avanzato di Argparse

• Mantieni la Semplicità: Non complicare eccessivamente la tua CLI. Usa sottocomandi e azioni personalizzate solo quando necessario.
• Fornisci Messaggi di Aiuto Chiari: Scrivi messaggi di aiuto chiari e concisi per ogni comando e argomento. Utilizza ampiamente l'argomento help in add_argument().
• Valida l'Input: Valida sempre l'input dell'utente per prevenire errori e vulnerabilità di sicurezza.
• Usa Convenzioni di Nomenclatura Consistenti: Segui convenzioni di nomenclatura consistenti per comandi, argomenti e opzioni. Considera l'uso di kebab-case (--my-option) per i nomi delle opzioni lunghe.
• Testa Approfonditamente: Testa la tua CLI a fondo con diversi input e scenari.
• Documenta la Tua CLI: Fornisci una documentazione completa per la tua CLI, inclusi esempi su come usare ogni comando e argomento. Strumenti come Sphinx possono generare documentazione dal tuo codice.
• Considera la Localizzazione: Se la tua CLI è destinata a un pubblico globale, considera la localizzazione dei messaggi di aiuto e di altro testo rivolto all'utente.

Conclusione

I sottocomandi e le classi di azione personalizzate sono strumenti potenti per creare CLI sofisticate e user-friendly con argparse. Padroneggiando queste funzionalità avanzate, è possibile costruire applicazioni a riga di comando robuste, manutenibili e scalabili che soddisfano le esigenze di una base di utenti diversificata. Dalla gestione di applicazioni multilingue alla gestione dei fusi orari in tutto il mondo, le possibilità sono vaste. Adotta queste tecniche per elevare il tuo scripting Python e lo sviluppo di strumenti a riga di comando al livello successivo.