`argparse` — Parser für Kommandozeilenoptionen, Argumente und Unterbefehle¶

Hinzugefügt in Version 3.2.

Hinweis

Während argparse das standardmäßig empfohlene Modul der Standardbibliothek für die Implementierung grundlegender Kommandozeilenanwendungen ist, stellen Autoren mit anspruchsvolleren Anforderungen daran, wie ihre Kommandozeilenanwendungen funktionieren, möglicherweise fest, dass es nicht das erforderliche Maß an Kontrolle bietet. Konsultieren Sie Auswahl einer Argument-Parsing-Bibliothek für Alternativen, die in Betracht gezogen werden können, wenn argparse Verhaltensweisen nicht unterstützt, die die Anwendung erfordert (wie z. B. die vollständige Deaktivierung der Unterstützung für verschachtelte Optionen und positionelle Argumente oder die Annahme von Optionsparameterwerten, die mit - beginnen, auch wenn sie einer anderen definierten Option entsprechen).

Das Modul argparse erleichtert das Schreiben benutzerfreundlicher Kommandozeilenoberflächen. Das Programm definiert, welche Argumente es benötigt, und argparse ermittelt, wie diese aus sys.argv zu parsen sind. Das Modul argparse generiert außerdem automatisch Hilfe- und Nutzungsnachrichten. Das Modul gibt auch Fehler aus, wenn Benutzer ungültige Argumente übergeben.

Die Unterstützung des Moduls argparse für Kommandozeilenoberflächen basiert auf einer Instanz von argparse.ArgumentParser. Es ist ein Container für Argumentspezifikationen und enthält Optionen, die für den Parser als Ganzes gelten.

parser = argparse.ArgumentParser(
                    prog='ProgramName',
                    description='What the program does',
                    epilog='Text at the bottom of help')

Die Methode ArgumentParser.add_argument() fügt einzelne Argumentspezifikationen zum Parser hinzu. Sie unterstützt positionelle Argumente, Optionen, die Werte akzeptieren, und Ein-/Ausschalt-Flags.

parser.add_argument('filename')           # positional argument
parser.add_argument('-c', '--count')      # option that takes a value
parser.add_argument('-v', '--verbose',
                    action='store_true')  # on/off flag

Die Methode ArgumentParser.parse_args() führt den Parser aus und platziert die extrahierten Daten in einem argparse.Namespace-Objekt.

args = parser.parse_args()
print(args.filename, args.count, args.verbose)

Hinweis

Wenn Sie eine Anleitung zum Upgrade von optparse-Code auf argparse suchen, siehe Upgrade von Optparse-Code.

ArgumentParser-Objekte¶

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

Erstellt ein neues ArgumentParser-Objekt. Alle Parameter sollten als Schlüsselwortargumente übergeben werden. Jeder Parameter hat seine eigene detailliertere Beschreibung unten, aber kurz gesagt sind sie:

prog - Der Name des Programms (Standard: wird aus den Attributen des __main__-Moduls und sys.argv[0] generiert)
usage - Die Zeichenkette, die die Programmnutzung beschreibt (Standard: wird aus den dem Parser hinzugefügten Argumenten generiert)
description - Text, der vor der Argumenthilfe angezeigt wird (standardmäßig kein Text)
epilog - Text, der nach der Argumenthilfe angezeigt wird (standardmäßig kein Text)
parents - Eine Liste von ArgumentParser-Objekten, deren Argumente ebenfalls einbezogen werden sollen
formatter_class - Eine Klasse zur Anpassung der Hilfeausgabe
prefix_chars - Die Menge der Zeichen, die optionale Argumente präfixen (Standard: „-“)
fromfile_prefix_chars - Die Menge der Zeichen, die Dateien präfixen, aus denen zusätzliche Argumente gelesen werden sollen (Standard: None)
argument_default - Der globale Standardwert für Argumente (Standard: None)
conflict_handler - Die Strategie zur Auflösung widersprüchlicher Optionalitäten (normalerweise unnötig)
add_help - Fügt dem Parser eine Option -h/--help hinzu (Standard: True)
allow_abbrev - Erlaubt die Abkürzung langer Optionen, wenn die Abkürzung eindeutig ist (Standard: True)
exit_on_error - Bestimmt, ob ArgumentParser bei einem Fehler mit Fehlerinformationen beendet wird oder nicht. (Standard: True)
suggest_on_error - Aktiviert Vorschläge für falsch geschriebene Argumentauswahlen und Unterparser-Namen (Standard: False)
color - Erlaubt Farbausgabe (Standard: True)

Geändert in Version 3.5: Der Parameter allow_abbrev wurde hinzugefügt.

Geändert in Version 3.8: In früheren Versionen deaktivierte allow_abbrev auch die Gruppierung kurzer Flags wie -vv, um -v -v zu bedeuten.

Geändert in Version 3.9: Der Parameter exit_on_error wurde hinzugefügt.

Geändert in Version 3.14: Die Parameter suggest_on_error und color wurden hinzugefügt.

Die folgenden Abschnitte beschreiben, wie jeder dieser Parameter verwendet wird.

prog¶

Standardmäßig berechnet ArgumentParser den Namen des Programms zur Anzeige in Hilfenachrichten, abhängig davon, wie der Python-Interpreter ausgeführt wurde.

Der Basisname von sys.argv[0], wenn eine Datei als Argument übergeben wurde.
Der Name des Python-Interpreters gefolgt von sys.argv[0], wenn ein Verzeichnis oder eine Zip-Datei als Argument übergeben wurde.
Der Name des Python-Interpreters gefolgt von -m gefolgt vom Modul- oder Paketnamen, wenn die Option -m verwendet wurde.

Dieser Standardwert ist fast immer wünschenswert, da er dazu führt, dass die Hilfenachrichten mit der Zeichenkette übereinstimmen, die zum Aufrufen des Programms in der Befehlszeile verwendet wurde. Um dieses Standardverhalten zu ändern, kann jedoch ein anderer Wert über das Argument prog= an ArgumentParser übergeben werden.

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

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

Beachten Sie, dass der Programmname, ob aus sys.argv[0], aus den Attributen des Moduls __main__ oder aus dem Argument prog= ermittelt, über den Formatierungsbezeichner %(prog)s für Hilfenachrichten verfügbar ist.

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

Geändert in Version 3.14: Der Standardwert für prog spiegelt nun wider, wie __main__ tatsächlich ausgeführt wurde, anstatt immer os.path.basename(sys.argv[0]) zu sein.

usage¶

Standardmäßig berechnet ArgumentParser die Nutzungsnachricht aus den enthaltenen Argumenten. Die Standardnachricht kann mit dem Schlüsselwortargument usage= überschrieben werden.

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

Der Formatierungsbezeichner %(prog)s steht zur Verfügung, um den Programmnamen in Ihren Nutzungsnachrichten einzufügen.

Wenn für den Hauptparser eine benutzerdefinierte Nutzungsnachricht angegeben wird, sollten Sie auch in Erwägung ziehen, das Argument prog an add_subparsers() oder die Argumente prog und usage an add_parser() zu übergeben, um konsistente Kommandozeilenpräfixe und Nutzungsinformationen über Unterparser hinweg sicherzustellen.

description¶

Die meisten Aufrufe des Konstruktors ArgumentParser verwenden das Schlüsselwortargument description=. Dieses Argument liefert eine kurze Beschreibung, was das Programm tut und wie es funktioniert. In Hilfenachrichten wird die Beschreibung zwischen der Nutzungszeichenkette der Befehlszeile und den Hilfenachrichten für die verschiedenen Argumente angezeigt.

Standardmäßig wird die Beschreibung so umgebrochen, dass sie in den angegebenen Platz passt. Um dieses Verhalten zu ändern, siehe das Argument formatter_class.

epilog¶

Manche Programme möchten eine zusätzliche Beschreibung des Programms nach der Beschreibung der Argumente anzeigen. Solcher Text kann über das Argument epilog= an ArgumentParser angegeben werden.

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

Wie beim Argument description wird der Text epilog= standardmäßig umgebrochen, aber dieses Verhalten kann mit dem Argument formatter_class für ArgumentParser angepasst werden.

parents¶

Manchmal teilen sich mehrere Parser einen gemeinsamen Satz von Argumenten. Anstatt die Definitionen dieser Argumente zu wiederholen, kann ein einzelner Parser mit allen gemeinsamen Argumenten verwendet und über das Argument parents= an ArgumentParser übergeben werden. Das Argument parents= nimmt eine Liste von ArgumentParser-Objekten entgegen, sammelt alle positionellen und optionalen Aktionen von ihnen und fügt diese Aktionen dem zu konstruierenden ArgumentParser-Objekt hinzu.

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

Beachten Sie, dass die meisten Eltern-Parser add_help=False angeben. Andernfalls sieht der ArgumentParser zwei -h/--help-Optionen (eine im Elternteil und eine im Kind) und löst einen Fehler aus.

Hinweis

Sie müssen die Parser vollständig initialisieren, bevor Sie sie über parents= übergeben. Wenn Sie die Eltern-Parser nach dem Kind-Parser ändern, werden diese Änderungen nicht im Kind widergespiegelt.

formatter_class¶

ArgumentParser-Objekte ermöglichen die Anpassung der Hilfeformatierung durch Angabe einer alternativen Formatierungsklasse. Derzeit gibt es vier solche Klassen:

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

RawDescriptionHelpFormatter und RawTextHelpFormatter bieten mehr Kontrolle darüber, wie Textbeschreibungen angezeigt werden. Standardmäßig werden ArgumentParser-Objekte die Texte description und epilog in den Hilfenachrichten der Befehlszeile umbrechen.

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

Die Übergabe von RawDescriptionHelpFormatter als formatter_class= zeigt an, dass description und epilog bereits korrekt formatiert sind und nicht umgebrochen werden sollen.

>>> 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 behält den Whitespace für alle Arten von Hilfetexten bei, einschließlich der Argumentbeschreibungen. Mehrere neue Zeilen werden jedoch durch eine ersetzt. Wenn Sie mehrere Leerzeilen beibehalten möchten, fügen Sie Leerzeichen zwischen die neuen Zeilen ein.

ArgumentDefaultsHelpFormatter fügt automatisch Informationen über Standardwerte zu jeder Argumenthilfenachricht hinzu.

>>> 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 verwendet den Namen des type-Arguments für jedes Argument als Anzeigenamen für seine Werte (anstatt dest zu verwenden, wie es der reguläre Formatter tut).

>>> 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¶

Die meisten Kommandozeilenoptionen verwenden - als Präfix, z. B. -f/--foo. Parser, die andere oder zusätzliche Präfixzeichen unterstützen müssen, z. B. für Optionen wie +f oder /foo, können diese über das Argument prefix_chars= im Konstruktor von ArgumentParser angeben.

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

Das Argument prefix_chars= ist standardmäßig '-'. Wenn eine Zeichenmenge angegeben wird, die - nicht enthält, werden Optionen wie -f/--foo nicht zugelassen.

fromfile_prefix_chars¶

Manchmal, wenn man mit einer besonders langen Argumentliste zu tun hat, kann es sinnvoll sein, die Liste der Argumente in einer Datei aufzubewahren, anstatt sie in der Befehlszeile einzugeben. Wenn das Argument fromfile_prefix_chars= an den Konstruktor von ArgumentParser übergeben wird, werden Argumente, die mit einem der angegebenen Zeichen beginnen, als Dateien behandelt und durch die enthaltenen Argumente ersetzt. Zum Beispiel:

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

Argumente, die aus einer Datei gelesen werden, müssen standardmäßig eine pro Zeile sein (aber siehe auch convert_arg_line_to_args()) und werden so behandelt, als ob sie sich an derselben Stelle befänden wie das ursprüngliche Argument, das die Datei in der Befehlszeile referenziert. Im obigen Beispiel wird der Ausdruck ['-f', 'foo', '@args.txt'] als äquivalent zum Ausdruck ['-f', 'foo', '-f', 'bar'] betrachtet.

Hinweis

Leere Zeilen werden als leere Zeichenketten ('') behandelt, die als Werte, aber nicht als Argumente zulässig sind. Leere Zeilen, die als Argumente gelesen werden, führen zu einem Fehler „unbekannte Argumente“.

ArgumentParser verwendet die Dateisystemkodierung und Fehlerbehandlung zum Lesen der Datei, die die Argumente enthält.

Das Argument fromfile_prefix_chars= ist standardmäßig None, was bedeutet, dass Argumente niemals als Dateireferenzen behandelt werden.

Geändert in Version 3.12: ArgumentParser hat die Kodierung und Fehlerbehandlung zum Lesen von Argumentdateien von Standardwerten (z. B. locale.getpreferredencoding(False) und "strict") auf die Dateisystemkodierung und Fehlerbehandlung geändert. Argumentdateien sollten unter Windows in UTF-8 und nicht in ANSI-Codepages kodiert sein.

argument_default¶

Im Allgemeinen werden Argumentstandardwerte entweder durch Übergabe eines Standardwerts an add_argument() oder durch Aufrufen der Methode set_defaults() mit einem bestimmten Satz von Namen-Wert-Paaren angegeben. Manchmal kann es jedoch nützlich sein, einen einzigen Parser-weiten Standardwert für Argumente festzulegen. Dies kann durch Übergabe des Schlüsselwortarguments argument_default= an ArgumentParser erreicht werden. Um beispielsweise die Attributerstellung bei Aufrufen von parse_args() global zu unterdrücken, übergeben wir 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()

allow_abbrev¶

Normalerweise erkennt ArgumentParser bei der Übergabe einer Argumentliste an die Methode parse_args() **Abkürzungen** von langen Optionen.

Diese Funktion kann durch Setzen von allow_abbrev auf False deaktiviert werden.

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

Hinzugefügt in Version 3.5.

conflict_handler¶

ArgumentParser-Objekte erlauben nicht zwei Aktionen mit demselben Optionsstring. Standardmäßig lösen ArgumentParser-Objekte eine Ausnahme aus, wenn versucht wird, ein Argument mit einem Optionsstring zu erstellen, der bereits in Verwendung ist.

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

Manchmal (z. B. bei der Verwendung von parents) kann es nützlich sein, ältere Argumente mit demselben Optionsstring einfach zu überschreiben. Um dieses Verhalten zu erreichen, kann der Wert 'resolve' dem Argument conflict_handler= von ArgumentParser übergeben werden.

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

Beachten Sie, dass ArgumentParser-Objekte eine Aktion nur dann entfernen, wenn alle ihre Optionsstrings überschrieben werden. Im obigen Beispiel bleibt die alte Aktion -f/--foo als Aktion -f erhalten, da nur der Optionsstring --foo überschrieben wurde.

add_help¶

Standardmäßig fügen ArgumentParser-Objekte eine Option hinzu, die einfach die Hilfenachricht des Parsers anzeigt. Wenn -h oder --help in der Befehlszeile angegeben wird, wird die Hilfe des ArgumentParser gedruckt.

Gelegentlich kann es nützlich sein, das Hinzufügen dieser Hilfeoption zu deaktivieren. Dies kann durch Übergabe von False als Argument add_help= an ArgumentParser erreicht werden.

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

Die Hilfeoption ist typischerweise -h/--help. Die Ausnahme davon ist, wenn prefix_chars= angegeben ist und - nicht enthält, in welchem Fall -h und --help keine gültigen Optionen sind. In diesem Fall wird das erste Zeichen in prefix_chars verwendet, um die Hilfeoptionen zu präfixen.

>>> 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¶

Normalerweise druckt ArgumentParser bei der Übergabe einer ungültigen Argumentliste an die Methode parse_args() eine **Nachricht** an sys.stderr und beendet sich mit dem Statuscode 2.

Wenn der Benutzer Fehler manuell abfangen möchte, kann die Funktion durch Setzen von exit_on_error auf False aktiviert werden.

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

Hinzugefügt in Version 3.9.

suggest_on_error¶

Standardmäßig beendet sich ArgumentParser mit Fehlermeldungen und listet die zulässigen Argumentoptionen (falls angegeben) oder Subparser-Namen auf, wenn ein Benutzer eine ungültige Argumentauswahl oder einen ungültigen Subparser-Namen übergibt.

Wenn der Benutzer Vorschläge für falsch geschriebene Argumentoptionen und Subparser-Namen aktivieren möchte, kann dies durch Setzen von suggest_on_error auf True geschehen. Beachten Sie, dass dies nur für Argumente gilt, wenn die angegebenen Optionen Zeichenketten sind.

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

Wenn Sie Code schreiben, der mit älteren Python-Versionen kompatibel sein muss und suggest_on_error opportunistisch nutzen möchten, wenn es verfügbar ist, können Sie es als Attribut nach der Initialisierung des Parsers setzen, anstatt das Schlüsselwortargument zu verwenden.

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

Hinzugefügt in Version 3.14.

color¶

Standardmäßig wird die Hilfenachricht farblich mit ANSI-Escape-Sequenzen ausgegeben. Wenn Sie reine Text-Hilfen wünschen, können Sie dies in Ihrer lokalen Umgebung oder im Argumentparser selbst deaktivieren, indem Sie color auf False setzen.

>>> 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'])

Hinzugefügt in Version 3.14.

Die Methode add_argument()¶

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

Definiert, wie ein einzelnes Kommandozeilenargument geparst werden soll. Jeder Parameter hat unten eine detailliertere Beschreibung, aber kurz gesagt sind es:

name oder flags - Entweder ein Name oder eine Liste von Optionszeichenfolgen, z. B. 'foo' oder '-f', '--foo'.
action - Der grundlegende Aktionstyp, der ausgeführt wird, wenn dieses Argument an der Kommandozeile angetroffen wird.
nargs - Die Anzahl der zu verbrauchenden Kommandozeilenargumente.
const - Ein konstanter Wert, der von einigen action und nargs-Auswahlen benötigt wird.
default - Der Wert, der erzeugt wird, wenn das Argument nicht in der Kommandozeile und nicht im Namespace-Objekt vorhanden ist.
type - Der Typ, in den das Kommandozeilenargument konvertiert werden soll.
choices - Eine Sequenz der zulässigen Werte für das Argument.
required - Ob die Kommandozeilenoption weggelassen werden darf (nur für optionale).
help - Eine kurze Beschreibung, was das Argument tut.
metavar - Ein Name für das Argument in Nutzungsmeldungen.
dest - Der Name des Attributs, das dem von parse_args() zurückgegebenen Objekt hinzugefügt werden soll.
deprecated - Ob die Verwendung des Arguments als veraltet gilt.

Die folgenden Abschnitte beschreiben, wie jeder dieser Parameter verwendet wird.

name or flags¶

Die Methode add_argument() muss wissen, ob ein optionales Argument wie -f oder --foo oder ein positionelles Argument wie eine Liste von Dateinamen erwartet wird. Die ersten Argumente, die an add_argument() übergeben werden, müssen daher entweder eine Reihe von Flags oder ein einfacher Argumentname sein.

Zum Beispiel könnte ein optionales Argument wie folgt erstellt werden:

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

während ein positionelles Argument wie folgt erstellt werden könnte:

>>> parser.add_argument('bar')

Wenn parse_args() aufgerufen wird, werden optionale Argumente durch das Präfix - identifiziert, und die verbleibenden Argumente werden als positionell angenommen.

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

Standardmäßig kümmert sich argparse automatisch um die interne Benennung und die Anzeige-Namen von Argumenten, was den Prozess vereinfacht, ohne dass zusätzliche Konfiguration erforderlich ist. Daher müssen Sie die Parameter dest und metavar nicht angeben. Der Parameter dest wird standardmäßig auf den Argumentnamen gesetzt, wobei Unterstriche _ Bindestriche - ersetzen. Der Parameter metavar wird standardmäßig auf den großgeschriebenen Namen gesetzt. Zum Beispiel:

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

action¶

ArgumentParser-Objekte assoziieren Kommandozeilenargumente mit Aktionen. Diese Aktionen können so ziemlich alles mit den zugehörigen Kommandozeilenargumenten tun, obwohl die meisten Aktionen einfach ein Attribut zum von parse_args() zurückgegebenen Objekt hinzufügen. Das Schlüsselwortargument action gibt an, wie die Kommandozeilenargumente behandelt werden sollen. Die bereitgestellten Aktionen sind:

'store' - Dies speichert einfach den Wert des Arguments. Dies ist die Standardaktion.
'store_const' - Dies speichert den Wert, der im Schlüsselwortargument const angegeben ist; Beachten Sie, dass das Schlüsselwortargument const standardmäßig None ist. Die Aktion 'store_const' wird am häufigsten mit optionalen Argumenten verwendet, die eine Art Flag angeben. Zum Beispiel:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
```

'store_true' und 'store_false' - Dies sind Sonderfälle von 'store_const', die zum Speichern der Werte True bzw. False verwendet werden. Zusätzlich erstellen sie Standardwerte von False bzw. 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' - Dies hängt jeden Argumentwert an eine Liste an. Dies ist nützlich, um zuzulassen, dass eine Option mehrmals angegeben wird. Wenn der Standardwert eine nicht leere Liste ist, beginnt der geparste Wert mit den Elementen der Standardliste, und alle Werte von der Kommandozeile werden nach diesen Standardwerten angehängt. Beispielanwendung:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append', default=['0'])
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['0', '1', '2'])
```
'append_const' - Dies speichert eine Liste und hängt den im Schlüsselwortargument const angegebenen Wert an die Liste an; Beachten Sie, dass das Schlüsselwortargument const standardmäßig None ist. Die Aktion 'append_const' ist typischerweise nützlich, wenn mehrere Argumente Konstanten in dieselbe Liste speichern müssen. Zum Beispiel:
```
>>> 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' - Dies speichert eine Liste und hängt jedes Element der mehrwertigen Argumentliste daran an. Die Aktion 'extend' wird typischerweise mit dem Schlüsselwortargument nargs mit dem Wert '+' oder '*' verwendet. Beachten Sie, dass, wenn nargs None (Standard) oder '?' ist, jeder Buchstabe des Argumentstrings an die Liste angehängt wird. Beispielanwendung:
```
>>> 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'])
```
Hinzugefügt in Version 3.8.
'count' - Dies zählt, wie oft ein Schlüsselwortargument vorkommt. Dies ist beispielsweise nützlich für die Erhöhung von Ausführlichkeitsgraden.
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
```
Beachten Sie, dass der *Standardwert* None ist, es sei denn, er wird explizit auf *0* gesetzt.
'help' - Dies gibt eine vollständige Hilfenachricht für alle Optionen im aktuellen Parser aus und beendet sich dann. Standardmäßig wird dem Parser automatisch eine Hilfeaktion hinzugefügt. Einzelheiten zur Erstellung der Ausgabe finden Sie unter ArgumentParser.

'version' - Dies erwartet ein Schlüsselwortargument version= im add_argument()-Aufruf und gibt beim Aufruf Versionsinformationen aus und beendet sich.

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

Sie können auch eine beliebige Aktion angeben, indem Sie eine Unterklasse von Action (z. B. BooleanOptionalAction) oder ein anderes Objekt, das dieselbe Schnittstelle implementiert, übergeben. Nur Aktionen, die Kommandozeilenargumente verbrauchen (z. B. 'store', 'append', 'extend' oder benutzerdefinierte Aktionen mit nicht-null nargs), können mit positionellen Argumenten verwendet werden.

Der empfohlene Weg, eine benutzerdefinierte Aktion zu erstellen, ist die Erweiterung von Action, wobei die Methode __call__() und optional die Methoden __init__() und format_usage() überschrieben werden. Sie können benutzerdefinierte Aktionen auch mit der Methode register() registrieren und sie unter ihrem registrierten Namen referenzieren.

Ein Beispiel für eine benutzerdefinierte Aktion

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

Weitere Details finden Sie unter Action.

nargs¶

ArgumentParser-Objekte assoziieren normalerweise ein einzelnes Kommandozeilenargument mit einer einzelnen auszuführenden Aktion. Das Schlüsselwortargument nargs assoziiert eine unterschiedliche Anzahl von Kommandozeilenargumenten mit einer einzelnen Aktion. Siehe auch Spezifizieren von mehrdeutigen Argumenten. Die unterstützten Werte sind:

N (eine Ganzzahl). N Argumente von der Kommandozeile werden in einer Liste gesammelt. Zum Beispiel:
```
>>> 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'])
```
Beachten Sie, dass nargs=1 eine Liste mit einem Element erzeugt. Dies unterscheidet sich vom Standard, bei dem das Element allein erzeugt wird.

'?'. Ein Argument wird, wenn möglich, von der Kommandozeile verbraucht und als einzelnes Element ausgegeben. Wenn kein Kommandozeilenargument vorhanden ist, wird der Wert von default verwendet. Beachten Sie, dass für optionale Argumente ein zusätzlicher Fall besteht – die Optionszeichenfolge ist vorhanden, aber nicht gefolgt von einem Kommandozeilenargument. In diesem Fall wird der Wert von const verwendet. Einige Beispiele zur Veranschaulichung:

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

Eine der häufigsten Anwendungen von nargs='?' ist die Zulassung optionaler Eingabe- und Ausgabedateien.

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

'*'. Alle vorhandenen Kommandozeilenargumente werden in einer Liste gesammelt. Beachten Sie, dass es im Allgemeinen wenig Sinn macht, mehr als ein positionelles Argument mit nargs='*' zu haben, aber mehrere optionale Argumente mit nargs='*' sind möglich. Zum Beispiel:

>>> 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'])

'+'. Genau wie bei '*' werden alle vorhandenen Kommandozeilenargumente in einer Liste gesammelt. Zusätzlich wird eine Fehlermeldung generiert, wenn mindestens ein Kommandozeilenargument nicht vorhanden war. Zum Beispiel:

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

Wenn das Schlüsselwortargument nargs nicht angegeben ist, wird die Anzahl der verbrauchten Argumente durch die action bestimmt. Im Allgemeinen bedeutet dies, dass ein einzelnes Kommandozeilenargument verbraucht wird und ein einzelnes Element (keine Liste) ausgegeben wird. Aktionen, die keine Kommandozeilenargumente verbrauchen (z. B. 'store_const'), setzen nargs=0.

const¶

Das Argument const von add_argument() wird verwendet, um konstante Werte zu halten, die nicht von der Kommandozeile gelesen werden, aber für die verschiedenen ArgumentParser-Aktionen benötigt werden. Die zwei häufigsten Verwendungen sind:

Wenn add_argument() mit action='store_const' oder action='append_const' aufgerufen wird. Diese Aktionen fügen den const-Wert einem der Attribute des von parse_args() zurückgegebenen Objekte hinzu. Beispiele finden Sie in der Beschreibung der action. Wenn const nicht an add_argument() übergeben wird, erhält es einen Standardwert von None.
Wenn add_argument() mit Optionszeichenfolgen (wie -f oder --foo) und nargs='?' aufgerufen wird. Dies erstellt ein optionales Argument, das von null oder einem Kommandozeilenargument gefolgt werden kann. Beim Parsen der Kommandozeile, wenn die Optionszeichenfolge ohne ein nachfolgendes Kommandozeilenargument angetroffen wird, wird der Wert von const verwendet. Beispiele finden Sie in der Beschreibung von nargs.

Geändert in Version 3.11: const=None standardmäßig, auch wenn action='append_const' oder action='store_const'.

default¶

Alle optionalen und einige positionelle Argumente können an der Kommandozeile weggelassen werden. Das Schlüsselwortargument default von add_argument(), dessen Wert standardmäßig None ist, gibt an, welcher Wert verwendet werden soll, wenn das Kommandozeilenargument nicht vorhanden ist. Für optionale Argumente wird der default-Wert verwendet, wenn die Optionszeichenfolge nicht an der Kommandozeile vorhanden war.

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

Wenn der Ziel-Namespace bereits ein gesetztes Attribut hat, überschreibt die Aktion *default* dieses nicht.

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

Wenn der default-Wert eine Zeichenkette ist, parst der Parser den Wert, als wäre er ein Kommandozeilenargument. Insbesondere wendet der Parser jegliche type-Konvertierung an, falls vorhanden, bevor das Attribut auf den von Namespace zurückgegebenen Rückgabewert gesetzt wird. Andernfalls verwendet der Parser den Wert unverändert.

>>> 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 positionelle Argumente mit nargs gleich ? oder * wird der default-Wert verwendet, wenn kein Kommandozeilenargument vorhanden war.

>>> 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 *erforderliche* Argumente (required=True) wird der default-Wert ignoriert. Dies gilt beispielsweise für positionelle Argumente mit nargs-Werten außer ? oder * oder optionale Argumente, die als required=True markiert sind.

Das Angeben von default=argparse.SUPPRESS führt dazu, dass kein Attribut hinzugefügt wird, wenn das Kommandozeilenargument nicht vorhanden war.

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

type¶

Standardmäßig liest der Parser Kommandozeilenargumente als einfache Zeichenketten ein. Oft sollte die Kommandozeilenzeichenkette stattdessen als ein anderer Typ interpretiert werden, wie z. B. ein float oder int. Der type-Schlüssel für add_argument() ermöglicht die Durchführung aller erforderlichen Typenprüfungen und Typkonvertierungen.

Wenn das type-Schlüsselwort zusammen mit dem default-Schlüsselwort verwendet wird, wird der Typkonverter nur angewendet, wenn der Standardwert eine Zeichenkette ist.

Das Argument für type kann ein aufrufbares Objekt sein, das eine einzelne Zeichenkette akzeptiert, oder der Name eines registrierten Typs (siehe register()). Wenn die Funktion ArgumentTypeError, TypeError oder ValueError auslöst, wird die Ausnahme abgefangen und eine gut formatierte Fehlermeldung angezeigt. Andere Ausnahmetypen werden nicht behandelt.

Gängige integrierte Typen und Funktionen können als Typkonverter verwendet werden.

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)

Auch benutzerdefinierte Funktionen können verwendet werden.

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

Die Funktion bool() wird nicht als Typkonverter empfohlen. Sie konvertiert nur leere Zeichenketten in False und nicht leere Zeichenketten in True. Dies ist normalerweise nicht das, was gewünscht wird.

Im Allgemeinen ist das type-Schlüsselwort eine Bequemlichkeit, die nur für einfache Konvertierungen verwendet werden sollte, die nur eine der drei unterstützten Ausnahmen auslösen können. Alles mit interessanterer Fehlerbehandlung oder Ressourcenverwaltung sollte nachträglich nach dem Parsen der Argumente erfolgen.

JSON- oder YAML-Konvertierungen haben beispielsweise komplexe Fehlerfälle, die eine bessere Berichterstattung erfordern, als das type-Schlüsselwort bieten kann. Eine JSONDecodeError würde nicht gut formatiert sein und eine FileNotFoundError-Ausnahme würde gar nicht behandelt.

Selbst FileType hat seine Grenzen für die Verwendung mit dem type-Schlüsselwort. Wenn ein Argument FileType verwendet und dann ein nachfolgendes Argument fehlschlägt, wird ein Fehler gemeldet, aber die Datei wird nicht automatisch geschlossen. In diesem Fall wäre es besser, zu warten, bis der Parser ausgeführt wurde, und dann die with-Anweisung zur Verwaltung der Dateien zu verwenden.

Für Typprüfer, die einfach gegen eine feste Menge von Werten prüfen, sollten Sie stattdessen das Schlüsselwort choices in Betracht ziehen.

choices¶

Einige Kommandozeilenargumente sollten aus einer eingeschränkten Auswahl von Werten ausgewählt werden. Dies kann durch Übergabe einer Sequenz als Schlüsselwortargument *choices* an add_argument() gehandhabt werden. Wenn die Kommandozeile geparst wird, werden die Argumentwerte geprüft, und eine Fehlermeldung wird angezeigt, wenn das Argument nicht einer der akzeptablen Werte war.

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

Jede Sequenz kann als *choices*-Wert übergeben werden, sodass list-Objekte, tuple-Objekte und benutzerdefinierte Sequenzen alle unterstützt werden.

Die Verwendung von enum.Enum wird nicht empfohlen, da es schwierig ist, sein Erscheinungsbild in Nutzungs-, Hilfe- und Fehlermeldungen zu steuern.

Beachten Sie, dass *choices* nach allen type-Konvertierungen geprüft werden. Daher sollten Objekte in *choices* mit dem angegebenen type übereinstimmen. Dies kann dazu führen, dass *choices* in Nutzungs-, Hilfe- oder Fehlermeldungen ungewohnt erscheinen.

Um *choices* benutzerfreundlich zu halten, erwägen Sie eine benutzerdefinierte Typ-Wrapper-Klasse, die Werte konvertiert und formatiert, oder lassen Sie type weg und behandeln Sie die Konvertierung in Ihrem Anwendungscode.

Formatierte Auswahlmöglichkeiten überschreiben den Standard-*metavar*, der normalerweise aus *dest* abgeleitet wird. Dies ist in der Regel das, was Sie wollen, da der Benutzer niemals den Parameter *dest* sieht. Wenn diese Anzeige nicht erwünscht ist (vielleicht weil es viele Auswahlmöglichkeiten gibt), geben Sie einfach einen expliziten metavar an.

required¶

Im Allgemeinen geht das Modul argparse davon aus, dass Flags wie -f und --bar *optionale* Argumente angeben, die auf der Befehlszeile immer weggelassen werden können. Um eine Option zu einer *erforderlichen* Option zu machen, kann True für das Schlüsselwortargument required= bei add_argument() angegeben werden.

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

Wie das Beispiel zeigt, wird parse_args() einen Fehler melden, wenn eine als required gekennzeichnete Option nicht auf der Befehlszeile vorhanden ist.

Hinweis

Erforderliche Optionen gelten allgemein als schlechter Stil, da Benutzer *Optionen* als *optional* erwarten und sie daher nach Möglichkeit vermieden werden sollten.

help¶

Der Wert von help ist ein String, der eine kurze Beschreibung des Arguments enthält. Wenn ein Benutzer Hilfe anfordert (normalerweise durch die Verwendung von -h oder --help auf der Befehlszeile), werden diese help-Beschreibungen für jedes Argument angezeigt.

Die help-Strings können verschiedene Formatierungspezifizierer enthalten, um Wiederholungen von Dingen wie dem Programmnamen oder dem Standardwert des Arguments zu vermeiden. Die verfügbaren Spezifizierer umfassen den Programmnamen %(prog)s und die meisten Schlüsselwortargumente von add_argument(), z. B. %(default)s, %(type)s usw.

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

Da der Hilfetext %-Formatierungen unterstützt, müssen Sie ein wörtliches % als %% maskieren, wenn es im Hilfetext erscheinen soll.

argparse unterstützt das Unterdrücken des Hilfseintrags für bestimmte Optionen, indem der help-Wert auf argparse.SUPPRESS gesetzt wird.

>>> 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¶

Wenn ArgumentParser Hilfemeldungen generiert, benötigt es eine Möglichkeit, sich auf jedes erwartete Argument zu beziehen. Standardmäßig verwenden ArgumentParser-Objekte den dest-Wert als „Namen“ jedes Objekts. Standardmäßig wird für positionelle Argumentaktionen der dest-Wert direkt verwendet, und für optionale Argumentaktionen wird der dest-Wert großgeschrieben. Ein einzelnes positionelles Argument mit dest='bar' wird also als bar referenziert. Ein einzelnes optionales Argument --foo, dem ein einzelnes Befehlszeilenargument folgen soll, wird als FOO referenziert. Ein Beispiel

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

Ein alternativer Name kann mit metavar angegeben werden.

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

Beachten Sie, dass metavar nur den *angezeigten* Namen ändert – der Name des Attributs im parse_args()-Objekt wird weiterhin durch den dest-Wert bestimmt.

Unterschiedliche Werte von nargs können dazu führen, dass der Metavar mehrmals verwendet wird. Die Angabe eines Tupels für metavar gibt eine andere Anzeige für jedes der Argumente an.

>>> 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¶

Die meisten ArgumentParser-Aktionen fügen dem von parse_args() zurückgegebenen Objekt einen Wert als Attribut hinzu. Der Name dieses Attributs wird durch das Schlüsselwortargument dest von add_argument() bestimmt. Für positionelle Argumentaktionen wird dest normalerweise als erstes Argument an add_argument() übergeben.

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

Für optionale Argumentaktionen wird der Wert von dest normalerweise aus den Optionsstrings abgeleitet. ArgumentParser generiert den Wert von dest, indem es den ersten langen Optionsstring nimmt und den anfänglichen ---String entfernt. Wenn keine langen Optionsstrings angegeben wurden, wird dest aus dem ersten kurzen Optionsstring abgeleitet, indem das anfängliche --Zeichen entfernt wird. Interne --Zeichen werden in _-Zeichen umgewandelt, um sicherzustellen, dass der String ein gültiger Attributname ist. Die folgenden Beispiele veranschaulichen dieses Verhalten.

>>> 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 ermöglicht die Angabe eines benutzerdefinierten Attributnamens.

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

deprecated¶

Im Laufe der Lebensdauer eines Projekts müssen möglicherweise einige Argumente aus der Befehlszeile entfernt werden. Bevor Sie sie entfernen, sollten Sie Ihre Benutzer darüber informieren, dass die Argumente veraltet sind und entfernt werden. Das Schlüsselwortargument deprecated von add_argument(), das standardmäßig auf False gesetzt ist, gibt an, ob das Argument veraltet ist und in Zukunft entfernt wird. Für Argumente wird, wenn deprecated auf True gesetzt ist, eine Warnung an sys.stderr ausgegeben, wenn das Argument verwendet wird.

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

Hinzugefügt in Version 3.13.

Aktionsklassen¶

Action-Klassen implementieren die Action API, einen aufrufbaren Aufruf, der einen aufrufbaren Aufruf zurückgibt, der Argumente von der Befehlszeile verarbeitet. Jedes Objekt, das dieser API folgt, kann als action-Parameter an add_argument() übergeben werden.

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

Action-Objekte werden von einem ArgumentParser verwendet, um die Informationen darzustellen, die zum Parsen eines einzelnen Arguments aus einem oder mehreren Strings von der Befehlszeile benötigt werden. Die Action-Klasse muss die beiden positionsgebundenen Argumente sowie alle an ArgumentParser.add_argument() übergebenen Schlüsselwortargumente außer der action selbst akzeptieren.

Instanzen von Action (oder Rückgabewerte von aufrufbaren Funktionen für den action-Parameter) sollten Attribute wie dest, option_strings, default, type, required, help usw. definiert haben. Der einfachste Weg, diese Attribute zu definieren, ist der Aufruf von Action.__init__().

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

Action-Instanzen müssen aufrufbar sein, daher müssen Unterklassen die Methode __call__() überschreiben, die vier Parameter akzeptieren sollte.

parser - Das ArgumentParser-Objekt, das diese Aktion enthält.
namespace - Das Namespace-Objekt, das von parse_args() zurückgegeben wird. Die meisten Aktionen fügen diesem Objekt mit setattr() ein Attribut hinzu.
values - Die zugehörigen Befehlszeilenargumente, mit angewandten Typkonvertierungen. Typkonvertierungen werden mit dem Schlüsselwortargument type von add_argument() angegeben.
option_string - Der Optionsstring, der verwendet wurde, um diese Aktion aufzurufen. Das Argument option_string ist optional und fehlt, wenn die Aktion einem positionellen Argument zugeordnet ist.

Die Methode __call__() kann beliebige Aktionen ausführen, setzt aber typischerweise Attribute im namespace basierend auf dest und values.

format_usage()¶: Action-Unterklassen können eine Methode format_usage() definieren, die kein Argument annimmt und einen String zurückgibt, der beim Drucken der Programmnutzung verwendet wird. Wenn eine solche Methode nicht bereitgestellt wird, wird eine sinnvolle Standardeinstellung verwendet.

class argparse.BooleanOptionalAction¶

Eine Unterklasse von Action zur Behandlung von booleschen Flags mit positiven und negativen Optionen. Das Hinzufügen eines einzelnen Arguments wie --foo erstellt automatisch sowohl --foo als auch --no-foo Optionen und speichert True bzw. False.

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

Hinzugefügt in Version 3.9.

Die Methode parse_args()¶

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

Konvertiert Argument-Strings in Objekte und weist sie als Attribute des Namespaces zu. Gibt den gefüllten Namespace zurück.

Vorherige Aufrufe von add_argument() bestimmen genau, welche Objekte erstellt und wie sie zugewiesen werden. Einzelheiten finden Sie in der Dokumentation zu add_argument().

args - Liste von zu parsierenden Strings. Standardmäßig wird dies aus sys.argv übernommen.
namespace - Ein Objekt, das die Attribute aufnehmen soll. Standardmäßig ist dies ein neues leeres Namespace-Objekt.

Optionswert-Syntax¶

Die Methode parse_args() unterstützt mehrere Möglichkeiten, den Wert einer Option anzugeben (falls sie einen benötigt). Im einfachsten Fall werden die Option und ihr Wert als zwei separate Argumente übergeben.

>>> 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 lange Optionen (Optionen mit Namen, die länger als ein einzelnes Zeichen sind) können Option und Wert auch als einzelnes Befehlszeilenargument übergeben werden, wobei = zur Trennung verwendet wird.

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

Für kurze Optionen (Optionen mit nur einem Zeichen) können die Option und ihr Wert zusammengefügt werden.

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

Mehrere kurze Optionen können zusammengefügt werden, wobei nur ein einziger --Präfix verwendet wird, solange nur die letzte Option (oder keine von ihnen) einen Wert benötigt.

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

Ungültige Argumente¶

Beim Parsen der Befehlszeile prüft parse_args() auf eine Vielzahl von Fehlern, darunter mehrdeutige Optionen, ungültige Typen, ungültige Optionen, falsche Anzahl von positionsgebundenen Argumenten usw. Wenn ein solcher Fehler auftritt, wird das Programm beendet und der Fehler zusammen mit einer Nutzungsmeldung ausgegeben.

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

Argumente, die `-` enthalten¶

Die Methode parse_args() versucht, Fehler zu melden, wann immer der Benutzer offensichtlich einen Fehler gemacht hat, aber einige Situationen sind von Natur aus mehrdeutig. Zum Beispiel könnte das Befehlszeilenargument -1 entweder ein Versuch sein, eine Option anzugeben, oder ein Versuch, ein positionsgebundenes Argument bereitzustellen. Die Methode parse_args() ist hier vorsichtig: Positionelle Argumente dürfen nur mit - beginnen, wenn sie wie negative Zahlen aussehen und keine Optionen im Parser vorhanden sind, die wie negative Zahlen aussehen.

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

Wenn Sie positionsgebundene Argumente haben, die mit - beginnen müssen und nicht wie negative Zahlen aussehen, können Sie das Pseudo-Argument '--' einfügen, das parse_args() mitteilt, dass alles danach ein positionsgebundenes Argument ist.

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

Siehe auch das argparse-Howto zu mehrdeutigen Argumenten für weitere Details.

Argument-Abkürzungen (Präfix-Abgleich)¶

Die Methode parse_args() erlaubt standardmäßig, dass lange Optionen zu einem Präfix abgekürzt werden können, wenn die Abkürzung eindeutig ist (der Präfix stimmt mit einer eindeutigen Option überein).

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

Für Argumente, die mehr als eine Option ergeben könnten, wird ein Fehler ausgegeben. Diese Funktion kann durch Setzen von allow_abbrev auf False deaktiviert werden.

Über `sys.argv` hinaus¶

Manchmal kann es nützlich sein, dass ein ArgumentParser andere Argumente als die von sys.argv parst. Dies kann durch Übergabe einer Liste von Strings an parse_args() erreicht werden. Dies ist nützlich für Tests in der interaktiven Eingabeaufforderung.

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

Das Namespace-Objekt¶

class argparse.Namespace¶

Einfache Klasse, die standardmäßig von parse_args() verwendet wird, um ein Objekt zu erstellen, das Attribute speichert und es zurückzugeben.

Diese Klasse ist bewusst einfach gehalten, nur eine Unterklasse von object mit einer lesbaren String-Darstellung. Wenn Sie eine Wörterbuch-ähnliche Ansicht der Attribute bevorzugen, können Sie die Standard-Python-Idiomatik vars() verwenden.

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

Es kann auch nützlich sein, dass ein ArgumentParser Attribute einem bereits vorhandenen Objekt zuweist und nicht einem neuen Namespace-Objekt. Dies kann durch Angabe des Schlüsselwortarguments namespace= erreicht werden.

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

Andere Hilfsprogramme¶

Unterbefehle¶

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

Viele Programme teilen ihre Funktionalität in eine Reihe von Unterbefehlen auf, z. B. kann das Programm svn Unterbefehle wie svn checkout, svn update und svn commit aufrufen. Das Aufteilen der Funktionalität auf diese Weise kann eine besonders gute Idee sein, wenn ein Programm mehrere verschiedene Funktionen ausführt, die unterschiedliche Arten von Befehlszeilenargumenten erfordern. ArgumentParser unterstützt die Erstellung solcher Unterbefehle mit der Methode add_subparsers(). Die Methode add_subparsers() wird normalerweise ohne Argumente aufgerufen und gibt ein spezielles Aktionsobjekt zurück. Dieses Objekt hat eine einzige Methode, add_parser(), die einen Befehlsnamen und beliebige ArgumentParser-Konstruktorargumente annimmt und ein ArgumentParser-Objekt zurückgibt, das wie gewohnt modifiziert werden kann.

Beschreibung der Parameter

title - Titel für die Unterparser-Gruppe in der Hilfeausgabe; standardmäßig „subcommands“, wenn eine Beschreibung vorhanden ist, andernfalls wird der Titel für positionelle Argumente verwendet.
description - Beschreibung für die Unterparser-Gruppe in der Hilfeausgabe, standardmäßig None.
prog - Nutzungsinformationen, die mit der Hilfe für Unterbefehle angezeigt werden, standardmäßig der Programmname und alle positionsgebundenen Argumente vor dem Unterparser-Argument.
parser_class - Klasse, die zur Erstellung von Unterparser-Instanzen verwendet wird, standardmäßig die Klasse des aktuellen Parsers (z. B. ArgumentParser).
action - der grundlegende Aktionstyp, der ausgeführt wird, wenn dieses Argument auf der Befehlszeile angetroffen wird.
dest - Name des Attributs, unter dem der Unterbefehlsname gespeichert wird; standardmäßig None und es wird kein Wert gespeichert.
required - Ob ein Unterbefehl angegeben werden muss oder nicht, standardmäßig False (hinzugefügt in 3.7).
help - Hilfe für die Unterparser-Gruppe in der Hilfeausgabe, standardmäßig None.
metavar - String, der die verfügbaren Unterbefehle in der Hilfe darstellt; standardmäßig ist dies None und es werden Unterbefehle in der Form {cmd1, cmd2, ..} dargestellt.

Einige Beispielnutzung

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

Beachten Sie, dass das von parse_args() zurückgegebene Objekt nur Attribute für den Hauptparser und den durch die Befehlszeile ausgewählten Unterparser enthält (und nicht für andere Unterparser). So sind im obigen Beispiel, wenn der Befehl a angegeben wird, nur die Attribute foo und bar vorhanden, und wenn der Befehl b angegeben wird, sind nur die Attribute foo und baz vorhanden.

Ähnlich wird, wenn eine Hilfemeldung von einem Subparser angefordert wird, nur die Hilfe für diesen speziellen Parser ausgegeben. Die Hilfemeldung enthält keine Meldungen des Parent-Parsers oder von Geschwister-Parsern. (Eine Hilfemeldung für jeden Subparser-Befehl kann jedoch durch Angabe des Arguments help= an add_parser() wie oben angegeben werden.)

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

Die Methode add_subparsers() unterstützt auch die Schlüsselwortargumente title und description. Wenn eines davon vorhanden ist, werden die Befehle des Subparsers in ihrer eigenen Gruppe in der Hilfeausgabe angezeigt. Zum Beispiel

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

Darüber hinaus unterstützt add_parser() ein zusätzliches Argument aliases, das es mehreren Zeichenketten ermöglicht, auf denselben Subparser zu verweisen. Dieses Beispiel aliasert wie svn co als Kurzform 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() unterstützt auch ein zusätzliches Argument deprecated, das es ermöglicht, den Subparser als veraltet zu kennzeichnen.

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

Hinzugefügt in Version 3.13.

Eine besonders effektive Methode zur Behandlung von Unterbefehlen ist die Kombination der Verwendung der Methode add_subparsers() mit Aufrufen von set_defaults(), damit jeder Subparser weiß, welche Python-Funktion er ausführen soll. Zum Beispiel

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

Auf diese Weise können Sie parse_args() die Aufgabe der Aufrufung der entsprechenden Funktion nach Abschluss der Argumentenanalyse übernehmen lassen. Das Verknüpfen von Funktionen mit Aktionen auf diese Weise ist in der Regel der einfachste Weg, um die unterschiedlichen Aktionen für jeden Ihrer Subparser zu behandeln. Wenn es jedoch notwendig ist, den Namen des aufgerufenen Subparsers zu überprüfen, funktioniert das Schlüsselwortargument dest für den Aufruf von add_subparsers()

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

Geändert in Version 3.7: Neuer schlüsselwort-only Parameter required.

Geändert in Version 3.14: Der prog eines Subparsers wird nicht mehr von einer benutzerdefinierten Nutzungsnachricht im Hauptparser beeinflusst.

FileType-Objekte¶

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

Die Fabrik FileType erstellt Objekte, die dem Argument type von ArgumentParser.add_argument() übergeben werden können. Argumente, die FileType-Objekte als Typ haben, öffnen Befehlszeilenargumente als Dateien mit den angeforderten Modi, Puffergrößen, Kodierungen und Fehlerbehandlungen (siehe die Funktion open() für weitere Details)

>>> 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-Objekte verstehen das Pseudo-Argument '-' und wandeln dieses automatisch in sys.stdin für lesbare FileType-Objekte und sys.stdout für schreibbare FileType-Objekte um

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

Hinweis

Wenn ein Argument FileType verwendet und dann ein nachfolgendes Argument fehlschlägt, wird ein Fehler gemeldet, aber die Datei wird nicht automatisch geschlossen. Dies kann auch Ausgabedateien überschreiben. In diesem Fall wäre es besser, bis nach dem Ausführen des Parsers zu warten und dann die with-Anweisung zur Verwaltung der Dateien zu verwenden.

Geändert in Version 3.4: Die Parameter encodings und errors wurden hinzugefügt.

Veraltet seit Version 3.14.

Argumentgruppen¶

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

Standardmäßig gruppiert ArgumentParser Befehlszeilenargumente in „positionelle Argumente“ und „Optionen“, wenn Hilfemeldungen angezeigt werden. Wenn es eine bessere konzeptionelle Gruppierung von Argumenten als diese Standardeinstellung gibt, können entsprechende Gruppen mit der Methode add_argument_group() erstellt werden

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

Die Methode add_argument_group() gibt ein Argumentgruppenobjekt zurück, das eine add_argument()-Methode hat, genau wie ein regulärer ArgumentParser. Wenn ein Argument zur Gruppe hinzugefügt wird, behandelt der Parser es wie ein normales Argument, zeigt es aber in einer separaten Gruppe für Hilfemeldungen an. Die Methode add_argument_group() akzeptiert die Argumente title und description, die zur Anpassung dieser Anzeige verwendet werden können

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

Die optionalen, nur-Schlüsselwort-Parameter argument_default und conflict_handler ermöglichen eine feinere Steuerung des Verhaltens der Argumentengruppe. Diese Parameter haben dieselbe Bedeutung wie im Konstruktor von ArgumentParser, gelten aber speziell für die Argumentengruppe und nicht für den gesamten Parser.

Beachten Sie, dass alle Argumente, die nicht in Ihren benutzerdefinierten Gruppen enthalten sind, in den üblichen Abschnitten „positionelle Argumente“ und „optionale Argumente“ landen.

Veraltet seit Version 3.11, entfernt in Version 3.14: Der Aufruf von add_argument_group() auf einer Argumentengruppe löst jetzt eine Ausnahme aus. Dieses Verschachteln wurde nie unterstützt, funktionierte oft nicht richtig und wurde unbeabsichtigt durch Vererbung offengelegt.

Veraltet seit Version 3.14: Die Übergabe von prefix_chars an add_argument_group() ist nun veraltet.

Gegenseitiger Ausschluss¶

ArgumentParser.add_mutually_exclusive_group(required=False)¶

Erstellt eine gegenseitig ausschließende Gruppe. argparse stellt sicher, dass nur eines der Argumente in der gegenseitig ausschließenden Gruppe in der Befehlszeile vorhanden war

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

Die Methode add_mutually_exclusive_group() akzeptiert auch ein Argument required, um anzugeben, dass mindestens eines der gegenseitig ausschließenden Argumente erforderlich ist

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

Beachten Sie, dass gegenseitig ausschließende Argumentgruppen derzeit nicht die Argumente title und description von add_argument_group() unterstützen. Eine gegenseitig ausschließende Gruppe kann jedoch einer Argumentengruppe hinzugefügt werden, die einen Titel und eine Beschreibung hat. Zum Beispiel

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

Veraltet seit Version 3.11, entfernt in Version 3.14: Der Aufruf von add_argument_group() oder add_mutually_exclusive_group() auf einer gegenseitig ausschließenden Gruppe löst jetzt eine Ausnahme aus. Dieses Verschachteln wurde nie unterstützt, funktionierte oft nicht richtig und wurde unbeabsichtigt durch Vererbung offengelegt.

Parser-Standardwerte¶

ArgumentParser.set_defaults(**kwargs)¶

Meistens werden die Attribute des von parse_args() zurückgegebenen Objekts vollständig durch die Inspektion der Befehlszeilenargumente und der Argumentaktionen bestimmt. set_defaults() ermöglicht das Hinzufügen einiger zusätzlicher Attribute, die ohne Inspektion der Befehlszeile bestimmt werden

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

Beachten Sie, dass Parser-Level-Standardwerte immer Argument-Level-Standardwerte überschreiben

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

Parser-Level-Standardwerte können besonders nützlich sein, wenn mit mehreren Parsern gearbeitet wird. Siehe die Methode add_subparsers() für ein Beispiel dieser Art.

ArgumentParser.get_default(dest)¶

Ruft den Standardwert für ein Namespace-Attribut ab, wie er entweder von add_argument() oder von set_defaults() gesetzt wurde

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

Hilfe ausgeben¶

In den meisten typischen Anwendungen kümmert sich parse_args() um die Formatierung und Ausgabe aller Nutzungs- oder Fehlermeldungen. Mehrere Formatierungsmethoden sind jedoch verfügbar

ArgumentParser.print_usage(file=None)¶: Gibt eine kurze Beschreibung aus, wie der ArgumentParser auf der Befehlszeile aufgerufen werden sollte. Wenn file None ist, wird sys.stdout angenommen.

ArgumentParser.print_help(file=None)¶: Gibt eine Hilfemeldung aus, einschließlich der Programmnutzung und Informationen über die mit dem ArgumentParser registrierten Argumente. Wenn file None ist, wird sys.stdout angenommen.

Es gibt auch Varianten dieser Methoden, die einen String zurückgeben, anstatt ihn zu drucken

ArgumentParser.format_usage()¶: Gibt einen String zurück, der eine kurze Beschreibung enthält, wie der ArgumentParser auf der Befehlszeile aufgerufen werden sollte.

ArgumentParser.format_help()¶: Gibt einen String zurück, der eine Hilfemeldung enthält, einschließlich der Programmnutzung und Informationen über die mit dem ArgumentParser registrierten Argumente.

Teilweise Analyse¶

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

Manchmal muss ein Skript nur einen bestimmten Satz von Befehlszeilenargumenten verarbeiten und die nicht erkannten Argumente für ein anderes Skript oder Programm übrig lassen. In diesen Fällen kann die Methode parse_known_args() nützlich sein.

Diese Methode funktioniert ähnlich wie parse_args(), löst aber keinen Fehler für zusätzliche, nicht erkannte Argumente aus. Stattdessen analysiert sie die bekannten Argumente und gibt ein zweielementiges Tupel zurück, das den ausgefüllten Namespace und die Liste aller nicht erkannten Argumente enthält.

>>> 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'])

Warnung

Präfixabgleichregeln gelten für parse_known_args(). Der Parser kann eine Option verbrauchen, auch wenn sie nur ein Präfix einer seiner bekannten Optionen ist, anstatt sie in der Liste der verbleibenden Argumente zu belassen.

Anpassung der Dateiverarbeitung¶

ArgumentParser.convert_arg_line_to_args(arg_line)¶

Argumente, die aus einer Datei gelesen werden (siehe das Schlüsselwortargument fromfile_prefix_chars im Konstruktor von ArgumentParser), werden als ein Argument pro Zeile gelesen. convert_arg_line_to_args() kann für eine ausgefeiltere Leseart überschrieben werden.

Diese Methode nimmt ein einzelnes Argument arg_line entgegen, das eine aus der Argumentdatei gelesene Zeichenkette ist. Sie gibt eine Liste von Argumenten zurück, die aus dieser Zeichenkette analysiert wurden. Die Methode wird einmal pro Zeile aufgerufen, die aus der Argumentdatei gelesen wird, in der angegebenen Reihenfolge.

Eine nützliche Überschreibung dieser Methode ist eine, die jedes durch Leerzeichen getrennte Wort als Argument behandelt. Das folgende Beispiel zeigt, wie dies gemacht wird

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

Beendigungsmethoden¶

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

Diese Methode beendet das Programm, indem sie mit dem angegebenen status beendet wird und, falls vorhanden, eine message an sys.stderr ausgibt, bevor dies geschieht. Der Benutzer kann diese Methode überschreiben, um diese Schritte anders zu handhaben

class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Exiting because of an error: {message}')
        exit(status)

ArgumentParser.error(message)¶: Diese Methode gibt eine Nutzungsmeldung, einschließlich der message, an sys.stderr aus und beendet das Programm mit dem Statuscode 2.

Verschachtelte Analyse¶

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

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

Eine Reihe von Unix-Befehlen erlaubt dem Benutzer, optionale Argumente mit positionellen Argumenten zu mischen. Die Methoden parse_intermixed_args() und parse_known_intermixed_args() unterstützen diesen Parsing-Stil.

Diese Parser unterstützen nicht alle argparse-Funktionen und lösen Ausnahmen aus, wenn nicht unterstützte Funktionen verwendet werden. Insbesondere sind Subparser und gegenseitig ausschließende Gruppen, die sowohl optionale als auch positionelle Argumente enthalten, nicht unterstützt.

Das folgende Beispiel zeigt den Unterschied zwischen parse_known_args() und parse_intermixed_args(): ersteres gibt ['2', '3'] als nicht analysierte Argumente zurück, während letzteres alle positionellen Argumente in rest sammelt.

>>> 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() gibt ein zweielementiges Tupel zurück, das den ausgefüllten Namespace und die Liste der verbleibenden Argumentzeichenketten enthält. parse_intermixed_args() löst eine Ausnahme aus, wenn noch nicht analysierte Argumentzeichenketten vorhanden sind.

Hinzugefügt in Version 3.7.

Registrieren benutzerdefinierter Typen oder Aktionen¶

ArgumentParser.register(registry_name, value, object)¶

Manchmal ist es wünschenswert, eine benutzerdefinierte Zeichenkette in Fehlermeldungen zu verwenden, um eine benutzerfreundlichere Ausgabe zu erzielen. In diesen Fällen kann register() verwendet werden, um benutzerdefinierte Aktionen oder Typen bei einem Parser zu registrieren und es Ihnen zu ermöglichen, auf den Typ unter seinem registrierten Namen anstatt unter seinem aufrufbaren Namen zu verweisen.

Die Methode register() akzeptiert drei Argumente: einen registry_name, der die interne Registrierung angibt, in der das Objekt gespeichert wird (z. B. action, type), value, den Schlüssel, unter dem das Objekt registriert wird, und object, das aufzurufende Objekt, das registriert wird.

Das folgende Beispiel zeigt, wie ein benutzerdefinierter Typ bei einem Parser registriert wird

>>> 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'

Ausnahmen¶

exception argparse.ArgumentError¶

Ein Fehler bei der Erstellung oder Verwendung eines Arguments (optional oder positionell).

Der String-Wert dieser Ausnahme ist die Nachricht, ergänzt um Informationen über das Argument, das sie verursacht hat.

exception argparse.ArgumentTypeError¶: Ausgelöst, wenn beim Konvertieren einer Befehlszeilenzeichenkette in einen Typ etwas schief geht.

Anleitungen und Tutorials

argparse — Parser für Kommandozeilenoptionen, Argumente und Unterbefehle¶

ArgumentParser-Objekte¶

prog¶

usage¶

description¶

epilog¶

parents¶

formatter_class¶

prefix_chars¶

fromfile_prefix_chars¶

argument_default¶

allow_abbrev¶

conflict_handler¶

add_help¶

exit_on_error¶

suggest_on_error¶

color¶

Die Methode add_argument()¶

name or flags¶

action¶

nargs¶

const¶

default¶

type¶

choices¶

required¶

help¶

metavar¶

dest¶

deprecated¶

Aktionsklassen¶

Die Methode parse_args()¶

Optionswert-Syntax¶

Ungültige Argumente¶

Argumente, die - enthalten¶

Argument-Abkürzungen (Präfix-Abgleich)¶

Über sys.argv hinaus¶

Das Namespace-Objekt¶

Andere Hilfsprogramme¶

Unterbefehle¶

FileType-Objekte¶

Argumentgruppen¶

Gegenseitiger Ausschluss¶

Parser-Standardwerte¶

Hilfe ausgeben¶

Teilweise Analyse¶

Anpassung der Dateiverarbeitung¶

Beendigungsmethoden¶

Verschachtelte Analyse¶

Registrieren benutzerdefinierter Typen oder Aktionen¶

Ausnahmen¶

`argparse` — Parser für Kommandozeilenoptionen, Argumente und Unterbefehle¶

Argumente, die `-` enthalten¶

Über `sys.argv` hinaus¶