argparse — Парсер для командно-строчных опций, аргументов и подкоманд

Новое в версии 2.7.

Исходный код: Lib/argparse.py

Модуль argparse упрощает создание удобных командно-строчных интерфейсов. Программа определяет требуемые аргументы, а argparse позаботится о том, как извлечь эти аргументы из sys.argv. Модуль argparse также автоматически генерирует сообщения справки и использования и сообщает об ошибках при передаче программе недопустимых аргументов.

1. Пример

Следующий код представляет собой программу Python, которая принимает список целых чисел и выводит либо сумму, либо максимум:

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)

Предполагая, что код Python выше сохранен в файле под названием prog.py, его можно запустить в командной строке, и он предоставит полезные сообщения справки:

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

При запуске с соответствующими аргументами он выводит либо сумму, либо максимум целых чисел из командной строки:

$ python prog.py 1 2 3 4
4

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

Если переданы недопустимые аргументы, будет выдано сообщение об ошибке:

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

В следующих разделах мы разберем этот пример.

1.1. Создание парсера

Первый шаг при использовании модуля argparse — создание объекта ArgumentParser:

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

Объект ArgumentParser будет содержать всю информацию, необходимую для разбора командной строки в типы данных Python.

1.2. Добавление аргументов

Заполнение объекта ArgumentParser информацией об аргументах программы выполняется с помощью вызовов метода add_argument(). Как правило, эти вызовы сообщают объекту ArgumentParser, как преобразовать строки из командной строки в объекты. Эта информация хранится и используется при вызове parse_args(). Например:

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

Позже, вызов parse_args() вернёт объект с двумя атрибутами, integers и accumulate. Атрибут integers будет списком одного или более целых чисел, а атрибут accumulate будет функцией sum(), если в командной строке была указана опция --sum, или функцией max(), если она не была указана.

1.3. Разбор аргументов

Объект ArgumentParser анализирует аргументы с помощью метода parse_args(). Это позволит проверить командную строку, преобразовать каждый аргумент в соответствующий тип и затем вызвать соответствующее действие. В большинстве случаев это означает создание простого объекта Namespace из атрибутов, извлеченных из командной строки:

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

В скрипте parse_args() обычно вызывается без аргументов, и ArgumentParser автоматически определяет аргументы командной строки из sys.argv.

2. Объекты 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)

Создает новый объект ArgumentParser. Все параметры должны передаваться в качестве ключевых аргументов. Каждый параметр имеет собственное более подробное описание ниже, но вкратце они такие:

prog - Имя программы (по умолчанию: sys.argv[0])
usage - Строка, описывающая использование программы (по умолчанию: генерируется из аргументов, добавленных в парсер)
description - Текст для отображения перед справкой по аргументам (по умолчанию: нет)
epilog - Текст для отображения после справки по аргументам (по умолчанию: нет)
parents - Список объектов ArgumentParser, аргументы которых также должны быть включены
formatter_class - Класс для настройки вывода справки
prefix_chars - Набор символов, которые предшествуют необязательным аргументам (по умолчанию: ‘-‘)
fromfile_prefix_chars - Набор символов, которые предшествуют файлам, из которых должны считываться дополнительные аргументы (по умолчанию: None)
argument_default - Глобальное значение по умолчанию для аргументов (по умолчанию: None)
conflict_handler - Стратегия разрешения конфликтов необязательных аргументов (обычно не требуется)
add_help - Добавить опцию справки в парсер (по умолчанию: True)

В следующих разделах описывается использование каждого из этих параметров.

2.1. prog

По умолчанию, объекты ArgumentParser используют sys.argv[0] для определения способа отображения имени программы в сообщениях справки. Этот параметр по умолчанию почти всегда желателен, поскольку он позволит сообщениям справки соответствовать тому, как программа была вызвана в командной строке. Например, рассмотрим файл под именем myprogram.py со следующим кодом:

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

Справка для этой программы отобразит myprogram.py в качестве имени программы (независимо от того, откуда была вызвана программа):

$ 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

Чтобы изменить это поведение по умолчанию, можно указать другое значение, используя аргумент prog= в 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

2.2. usage

По умолчанию, ArgumentParser рассчитывает сообщение об использовании из содержащихся в нём аргументов:

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

Сообщению об использовании можно присвоить значение с помощью ключевого аргумента usage=:

>>> 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 доступен для вставки имени программы в сообщения об использовании.

2.3. description

Большинство вызовов конструктора ArgumentParser используют ключевой аргумент description=. Этот аргумент дает краткое описание того, что делает программа и как она работает. В сообщениях справки описание отображается между строкой использования командной строки и справкой по различным аргументам:

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

2.4. epilog

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

2.5. parents

Иногда несколько парсеров используют общий набор аргументов. Вместо повторения определений этих аргументов можно использовать один парсер со всеми общими аргументами и передать его в аргумент 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=. Если вы измените родительские парсеры после дочернего парсера, эти изменения не будут отражены в дочернем.

2.6. formatter_class

ArgumentParser объекты позволяют настраивать форматирование справки, указав альтернативный класс форматирования. В настоящее время существует три таких класса:

class argparse.RawDescriptionHelpFormatter
class argparse.RawTextHelpFormatter
class argparse.ArgumentDefaultsHelpFormatter

Первые два обеспечивают больший контроль над отображением текстовых описаний, а последний автоматически добавляет информацию о значениях по умолчанию аргументов.

По умолчанию, объекты ArgumentParser разбивают на строки текст описания и эпилога в сообщениях справки командной строки:

>>> 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= указывает, что описание и эпилог уже отформатированы должным образом и не должны разбиваться на строки:

>>> 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 сохраняет отступы для всего текста справки, включая описания аргументов. Однако несколько новых строк заменяются одной. Если вы хотите сохранить несколько пустых строк, добавьте пробелы между новыми строками.

Другой доступный класс форматирования, 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 [bar ...]]

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

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

2.7. prefix_chars

Большинство опций командной строки используют - в качестве префикса, например, -f/--foo. Парсеры, которым необходимо поддерживать различные или дополнительные символы префикса, например, для опций, таких как +f или /foo, могут указать их, используя аргумент prefix_chars= конструктора ArgumentParser:

>>> 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 опций.

2.8. fromfile_prefix_chars

Иногда, например, при работе с длинными списками аргументов, может быть целесообразно хранить список аргументов в файле вместо ввода их в командной строке. Если аргумент fromfile_prefix_chars= передан конструктору ArgumentParser, то аргументы, начинающиеся с любого указанного символа, будут обрабатываться как файлы и будут заменены аргументами, которые они содержат. Например:

>>> 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', 'bar'].

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

2.9. argument_default

Обычно значения по умолчанию аргументов задаются либо путем передачи значения по умолчанию методу 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()

2.10. conflict_handler

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

Иногда (например, при использовании parents) может быть полезно просто переопределить более старые аргументы с той же строкой опции. Для получения этого поведения значение '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 была перезаписана.

2.11. add_help

По умолчанию объекты ArgumentParser добавляют опцию, которая просто отображает сообщение справки парсера. Например, рассмотрим файл под названием myprogram.py с кодом:

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

Если -h или --help указаны в командной строке, будет выведена справка ArgumentParser:

$ 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

3. The add_argument() method

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

Определяет, как должен анализироваться отдельный аргумент командной строки. Каждый параметр имеет свое более подробное описание ниже, но коротко они такие:

имя или флаги - Либо имя, либо список строк опций, например, foo или -f, --foo.
действие - Основной тип действия, которое должно быть выполнено при появлении этого аргумента в командной строке.
nargs - Количество аргументов командной строки, которые должны быть обработаны.
const - Постоянное значение, необходимое для некоторых действий и выборов nargs.
default - Значение, получаемое, если аргумент отсутствует в командной строке.
тип - Тип, к которому должен быть преобразован аргумент командной строки.
choices - Контейнер допустимых значений для аргумента.
required - Является ли аргумент обязательным (только для необязательных).
help - Краткое описание того, что делает аргумент.
metavar - Имя аргумента в сообщениях об использовании.
dest - Имя атрибута, который будет добавлен к объекту, возвращаемому методом parse_args().

Следующие разделы описывают, как каждое из них используется.

3.1. имя или флаги

Метод add_argument() должен знать, является ли аргумент необязательным, например, -f или --foo, или позиционным, например, списком имён файлов. Первые аргументы, передаваемые в add_argument(), должны быть либо серией флагов, либо простым именем аргумента. Например, необязательный аргумент можно создать так:

>>> 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: too few arguments

3.2. действие

ArgumentParser объекты связывают аргументы командной строки с действиями. Эти действия могут делать практически всё с аргументами командной строки, хотя большинство действий просто добавляет атрибут к объекту, возвращаемому parse_args(). Аргумент action определяет, как должны обрабатываться аргументы командной строки. Доступные действия:

'store' — просто сохраняет значение аргумента. Это значение по умолчанию. Например:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args('--foo 1'.split())
Namespace(foo='1')
```
'store_const' — сохраняет значение, указанное аргументом const. Действие 'store_const' чаще всего используется с необязательными аргументами, которые задают некий флаг. Например:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
```
'store_true' и 'store_false' — это специальные случаи 'store_const' для хранения значений True и False соответственно. Кроме того, они создают значения по умолчанию False и 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(bar=False, baz=True, foo=True)
```
'append' — хранит список и добавляет каждое значение аргумента в список. Это полезно, если опцию можно указать несколько раз. Пример использования:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])
```
'append_const' — хранит список и добавляет значение, указанное аргументом const, в список. (Обратите внимание, что аргумент const имеет значение по умолчанию None.) Действие 'append_const' обычно полезно, когда несколько аргументов должны хранить константы в одном списке. Например:
```
>>> 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=[<type 'str'>, <type 'int'>])
```
'count' — подсчитывает количество раз, когда встречается аргумент. Например, это полезно для изменения уровня подробности:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count')
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
```
'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

Также можно указать любое действие, передав подкласс Action или другой объект, реализующий тот же интерфейс. Рекомендуется расширить Action, переопределив метод __call__ и необязательно метод __init__.

Пример пользовательского действия:

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super(FooAction, self).__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.

3.3. nargs

Объекты ArgumentParser обычно связывают один аргумент командной строки с одним действием. Аргумент nargs связывает различное количество аргументов командной строки с одним действием. Поддерживаемые значения:

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=<open file 'input.txt', mode 'r' at 0x...>,
          outfile=<open file 'output.txt', mode 'w' at 0x...>)
>>> parser.parse_args([])
Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>,
          outfile=<open file '<stdout>', mode 'w' at 0x...>)
```
'*'. Все аргументы командной строки, присутствующие в списке, собираются в список. Обратите внимание, что обычно не имеет большого смысла иметь более одного позиционного аргумента с 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: too few arguments
```

argparse.REMAINDER. Все оставшиеся аргументы командной строки собираются в список. Это часто бывает полезно для утилит командной строки, которые направляют вызов другим утилитам командной строки:
```
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo')
>>> parser.add_argument('command')
>>> parser.add_argument('args', nargs=argparse.REMAINDER)
>>> print parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())
Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
```

Если аргумент nargs не предоставлен, количество потребляемых аргументов определяется действием action. Как правило, это означает, что будет потреблён один аргумент командной строки и будет произведён один элемент (а не список).

3.4. const

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

Когда add_argument() вызывается с action='store_const' или action='append_const'. Эти действия добавляют значение const в один из атрибутов объекта, возвращаемого parse_args(). Примеры см. в описании action.
Когда add_argument() вызывается со строками опций (например, -f или --foo) и nargs='?'. Это создаёт необязательный аргумент, за которым может следовать ноль или один аргумент командной строки. При обработке командной строки, если встречается строка опции без последующего аргумента командной строки, используется значение const вместо него. Примеры см. в описании nargs.

Для действий 'store_const' и 'append_const' аргумент const должен быть задан. Для других действий он имеет значение по умолчанию None.

3.5. значение по умолчанию

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

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

Если значение 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')

3.6. тип

По умолчанию объекты ArgumentParser считывают аргументы командной строки как простые строки. Однако довольно часто строка командной строки должна интерпретироваться как другой тип, например, float или int. Аргумент type метода add_argument() позволяет выполнить необходимые проверки типа и преобразования типа. Стандартные встроенные типы и функции могут быть использованы непосредственно как значение аргумента type:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=file)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2)

См. раздел о ключевом аргументе default, чтобы узнать, когда аргумент type применяется к аргументам по умолчанию.

Для удобства работы с различными типами файлов модуль argparse предоставляет фабрику FileType, которая принимает аргументы mode= и bufsize= объекта file. Например, FileType('w') можно использовать для создания записываемого файла:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)

type= может принимать любой вызываемый объект, который принимает один строковый аргумент и возвращает преобразованное значение:

>>> def perfect_square(string):
...     value = int(string)
...     sqrt = math.sqrt(value)
...     if sqrt != int(sqrt):
...         msg = "%r is not a perfect square" % string
...         raise argparse.ArgumentTypeError(msg)
...     return value
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square

Ключевой аргумент choices может быть более удобен для средств проверки типов, которые просто проверяют значения на соответствие диапазону:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=xrange(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

См. раздел choices для получения более подробной информации.

3.7. choices

Некоторые аргументы командной строки должны выбираться из ограниченного набора значений. Это можно сделать, передав контейнерный объект как ключевой аргумент choices в add_argument(). При разборе командной строки значения аргументов будут проверены, и будет выведено сообщение об ошибке, если аргумент не является одним из допустимых значений:

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

Обратите внимание, что проверка на включение в контейнер choices выполняется после любых преобразований типа type, поэтому тип объектов в контейнере choices должен соответствовать типу, указанному в type:

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

Любой объект, поддерживающий оператор in, может быть передан в качестве значения choices, поэтому объекты dict, объекты set, пользовательские контейнеры и т. д. также поддерживаются.

3.8. required

В целом, модуль argparse предполагает, что флаги, такие как -f и --bar, обозначают необязательные аргументы, которые всегда можно опустить в командной строке. Чтобы сделать опцию обязательной, можно указать True для ключевого аргумента required= в add_argument():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required

Как показывает пример, если опция помечена как required, parse_args() сообщит об ошибке, если эта опция отсутствует в командной строке.

Примечание

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

3.9. help

Значение help — это строка, содержащая краткое описание аргумента. Когда пользователь запрашивает справку (обычно используя -h или --help в командной строке), эти описания help будут отображаться с каждым аргументом:

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

argparse поддерживает отключение записи справки для определённых опций, установив значение help в 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

3.10. metavar

Когда ArgumentParser генерирует сообщения справки, ему нужен способ сослаться на каждый ожидаемый аргумент. По умолчанию объекты ArgumentParser используют значение dest в качестве «имени» каждого объекта. По умолчанию для позиционных аргументов действия используется значение dest напрямую, а для необязательных аргументов действий значение dest приводится к верхнему регистру. Таким образом, один позиционный аргумент с dest='bar' будет обозначен как bar. Один необязательный аргумент --foo, за которым должен следовать один аргумент командной строки, будет обозначен как FOO. Пример:

>>> 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. Передача кортежа в 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

3.11. dest

Большинство действий 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')

3.12. Классы действий

Классы действий реализуют API действий, вызываемый объект, который возвращает вызываемый объект, обрабатывающий аргументы из командной строки. Любой объект, соответствующий этому API, может быть передан в качестве параметра action в 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 используются ArgumentParser для представления информации, необходимой для разбора одного аргумента из одной или нескольких строк командной строки. Класс Action должен принимать два позиционных аргумента плюс любые ключевые аргументы, переданные в ArgumentParser.add_argument(), за исключением самого action.

Экземпляры Action (или возвращаемое значение любого вызываемого объекта параметра action должны иметь определённые атрибуты «dest», «option_strings», «default», «type», «required», «help» и т. д. Самый простой способ гарантировать определение этих атрибутов — вызвать Action.__init__.

Объекты Action должны быть вызываемыми, поэтому подклассы должны переопределять метод __call__, который должен принимать четыре параметра:

parser — Объект ArgumentParser, содержащий это действие.
namespace — Объект Namespace, который будет возвращён методом parse_args(). Большинство действий добавляют атрибут в этот объект с помощью setattr().
values — Аргументы командной строки с применёнными преобразованиями типа. Преобразования типов задаются ключевым аргументом type в add_argument().
option_string — Строка опции, которая была использована для вызова этого действия. Аргумент option_string является необязательным и отсутствует, если действие связано с позиционным аргументом.

Метод __call__ может выполнять произвольные действия, но обычно устанавливает атрибуты в объекте namespace на основе dest и values.

4. Метод parse_args()

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

Преобразуйте строки аргументов в объекты и назначьте их как атрибуты пространства имен. Верните заполненное пространство имен.

Предыдущие вызовы add_argument() определяют точно, какие объекты создаются и как они назначаются. См. документацию по add_argument() для получения подробностей.

args - Список строк для разбора. По умолчанию берется из sys.argv.
namespace - Объект, которому будут назначены атрибуты. По умолчанию создается новый пустой объект Namespace.

4.1. Синтаксис значения параметра

Метод 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')

4.2. Некорректные аргументы

Во время разбора командной строки 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

4.3. Аргументы, содержащие `-`

Метод 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)

4.4. Сокращения аргументов (совпадение по префиксу)

Метод 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

Ошибка генерируется для аргументов, которые могут соответствовать нескольким параметрам.

4.5. Выходя за рамки `sys.argv`

Иногда может быть полезно, чтобы ArgumentParser анализировал аргументы, отличные от тех, что находятся в sys.argv. Этого можно добиться, передав список строк методу parse_args(). Это полезно для тестирования в интерактивном режиме:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
...     'integers', metavar='int', type=int, choices=xrange(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])

4.6. Объект Namespace

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

Этот класс преднамеренно прост, это просто подкласс object с читаемым строковым представлением. Если вы предпочитаете иметь представление об атрибутах в виде словаря, вы можете использовать стандартный Python-идиом vars():

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

Также может быть полезно, чтобы ArgumentParser назначал атрибуты уже существующему объекту, а не новому объекту Namespace. Этого можно добиться, указав ключевой аргумент namespace=:

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

5. Другие утилиты

5.1. Подкоманды

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

Многие программы разбивают свою функциональность на множество подкоманд, например, программа svn может вызывать подкоманды, такие как svn checkout, svn update, и svn commit. Такое разделение функциональности может быть особенно полезным, когда программа выполняет несколько различных функций, которые требуют различных типов аргументов командной строки. ArgumentParser поддерживает создание таких подкоманд с помощью метода add_subparsers(). Метод add_subparsers() обычно вызывается без аргументов и возвращает специальный объект действия. Этот объект имеет один метод, add_parser(), который принимает имя команды и любые аргументы конструктора ArgumentParser, и возвращает объект ArgumentParser, который можно изменять как обычно.

Описание параметров:

title - заголовок группы подпарсеров в выводе справки; по умолчанию «подкоманды», если описание предоставлено, в противном случае используется заголовок для позиционных аргументов
description - описание группы подпарсеров в выводе справки, по умолчанию None
prog - информация об использовании, которая будет отображаться со справкой по подкомандам; по умолчанию имя программы и любые позиционные аргументы перед аргументом подпарсера
parser_class - класс, который будет использоваться для создания экземпляров подпарсеров; по умолчанию класс текущего парсера (например, ArgumentParser)
действие - базовый тип действия, которое должно быть выполнено, когда этот аргумент встретится в командной строке
dest - имя атрибута, в котором будет храниться имя подкоманды; по умолчанию None и значение не сохраняется
help - справка по группе подпарсеров в выводе справки, по умолчанию None
metavar - строка, представляющая доступные подкоманды в справке; по умолчанию None и представляет подкоманды в формате {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.

Аналогично, когда запрашивается сообщение справки от подпарсера, будет напечатана только справка по этому конкретному парсеру. Сообщение справки не будет включать сообщения родительского парсера или парсеров-братьев. (Сообщение справки для каждой подкоманды подпарсера, однако, можно задать, передав аргумент help= в add_parser() как показано выше.)

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

Один из особенно эффективных способов обработки подкоманд — это сочетание использования метода add_subparsers() с вызовами set_defaults(), чтобы каждый подпарсер знал, какую функцию Python он должен выполнить. Например:

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

5.2. Объекты FileType

class argparse.FileType(mode='r', bufsize=None)

Фабрика FileType создает объекты, которые могут быть переданы в аргумент типа метода ArgumentParser.add_argument(). Аргументы, у которых объекты FileType являются их типом, будут открывать аргументы командной строки как файлы с запрошенными режимами и размерами буфера:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
>>> parser.parse_args(['--output', 'out'])
Namespace(output=<open file 'out', mode 'wb' at 0x...>)

Объекты FileType понимают псевдоаргумент '-' и автоматически преобразуют его в sys.stdin для читаемых объектов FileType и sys.stdout для записываемых объектов FileType:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>)

5.3. Группы аргументов

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

По умолчанию, ArgumentParser группирует аргументы командной строки в «позиционные аргументы» и «опциональные аргументы» при отображении сообщений справки. Когда существует лучшая концептуальная группировка аргументов, чем эта по умолчанию, соответствующие группы можно создать, используя метод add_argument_group():

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

group:
  bar    bar help
  --foo FOO  foo help

Метод add_argument_group() возвращает объект группы аргументов, у которого есть метод add_argument(), как у обычного ArgumentParser. Когда аргумент добавляется в группу, парсер обрабатывает его так же, как обычный аргумент, но отображает аргумент в отдельной группе для сообщений справки. Метод add_argument_group() принимает аргументы title и description, которые могут использоваться для настройки этого отображения:

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

Обратите внимание, что любые аргументы, не входящие в ваши пользовательские группы, будут возвращены в обычные разделы «позиционные аргументы» и «опциональные аргументы».

5.4. Взаимоисключение

ArgumentParser.add_mutually_exclusive_group(required=False)

Создайте группу взаимоисключающих аргументов. argparse будет гарантировать, что только один из аргументов в группе взаимоисключения присутствовал в командной строке:

>>> 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() также принимает аргумент required, чтобы указать, что по крайней мере один из взаимоисключающих аргументов обязателен:

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

Обратите внимание, что в настоящее время группы взаимоисключающих аргументов не поддерживают аргументы title и description метода add_argument_group().

5.5. Значения по умолчанию парсера

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'

5.6. Вывод справки

В большинстве типовых приложений 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.

5.7. Частичный парсинг

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

Предупреждение

Правила сопоставления по префиксу применяются к parse_known_args(). Парсер может использовать опцию, даже если она является только префиксом одной из известных опций, вместо того, чтобы оставить её в списке оставшихся аргументов.

5.8. Настройка парсинга файлов

ArgumentParser.convert_arg_line_to_args(arg_line)

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

Этот метод принимает один аргумент arg_line, который является строкой, считанной из файла аргументов. Он возвращает список аргументов, разобранных из этой строки. Метод вызывается один раз на каждую строку, считанную из файла аргументов, в порядке.

Полезным переопределением этого метода является тот, который обрабатывает каждое слово, разделенное пробелом, как аргумент:

def convert_arg_line_to_args(self, arg_line):
    return arg_line.split()

5.9. Методы завершения

ArgumentParser.exit(status=0, message=None): Этот метод завершает программу, завершая её с указанным статусом и, если задано, он выводит сообщение перед этим.

ArgumentParser.error(message): Этот метод выводит сообщение об использовании, включая сообщение, в стандартный вывод ошибок и завершает программу со статусом 2.

6. Обновление кода optparse

Изначально модуль argparse пытался сохранить совместимость с optparse. Однако optparse было сложно расширять прозрачно, особенно с изменениями, необходимыми для поддержки новых nargs= спецификаторов и улучшенных сообщений об использовании. Когда почти всё в optparse было либо скопировано, либо подправлено, уже не казалось практичным сохранять обратную совместимость.

Модуль argparse улучшает модуль стандартной библиотеки optparse во многих отношениях, включая:

Обработку позиционных аргументов.
Поддержку подкоманд.
Поддержку альтернативных префиксов опций, таких как + и /.
Обработку аргументов типа «ноль или более» и «один или более».
Генерацию более информативных сообщений об использовании.
Предоставление гораздо более простого интерфейса для пользовательских type и action.

Частичный путь обновления от optparse до argparse:

Замените все вызовы optparse.OptionParser.add_option() на вызовы ArgumentParser.add_argument().
Замените (options, args) = parser.parse_args() на args = parser.parse_args() и добавьте дополнительные вызовы ArgumentParser.add_argument() для позиционных аргументов. Имейте в виду, что то, что ранее называлось options, теперь в контексте argparse называется args.
Замените optparse.OptionParser.disable_interspersed_args() установкой nargs позиционного аргумента на argparse.REMAINDER или используйте parse_known_args() для сбора необработанных аргументов в отдельном списке.
Замените действия обратного вызова и ключевые аргументы callback_* на аргументы type или action.
Замените строковые имена для ключевых аргументов type соответствующими объектами типов (например, int, float, complex и т. д.).
Замените optparse.Values на Namespace и optparse.OptionError и optparse.OptionValueError на ArgumentError.
Замените строки с неявными аргументами, такими как %default или %prog, стандартным синтаксисом Python для использования словарей для форматирования строк, то есть %(default)s и %(prog)s.
Замените аргумент конструктора OptionParser version вызовом parser.add_argument('--version', action='version', version='<the version>').