Avansert Python Argparse: Mestring av Underkommandoer og Egendefinerte Handlingsklasser

Pythons argparse-modul er et kraftig verktøy for å lage kommandolinjegrensesnitt (CLI-er). Selv om grunnleggende bruk er relativt enkel, tilbyr argparse avanserte funksjoner som muliggjør opprettelsen av sofistikerte og brukervennlige CLI-er. Dette blogginnlegget dykker ned i to slike avanserte funksjoner: underkommandoer og egendefinerte handlingsklasser.

Hvorfor avansert Argparse?

For enkle skript med bare noen få alternativer, kan grunnleggende argparse-funksjonalitet være tilstrekkelig. Men etter hvert som skriptene dine vokser i kompleksitet og funksjonalitet, blir et mer strukturert og organisert CLI essensielt. Avanserte argparse-funksjoner hjelper til med å:

• Forbedre brukeropplevelsen: Tilby et klart og intuitivt grensesnitt for brukere.
• Øke vedlikeholdbarheten av koden: Organisere koden din i logiske moduler, noe som gjør den lettere å forstå og vedlikeholde.
• Øke funksjonaliteten: Støtte komplekse arbeidsflyter og flere operasjoner innenfor ett enkelt skript.
• Fremme gjenbrukbarhet: Lage gjenbrukbare komponenter som kan brukes i forskjellige deler av applikasjonen din.

Underkommandoer: Organisere komplekse CLI-er

Underkommandoer er en måte å gruppere relaterte kommandoer under én hovedkommando. Dette er spesielt nyttig for applikasjoner som utfører en rekke forskjellige oppgaver. Tenk på Git, for eksempel. Det bruker underkommandoer i stor utstrekning: git commit, git push, git pull, og så videre. Hver underkommando har sitt eget sett med argumenter og alternativer.

Implementere underkommandoer med argparse

For å implementere underkommandoer med argparse, bruker du add_subparsers()-metoden. Her er et grunnleggende eksempel:

            
import argparse

# Opprett hovedparseren
parser = argparse.ArgumentParser(description='Et enkelt eksempel med underkommandoer')

# Opprett underparseren
subparsers = parser.add_subparsers(dest='command', help='Tilgjengelige kommandoer')

# Opprett 'add'-underkommandoen
add_parser = subparsers.add_parser('add', help='Legg sammen to tall')
add_parser.add_argument('x', type=int, help='Første tall')
add_parser.add_argument('y', type=int, help='Andre tall')

# Opprett 'subtract'-underkommandoen
subtract_parser = subparsers.add_parser('subtract', help='Trekk fra to tall')
subtract_parser.add_argument('x', type=int, help='Første tall')
subtract_parser.add_argument('y', type=int, help='Andre tall')

# Pars argumentene
args = parser.parse_args()

# Utfør handlingen basert på underkommandoen
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'Forskjellen er: {result}')
else:
    parser.print_help()

            

              
                Copy
              
            
          

I dette eksempelet:

• Vi oppretter en hovedparser ved hjelp av argparse.ArgumentParser().
• Vi legger til en underparser ved hjelp av parser.add_subparsers(dest='command', help='Tilgjengelige kommandoer'). dest-argumentet spesifiserer attributtet som vil lagre navnet på den valgte underkommandoen.
• Vi oppretter to underkommandoer, 'add' og 'subtract', ved hjelp av subparsers.add_parser().
• Hver underkommando har sitt eget sett med argumenter (x og y).
• Vi parser argumentene ved hjelp av parser.parse_args().
• Vi sjekker verdien av args.command for å avgjøre hvilken underkommando som ble valgt, og utfører deretter den tilsvarende handlingen.

For å kjøre dette skriptet, vil du bruke kommandoer som:

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

Avanserte teknikker for underkommandoer

1. Bruke funksjoner til å håndtere underkommandoer

En mer organisert tilnærming er å definere separate funksjoner for å håndtere hver underkommando. Dette forbedrer kodens lesbarhet og vedlikeholdbarhet.

            
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'Forskjellen er: {result}')

# Opprett hovedparseren
parser = argparse.ArgumentParser(description='Et enkelt eksempel med underkommandoer')

# Opprett underparseren
subparsers = parser.add_subparsers(dest='command', help='Tilgjengelige kommandoer')

# Opprett 'add'-underkommandoen
add_parser = subparsers.add_parser('add', help='Legg sammen to tall')
add_parser.add_argument('x', type=int, help='Første tall')
add_parser.add_argument('y', type=int, help='Andre tall')
add_parser.set_defaults(func=add)

# Opprett 'subtract'-underkommandoen
subtract_parser = subparsers.add_parser('subtract', help='Trekk fra to tall')
subtract_parser.add_argument('x', type=int, help='Første tall')
subtract_parser.add_argument('y', type=int, help='Andre tall')
subtract_parser.set_defaults(func=subtract)

# Pars argumentene
args = parser.parse_args()

# Kall funksjonen som er assosiert med underkommandoen
if hasattr(args, 'func'):
    args.func(args)
else:
    parser.print_help()

            

              
                Copy
              
            
          

Her bruker vi set_defaults(func=...) for å assosiere en funksjon med hver underkommando. Deretter, etter parsing, kaller vi den aktuelle funksjonen hvis den eksisterer.

2. Nøstede underkommandoer

Du kan nøste underkommandoer for å lage enda mer komplekse og hierarkiske CLI-er. Vurder for eksempel et CLI for å administrere skyressurser:

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

I dette eksempelet er cloud hovedkommandoen, compute og storage er underkommandoer, og instance og bucket er under-underkommandoer.

3. Eksempel fra den virkelige verden: Internasjonaliseringsverktøy

Se for deg et verktøy for å håndtere oversettelser i en flerspråklig applikasjon. Du kan bruke underkommandoer for å organisere de forskjellige operasjonene:

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

Denne tilnærmingen gir en klar separasjon av ansvarsområder og gjør verktøyet enklere å bruke og vedlikeholde, spesielt når man håndterer mange språk og oversettelsesarbeidsflyter som gjelder for forskjellige land.

Egendefinerte handlingsklasser: Skreddersy argumentparsing

argparse lar deg definere egendefinerte handlingsklasser for å tilpasse hvordan argumenter blir behandlet. Dette er nyttig i scenarioer der standard oppførsel for argumentbehandling ikke er tilstrekkelig. En handlingsklasse er en klasse som arver fra argparse.Action og overstyrer __call__-metoden.

Opprette en egendefinert handlingsklasse

Her er et eksempel på en egendefinert handlingsklasse som konverterer et argument til store bokstaver:

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

# Opprett parseren
parser = argparse.ArgumentParser(description='Eksempel med egendefinert handling')

# Legg til et argument med den egendefinerte handlingen
parser.add_argument('--name', action=ToUpper, help='Navn som skal konverteres til store bokstaver')
parser.add_argument('--cities', action=ToUpper, nargs='+', help='Liste over byer som skal konverteres til store bokstaver')

# Pars argumentene
args = parser.parse_args()

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

            

              
                Copy
              
            
          

I dette eksempelet:

• Vi definerer en klasse ToUpper som arver fra argparse.Action.
• __call__-metoden blir kalt når argumentet blir møtt. Den tar følgende argumenter:
  • parser: ArgumentParser-objektet.
  • namespace: Navnerom-objektet der de parsede argumentene lagres.
  • values: Verdien(e) til argumentet.
  • option_string: Alternativstrengen som ble brukt for å påkalle denne handlingen (f.eks. --name).
• Inne i __call__-metoden konverterer vi verdien til store bokstaver ved hjelp av values.upper() og lagrer den i navnerommet ved hjelp av setattr(namespace, self.dest, values.upper()).
• Vi legger til et argument til parseren ved hjelp av parser.add_argument('--name', action=ToUpper, help='Navn som skal konverteres til store bokstaver'). Vi spesifiserer action-argumentet som vår egendefinerte handlingsklasse.

For å kjøre dette skriptet, vil du bruke kommandoer som:

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

Bruksområder for egendefinerte handlingsklasser

1. Validering av input

Du kan bruke egendefinerte handlingsklasser for å validere input og kaste en feil hvis inputen er ugyldig. For eksempel kan du lage en handlingsklasse som sjekker om en fil eksisterer eller om et tall er innenfor et spesifikt område.

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

parser = argparse.ArgumentParser(description='Eksempel som validerer om filen eksisterer.')
parser.add_argument('--input-file', action=FileMustExist, help='Sti til input-fil.')

args = parser.parse_args()

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

            

              
                Copy
              
            
          

2. Konvertering av enheter

Du kan bruke egendefinerte handlingsklasser for å konvertere enheter. For eksempel kan du lage en handlingsklasse som konverterer temperaturer fra Celsius til Fahrenheit.

3. Håndtering av komplekse datastrukturer

Hvis du trenger å parse argumenter til komplekse datastrukturer (f.eks. ordbøker, lister med objekter), kan du bruke egendefinerte handlingsklasser for å håndtere parsingslogikken.

4. Eksempel: Håndtering av tidssoner

Tenk deg en applikasjon som må håndtere datoer og tider i forskjellige tidssoner. En egendefinert handlingsklasse kan brukes til å parse en datostreng og konvertere den til en spesifikk tidssone ved hjelp av 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"Ugyldig dato/tid-format. Bruk ISO-format (ÅÅÅÅ-MM-DDTHH:MM:SS): {values}")
        except pytz.exceptions.UnknownTimeZoneError:
            raise argparse.ArgumentTypeError(f"Ugyldig tidssone: {self.timezone}")

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

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

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

            

              
                Copy
              
            
          

Dette eksempelet viser hvordan egendefinerte handlinger kan håndtere tidssonekonverteringer ved hjelp av pytz-biblioteket, og demonstrerer en mer sofistikert bruk som er globalt relevant.

Beste praksis for bruk av avansert Argparse

• Hold det enkelt: Ikke overkompliser ditt CLI. Bruk underkommandoer og egendefinerte handlinger bare når det er nødvendig.
• Gi klare hjelpemeldinger: Skriv klare og konsise hjelpemeldinger for hver kommando og hvert argument. Bruk help-argumentet i add_argument() flittig.
• Valider input: Valider alltid brukerinput for å forhindre feil og sikkerhetssårbarheter.
• Bruk konsekvente navnekonvensjoner: Følg konsekvente navnekonvensjoner for kommandoer, argumenter og alternativer. Vurder å bruke kebab-case (--mitt-alternativ) for lange alternativnavn.
• Test grundig: Test ditt CLI grundig med forskjellige input og scenarioer.
• Dokumenter ditt CLI: Gi omfattende dokumentasjon for ditt CLI, inkludert eksempler på hvordan du bruker hver kommando og hvert argument. Verktøy som Sphinx kan generere dokumentasjon fra koden din.
• Vurder lokalisering: Hvis ditt CLI er ment for et globalt publikum, bør du vurdere å lokalisere hjelpemeldingene og annen brukerrettet tekst.

Konklusjon

Underkommandoer og egendefinerte handlingsklasser er kraftige verktøy for å lage sofistikerte og brukervennlige CLI-er med argparse. Ved å mestre disse avanserte funksjonene kan du bygge robuste, vedlikeholdbare og skalerbare kommandolinjeapplikasjoner som møter behovene til en mangfoldig brukerbase. Fra å administrere flerspråklige applikasjoner til å håndtere tidssoner over hele kloden, er mulighetene enorme. Ta i bruk disse teknikkene for å løfte din Python-scripting og utvikling av kommandolinjeverktøy til neste nivå.