Python Argparse Avanceret: Mestring af Subkommandoer og Brugerdefinerede Handlingsklasser

Pythons argparse modul er et kraftfuldt værktøj til at skabe kommandolinjegrænseflader (CLI'er). Selvom grundlæggende brug er relativt ligetil, tilbyder argparse avancerede funktioner, der giver mulighed for at skabe sofistikerede og brugervenlige CLI'er. Dette blogindlæg dykker ned i to sådanne avancerede funktioner: subkommandoer og brugerdefinerede handlingsklasser.

Hvorfor Avanceret Argparse?

For simple scripts med kun få muligheder kan grundlæggende argparse funktionalitet være tilstrækkelig. Men efterhånden som dine scripts vokser i kompleksitet og funktionalitet, bliver en mere struktureret og organiseret CLI essentiel. Avancerede argparse funktioner hjælper med at:

• Forbedre Brugeroplevelsen: Give en klar og intuitiv grænseflade for brugerne.
• Forbedre Kodevedligeholdelse: Organiser din kode i logiske moduler, hvilket gør det lettere at forstå og vedligeholde.
• Øge Funktionaliteten: Understøtte komplekse arbejdsgange og flere operationer inden for et enkelt script.
• Fremme Genanvendelighed: Opret genanvendelige komponenter, der kan anvendes på forskellige dele af din applikation.

Subkommandoer: Organisering af Komplekse CLI'er

Subkommandoer er en måde at gruppere relaterede kommandoer under en enkelt hovedkommando. Dette er især nyttigt for applikationer, der udfører en række forskellige opgaver. Tænk på Git, for eksempel. Det bruger subkommandoer i udstrakt grad: git commit, git push, git pull og så videre. Hver subkommando har sit eget sæt af argumenter og muligheder.

Implementering af Subkommandoer med argparse

For at implementere subkommandoer med argparse, skal du bruge metoden add_subparsers(). Her er et grundlæggende eksempel:

            
import argparse

# Opret hovedparseren
parser = argparse.ArgumentParser(description='Et simpelt eksempel med subkommandoer')

# Opret subparseren
subparsers = parser.add_subparsers(dest='command', help='Tilgængelige kommandoer')

# Opret 'add' subkommandoen
add_parser = subparsers.add_parser('add', help='Tilføj to tal')
add_parser.add_argument('x', type=int, help='Første tal')
add_parser.add_argument('y', type=int, help='Andet tal')

# Opret 'subtract' subkommandoen
subtract_parser = subparsers.add_parser('subtract', help='Træk to tal fra hinanden')
subtract_parser.add_argument('x', type=int, help='Første tal')
subtract_parser.add_argument('y', type=int, help='Andet tal')

# Parse argumenterne
args = parser.parse_args()

# Udfør handlingen baseret på subkommandoen
if args.command == 'add':
    result = args.x + args.y
    print(f'Summen er: {result}')
elif args.command == 'subtract':
    result = args.x - args.y
    print(f'Forskellen er: {result}')
else:
    parser.print_help()

            

              
                Copy
              
            
          

I dette eksempel:

• Vi opretter en hovedparser ved hjælp af argparse.ArgumentParser().
• Vi tilføjer en subparser ved hjælp af parser.add_subparsers(dest='command', help='Tilgængelige kommandoer'). Argumentet dest specificerer det attribut, der gemmer navnet på den valgte subkommando.
• Vi opretter to subkommandoer, 'add' og 'subtract', ved hjælp af subparsers.add_parser().
• Hver subkommando har sit eget sæt af argumenter (x og y).
• Vi parser argumenterne ved hjælp af parser.parse_args().
• Vi kontrollerer værdien af args.command for at bestemme, hvilken subkommando der blev valgt, og udfører derefter den tilsvarende handling.

For at køre dette script, ville du bruge kommandoer som:

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

Avancerede Subkommandoteknikker

1. Brug af Funktioner til at Håndtere Subkommandoer

En mere organiseret tilgang er at definere separate funktioner til at håndtere hver subkommando. Dette forbedrer kodens læsbarhed og vedligeholdelse.

            
import argparse

def add(args):
    result = args.x + args.y
    print(f'Summen er: {result}')

def subtract(args):
    result = args.x - args.y
    print(f'Forskellen er: {result}')

# Opret hovedparseren
parser = argparse.ArgumentParser(description='Et simpelt eksempel med subkommandoer')

# Opret subparseren
subparsers = parser.add_subparsers(dest='command', help='Tilgængelige kommandoer')

# Opret 'add' subkommandoen
add_parser = subparsers.add_parser('add', help='Tilføj to tal')
add_parser.add_argument('x', type=int, help='Første tal')
add_parser.add_argument('y', type=int, help='Andet tal')
add_parser.set_defaults(func=add)

# Opret 'subtract' subkommandoen
subtract_parser = subparsers.add_parser('subtract', help='Træk to tal fra hinanden')
subtract_parser.add_argument('x', type=int, help='Første tal')
subtract_parser.add_argument('y', type=int, help='Andet tal')
subtract_parser.set_defaults(func=subtract)

# Parse argumenterne
args = parser.parse_args()

# Kald funktionen knyttet til subkommandoen
if hasattr(args, 'func'):
    args.func(args)
else:
    parser.print_help()

            

              
                Copy
              
            
          

Her bruger vi set_defaults(func=...) til at knytte en funktion til hver subkommando. Derefter, efter parsing, kalder vi den relevante funktion, hvis den findes.

2. Indlejring af Subkommandoer

Du kan indlejre subkommandoer for at skabe endnu mere komplekse og hierarkiske CLI'er. Overvej f.eks. en CLI til administration af cloud-ressourcer:

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

I dette eksempel er cloud hovedkommandoen, compute og storage er subkommandoer, og instance og bucket er sub-subkommandoer.

3. Eksempel fra den Virkelige Verden: Internationaliseringsværktøj

Forestil dig et værktøj til administration af oversættelser i en applikation med flere sprog. Du kan bruge subkommandoer til at organisere de forskellige operationer:

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

Denne tilgang giver mulighed for en klar adskillelse af ansvarsområder og gør værktøjet lettere at bruge og vedligeholde, især når man beskæftiger sig med adskillige sprog og oversættelsesarbejdsgange, der er gældende på tværs af forskellige lande.

Brugerdefinerede Handlingsklasser: Skræddersy Argumentparsing

argparse giver dig mulighed for at definere brugerdefinerede handlingsklasser for at tilpasse, hvordan argumenter behandles. Dette er nyttigt i scenarier, hvor standardbehandlingen af argumenter ikke er tilstrækkelig. En handlingsklasse er en klasse, der arver fra argparse.Action og tilsidesætter metoden __call__.

Oprettelse af en Brugerdefineret Handlingsklasse

Her er et eksempel på en brugerdefineret handlingsklasse, der konverterer et argument til store bogstaver:

            
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())

# Opret parseren
parser = argparse.ArgumentParser(description='Eksempel med brugerdefineret handling')

# Tilføj et argument med den brugerdefinerede handling
parser.add_argument('--name', action=ToUpper, help='Navn der skal konverteres til store bogstaver')
parser.add_argument('--cities', action=ToUpper, nargs='+', help='Liste over byer der skal konverteres til store bogstaver')

# Parse argumenterne
args = parser.parse_args()

# Udskriv resultatet
if args.name:
    print(f'Navn: {args.name}')
if args.cities:
    print(f'Byer: {args.cities}')

            

              
                Copy
              
            
          

I dette eksempel:

• Vi definerer en klasse ToUpper, der arver fra argparse.Action.
• Metoden __call__ kaldes, når argumentet stødes på. Den tager følgende argumenter:
  • parser: Objektet ArgumentParser.
  • namespace: Navnerumsobjektet, hvor de parsede argumenter gemmes.
  • values: Værdien/værdierne af argumentet.
  • option_string: Den optionstreng, der blev brugt til at påkalde denne handling (f.eks. --name).
• Inde i metoden __call__ konverterer vi værdien til store bogstaver ved hjælp af values.upper() og gemmer den i navnerummet ved hjælp af setattr(namespace, self.dest, values.upper()).
• Vi tilføjer et argument til parseren ved hjælp af parser.add_argument('--name', action=ToUpper, help='Navn der skal konverteres til store bogstaver'). Vi angiver argumentet action som vores brugerdefinerede handlingsklasse.

For at køre dette script, ville du bruge kommandoer som:

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

Anvendelsestilfælde for Brugerdefinerede Handlingsklasser

1. Validering af Input

Du kan bruge brugerdefinerede handlingsklasser til at validere input og udløse en fejl, hvis input er ugyldigt. Du kan f.eks. oprette en handlingsklasse, der kontrollerer, om en fil findes, eller om et tal er inden for et bestemt interval.

            
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'Filen blev ikke fundet: {values}')
        setattr(namespace, self.dest, values)

parser = argparse.ArgumentParser(description='Eksempel på validering af fileksistens.')
parser.add_argument('--input-file', action=FileMustExist, help='Sti til inputfil.')

args = parser.parse_args()

print(f'Inputfil: {args.input_file}')

            

              
                Copy
              
            
          

2. Konvertering af Enheder

Du kan bruge brugerdefinerede handlingsklasser til at konvertere enheder. Du kan f.eks. oprette en handlingsklasse, der konverterer temperaturer fra Celsius til Fahrenheit.

3. Håndtering af Komplekse Datastrukturer

Hvis du har brug for at parse argumenter til komplekse datastrukturer (f.eks. ordbøger, lister over objekter), kan du bruge brugerdefinerede handlingsklasser til at håndtere parsinglogikken.

4. Eksempel: Håndtering af Tidszoner

Overvej en applikation, der har brug for at håndtere datoer og klokkeslæt i forskellige tidszoner. En brugerdefineret handlingsklasse kan bruges til at parse en datostreng og konvertere den til en bestemt tidszone ved hjælp af biblioteker som 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"Ugyldigt dato/klokkeslæt format. Brug ISO format (YYYY-MM-DDTHH:MM:SS): {values}")
        except pytz.exceptions.UnknownTimeZoneError:
            raise argparse.ArgumentTypeError(f"Ugyldig tidszone: {self.timezone}")

parser = argparse.ArgumentParser(description='Eksempel med tidszonekonvertering.')
parser.add_argument('--event-time', action=TimeZoneConverter, timezone='America/Los_Angeles', help='Begivenhedstid i ISO-format (YYYY-MM-DDTHH:MM:SS). Konverterer til America/Los_Angeles tidszone.')

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

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

            

              
                Copy
              
            
          

Dette eksempel viser, hvordan brugerdefinerede handlinger kan håndtere tidszonekonverteringer ved hjælp af pytz-biblioteket, hvilket demonstrerer en mere sofistikeret brug, der er globalt relevant.

Bedste Fremgangsmåder til Brug af Avanceret Argparse

• Hold det Simpelt: Overkomplicer ikke din CLI. Brug kun subkommandoer og brugerdefinerede handlinger, når det er nødvendigt.
• Angiv Tydelige Hjælpemeddelelser: Skriv tydelige og præcise hjælpemeddelelser for hver kommando og argument. Brug argumentet help i add_argument() i udstrakt grad.
• Valider Input: Valider altid brugerinput for at forhindre fejl og sikkerhedssårbarheder.
• Brug Konsistente Navngivningskonventioner: Følg konsistente navngivningskonventioner for kommandoer, argumenter og muligheder. Overvej at bruge kebab-case (--my-option) til lange optionsnavne.
• Test Grundigt: Test din CLI grundigt med forskellige input og scenarier.
• Dokumenter Din CLI: Angiv omfattende dokumentation for din CLI, herunder eksempler på, hvordan du bruger hver kommando og argument. Værktøjer som Sphinx kan generere dokumentation fra din kode.
• Overvej Lokalisering: Hvis din CLI er beregnet til et globalt publikum, skal du overveje at lokalisere dine hjælpemeddelelser og anden brugerrettet tekst.

Konklusion

Subkommandoer og brugerdefinerede handlingsklasser er kraftfulde værktøjer til at skabe sofistikerede og brugervenlige CLI'er med argparse. Ved at mestre disse avancerede funktioner kan du bygge robuste, vedligeholdelige og skalerbare kommandolinjeapplikationer, der imødekommer behovene hos en mangfoldig brugerbase. Fra administration af applikationer med flere sprog til håndtering af tidszoner over hele kloden er mulighederne store. Omfavn disse teknikker for at løfte din Python-scripting og kommandolinjeværktøjsudvikling til det næste niveau.