`argparse` — Parser for command-line options, arguments and sub-commands¶

Нове в версії 3.2.

Вихідний код: Lib/argparse.py

The argparse module makes it easy to write user-friendly command-line interfaces. The program defines what arguments it requires, and argparse will figure out how to parse those out of sys.argv. The argparse module also automatically generates help and usage messages and issues errors when users give the program invalid arguments.

Example¶

The following code is a Python program that takes a list of integers and produces either the sum or the max:

import argparse

parser = argparse.ArgumentParser(description='Process some integers.')
parser.add_argument('integers', metavar='N', type=int, nargs='+',
                    help='an integer for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
                    const=sum, default=max,
                    help='sum the integers (default: find the max)')

args = parser.parse_args()
print(args.accumulate(args.integers))

Assuming the Python code above is saved into a file called prog.py, it can be run at the command line and provides useful help messages:

$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]

Process some integers.

positional arguments:
 N           an integer for the accumulator

optional arguments:
 -h, --help  show this help message and exit
 --sum       sum the integers (default: find the max)

When run with the appropriate arguments, it prints either the sum or the max of the command-line integers:

$ python prog.py 1 2 3 4
4

$ python prog.py 1 2 3 4 --sum
10

If invalid arguments are passed in, it will issue an error:

$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'

The following sections walk you through this example.

Creating a parser¶

The first step in using the argparse is creating an ArgumentParser object:

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

The ArgumentParser object will hold all the information necessary to parse the command line into Python data types.

Adding arguments¶

Filling an ArgumentParser with information about program arguments is done by making calls to the add_argument() method. Generally, these calls tell the ArgumentParser how to take the strings on the command line and turn them into objects. This information is stored and used when parse_args() is called. For example:

>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
...                     const=sum, default=max,
...                     help='sum the integers (default: find the max)')

Later, calling parse_args() will return an object with two attributes, integers and accumulate. The integers attribute will be a list of one or more ints, and the accumulate attribute will be either the sum() function, if --sum was specified at the command line, or the max() function if it was not.

Parsing arguments¶

ArgumentParser parses arguments through the parse_args() method. This will inspect the command line, convert each argument to the appropriate type and then invoke the appropriate action. In most cases, this means a simple Namespace object will be built up from attributes parsed out of the command line:

>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

In a script, parse_args() will typically be called with no arguments, and the ArgumentParser will automatically determine the command-line arguments from sys.argv.

Об’єкти ArgumentParser¶

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

Створіть новий об’єкт ArgumentParser. Усі параметри слід передати як аргументи ключового слова. Кожен параметр має власний більш детальний опис нижче, але коротко вони:

prog - The name of the program (default: sys.argv[0])
usage - рядок, що описує використання програми (за замовчуванням: генерується з аргументів, доданих до аналізатора)
description - Text to display before the argument help (default: none)
epilog - Text to display after the argument help (default: none)
Parents - список об’єктів ArgumentParser, аргументи яких також мають бути включені
formatter_class - клас для налаштування виведення довідки
prefix_chars - набір символів, які є префіксом необов’язкових аргументів (за замовчуванням: „-„)
fromfile_prefix_chars - набір символів, які є префіксами файлів, з яких слід читати додаткові аргументи (за замовчуванням: None)
argument_default - глобальне значення за замовчуванням для аргументів (за замовчуванням: None)
конфлікт_обробник - стратегія вирішення конфліктних опцій (зазвичай непотрібних)
add_help - додає опцію -h/--help до аналізатора (за замовчуванням: True)
allow_abbrev - Дозволяє скорочувати довгі параметри, якщо скорочення є однозначним. (за замовчуванням: True)
exit_on_error - Determines whether or not ArgumentParser exits with error info when an error occurs. (default: True)

Змінено в версії 3.5: Додано параметр allow_abbrev.

Змінено в версії 3.8: У попередніх версіях allow_abbrev також вимикав групування коротких прапорців, таких як -vv, щоб означати -v -v.

Змінено в версії 3.9: Додано параметр exit_on_error.

У наступних розділах описано, як використовується кожен із них.

прог¶

By default, ArgumentParser objects use sys.argv[0] to determine how to display the name of the program in help messages. This default is almost always desirable because it will make the help messages match how the program was invoked on the command line. For example, consider a file named myprogram.py with the following code:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

The help for this program will display myprogram.py as the program name (regardless of where the program was invoked from):

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

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

To change this default behavior, another value can be supplied using the prog= argument to ArgumentParser:

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

optional arguments:
 -h, --help  show this help message and exit

Зауважте, що ім’я програми, незалежно від того, чи визначається з sys.argv[0] або з prog= аргументу, доступне для довідкових повідомлень за допомогою специфікатора формату %(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]

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

використання¶

By default, ArgumentParser calculates the usage message from the arguments it contains:

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

positional arguments:
 bar          bar help

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

The default message can be overridden with the usage= keyword 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

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

Специфікатор формату %(prog)s доступний для заповнення назви програми у ваших повідомленнях про використання.

опис¶

Most calls to the ArgumentParser constructor will use the description= keyword argument. This argument gives a brief description of what the program does and how it works. In help messages, the description is displayed between the command-line usage string and the help messages for the various arguments:

>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

optional arguments:
 -h, --help  show this help message and exit

За замовчуванням опис буде перенесено на рядок, щоб він поміщався в заданий простір. Щоб змінити цю поведінку, перегляньте аргумент formatter_class.

епілог¶

Деякі програми люблять відображати додатковий опис програми після опису аргументів. Такий текст можна вказати за допомогою аргументу epilog= для 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

optional arguments:
 -h, --help  show this help message and exit

And that's how you'd foo a bar

Як і в випадку з аргументом description, текст epilog= за замовчуванням переносить рядки, але цю поведінку можна налаштувати за допомогою аргументу formatter_class на ArgumentParser.

батьки¶

Іноді кілька аналізаторів використовують загальний набір аргументів. Замість того, щоб повторювати визначення цих аргументів, можна використати єдиний синтаксичний аналізатор із усіма спільними аргументами та переданим аргументом parents= для ArgumentParser. Аргумент parents= бере список об’єктів ArgumentParser, збирає всі позиційні та необов’язкові дії з них і додає ці дії до об’єкта ArgumentParser, який створюється:

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

Зауважте, що більшість батьківських аналізаторів вказуватимуть add_help=False. Інакше ArgumentParser побачить два параметри -h/--help (один у батьківському і один у дочірньому) і викличе помилку.

Примітка

Ви повинні повністю ініціалізувати аналізатори перед тим, як передавати їх через parents=. Якщо ви змінюєте батьківські аналізатори після дочірнього, ці зміни не відображатимуться в дочірньому.

formatter_class¶

Об’єкти ArgumentParser дозволяють налаштувати форматування довідки шляхом визначення альтернативного класу форматування. На даний момент існує чотири таких класи:

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

RawDescriptionHelpFormatter і RawTextHelpFormatter дають більше контролю над тим, як відображаються текстові описи. За замовчуванням об’єкти ArgumentParser переносять тексти description і epilog у довідкові повідомлення командного рядка:

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

optional arguments:
 -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

Передача RawDescriptionHelpFormatter як formatter_class= вказує на те, що description і epilog вже правильно відформатовані і не повинні бути перенесені в рядок:

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

optional arguments:
 -h, --help  show this help message and exit

RawTextHelpFormatter maintains whitespace for all sorts of help text, including argument descriptions. However, multiple new lines are replaced with one. If you wish to preserve multiple blank lines, add spaces between the newlines.

ArgumentDefaultsHelpFormatter автоматично додає інформацію про значення за замовчуванням до кожного довідкового повідомлення аргументу:

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

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

MetavarTypeHelpFormatter використовує ім’я аргументу type для кожного аргументу як відображуване ім’я для його значень (замість використання dest, як це робить звичайний засіб форматування):

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

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

prefix_chars¶

Most command-line options will use - as the prefix, e.g. -f/--foo. Parsers that need to support different or additional prefix characters, e.g. for options like +f or /foo, may specify them using the prefix_chars= argument to the ArgumentParser constructor:

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

Аргумент prefix_chars= за умовчанням має значення '-'. Якщо вказати набір символів, який не містить -, параметри -f/--foo будуть заборонені.

fromfile_prefix_chars¶

Sometimes, for example when dealing with a particularly long argument list, it may make sense to keep the list of arguments in a file rather than typing it out at the command line. If the fromfile_prefix_chars= argument is given to the ArgumentParser constructor, then arguments that start with any of the specified characters will be treated as files, and will be replaced by the arguments they contain. For example:

>>> with open('args.txt', 'w') 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')

Аргументи, зчитані з файлу, за замовчуванням мають бути по одному на рядок (але дивіться також convert_arg_line_to_args()) і обробляються так, ніби вони знаходяться в тому самому місці, що й вихідний аргумент посилання на файл у командному рядку. Отже, у наведеному вище прикладі вираз ['-f', 'foo', '@args.txt'] вважається еквівалентним виразу ['-f', 'foo', '-f ', 'бар'].

Аргумент fromfile_prefix_chars= за умовчанням має значення None, що означає, що аргументи ніколи не розглядатимуться як посилання на файли.

аргумент_за замовчуванням¶

Як правило, параметри за замовчуванням вказуються або передачею значення за замовчуванням add_argument(), або викликом методів set_defaults() із певним набором пар ім’я-значення. Іноді, однак, може бути корисно вказати єдине значення за замовчуванням для параметрів аналізатора. Це можна зробити, передавши аргумент ключового слова argument_default= до ArgumentParser. Наприклад, щоб глобально заборонити створення атрибутів у викликах parse_args(), ми надаємо 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()

дозволити_скорочене¶

Зазвичай, коли ви передаєте список аргументів у метод parse_args() ArgumentParser, він розпізнає абревіатури довгих параметрів.

Цю функцію можна вимкнути, встановивши для параметра allow_abbrev значення 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

Нове в версії 3.5.

обробник_конфлікту¶

Об’єкти ArgumentParser не дозволяють дві дії з однаковим рядком параметрів. За замовчуванням об’єкти ArgumentParser викликають виняток, якщо робиться спроба створити аргумент із рядком параметрів, який уже використовується:

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

Іноді (наприклад, під час використання батьків) може бути корисним просто замінити будь-які старіші аргументи тим самим рядком параметрів. Щоб отримати таку поведінку, значення 'resolve' можна надати аргументу conflict_handler= 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]

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

Зауважте, що об’єкти ArgumentParser видаляють дію лише в тому випадку, якщо перевизначено всі рядки параметрів. Отже, у наведеному вище прикладі стара дія -f/--foo зберігається як дія -f, тому що було замінено лише рядок опції --foo.

add_help¶

By default, ArgumentParser objects add an option which simply displays the parser’s help message. For example, consider a file named myprogram.py containing the following code:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

If -h or --help is supplied at the command line, the ArgumentParser help will be printed:

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

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

Іноді може бути корисним вимкнути додавання цієї опції довідки. Цього можна досягти, передавши False як аргумент add_help= до ArgumentParser:

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

optional arguments:
 --foo FOO  foo help

Параметром довідки зазвичай є -h/--help. Винятком є те, що prefix_chars= указано і не містить -, у цьому випадку -h і --help не є дійсними параметрами. У цьому випадку перший символ у prefix_chars використовується для префіксу параметрів довідки:

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

optional arguments:
  +h, ++help  show this help message and exit

exit_on_error¶

Normally, when you pass an invalid argument list to the parse_args() method of an ArgumentParser, it will exit with error info.

Якщо користувач хоче виловлювати помилки вручну, цю функцію можна ввімкнути, встановивши для exit_on_error значення 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

Нове в версії 3.9.

Метод add_argument().¶

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

Визначте, як слід аналізувати один аргумент командного рядка. Кожен параметр має власний більш детальний опис нижче, але коротко вони:

name or flags - Either a name or a list of option strings, e.g. foo or -f, --foo.
action - основний тип дії, яку потрібно виконати, коли цей аргумент зустрічається в командному рядку.
nargs – кількість аргументів командного рядка, які мають бути використані.
const – постійне значення, необхідне для вибору деяких action і nargs.
default – значення, створене, якщо аргумент відсутній у командному рядку та якщо він відсутній в об’єкті простору імен.
type – тип, до якого потрібно перетворити аргумент командного рядка.
choices - A container of the allowable values for the argument.
required – чи можна пропустити параметр командного рядка (тільки необов’язковий).
help - короткий опис того, що робить аргумент.
metavar – назва аргументу в повідомленнях про використання.
dest – ім’я атрибута, який буде додано до об’єкта, повернутого parse_args().

У наступних розділах описано, як використовується кожен із них.

назву чи прапори¶

The add_argument() method must know whether an optional argument, like -f or --foo, or a positional argument, like a list of filenames, is expected. The first arguments passed to add_argument() must therefore be either a series of flags, or a simple argument name. For example, an optional argument could be created like:

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

тоді як позиційний аргумент може бути створений таким чином:

>>> parser.add_argument('bar')

Під час виклику parse_args() необов’язкові аргументи ідентифікуються префіксом -, а решта аргументів вважатиметься позиційними:

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

дію¶

Об’єкти ArgumentParser пов’язують аргументи командного рядка з діями. Ці дії можуть робити що завгодно з пов’язаними з ними аргументами командного рядка, хоча більшість дій просто додають атрибут до об’єкта, який повертає parse_args(). Аргумент ключового слова action визначає, як слід обробляти аргументи командного рядка. Надані дії:

'store' - This just stores the argument’s value. This is the default action. For example:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args('--foo 1'.split())
Namespace(foo='1')

'store_const' - This stores the value specified by the const keyword argument. The 'store_const' action is most commonly used with optional arguments that specify some sort of flag. For example:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
```

'store_true' and 'store_false' - These are special cases of 'store_const' used for storing the values True and False respectively. In addition, they create default values of False and True respectively. For example:

>>> 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' - This stores a list, and appends each argument value to the list. This is useful to allow an option to be specified multiple times. Example usage:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])

'append_const' - This stores a list, and appends the value specified by the const keyword argument to the list. (Note that the const keyword argument defaults to None.) The 'append_const' action is typically useful when multiple arguments need to store constants to the same list. For example:

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

'count' – підраховує кількість разів, коли виникає аргумент ключового слова. Наприклад, це корисно для збільшення рівнів докладності:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
```
Зауважте, за замовчуванням буде None, якщо явно не встановлено 0.
'help' - друкує повне повідомлення довідки для всіх параметрів у поточному парсері, а потім завершує роботу. За замовчуванням дія довідки автоматично додається до аналізатора. Дивіться ArgumentParser для детальної інформації про те, як створюється вихід.
'version' – очікується ключовий аргумент version= у виклику add_argument(), друкується інформація про версію та завершується після виклику:
```
>>> 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
```

'extend' - This stores a list, and extends each argument value to the list. Example usage:

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

Нове в версії 3.8.

You may also specify an arbitrary action by passing an Action subclass or other object that implements the same interface. The BooleanOptionalAction is available in argparse and adds support for boolean actions such as --foo and --no-foo:

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

Нове в версії 3.9.

The recommended way to create a custom action is to extend Action, overriding the __call__ method and optionally the __init__ and format_usage methods.

Приклад спеціальної дії:

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

Для отримання додаткової інформації див. Action.

наргс¶

ArgumentParser objects usually associate a single command-line argument with a single action to be taken. The nargs keyword argument associates a different number of command-line arguments with a single action. The supported values are:

N (ціле число). N аргументів з командного рядка буде зібрано разом у список. Наприклад:
```
>>> 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'])
```
Зауважте, що nargs=1 створює список з одного елемента. Це відрізняється від типового, коли елемент створюється сам по собі.

'?'. Один аргумент буде використано з командного рядка, якщо це можливо, і створено як окремий елемент. Якщо аргумент командного рядка відсутній, буде отримано значення з default. Зауважте, що для необов’язкових аргументів існує додатковий випадок – рядок параметрів присутній, але не слідує за аргументом командного рядка. У цьому випадку буде отримано значення з const. Деякі приклади для ілюстрації:

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

Одне з найпоширеніших застосувань nargs='?'' — дозволити додаткові файли введення та виведення:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
...                     default=sys.stdin)
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
...                     default=sys.stdout)
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
>>> parser.parse_args([])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)

'*'. Усі присутні аргументи командного рядка збираються у список. Зауважте, що зазвичай не має сенсу мати більше одного позиційного аргументу з nargs='*', але кілька необов’язкових аргументів з nargs='*' можливі. Наприклад:
```
>>> 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'])
```

'+'. Подібно до '*', усі наявні аргументи командного рядка збираються в список. Крім того, буде створено повідомлення про помилку, якщо не було принаймні одного аргументу командного рядка. Наприклад:
```
>>> 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
```

If the nargs keyword argument is not provided, the number of arguments consumed is determined by the action. Generally this means a single command-line argument will be consumed and a single item (not a list) will be produced.

конст¶

Аргумент const add_argument() використовується для зберігання постійних значень, які не читаються з командного рядка, але потрібні для різних дій ArgumentParser. Два найпоширеніші його використання:

When add_argument() is called with action='store_const' or action='append_const'. These actions add the const value to one of the attributes of the object returned by parse_args(). See the action description for examples.
When add_argument() is called with option strings (like -f or --foo) and nargs='?'. This creates an optional argument that can be followed by zero or one command-line arguments. When parsing the command line, if the option string is encountered with no command-line argument following it, the value of const will be assumed instead. See the nargs description for examples.

With the 'store_const' and 'append_const' actions, the const keyword argument must be given. For other actions, it defaults to None.

за замовчуванням¶

Усі додаткові аргументи та деякі позиційні аргументи можна пропустити в командному рядку. Аргумент ключового слова default add_argument(), значення якого за замовчуванням None, визначає, яке значення слід використовувати, якщо аргумент командного рядка відсутній. Для необов’язкових аргументів використовується значення за замовчуванням, якщо рядок параметрів відсутній у командному рядку:

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

If the target namespace already has an attribute set, the action default will not over write it:

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

Якщо значенням default є рядок, синтаксичний аналізатор аналізує значення так, ніби це аргумент командного рядка. Зокрема, синтаксичний аналізатор застосовує будь-який аргумент перетворення type, якщо він надається, перед встановленням атрибута для значення, що повертається Namespace. В іншому випадку аналізатор використовує значення як є:

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

Для позиційних аргументів, у яких nargs дорівнює ? або *, значення default використовується, якщо аргумент командного рядка відсутній:

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

Якщо вказати default=argparse.SUPPRESS, атрибут не буде додано, якщо аргумент командного рядка відсутній:

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

типу¶

За замовчуванням аналізатор читає аргументи командного рядка як прості рядки. Однак досить часто рядок командного рядка слід інтерпретувати як інший тип, наприклад float або int. Ключове слово type для add_argument() дозволяє виконувати будь-які необхідні перевірки типів і перетворення типів.

Якщо ключове слово type використовується з ключовим словом default, конвертер типів застосовується, лише якщо значенням за замовчуванням є рядок.

The argument to type can be any callable that accepts a single string. If the function raises ArgumentTypeError, TypeError, or ValueError, the exception is caught and a nicely formatted error message is displayed. No other exception types are handled.

Загальні вбудовані типи та функції можна використовувати як перетворювачі типів:

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('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)

Також можна використовувати визначені користувачем функції:

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

Функцію bool() не рекомендується використовувати як перетворювач типів. Усе, що він робить, це перетворює порожні рядки на False, а непорожні рядки — на True. Зазвичай це не те, чого хочеться.

Загалом, ключове слово type є зручним, і його слід використовувати лише для простих перетворень, які можуть викликати лише одне з трьох підтримуваних винятків. Усе, що має більш цікаву обробку помилок або керування ресурсами, має бути зроблено нижче за течією після аналізу аргументів.

For example, JSON or YAML conversions have complex error cases that require better reporting than can be given by the type keyword. A JSONDecodeError would not be well formatted and a FileNotFound exception would not be handled at all.

Even FileType has its limitations for use with the type keyword. If one argument uses FileType and then a subsequent argument fails, an error is reported but the file is not automatically closed. In this case, it would be better to wait until after the parser has run and then use the with-statement to manage the files.

Для засобів перевірки типів, які просто перевіряють фіксований набір значень, подумайте про використання ключового слова choices.

вибір¶

Some command-line arguments should be selected from a restricted set of values. These can be handled by passing a container object as the choices keyword argument to add_argument(). When the command line is parsed, argument values will be checked, and an error message will be displayed if the argument was not one of the acceptable values:

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

Note that inclusion in the choices container is checked after any type conversions have been performed, so the type of the objects in the choices container should match the type specified:

>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

Any container can be passed as the choices value, so list objects, set objects, and custom containers are all supported.

Використання enum.Enum не рекомендується, оскільки важко контролювати його появу в повідомленнях про використання, довідці та помилках.

Formatted choices overrides the default metavar which is normally derived from dest. This is usually what you want because the user never sees the dest parameter. If this display isn’t desirable (perhaps because there are many choices), just specify an explicit metavar.

вимагається¶

In general, the argparse module assumes that flags like -f and --bar indicate optional arguments, which can always be omitted at the command line. To make an option required, True can be specified for the required= keyword argument to 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

Як показує приклад, якщо параметр позначено як required, parse_args() повідомить про помилку, якщо цей параметр відсутній у командному рядку.

Примітка

Обов’язкові параметри зазвичай вважаються поганим тоном, оскільки користувачі очікують, що параметри будуть необов’язковими, тому їх слід уникати, коли це можливо.

допомогти¶

The help value is a string containing a brief description of the argument. When a user requests help (usually by using -h or --help at the command line), these help descriptions will be displayed with each argument:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
...                     help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
...                     help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]

positional arguments:
 bar     one of the bars to be frobbled

optional arguments:
 -h, --help  show this help message and exit
 --foo   foo the bars before frobbling

Рядки help можуть містити різні специфікатори формату, щоб уникнути повторення таких речей, як назва програми або аргумент default. Доступні специфікатори включають назву програми, %(prog)s та більшість ключових аргументів для add_argument(), напр. %(default)s, %(type)s тощо:

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

optional arguments:
 -h, --help  show this help message and exit

Оскільки рядок довідки підтримує %-formatting, якщо ви хочете, щоб літерал % з’явився в рядку довідки, ви повинні екранувати його як %%.

argparse supports silencing the help entry for certain options, by setting the help value to argparse.SUPPRESS:

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

optional arguments:
  -h, --help  show this help message and exit

метавар¶

When ArgumentParser generates help messages, it needs some way to refer to each expected argument. By default, ArgumentParser objects use the dest value as the «name» of each object. By default, for positional argument actions, the dest value is used directly, and for optional argument actions, the dest value is uppercased. So, a single positional argument with dest='bar' will be referred to as bar. A single optional argument --foo that should be followed by a single command-line argument will be referred to as FOO. An example:

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

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

Альтернативну назву можна вказати за допомогою 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

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

Зауважте, що metavar змінює лише відображене ім’я – ім’я атрибута об’єкта parse_args() все ще визначається значенням dest.

Різні значення nargs можуть спричинити багаторазове використання метаперемінної. Надання кортежу для metavar визначає інше відображення для кожного з аргументів:

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

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

дест¶

Більшість дій ArgumentParser додають певне значення як атрибут об’єкта, який повертає parse_args(). Ім’я цього атрибута визначається ключовим аргументом dest add_argument(). Для дій позиційного аргументу dest зазвичай надається як перший аргумент add_argument():

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

Для необов’язкових дій аргументів значення dest зазвичай виводиться з рядків параметрів. ArgumentParser генерує значення dest, беручи перший довгий рядок параметрів і видаляючи початковий рядок --. Якщо не було надано довгих рядків параметрів, dest буде отримано з першого короткого рядка параметрів шляхом видалення початкового символу -. Усі внутрішні символи «-» буде перетворено на символи «_», щоб переконатися, що рядок є дійсною назвою атрибута. Наведені нижче приклади ілюструють цю поведінку:

>>> 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 дозволяє надати ім’я спеціального атрибута:

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

Класи дії¶

Action classes implement the Action API, a callable which returns a callable which processes arguments from the command-line. Any object which follows this API may be passed as the action parameter to 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 objects are used by an ArgumentParser to represent the information needed to parse a single argument from one or more strings from the command line. The Action class must accept the two positional arguments plus any keyword arguments passed to ArgumentParser.add_argument() except for the action itself.

Instances of Action (or return value of any callable to the action parameter) should have attributes «dest», «option_strings», «default», «type», «required», «help», etc. defined. The easiest way to ensure these attributes are defined is to call Action.__init__.

Action instances should be callable, so subclasses must override the __call__ method, which should accept four parameters:

parser - The ArgumentParser object which contains this action.
namespace - The Namespace object that will be returned by parse_args(). Most actions add an attribute to this object using setattr().
values - The associated command-line arguments, with any type conversions applied. Type conversions are specified with the type keyword argument to add_argument().
option_string - The option string that was used to invoke this action. The option_string argument is optional, and will be absent if the action is associated with a positional argument.

The __call__ method may perform arbitrary actions, but will typically set attributes on the namespace based on dest and values.

Action subclasses can define a format_usage method that takes no argument and return a string which will be used when printing the usage of the program. If such method is not provided, a sensible default will be used.

Метод parse_args().¶

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

Перетворіть рядки аргументів на об’єкти та призначте їх як атрибути простору імен. Повернути заповнений простір імен.

Previous calls to add_argument() determine exactly what objects are created and how they are assigned. See the documentation for add_argument() for details.

args - список рядків для аналізу. Типове значення взято з sys.argv.
namespace – об’єкт для отримання атрибутів. Типовим є новий порожній об’єкт Namespace.

Синтаксис значення опції¶

Метод parse_args() підтримує кілька способів визначення значення параметра (якщо воно приймається). У найпростішому випадку параметр і його значення передаються як два окремих аргументи:

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

Для довгих параметрів (параметрів з іменами, довшими за один символ), параметр і значення також можна передати як один аргумент командного рядка, використовуючи =, щоб розділити їх:

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

Для коротких опцій (опції лише з одного символу) опцію та її значення можна об’єднати:

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

Кілька коротких опцій можна об’єднати разом, використовуючи лише один префікс -, якщо тільки остання опція (або жодна з них) вимагає значення:

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

Недійсні аргументи¶

Під час аналізу командного рядка parse_args() перевіряє наявність різноманітних помилок, включаючи неоднозначні параметри, недійсні типи, недійсні параметри, неправильну кількість позиційних аргументів тощо. Коли він стикається з такою помилкою, він виходить і друкує помилку разом із повідомленням про використання:

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

Аргументи, що містять `-`¶

Метод parse_args() намагається видавати помилки щоразу, коли користувач явно зробив помилку, але деякі ситуації за своєю суттю неоднозначні. Наприклад, аргумент командного рядка «-1» може бути або спробою вказати параметр, або спробою надати позиційний аргумент. Метод parse_args() тут обережний: позиційні аргументи можуть починатися лише з -, якщо вони виглядають як від’ємні числа, і в аналізаторі немає параметрів, які виглядають як від’ємні числа:

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

Якщо у вас є позиційні аргументи, які повинні починатися з - і не виглядати як від’ємні числа, ви можете вставити псевдоаргумент ''--', який повідомляє parse_args(), що все після цього є позиційним аргументом:

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

Скорочення аргументів (відповідність префіксу)¶

Метод parse_args() за замовчуванням дозволяє скорочувати довгі параметри до префікса, якщо скорочення є однозначним (префікс відповідає унікальному параметру):

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

Помилка створюється для аргументів, які можуть давати більше одного варіанту. Цю функцію можна вимкнути, встановивши для дозволити_скорочене значення False.

За межами `sys.argv`¶

Sometimes it may be useful to have an ArgumentParser parse arguments other than those of sys.argv. This can be accomplished by passing a list of strings to parse_args(). This is useful for testing at the interactive prompt:

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

Об’єкт простору імен¶

class argparse.Namespace¶: Простий клас, який за замовчуванням використовується parse_args() для створення об’єкта з атрибутами та повернення його.

Цей клас навмисне простий, просто підклас object із читабельним представленням рядка. Якщо ви віддаєте перевагу перегляду атрибутів у форматі dict, ви можете використовувати стандартну ідіому Python vars():

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

Також може бути корисним, щоб ArgumentParser призначав атрибути вже існуючому об’єкту, а не новому об’єкту Namespace. Цього можна досягти, вказавши аргумент ключового слова namespace=:

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

Інші комунальні послуги¶

Підкоманди¶

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

Many programs split up their functionality into a number of sub-commands, for example, the svn program can invoke sub-commands like svn checkout, svn update, and svn commit. Splitting up functionality this way can be a particularly good idea when a program performs several different functions which require different kinds of command-line arguments. ArgumentParser supports the creation of such sub-commands with the add_subparsers() method. The add_subparsers() method is normally called with no arguments and returns a special action object. This object has a single method, add_parser(), which takes a command name and any ArgumentParser constructor arguments, and returns an ArgumentParser object that can be modified as usual.

Опис параметрів:

title - title for the sub-parser group in help output; by default «subcommands» if description is provided, otherwise uses title for positional arguments
description - description for the sub-parser group in help output, by default None
prog - usage information that will be displayed with sub-command help, by default the name of the program and any positional arguments before the subparser argument
parser_class - class which will be used to create sub-parser instances, by default the class of the current parser (e.g. ArgumentParser)
action - основний тип дії, яка виконується, коли цей аргумент зустрічається в командному рядку
dest - ім’я атрибута, під яким буде зберігатися ім’я підкоманди; за замовчуванням None і жодне значення не зберігається
required - чи потрібно надавати підкоманду, за замовчуванням False (додано в 3.7)
help - довідка для групи суб-парсера у виведенні довідки, за замовчуванням None
metavar - string presenting available sub-commands in help; by default it is None and presents sub-commands in form {cmd1, cmd2, ..}

Деякі приклади використання:

>>> # 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='sub-command 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='XYZ', 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)

Зауважте, що об’єкт, який повертає parse_args(), міститиме лише атрибути для головного синтаксичного аналізатора та підпарсера, вибраного командним рядком (а не будь-яких інших підпарсерів). Отже, у прикладі вище, коли вказано команду a, присутні лише атрибути foo і bar, а коли вказано команду b, лише наявні атрибути foo і baz.

Similarly, when a help message is requested from a subparser, only the help for that particular parser will be printed. The help message will not include parent parser or sibling parser messages. (A help message for each subparser command, however, can be given by supplying the help= argument to add_parser() as above.)

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

positional arguments:
  {a,b}   sub-command help
    a     a help
    b     b help

optional arguments:
  -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

optional arguments:
  -h, --help  show this help message and exit

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

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

Метод add_subparsers() також підтримує ключові аргументи title і description. Якщо будь-який з них присутній, команди субпарсера відображатимуться у власній групі у виведенні довідки. Наприклад:

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

optional arguments:
  -h, --help  show this help message and exit

subcommands:
  valid subcommands

  {foo,bar}   additional help

Furthermore, add_parser supports an additional aliases argument, which allows multiple strings to refer to the same subparser. This example, like svn, aliases co as a shorthand for 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')

One particularly effective way of handling sub-commands is to combine the use of the add_subparsers() method with calls to set_defaults() so that each subparser knows which Python function it should execute. For example:

>>> # sub-command 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()
>>>
>>> # 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))

Таким чином, ви можете дозволити parse_args() виконати роботу з виклику відповідної функції після завершення аналізу аргументу. Пов’язування функцій із подібними діями зазвичай є найпростішим способом обробки різних дій для кожного з ваших підпарсерів. Однак, якщо необхідно перевірити ім’я викликаного субпарсера, аргумент ключового слова dest для виклику 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')

Змінено в версії 3.7: New required keyword argument.

Об’єкти FileType¶

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

Фабрика FileType створює об’єкти, які можна передати в аргумент типу ArgumentParser.add_argument(). Аргументи, які мають тип об’єктів FileType, відкриватимуть аргументи командного рядка як файли з потрібними режимами, розмірами буфера, кодуванням і обробкою помилок (додаткову інформацію див. у функції open()):

>>> 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 objects understand the pseudo-argument '-' and automatically convert this into sys.stdin for readable FileType objects and sys.stdout for writable FileType objects:

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

Нове в версії 3.4: The encodings and errors keyword arguments.

Групи аргументів¶

ArgumentParser.add_argument_group(title=None, description=None)¶

By default, ArgumentParser groups command-line arguments into «positional arguments» and «optional arguments» when displaying help messages. When there is a better conceptual grouping of arguments than this default one, appropriate groups can be created using the add_argument_group() method:

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

The add_argument_group() method returns an argument group object which has an add_argument() method just like a regular ArgumentParser. When an argument is added to the group, the parser treats it just like a normal argument, but displays the argument in a separate group for help messages. The add_argument_group() method accepts title and description arguments which can be used to customize this display:

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

Зверніть увагу, що будь-які аргументи, які не входять до визначених користувачем груп, повертаються до звичайних розділів «позиційні аргументи» та «необов’язкові аргументи».

Взаємне виключення¶

ArgumentParser.add_mutually_exclusive_group(required=False)¶

Create a mutually exclusive group. argparse will make sure that only one of the arguments in the mutually exclusive group was present on the command line:

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

Метод add_mutually_exclusive_group() також приймає обов’язковий аргумент, щоб вказати, що потрібен принаймні один із взаємовиключних аргументів:

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

Note that currently mutually exclusive argument groups do not support the title and description arguments of add_argument_group().

Параметри аналізатора за замовчуванням¶

ArgumentParser.set_defaults(**kwargs)¶

У більшості випадків атрибути об’єкта, які повертає parse_args(), будуть повністю визначені шляхом перевірки аргументів командного рядка та дій аргументів. set_defaults() дозволяє додавати деякі додаткові атрибути, які визначаються без перевірки командного рядка:

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

Зверніть увагу, що значення за замовчуванням на рівні аналізатора завжди перекривають значення за замовчуванням на рівні аргументів:

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

Значення за замовчуванням на рівні парсера можуть бути особливо корисними під час роботи з декількома парсерами. Перегляньте метод add_subparsers() для прикладу цього типу.

ArgumentParser.get_default(dest)¶

Отримати значення за замовчуванням для атрибута простору імен, встановлене або add_argument(), або set_defaults():

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

Друк довідки¶

У більшості типових програм parse_args() подбає про форматування та друк будь-яких повідомлень про використання чи помилки. Однак доступно кілька методів форматування:

ArgumentParser.print_usage(file=None)¶: Надрукуйте короткий опис того, як ArgumentParser слід викликати в командному рядку. Якщо file має значення None, передбачається sys.stdout.

ArgumentParser.print_help(file=None)¶: Надрукуйте довідкове повідомлення, включно з використанням програми та інформацією про аргументи, зареєстровані в ArgumentParser. Якщо file має значення None, передбачається sys.stdout.

Існують також варіанти цих методів, які просто повертають рядок замість того, щоб друкувати його:

ArgumentParser.format_usage()¶: Повертає рядок, що містить короткий опис того, як ArgumentParser слід викликати в командному рядку.

ArgumentParser.format_help()¶: Повертає рядок, що містить довідкове повідомлення, включаючи використання програми та інформацію про аргументи, зареєстровані в ArgumentParser.

Частковий розбір¶

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

Іноді сценарій може аналізувати лише кілька аргументів командного рядка, передаючи решту аргументів іншому сценарію чи програмі. У цих випадках може бути корисним метод parse_known_args(). Він працює так само, як parse_args(), за винятком того, що не створює помилки, коли присутні додаткові аргументи. Замість цього він повертає кортеж із двома елементами, що містить заповнений простір імен і список решти рядків аргументів.

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

Попередження

Prefix matching rules apply to parse_known_args(). The parser may consume an option even if it’s just a prefix of one of its known options, instead of leaving it in the remaining arguments list.

Налаштування аналізу файлів¶

ArgumentParser.convert_arg_line_to_args(arg_line)¶

Аргументи, які зчитуються з файлу (див. аргумент ключового слова fromfile_prefix_chars конструктора ArgumentParser), зчитуються по одному аргументу на рядок. convert_arg_line_to_args() можна замінити для кращого читання.

Цей метод приймає один аргумент arg_line, який є рядком, прочитаним з файлу аргументів. Він повертає список аргументів, розібраних із цього рядка. Метод викликається один раз на рядок, який читається з файлу аргументів, по порядку.

Корисною заміною цього методу є те, що розглядає кожне розділене пробілом слово як аргумент. Наступний приклад демонструє, як це зробити:

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

Методи виходу¶

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

This method terminates the program, exiting with the specified status and, if given, it prints a message before that. The user can override this method to handle these steps differently:

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)¶: This method prints a usage message including the message to the standard error and terminates the program with a status code of 2.

Змішаний розбір¶

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

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

Ряд команд Unix дозволяє користувачеві змішувати додаткові аргументи з позиційними. Методи parse_intermixed_args() і parse_known_intermixed_args() підтримують цей стиль аналізу.

These parsers do not support all the argparse features, and will raise exceptions if unsupported features are used. In particular, subparsers, argparse.REMAINDER, and mutually exclusive groups that include both optionals and positionals are not supported.

У наступному прикладі показано різницю між parse_known_args() і parse_intermixed_args(): перший повертає ['2', '3'] як нерозібрані аргументи, а другий збирає всі позиційні елементи в 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() повертає кортеж із двома елементами, що містить заповнений простір імен і список решти рядків аргументів. parse_intermixed_args() викликає помилку, якщо залишилися нерозібрані рядки аргументів.

Нове в версії 3.7.

Upgrading optparse code¶

Originally, the argparse module had attempted to maintain compatibility with optparse. However, optparse was difficult to extend transparently, particularly with the changes required to support the new nargs= specifiers and better usage messages. When most everything in optparse had either been copy-pasted over or monkey-patched, it no longer seemed practical to try to maintain the backwards compatibility.

The argparse module improves on the standard library optparse module in a number of ways including:

Handling positional arguments.
Supporting sub-commands.
Allowing alternative option prefixes like + and /.
Handling zero-or-more and one-or-more style arguments.
Producing more informative usage messages.
Providing a much simpler interface for custom type and action.

A partial upgrade path from optparse to argparse:

Replace all optparse.OptionParser.add_option() calls with ArgumentParser.add_argument() calls.
Replace (options, args) = parser.parse_args() with args = parser.parse_args() and add additional ArgumentParser.add_argument() calls for the positional arguments. Keep in mind that what was previously called options, now in the argparse context is called args.
Replace optparse.OptionParser.disable_interspersed_args() by using parse_intermixed_args() instead of parse_args().
Replace callback actions and the callback_* keyword arguments with type or action arguments.
Replace string names for type keyword arguments with the corresponding type objects (e.g. int, float, complex, etc).
Replace optparse.Values with Namespace and optparse.OptionError and optparse.OptionValueError with ArgumentError.
Replace strings with implicit arguments such as %default or %prog with the standard Python syntax to use dictionaries to format strings, that is, %(default)s and %(prog)s.
Replace the OptionParser constructor version argument with a call to parser.add_argument('--version', action='version', version='<the version>').

argparse — Parser for command-line options, arguments and sub-commands¶