`argparse` — Parser för kommandoradsalternativ, argument och underkommandon¶

Tillagd i version 3.2.

Anteckning

Medan argparse är den rekommenderade standardbiblioteksmodulen för implementering av grundläggande kommandoradsapplikationer, kan författare med mer krävande krav på exakt hur deras kommandoradsapplikationer beter sig tycka att den inte ger den nödvändiga kontrollnivån. Se Att välja ett bibliotek för argumentparsning för alternativ att överväga när argparse inte stöder beteenden som programmet kräver (t.ex. att helt inaktivera stöd för insprängda alternativ och positionella argument, eller att acceptera alternativparametervärden som börjar med - även om de motsvarar ett annat definierat alternativ).

Modulen argparse gör det enkelt att skriva användarvänliga kommandoradsgränssnitt. Programmet definierar vilka argument det behöver och argparse räknar ut hur dessa ska tolkas ur sys.argv. Modulen argparse genererar också automatiskt hjälp- och användningsmeddelanden. Modulen kommer också att ge felmeddelanden när användare ger programmet ogiltiga argument.

argparse-modulens stöd för kommandoradsgränssnitt är uppbyggt kring en instans av argparse.ArgumentParser. Den är en behållare för argumentspecifikationer och har alternativ som gäller för parsern som helhet:

parser = argparse.ArgumentParser(
                    prog='Programnamn',
                    description='Vad programmet gör',
                    epilog='Text längst ner i hjälpen')

Metoden ArgumentParser.add_argument() kopplar individuella argumentspecifikationer till parsern. Den stöder positionella argument, alternativ som accepterar värden och on/off-flaggor:

parser.add_argument('filnamn') # positionellt argument
parser.add_argument('-c', '--count') # alternativ som tar ett värde
parser.add_argument('-v', '--verbose',
                    action='store_true') # på/av-flagga

Metoden ArgumentParser.parse_args() kör parsern och placerar de extraherade uppgifterna i ett argparse.Namespace-objekt:

args = parser.parse_args()
print(args.filnamn, args.antal, args.verbose)

Anteckning

Om du letar efter en guide om hur du uppgraderar optparse-kod till argparse, se Uppgradering av Optparse-kod.

ArgumentParser-objekt¶

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True, *, suggest_on_error=False, color=True)¶

Skapa ett nytt ArgumentParser-objekt. Alla parametrar ska skickas som nyckelordsargument. Varje parameter har sin egen mer detaljerade beskrivning nedan, men i korthet är de:

prog - Namnet på programmet (standard: genereras från modulattributen __main__ och sys.argv[0])
usage - Sträng som beskriver hur programmet används (standard: genereras från argument som läggs till i parsern)
description - Text som ska visas före argumentet help (ingen text som standard)
epilog - Text som ska visas efter argumentet help (ingen text som standard)
parents - En lista över ArgumentParser-objekt vars argument också ska inkluderas
formatter_class - En klass för att anpassa hjälputmatningen
prefix_chars - Uppsättningen av tecken som prefixar valfria argument (standard: ’-’)
fromfile_prefix_chars - Uppsättningen tecken som prefixar filer från vilka ytterligare argument ska läsas (standard: None)
argument_default - Det globala standardvärdet för argument (standard: None)
conflict_handler - Strategi för att lösa motstridiga tillval (vanligtvis onödig)
add_help - Lägg till ett -h/--help-alternativ till parsern (standard: True)
allow_abbrev - Tillåter att långa alternativ förkortas om förkortningen är entydig (standard: True)
exit_on_error - Bestämmer om ArgumentParser avslutas med felinformation när ett fel inträffar eller inte. (standard: True)
suggest_on_error - Aktiverar förslag för felskrivna argumentval och namn på subparser (standard: False)
color - Tillåt färgutmatning (standard: True)

Ändrad i version 3.5: parametern allow_abbrev har lagts till.

Ändrad i version 3.8: I tidigare versioner avaktiverade allow_abbrev också gruppering av korta flaggor som -vv för att betyda -v -v.

Ändrad i version 3.9: parametern exit_on_error har lagts till.

Ändrad i version 3.14: parametrarna suggest_on_error och color har lagts till.

I följande avsnitt beskrivs hur de olika funktionerna används.

prog¶

Som standard beräknar ArgumentParser namnet på det program som ska visas i hjälpmeddelanden beroende på hur Python-tolken kördes:

basnamn av sys.argv[0] om en fil skickades som argument.
Namnet på Python-tolken följt av sys.argv[0] om en katalog eller en zip-fil skickades som argument.
Python-tolkens namn följt av -m följt av modul- eller paketnamnet om alternativet -m användes.

Denna standard är nästan alltid önskvärd eftersom det gör att hjälpmeddelandena matchar den sträng som användes för att anropa programmet på kommandoraden. För att ändra detta standardbeteende kan dock ett annat värde anges med argumentet prog= till ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

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

Observera att programnamnet, oavsett om det hämtas från sys.argv[0], från modulattributen __main__ eller från argumentet prog=, är tillgängligt för hjälpmeddelanden som använder formatspecificeraren %(prog)s.

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program

Ändrad i version 3.14: Standardvärdet för prog återspeglar nu hur __main__ faktiskt exekverades, i stället för att alltid vara os.path.basename(sys.argv[0]).

användning¶

Som standard beräknar ArgumentParser användningsmeddelandet från de argument som den innehåller. Standardmeddelandet kan åsidosättas med nyckelordet usage= argument:

>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]

positional arguments:
 bar          bar help

options:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help

Formatangivelsen %(prog)s är tillgänglig för att fylla i programnamnet i dina användningsmeddelanden.

När ett anpassat användningsmeddelande anges för huvudparsern kanske du också vill överväga att skicka argumentet prog till add_subparsers() eller argumenten prog och usage till add_parser(), för att säkerställa konsekventa kommandoprefix och användningsinformation mellan underparsers.

beskrivning¶

De flesta anrop till konstruktören ArgumentParser kommer att använda nyckelordsargumentet description=. Detta argument ger en kort beskrivning av vad programmet gör och hur det fungerar. I hjälpmeddelanden visas beskrivningen mellan kommandoradsanvändningssträngen och hjälpmeddelandena för de olika argumenten.

Som standard kommer beskrivningen att radbrytas så att den ryms inom det angivna utrymmet. För att ändra detta beteende, se argumentet formatter_class.

epilog¶

Vissa program vill visa ytterligare en beskrivning av programmet efter beskrivningen av argumenten. Sådan text kan anges med hjälp av argumentet epilog= till ArgumentParser:

>>> parser = argparse.ArgumentParser(
...     description='A foo that bars',
...     epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

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

And that's how you'd foo a bar

Precis som med argumentet description är texten epilog= som standard radbrytande, men detta beteende kan justeras med argumentet formatter_class till ArgumentParser.

föräldrar¶

Ibland delar flera parsers en gemensam uppsättning argument. Istället för att upprepa definitionerna av dessa argument, kan en enda parser med alla de delade argumenten och som skickas till parents= argumentet till ArgumentParser användas. Argumentet parents= tar en lista med ArgumentParser-objekt, samlar in alla positionella och valfria åtgärder från dem och lägger till dessa åtgärder till ArgumentParser-objektet som konstrueras:

>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)

Observera att de flesta överordnade parsers kommer att ange add_help=False. Annars kommer ArgumentParser att se två -h/--help-alternativ (ett i den överordnade och ett i den underordnade) och ge upphov till ett fel.

Anteckning

Du måste initialisera parsarna fullständigt innan du skickar dem via parents=. Om du ändrar de överordnade parsarna efter den underordnade parsern kommer dessa ändringar inte att återspeglas i den underordnade parsern.

formatter_klass¶

ArgumentParser-objekt gör det möjligt att anpassa hjälpformateringen genom att ange en alternativ formateringsklass. För närvarande finns det fyra sådana klasser:

class argparse.RawDescriptionHelpFormatter¶
class argparse.RawTextHelpFormatter¶
class argparse.ArgumentDefaultsHelpFormatter¶
class argparse.MetavarTypeHelpFormatter¶

RawDescriptionHelpFormatter och RawTextHelpFormatter ger mer kontroll över hur textbeskrivningar visas. Som standard radbryter ArgumentParser-objekten texten description och epilog i kommandoradshjälpmeddelanden:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='''this description
...         was indented weird
...             but that is okay''',
...     epilog='''
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

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

likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines

Om du anger RawDescriptionHelpFormatter som formatter_class= indikerar det att description och epilog redan är korrekt formaterade och inte ska radbrytas:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('''\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '''))
>>> parser.print_help()
usage: PROG [-h]

Please do not mess up this text!
--------------------------------
   I have indented it
   exactly the way
   I want it

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

RawTextHelpFormatter bibehåller blanksteg för alla typer av hjälptexter, inklusive argumentbeskrivningar. Flera nya linjer ersätts dock med en. Om du vill bevara flera tomma rader lägger du till mellanslag mellan nylinjerna.

ArgumentDefaultsHelpFormatter lägger automatiskt till information om standardvärden till varje argumenthjälpmeddelande:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar ...]

positional arguments:
 bar         BAR! (default: [1, 2, 3])

options:
 -h, --help  show this help message and exit
 --foo FOO   FOO! (default: 42)

MetavarTypeHelpFormatter använder namnet på type-argumentet för varje argument som visningsnamn för dess värden (i stället för att använda dest som den vanliga formateraren gör):

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float

positional arguments:
  float

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

prefix_chars¶

De flesta kommandoradsalternativ använder - som prefix, t.ex. -f/--foo. Parsers som behöver stödja andra eller ytterligare prefixtecken, t.ex. för alternativ som +f eller /foo, kan ange dem med argumentet prefix_chars= till ArgumentParser-konstruktören:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')

Argumentet prefix_chars= är som standard '-'. Om du anger en uppsättning tecken som inte innehåller - kommer alternativen -f/--foo inte att tillåtas.

frånfil_prefix_chars¶

Ibland, när man har att göra med en särskilt lång argumentlista, kan det vara vettigt att spara listan med argument i en fil i stället för att skriva ut den på kommandoraden. Om argumentet fromfile_prefix_chars= ges till konstruktören ArgumentParser, kommer argument som börjar med något av de angivna tecknen att behandlas som filer och ersättas av de argument de innehåller. Till exempel:

>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:
...     fp.write('-f\nbar')
...
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')

Argument som läses från en fil måste som standard vara en per rad (men se även convert_arg_line_to_args()) och behandlas som om de stod på samma plats som det ursprungliga filrefererande argumentet på kommandoraden. I exemplet ovan anses alltså uttrycket ['-f', 'foo', '@args.txt'] vara likvärdigt med uttrycket ['-f', 'foo', '-f', 'bar'].

Anteckning

Tomma rader behandlas som tomma strängar (''), som är tillåtna som värden men inte som argument. Tomma rader som läses som argument resulterar i felet ”unrecognized arguments”.

ArgumentParser använder filesystem encoding and error handler för att läsa filen som innehåller argument.

Argumentet fromfile_prefix_chars= har standardvärdet None, vilket innebär att argument aldrig kommer att behandlas som filreferenser.

Ändrad i version 3.12: ArgumentParser ändrade kodning och fel för att läsa argumentfiler från standard (t.ex. locale.getpreferredencoding(False) och "strict") till filesystem encoding and error handler. Argumentsfilen bör kodas i UTF-8 istället för ANSI Codepage på Windows.

argument_default¶

I allmänhet anges standardvärden för argument antingen genom att skicka ett standardvärde till add_argument() eller genom att anropa metoderna set_defaults() med en specifik uppsättning namn-värde-par. Ibland kan det dock vara användbart att ange en enda parser-omfattande standard för argument. Detta kan åstadkommas genom att skicka nyckelordsargumentet argument_default= till ArgumentParser. Till exempel, för att globalt undertrycka skapandet av attribut vid parse_args()-anrop, anger vi argument_default=SUPPRESS:

>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()

tillåt_abbrev¶

Normalt, när du skickar en argumentlista till metoden parse_args() i en ArgumentParser, känner den igen förkortningar av långa alternativ.

Denna funktion kan avaktiveras genom att ställa in allow_abbrev till False:

>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
>>> parser.add_argument('--foobar', action='store_true')
>>> parser.add_argument('--foonley', action='store_false')
>>> parser.parse_args(['--foon'])
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon

Tillagd i version 3.5.

konflikt_hanterare¶

ArgumentParser-objekt tillåter inte två åtgärder med samma alternativsträng. Som standard gör ArgumentParser-objekt ett undantag om ett försök görs att skapa ett argument med en alternativsträng som redan används:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
 ..
ArgumentError: argument --foo: conflicting option string(s): --foo

Ibland (t.ex. när man använder parents) kan det vara användbart att helt enkelt åsidosätta äldre argument med samma alternativsträng. För att få detta beteende kan värdet 'resolve' anges till argumentet conflict_handler= i ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]

options:
 -h, --help  show this help message and exit
 -f FOO      old foo help
 --foo FOO   new foo help

Observera att ArgumentParser-objekt endast tar bort en åtgärd om alla dess alternativsträngar är åsidosatta. Så i exemplet ovan behålls den gamla åtgärden -f/--foo som åtgärden -f, eftersom endast alternativsträngen --foo åsidosattes.

lägg till_hjälp¶

Som standard lägger ArgumentParser-objekt till ett alternativ som helt enkelt visar parserns hjälpmeddelande. Om -h eller --help anges på kommandoraden, kommer ArgumentParser hjälp att skrivas ut.

Ibland kan det vara bra att avaktivera tillägget av detta hjälpalternativ. Detta kan göras genom att ange False som argument för add_help= till ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]

options:
 --foo FOO  foo help

Hjälpalternativet är vanligtvis -h/--help. Undantaget är om prefix_chars= anges och inte inkluderar -, i vilket fall -h och --help inte är giltiga alternativ. I detta fall används det första tecknet i prefix_chars som prefix för hjälpalternativen:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]

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

exit_on_error¶

När du skickar en ogiltig argumentlista till metoden parse_args() i en ArgumentParser, skriver den normalt ut ett meddelande till sys.stderr och avslutas med statuskoden 2.

Om användaren vill fånga upp fel manuellt kan funktionen aktiveras genom att ställa in exit_on_error till False:

>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
...     parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
...     print('Catching an argumentError')
...
Catching an argumentError

Tillagd i version 3.9.

föreslå_på_fel¶

Som standard, när en användare skickar ett ogiltigt argumentval eller subparsernamn, kommer ArgumentParser att avslutas med felinformation och lista de tillåtna argumentvalen (om de anges) eller subparsernamnen som en del av felmeddelandet.

Om användaren vill aktivera förslag för felskrivna argumentval och namn på subparser kan funktionen aktiveras genom att ställa in suggest_on_error till True. Observera att detta endast gäller för argument när de angivna alternativen är strängar:

>>> parser = argparse.ArgumentParser(description='Process some integers.',
                                     suggest_on_error=True)
>>> parser.add_argument('--action', choices=['sum', 'max'])
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.parse_args(['--action', 'sumn', 1, 2, 3])
tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant 'sum'? (choose from 'sum', 'max')

Om du skriver kod som måste vara kompatibel med äldre Python-versioner och vill använda suggest_on_error när det är tillgängligt, kan du ställa in det som ett attribut efter initiering av parsern istället för att använda nyckelordsargumentet:

>>> parser = argparse.ArgumentParser(description='Process some integers.')
>>> parser.suggest_on_error = True

Tillagd i version 3.14.

färg¶

Som standard skrivs hjälpmeldingen ut i färg med hjälp av ANSI-sekvenser. Om du vill ha hjälpmeddelanden i ren text kan du inaktivera detta i din lokala miljö eller i argumentparsern själv genom att ställa in color till False:

>>> parser = argparse.ArgumentParser(description='Process some integers.',
...                                  color=False)
>>> parser.add_argument('--action', choices=['sum', 'max'])
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.parse_args(['--help'])

Tillagd i version 3.14.

Metoden add_argument()¶

ArgumentParser.add_argument(name or flags..., *[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])¶

Definiera hur ett enskilt kommandoradsargument ska tolkas. Varje parameter har sin egen mer detaljerade beskrivning nedan, men i korthet är de följande:

name or flags - Antingen ett namn eller en lista med alternativsträngar, t.ex. 'foo' eller '-f', '--foo'.
action - Den grundläggande typ av åtgärd som ska vidtas när detta argument påträffas på kommandoraden.
nargs - Antalet kommandoradsargument som ska användas.
const - Ett konstant värde som krävs för vissa action- och nargs-val.
default - Det värde som produceras om argumentet inte finns på kommandoraden och om det inte finns i namnrymdsobjektet.
type - Den typ som kommandoradsargumentet ska konverteras till.
choices - En sekvens av tillåtna värden för argumentet.
required - Om kommandoradsalternativet kan utelämnas eller inte (endast optioner).
help - En kort beskrivning av vad argumentet gör.
metavar - Ett namn för argumentet i användningsmeddelanden.
dest - Namnet på det attribut som ska läggas till i det objekt som returneras av parse_args().
deprecated - Om användningen av argumentet är föråldrad eller inte.

I följande avsnitt beskrivs hur de olika funktionerna används.

namn eller flaggor¶

Metoden add_argument() måste veta om ett valfritt argument, som -f eller --foo, eller ett positionellt argument, som en lista med filnamn, förväntas. De första argumenten som skickas till add_argument() måste därför vara antingen en serie flaggor eller ett enkelt argumentnamn.

Ett valfritt argument kan t.ex. skapas på följande sätt:

>>> parser.add_argument('-f', '--foo')

medan ett positionellt argument kan skapas som:

>>> parser.add_argument('bar')

När parse_args() anropas kommer valfria argument att identifieras med prefixet -, och de återstående argumenten kommer att antas vara positionella:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar

Som standard hanterar argparse automatiskt den interna namngivningen och visningsnamnen för argument, vilket förenklar processen utan att kräva ytterligare konfiguration. Därför behöver du inte ange parametrarna dest och metavar. Parametern dest är som standard argumentnamnet med understrykningar _ som ersätter bindestreck - . Parametern metavar använder som standard namnet med versaler. Till exempel:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo-bar')
>>> parser.parse_args(['--foo-bar', 'FOO-BAR']
Namespace(foo_bar='FOO-BAR')
>>> parser.print_help()
usage:  [-h] [--foo-bar FOO-BAR]

optional arguments:
 -h, --help  show this help message and exit
 --foo-bar FOO-BAR

åtgärd¶

ArgumentParser-objekt associerar kommandoradsargument med åtgärder. Dessa åtgärder kan göra nästan vad som helst med de kommandoradsargument som associeras med dem, även om de flesta åtgärder helt enkelt lägger till ett attribut till det objekt som returneras av parse_args(). Nyckelordsargumentet action anger hur kommandoradsargumenten ska hanteras. De medföljande åtgärderna är:

'store' - Detta lagrar bara argumentets värde. Detta är standardåtgärden.
'store_const' - Detta lagrar det värde som anges av const-nyckelordsargumentet; observera att const-nyckelordsargumentet som standard är None. Aktionen 'store_const' används oftast med valfria argument som anger någon form av flagga. Till exempel:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
```

'store_true' och 'store_false' - Dessa är specialfall av 'store_const' som används för att lagra värdena True respektive False. Dessutom skapar de standardvärden för False respektive True:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(foo=True, bar=False, baz=True)

'append' - Detta lagrar en lista och lägger till varje argumentvärde i listan. Det är användbart för att tillåta att ett alternativ anges flera gånger. Om standardvärdet inte är tomt kommer standardelementen att finnas i det analyserade värdet för alternativet, med eventuella värden från kommandoraden tillagda efter dessa standardvärden. Exempel på användning:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])
```

'append_const' - Detta lagrar en lista och lägger till det värde som anges av const-nyckelordsargumentet till listan; observera att const-nyckelordsargumentet som standard är None. Åtgärden 'append_const' är vanligtvis användbar när flera argument behöver lagra konstanter i samma lista. Till exempel:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<class 'str'>, <class 'int'>])

'extend' - Detta lagrar en lista och lägger till varje objekt från den flervärdiga argumentlistan till den. Åtgärden 'extend' används vanligtvis med nyckelordet nargs med argumentvärdet '+' eller '*'. Observera att när nargs är None (standard) eller '?', kommer varje tecken i argumentsträngen att läggas till i listan. Exempel på användning:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Namespace(foo=['f1', 'f2', 'f3', 'f4'])
```
Tillagd i version 3.8.
'count' - Detta räknar antalet gånger ett nyckelordsargument förekommer. Detta är t.ex. användbart för att öka ordrikedomen:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
```
Observera att standard kommer att vara None om det inte uttryckligen sätts till 0.
'help' - Detta skriver ut ett komplett hjälpmeddelande för alla alternativ i den aktuella parsern och avslutar sedan. Som standard läggs en hjälpåtgärd automatiskt till i parsern. Se ArgumentParser för detaljer om hur utdata skapas.

'version' - Detta förväntar sig ett version= nyckelordsargument i add_argument()-anropet, och skriver ut versionsinformation och avslutas när det anropas:

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> parser.parse_args(['--version'])
PROG 2.0

Du kan också ange en godtycklig åtgärd genom att skicka en Action-underklass (t.ex. BooleanOptionalAction) eller ett annat objekt som implementerar samma gränssnitt. Endast åtgärder som använder kommandoradsargument (t.ex. 'store', 'append', 'extend' eller anpassade åtgärder med nargs som inte är noll) kan användas med positionella argument.

Det rekommenderade sättet att skapa en anpassad åtgärd är att utöka Action, åsidosätta metoden __call__() och eventuellt metoderna __init__() och format_usage(). Du kan också registrera anpassade åtgärder med hjälp av metoden register() och referera till dem med deras registrerade namn.

Ett exempel på en anpassad åtgärd:

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super().__init__(option_strings, dest, **kwargs)
...     def __call__(self, parser, namespace, values, option_string=None):
...         print('%r %r %r' % (namespace, values, option_string))
...         setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')

För mer information, se Action.

nargs¶

ArgumentParser-objekt associerar vanligtvis ett enda kommandoradsargument med en enda åtgärd som skall vidtas. Nyckelordsargumentet nargs associerar ett annat antal kommandoradsargument med en enda åtgärd. Se även Specificering av tvetydiga argument. De värden som stöds är:

N (ett heltal). N argument från kommandoraden kommer att samlas ihop till en lista. Till exempel:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])
```
Observera att nargs=1 producerar en lista med ett objekt. Detta skiljer sig från standardinställningen, där varje objekt produceras för sig.

'?'. Ett argument hämtas från kommandoraden om möjligt och produceras som ett enda objekt. Om det inte finns något argument på kommandoraden produceras värdet från default. Observera att för valfria argument finns det ytterligare ett fall - alternativsträngen finns men följs inte av ett kommandoradsargument. I detta fall kommer värdet från const att produceras. Några exempel för att illustrera detta:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args(['XX', '--foo', 'YY'])
Namespace(bar='XX', foo='YY')
>>> parser.parse_args(['XX', '--foo'])
Namespace(bar='XX', foo='c')
>>> parser.parse_args([])
Namespace(bar='d', foo='d')

En av de vanligaste användningarna av nargs='?' är att tillåta valfria inmatnings- och utdatafiler:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?')
>>> parser.add_argument('outfile', nargs='?')
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile='input.txt', outfile='output.txt')
>>> parser.parse_args(['input.txt'])
Namespace(infile='input.txt', outfile=None)
>>> parser.parse_args([])
Namespace(infile=None, outfile=None)

'*'. Alla kommandoradsargument som finns samlas i en lista. Observera att det i allmänhet inte är särskilt meningsfullt att ha mer än ett positionellt argument med nargs='*', men det är möjligt att ha flera valfria argument med nargs='*'. Till exempel:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

'+'. Precis som i '*' samlas alla kommandoradsargument som finns i en lista. Dessutom genereras ett felmeddelande om det inte fanns minst ett kommandoradsargument. Till exempel:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args(['a', 'b'])
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: the following arguments are required: foo

Om nyckelordsargumentet nargs inte anges, bestäms antalet argument som förbrukas av action. I allmänhet innebär detta att ett enda kommandoradsargument kommer att förbrukas och ett enda objekt (inte en lista) kommer att produceras. Åtgärder som inte förbrukar kommandoradsargument (t.ex. 'store_const') anger nargs=0.

konst¶

Argumentet const i add_argument() används för att hålla konstanta värden som inte läses från kommandoraden men som krävs för de olika ArgumentParser-åtgärderna. De två vanligaste användningarna av den är:

När add_argument() anropas med action='store_const' eller action='append_const'. Dessa åtgärder lägger till värdet const till en av attributen för objektet som returneras av parse_args(). Se beskrivningen av action för exempel. Om const inte anges för add_argument(), får den standardvärdet None.
När add_argument() anropas med optionssträngar (som -f eller --foo) och nargs='?'. Detta skapar ett valfritt argument som kan följas av noll eller ett kommandoradsargument. Om alternativsträngen påträffas utan något efterföljande kommandoradsargument när kommandoraden analyseras, kommer värdet på const att antas vara None istället. Se nargs-beskrivningen för exempel.

Ändrad i version 3.11: const=None som standard, inklusive när action='append_const' eller action='store_const'.

standard¶

Alla valfria argument och vissa positionella argument kan utelämnas på kommandoraden. Nyckelordsargumentet default i add_argument(), vars standardvärde är None, anger vilket värde som ska användas om kommandoradsargumentet inte finns med. För valfria argument används default-värdet när alternativsträngen inte fanns på kommandoraden:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)

Om målnamnrymden redan har en attributuppsättning kommer åtgärden default inte att skriva över den:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)

Om default-värdet är en sträng, analyserar parsern värdet som om det vore ett kommandoradsargument. I synnerhet tillämpar parsern ett typ-konverteringsargument, om det tillhandahålls, innan attributet ställs in på returvärdet för Namespace. Annars använder parsern värdet som det är:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)

För positionella argument med nargs lika med ? eller * används default-värdet om inget kommandoradsargument fanns:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)

För required-argument ignoreras värdet default. Detta gäller till exempel positionsargument med nargs-värden som inte är ? eller *, eller valfria argument markerade som required=True.

Om du anger default=argparse.SUPPRESS läggs inget attribut till om kommandoradsargumentet inte fanns:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')

typ¶

Som standard läser parsern in kommandoradsargument som enkla strängar. Men ofta bör kommandoradssträngen istället tolkas som en annan typ, t.ex. en float eller int. Nyckelordet type för add_argument() gör att alla nödvändiga typkontroller och typkonverteringar kan utföras.

Om nyckelordet type används tillsammans med nyckelordet default tillämpas typomvandlaren endast om default är en sträng.

Argumentet till type kan vara en callable som accepterar en enda sträng eller namnet på en registrerad typ (se register()) Om funktionen ger upphov till ArgumentTypeError, TypeError eller ValueError fångas undantaget upp och ett snyggt formaterat felmeddelande visas. Andra undantagstyper hanteras inte.

Vanliga inbyggda typer och funktioner kan användas som typomvandlare:

import argparse
import pathlib

parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('datapath', type=pathlib.Path)

Användardefinierade funktioner kan också användas:

>>> def hyphenated(string):
...     return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')

Funktionen bool() rekommenderas inte som typomvandlare. Allt den gör är att konvertera tomma strängar till False och icke-tomma strängar till True. Detta är vanligtvis inte vad som önskas.

I allmänhet är nyckelordet type en bekvämlighet som bara bör användas för enkla konverteringar som bara kan ge upphov till ett av de tre undantag som stöds. Allt med mer intressant felhantering eller resurshantering bör göras nedströms efter att argumenten har analyserats.

Till exempel har JSON- eller YAML-konverteringar komplexa fel som kräver bättre rapportering än vad som kan ges av nyckelordet type. Ett JSONDecodeError skulle inte vara välformaterat och ett FileNotFoundError undantag skulle inte hanteras alls.

Även FileType har sina begränsningar för användning med nyckelordet type. Om ett argument använder FileType och sedan ett efterföljande argument misslyckas, rapporteras ett fel men filen stängs inte automatiskt. I det här fallet är det bättre att vänta tills efter att parsern har körts och sedan använda with-statement för att hantera filerna.

För typkontrollprogram som bara kontrollerar mot en fast uppsättning värden kan du överväga att använda nyckelordet choices i stället.

val¶

Vissa kommandoradsargument bör väljas från en begränsad uppsättning värden. Dessa kan hanteras genom att skicka ett sequence-objekt som argument för nyckelordet choices till add_argument(). När kommandoraden analyseras kontrolleras argumentvärdena och ett felmeddelande visas om argumentet inte var ett av de godtagbara värdena:

>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')

Observera att inkludering i choices-sekvensen kontrolleras efter att eventuella typ-konverteringar har utförts, så typen av objekten i choices-sekvensen bör överensstämma med den typ som anges.

Vilken sekvens som helst kan skickas som choices-värde, så list-objekt, tuple-objekt och anpassade sekvenser stöds alla.

Användning av enum.Enum rekommenderas inte eftersom det är svårt att kontrollera dess utseende i användnings-, hjälp- och felmeddelanden.

Formaterade val åsidosätter standardvärdet metavar som normalt härleds från dest. Detta är vanligtvis vad du vill ha eftersom användaren aldrig ser parametern dest. Om den här visningen inte är önskvärd (kanske för att det finns många valmöjligheter), ange bara en explicit metavar.

obligatoriskt¶

I allmänhet antar modulen argparse att flaggor som -f och --bar anger valfria argument, som alltid kan utelämnas på kommandoraden. För att göra ett alternativ krävt kan True anges för nyckelordsargumentet required= till add_argument():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-h] --foo FOO
: error: the following arguments are required: --foo

Som exemplet visar, om ett alternativ är markerat som required, kommer parse_args() att rapportera ett fel om det alternativet inte finns på kommandoraden.

Anteckning

Obligatoriska alternativ anses i allmänhet vara dålig form eftersom användare förväntar sig att alternativ ska vara valbara, och därför bör de undvikas när det är möjligt.

hjälp¶

Värdet help är en sträng som innehåller en kort beskrivning av argumentet. När en användare begär hjälp (vanligtvis genom att använda -h eller --help på kommandoraden) visas dessa help-beskrivningar för varje argument.

Strängarna help kan innehålla olika formatspecifikatorer för att undvika upprepning av t.ex. programnamnet eller argumentet default. De tillgängliga specifikatorerna inkluderar programnamnet, %(prog)s och de flesta nyckelordsargument till add_argument(), t.ex. %(default)s, %(type)s, etc:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
...                     help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar     the bar to frobble (default: 42)

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

Eftersom hjälpsträngen stöder %-f-matrisering måste du, om du vill att en bokstavlig % ska visas i hjälpsträngen, escapen den som %%.

argparse stöder att tysta ner hjälptexten för vissa alternativ genom att ställa in värdet help till argparse.SUPPRESS:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]

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

metavar¶

När ArgumentParser genererar hjälpmeddelanden behöver den något sätt att hänvisa till varje förväntat argument. Som standard använder ArgumentParser-objekt dest-värdet som ”namn” för varje objekt. Som standard används dest-värdet direkt för åtgärder med positionella argument, och för åtgärder med valfria argument används dest-värdet med versaler. Ett enskilt positionellt argument med dest='bar' kommer alltså att kallas bar. Ett enda valfritt argument --foo som ska följas av ett enda kommandoradsargument kommer att refereras till som FOO. Ett exempel:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo FOO] bar

positional arguments:
 bar

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

Ett alternativt namn kan anges med metavar:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo YYY] XXX

positional arguments:
 XXX

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

Observera att metavar endast ändrar det visade namnet - attributets namn på parse_args()-objektet bestäms fortfarande av dest-värdet.

Olika värden på nargs kan göra att metavar används flera gånger. Om man ger en tupel till metavar anges en annan visning för vart och ett av argumenten:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]

options:
 -h, --help     show this help message and exit
 -x X X
 --foo bar baz

dest¶

De flesta ArgumentParser-åtgärder lägger till ett värde som ett attribut för det objekt som returneras av parse_args(). Namnet på detta attribut bestäms av nyckelordsargumentet dest i add_argument(). För åtgärder med positionella argument anges dest normalt som det första argumentet till add_argument():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')

För valfria argumentåtgärder härleds värdet av dest normalt från optionssträngarna. ArgumentParser genererar värdet av dest genom att ta den första långa optionssträngen och ta bort den inledande strängen --. Om inga långa optionssträngar har angetts, härleds dest från den första korta optionssträngen genom att ta bort det inledande tecknet -. Alla interna - -tecken konverteras till _ -tecken för att säkerställa att strängen är ett giltigt attributnamn. Exemplen nedan illustrerar detta beteende:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')

dest tillåter att ett anpassat attributnamn anges:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')

utfasad¶

Under ett projekts livstid kan vissa argument behöva tas bort från kommandoraden. Innan du tar bort dem bör du informera dina användare om att argumenten är föråldrade och kommer att tas bort. Nyckelordsargumentet deprecated i add_argument(), som har False som standard, anger om argumentet är föråldrat och kommer att tas bort i framtiden. För argument, om deprecated är True, kommer en varning att skrivas ut till sys.stderr när argumentet används:

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='snake.py')
>>> parser.add_argument('--legs', default=0, type=int, deprecated=True)
>>> parser.parse_args([])
Namespace(legs=0)
>>> parser.parse_args(['--legs', '4'])
snake.py: warning: option '--legs' is deprecated
Namespace(legs=4)

Tillagd i version 3.13.

Åtgärdsklasser¶

Action-klasser implementerar Action API, en anropsbar som returnerar en anropsbar som bearbetar argument från kommandoraden. Alla objekt som följer detta API kan skickas som parametern action till add_argument().

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)¶

Action-objekt används av en ArgumentParser för att representera den information som behövs för att analysera ett enda argument från en eller flera strängar från kommandoraden. Klassen Action måste acceptera de två positionella argumenten plus alla nyckelordsargument som skickas till ArgumentParser.add_argument() förutom själva action.

Instanser av Action (eller returvärdet av en anropbar till parametern action) bör ha attributen dest, option_strings, default, type, required, help, etc. definierade. Det enklaste sättet att säkerställa att dessa attribut är definierade är att anropa Action.__init__().

__call__(parser, namespace, values, option_string=None)¶

Action-instanser ska vara anropsbara, så underklasser måste åsidosätta __call__()-metoden, som ska acceptera fyra parametrar:

parser - Det ArgumentParser-objekt som innehåller denna åtgärd.
namespace - Det Namespace-objekt som kommer att returneras av parse_args(). De flesta åtgärder lägger till ett attribut till detta objekt med hjälp av setattr().
values - De associerade kommandoradsargumenten, med eventuella typkonverteringar tillämpade. Typkonverteringar anges med nyckelordsargumentet type till add_argument().
option_string - Den alternativsträng som användes för att anropa denna åtgärd. Argumentet option_string är valfritt och saknas om åtgärden associeras med ett positionellt argument.

Metoden __call__() kan utföra godtyckliga åtgärder, men kommer vanligtvis att ställa in attribut på namespace baserat på dest och values.

format_usage()¶: Action subklasser kan definiera en format_usage() metod som inte tar något argument och returnerar en sträng som kommer att användas vid utskrift av programmets användning. Om en sådan metod inte tillhandahålls kommer en förnuftig standard att användas.

class argparse.BooleanOptionalAction¶

En subklass av Action för hantering av booleska flaggor med positiva och negativa alternativ. Genom att lägga till ett enda argument som --foo skapas automatiskt både --foo och --no-foo alternativ, som lagrar True respektive False:

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)

Tillagd i version 3.9.

Metoden parse_args()¶

ArgumentParser.parse_args(args=None, namespace=None)¶

Konverterar argumentsträngar till objekt och tilldelar dem som attribut för namnrymden. Returnera det ifyllda namnrymden.

Tidigare anrop till add_argument() avgör exakt vilka objekt som skapas och hur de tilldelas. Se dokumentationen för add_argument() för mer information.

args - Lista över strängar som ska analyseras. Standardvärdet hämtas från sys.argv.
namespace - Ett objekt som tar emot attributen. Standard är ett nytt tomt Namespace-objekt.

Syntax för optionsvärde¶

Metoden parse_args() stöder flera sätt att ange värdet på ett alternativ (om det tar ett sådant). I det enklaste fallet skickas alternativet och dess värde som två separata argument:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)

För långa alternativ (alternativ med namn som är längre än ett enda tecken) kan alternativet och värdet också skickas som ett enda argument på kommandoraden, med = för att separera dem:

>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)

För korta alternativ (alternativ som bara är ett tecken långa) kan alternativet och dess värde sammankopplas:

>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')

Flera korta alternativ kan sammanfogas med hjälp av ett enda prefix -, så länge som endast det sista alternativet (eller inget av dem) kräver ett värde:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')

Ogiltiga argument¶

När kommandoraden analyseras kontrollerar parse_args() en mängd olika fel, inklusive tvetydiga alternativ, ogiltiga typer, ogiltiga alternativ, fel antal positionella argument, etc. När den stöter på ett sådant fel avslutas den och skriver ut felet tillsammans med ett användningsmeddelande:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')

>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger

Argument som innehåller `-`¶

Metoden parse_args() försöker ge felmeddelanden när det är uppenbart att användaren har gjort ett misstag, men vissa situationer är i sig tvetydiga. Till exempel kan kommandoradsargumentet -1 antingen vara ett försök att ange ett alternativ eller ett försök att ange ett positionsargument. Metoden parse_args() är försiktig här: positionella argument får endast börja med - om de ser ut som negativa tal och det inte finns några alternativ i parsern som ser ut som negativa tal:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')

>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')

>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument

Om du har positionella argument som måste börja med - och inte ser ut som negativa tal, kan du infoga pseudoargumentet '--' som talar om för parse_args() att allt efter det är ett positionellt argument:

>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)

Se även the argparse howto on ambiguous arguments för mer information.

Argumentförkortningar (prefixmatchning)¶

Metoden parse_args() by default tillåter att långa alternativ förkortas till ett prefix, om förkortningen är otvetydig (prefixet matchar ett unikt alternativ):

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon

Ett felmeddelande visas för argument som kan ge mer än ett alternativ. Denna funktion kan avaktiveras genom att ställa in tillåt_abbrev till False.

Bortom `sys.argv`¶

Ibland kan det vara användbart att låta en ArgumentParser analysera andra argument än de som finns i sys.argv. Detta kan åstadkommas genom att skicka en lista med strängar till parse_args(). Detta är användbart för att testa vid den interaktiva prompten:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
...     'integers', metavar='int', type=int, choices=range(10),
...     nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
...     '--sum', dest='accumulate', action='store_const', const=sum,
...     default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

Namespace-objektet¶

class argparse.Namespace¶

Enkel klass som används som standard av parse_args() för att skapa ett objekt som innehåller attribut och returnera det.

Den här klassen är avsiktligt enkel, bara en object-underklass med en läsbar strängrepresentation. Om du föredrar att ha en diktliknande vy över attributen kan du använda Pythons standardidiom, vars():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}

Det kan också vara användbart att låta en ArgumentParser tilldela attribut till ett redan existerande objekt, snarare än ett nytt Namespace-objekt. Detta kan uppnås genom att ange nyckelordet namespace= argument:

>>> class C:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

Andra verktyg¶

Underkommandon¶

ArgumentParser.add_subparsers(*[, title][, description][, prog][, parser_class][, action][, dest][, required][, help][, metavar])¶

Många program delar upp sin funktionalitet i ett antal underkommandon, till exempel kan programmet svn anropa underkommandon som svn checkout, svn update och svn commit. Att dela upp funktionalitet på det här sättet kan vara en särskilt bra idé när ett program utför flera olika funktioner som kräver olika typer av kommandoradsargument. ArgumentParser stöder skapandet av sådana underkommandon med metoden add_subparsers(). Metoden add_subparsers() anropas normalt utan argument och returnerar ett speciellt action-objekt. Detta objekt har en enda metod, add_parser(), som tar ett kommandonamn och eventuella ArgumentParser-konstruktorargument, och returnerar ett ArgumentParser-objekt som kan modifieras som vanligt.

Beskrivning av parametrar:

title - titel för sub-parser-gruppen i hjälputmatningen; standard är ”subcommands” om beskrivning anges, annars används titel för positionsargument
description - beskrivning för sub-parser-gruppen i hjälputdata, standard None
prog - användningsinformation som kommer att visas med hjälp för underkommandon, som standard namnet på programmet och eventuella positionsargument före subparser-argumentet
parser_class - klass som kommer att användas för att skapa sub-parser-instanser, som standard klassen för den aktuella parsern (t.ex. ArgumentParser)
action - den grundläggande typ av åtgärd som ska vidtas när detta argument påträffas på kommandoraden
dest - namnet på det attribut under vilket namnet på underkommandot lagras; som standard None och inget värde lagras
required - Huruvida ett underkommando måste anges eller inte, som standard False (tillagd i 3.7)
help - hjälp för sub-parser-gruppen i hjälputmatningen, som standard None
metavar - sträng som presenterar tillgängliga underkommandon i hjälpen; som standard är den None och presenterar underkommandon i form {cmd1, cmd2, ..}

Några exempel på användning:

>>> # create the top-level parser
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='subcommand help')
>>>
>>> # create the parser for the "a" command
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create the parser for the "b" command
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')
>>>
>>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)

Observera att det objekt som returneras av parse_args() endast innehåller attribut för huvudparsern och den underparser som valdes på kommandoraden (och inte några andra underparsers). Så i exemplet ovan, när kommandot a anges, är det bara attributen foo och bar som finns, och när kommandot b anges, är det bara attributen foo och baz som finns.

På samma sätt gäller att när ett hjälpmeddelande begärs från en subparser, skrivs endast hjälpen för den aktuella parsern ut. Hjälpmeddelandet innehåller inte meddelanden från den överordnade parsern eller syskonparsern. (Ett hjälpmeddelande för varje subparser-kommando kan dock ges genom att ange argumentet help= till add_parser() enligt ovan)

>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
  {a,b}   subcommand help
    a     a help
    b     b help

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

>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar

positional arguments:
  bar     bar help

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

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]

options:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

Metoden add_subparsers() har även stöd för nyckelordsargumenten title och description. När något av dem finns med visas kommandona för underparsaren i en egen grupp i hjälputmatningen. Till exempel:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
...                                    description='valid subcommands',
...                                    help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage:  [-h] {foo,bar} ...

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

subcommands:
  valid subcommands

  {foo,bar}   additional help

Dessutom stöder add_parser() ett ytterligare aliases-argument, vilket gör att flera strängar kan referera till samma subparser. Detta exempel, liksom svn, alias co som en förkortning för checkout:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>> checkout = subparsers.add_parser('checkout', aliases=['co'])
>>> checkout.add_argument('foo')
>>> parser.parse_args(['co', 'bar'])
Namespace(foo='bar')

add_parser() stöder också ett ytterligare deprecated-argument, som gör det möjligt att depreciera subparsern.

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='chicken.py')
>>> subparsers = parser.add_subparsers()
>>> run = subparsers.add_parser('run')
>>> fly = subparsers.add_parser('fly', deprecated=True)
>>> parser.parse_args(['fly'])
chicken.py: warning: command 'fly' is deprecated
Namespace()

Tillagd i version 3.13.

Ett särskilt effektivt sätt att hantera underkommandon är att kombinera användningen av metoden add_subparsers() med anrop till set_defaults() så att varje subparser vet vilken Python-funktion den ska utföra. Till exempel:

>>> # subcommand functions
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(required=True)
>>>
>>> # create the parser for the "foo" command
>>> parser_foo = subparsers.add_parser('foo')
>>> parser_foo.add_argument('-x', type=int, default=1)
>>> parser_foo.add_argument('y', type=float)
>>> parser_foo.set_defaults(func=foo)
>>>
>>> # create the parser for the "bar" command
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))

På så sätt kan du låta parse_args() göra jobbet att anropa lämplig funktion efter att parsningen av argumenten är klar. Att associera funktioner med åtgärder på det här sättet är vanligtvis det enklaste sättet att hantera olika åtgärder för var och en av dina subparsers. Men om det är nödvändigt att kontrollera namnet på den subparsare som anropades, fungerar nyckelordsargumentet dest till add_subparsers()-anropet:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')

Ändrad i version 3.7: Ny krävd parameter som endast innehåller nyckelord.

Ändrad i version 3.14: Subparsers prog påverkas inte längre av ett anpassat användningsmeddelande i huvudparsern.

FileType-objekt¶

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)¶

Fabriken FileType skapar objekt som kan skickas till typargumentet i ArgumentParser.add_argument(). Argument som har FileType-objekt som typ kommer att öppna kommandoradsargument som filer med de begärda lägena, buffertstorlekarna, kodningarna och felhanteringen (se funktionen open() för mer information):

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

FileType-objekt förstår pseudoargumentet '-' och konverterar detta automatiskt till sys.stdin för läsbara FileType-objekt och sys.stdout för skrivbara FileType-objekt:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

Anteckning

Om ett argument använder FileType och ett efterföljande argument misslyckas, rapporteras ett fel men filen stängs inte automatiskt. Detta kan också förstöra utdatafilerna. I det här fallet är det bättre att vänta tills parsern har körts och sedan använda with-statement för att hantera filerna.

Ändrad i version 3.4: Parametrarna encodings och errors har lagts till.

Föråldrad sedan version 3.14.

Argumentgrupper¶

ArgumentParser.add_argument_group(title=None, description=None, *[, argument_default][, conflict_handler])¶

Som standard grupperar ArgumentParser kommandoradsargument i ”positionella argument” och ”alternativ” när hjälpmeddelanden visas. När det finns en bättre konceptuell gruppering av argument än denna standardgruppering kan lämpliga grupper skapas med hjälp av metoden add_argument_group():

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> parser.print_help()
usage: PROG [--foo FOO] bar

group:
  bar    bar help
  --foo FOO  foo help

Metoden add_argument_group() returnerar ett argumentgruppsobjekt som har en metod add_argument() precis som en vanlig ArgumentParser. När ett argument läggs till i gruppen behandlar parsern det precis som ett vanligt argument, men visar argumentet i en separat grupp för hjälpmeddelanden. Metoden add_argument_group() accepterar argumenten title och description som kan användas för att anpassa denna visning:

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'group1 description')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'group2 description')
>>> group2.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [--bar BAR] foo

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help

De valfria parametrarna argument_default och conflict_handler, som endast innehåller nyckelord, ger möjlighet till mer detaljerad kontroll av argumentgruppens beteende. Dessa parametrar har samma betydelse som i ArgumentParser-konstruktören, men gäller specifikt för argumentgruppen snarare än för hela parsern.

Observera att alla argument som inte finns i dina användardefinierade grupper hamnar tillbaka i de vanliga avsnitten ”positionella argument” och ”valfria argument”.

Deprecated since version 3.11, removed in version 3.14: Anrop av add_argument_group() på en argumentgrupp ger nu upphov till ett undantag. Denna nestning stöddes aldrig, fungerade ofta inte korrekt och exponerades oavsiktligt genom arv.

Föråldrad sedan version 3.14: Att skicka prefix_chars till add_argument_group() är nu föråldrat.

Ömsesidigt uteslutande¶

ArgumentParser.add_mutually_exclusive_group(required=False)¶

Skapa en ömsesidigt exklusiv grupp. argparse kommer att se till att endast ett av argumenten i den ömsesidigt exklusiva gruppen fanns på kommandoraden:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group()
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args(['--foo'])
Namespace(bar=True, foo=True)
>>> parser.parse_args(['--bar'])
Namespace(bar=False, foo=False)
>>> parser.parse_args(['--foo', '--bar'])
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo

Metoden add_mutually_exclusive_group() accepterar också ett required-argument, för att ange att minst ett av de ömsesidigt uteslutande argumenten krävs:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required

Observera att argumentgrupper som för närvarande är ömsesidigt exklusiva inte stöder argumenten title och description i add_argument_group(). En ömsesidigt exklusiv grupp kan dock läggas till i en argumentgrupp som har en titel och en beskrivning. Till exempel:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_argument_group('Group title', 'Group description')
>>> exclusive_group = group.add_mutually_exclusive_group(required=True)
>>> exclusive_group.add_argument('--foo', help='foo help')
>>> exclusive_group.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [-h] (--foo FOO | --bar BAR)

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

Group title:
  Group description

  --foo FOO   foo help
  --bar BAR   bar help

Deprecated since version 3.11, removed in version 3.14: Anrop av add_argument_group() eller add_mutually_exclusive_group() på en ömsesidigt exklusiv grupp ger nu upphov till ett undantag. Denna nestning stöddes aldrig, fungerade ofta inte korrekt och exponerades oavsiktligt genom arv.

Standardvärden för parser¶

ArgumentParser.set_defaults(**kwargs)¶

För det mesta kommer attributen för det objekt som returneras av parse_args() att vara helt bestämda genom att inspektera kommandoradsargumenten och argumentåtgärderna. set_defaults() gör att några ytterligare attribut som bestäms utan någon inspektion av kommandoraden kan läggas till:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.set_defaults(bar=42, baz='badger')
>>> parser.parse_args(['736'])
Namespace(bar=42, baz='badger', foo=736)

Observera att standardvärden på parsernivå alltid åsidosätter standardvärden på argumentnivå:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')

Standardvärden på parser-nivå kan vara särskilt användbara när man arbetar med flera parsers. Se metoden add_subparsers() för ett exempel på denna typ.

ArgumentParser.get_default(dest)¶

Hämta standardvärdet för ett namnrymdsattribut, som anges antingen av add_argument() eller av set_defaults():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'

Hjälp med utskrift¶

I de flesta typiska applikationer kommer parse_args() att ta hand om formateringen och skriva ut eventuella användnings- eller felmeddelanden. Det finns dock flera formateringsmetoder tillgängliga:

ArgumentParser.print_usage(file=None)¶: Skriv ut en kort beskrivning av hur ArgumentParser ska anropas på kommandoraden. Om file är None, antas sys.stdout.

ArgumentParser.print_help(file=None)¶: Skriv ut ett hjälpmeddelande, inklusive programanvändning och information om de argument som registrerats med ArgumentParser. Om file är None, antas sys.stdout.

Det finns också varianter av dessa metoder som helt enkelt returnerar en sträng i stället för att skriva ut den:

ArgumentParser.format_usage()¶: Returnerar en sträng som innehåller en kort beskrivning av hur ArgumentParser ska anropas på kommandoraden.

ArgumentParser.format_help()¶: Returnerar en sträng som innehåller ett hjälpmeddelande, inklusive programanvändning och information om de argument som registrerats med ArgumentParser.

Partiell parsning¶

ArgumentParser.parse_known_args(args=None, namespace=None)¶

Ibland behöver ett skript bara hantera en viss uppsättning kommandoradsargument och lämna eventuella oigenkända argument till ett annat skript eller program. I dessa fall kan metoden parse_known_args() vara användbar.

Den här metoden fungerar på samma sätt som parse_args(), men den ger inte felmeddelanden för extra, okända argument. Istället analyserar den de kända argumenten och returnerar en tupel med två objekt som innehåller den fyllda namnrymden och listan över eventuella okända argument.

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

Varning

Prefixmatchning regler gäller för parse_known_args(). Parsern kan konsumera ett alternativ även om det bara är ett prefix av ett av dess kända alternativ, istället för att lämna det i den återstående argumentlistan.

Anpassa filparsning¶

ArgumentParser.convert_arg_line_to_args(arg_line)¶

Argument som läses från en fil (se nyckelordsargumentet fromfile_prefix_chars till konstruktören ArgumentParser) läses ett argument per rad. convert_arg_line_to_args() kan åsidosättas för mer avancerad läsning.

Denna metod tar ett enda argument arg_line som är en sträng som läses från argumentfilen. Den returnerar en lista med argument som tolkats från denna sträng. Metoden anropas en gång per rad som läses från argumentfilen, i ordning.

En användbar överstyrning av denna metod är en som behandlar varje mellanslagsseparerat ord som ett argument. Följande exempel visar hur man gör detta:

klass MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()

Spännande metoder¶

ArgumentParser.exit(status=0, message=None)¶

Den här metoden avslutar programmet med den angivna statusen och, om den anges, skriver den ut ett meddelande till sys.stderr innan dess. Användaren kan åsidosätta den här metoden för att hantera dessa steg annorlunda:

class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Avslutar på grund av ett fel: {message}')
        exit(status)

ArgumentParser.error(message)¶: Denna metod skriver ut ett användningsmeddelande, inklusive message, till sys.stderr och avslutar programmet med statuskoden 2.

Intermixad parsning¶

ArgumentParser.parse_intermixed_args(args=None, namespace=None)¶

ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)¶

Ett antal Unix-kommandon tillåter användaren att blanda valfria argument med positionella argument. Metoderna parse_intermixed_args() och parse_known_intermixed_args() stöder denna parsningsstil.

Dessa parsers har inte stöd för alla argparse-funktioner, och kommer att ge upphov till undantag om funktioner som inte stöds används. I synnerhet stöds inte subparsers och ömsesidigt exklusiva grupper som innehåller både optionals och positionals.

Följande exempel visar skillnaden mellan parse_known_args() och parse_intermixed_args(): den förra returnerar ['2', '3'] som oanalyserade argument, medan den senare samlar alla positionaler i rest.

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

parse_known_intermixed_args() returnerar en tupel med två objekt som innehåller den fyllda namnrymden och listan över återstående argumentsträngar. parse_intermixed_args() ger upphov till ett fel om det finns några återstående oanalyserade argumentsträngar.

Tillagd i version 3.7.

Registrering av anpassade typer eller åtgärder¶

ArgumentParser.register(registry_name, value, object)¶

Ibland är det önskvärt att använda en anpassad sträng i felmeddelanden för att ge en mer användarvänlig utdata. I dessa fall kan register() användas för att registrera anpassade åtgärder eller typer med en parser och låta dig referera till typen med deras registrerade namn istället för deras anropsbara namn.

Metoden register() tar emot tre argument - ett registry_name, som anger det interna register där objektet ska lagras (t.ex. action, type), value, som är den nyckel under vilken objektet ska registreras, och object, den anropbara enhet som ska registreras.

Följande exempel visar hur man registrerar en anpassad typ med en parser:

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))
>>> parser.add_argument('--foo', type='hexadecimal integer')
_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> parser.parse_args(['--foo', '0xFA'])
Namespace(foo=250)
>>> parser.parse_args(['--foo', '1.2'])
usage: PROG [-h] [--foo FOO]
PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'

Undantag¶

exception argparse.ArgumentError¶

Ett fel vid skapande eller användning av ett argument (valfritt eller positionellt).

Strängvärdet för detta undantag är meddelandet, kompletterat med information om det argument som orsakade det.

exception argparse.ArgumentTypeError¶: Utlöses när något går fel när en kommandoradssträng konverteras till en typ.

Guider och handledning

argparse — Parser för kommandoradsalternativ, argument och underkommandon¶

ArgumentParser-objekt¶

prog¶

användning¶

beskrivning¶

epilog¶

föräldrar¶

formatter_klass¶

prefix_chars¶

frånfil_prefix_chars¶

argument_default¶

tillåt_abbrev¶

konflikt_hanterare¶

lägg till_hjälp¶

exit_on_error¶

föreslå_på_fel¶

färg¶

Metoden add_argument()¶

namn eller flaggor¶

åtgärd¶

nargs¶

konst¶

standard¶

typ¶

val¶

obligatoriskt¶

hjälp¶

metavar¶

dest¶

utfasad¶

Åtgärdsklasser¶

Metoden parse_args()¶

Syntax för optionsvärde¶

Ogiltiga argument¶

Argument som innehåller -¶

Argumentförkortningar (prefixmatchning)¶

Bortom sys.argv¶

Namespace-objektet¶

Andra verktyg¶

Underkommandon¶

FileType-objekt¶

Argumentgrupper¶

Ömsesidigt uteslutande¶

Standardvärden för parser¶

Hjälp med utskrift¶

Partiell parsning¶

Anpassa filparsning¶

Spännande metoder¶

Intermixad parsning¶

Registrering av anpassade typer eller åtgärder¶

Undantag¶

`argparse` — Parser för kommandoradsalternativ, argument och underkommandon¶

Argument som innehåller `-`¶

Bortom `sys.argv`¶