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

Новая версия с 3.2.

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

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

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

Следующие разделы помогут вам разобраться с этим примером.

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

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

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

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

16.4.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(), если нет.

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

16.4.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, allow_abbrev=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 - Добавить опцию справки в парсер (по умолчанию: -h/--help)
allow_abbrev - Разрешает сокращения длинных опций, если сокращение однозначно. (по умолчанию: True)

Изменено в версии 3.5: Параметр allow_abbrev был добавлен.

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

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

16.4.2.2. usage

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

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

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

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

16.4.2.5. Родительские парсеры

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

16.4.2.6. Класс форматирования

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

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)

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

16.4.2.7. Символы префикса

Большинство опций командной строки используют - в качестве префикса, например, -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 станут недоступными.

16.4.2.8. Символы префикса для файлов

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

16.4.2.9. Значение по умолчанию аргумента

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

16.4.2.10. Разрешение сокращений

Обычно, когда вы передаете список аргументов методу 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.

16.4.2.11. Обработчик конфликтов

Объекты 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 была перезаписана.

16.4.2.12. Добавление опции справки

По умолчанию объекты 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

16.4.3. Метод add_argument()

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

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

имя или флаги - либо имя, либо список строк-флагов, например foo или -f, --foo.
действие - основной тип действия, которое должно быть выполнено, когда этот аргумент встречен в командной строке.
nargs - количество аргументов командной строки, которые должны быть использованы.
const - константное значение, требуемое некоторыми действиями и nargs.
значение по умолчанию - значение, которое используется, если аргумент отсутствует в командной строке.
тип - тип, в который должен быть преобразован аргумент командной строки.
допустимые значения - контейнер допустимых значений для аргумента.
обязательный - является ли аргумент командной строки обязательным (только для необязательных).
подсказка - краткое описание того, что делает аргумент.
метапеременная - имя аргумента в сообщениях справки.
dest - имя атрибута, которое будет добавлено в объект, возвращаемый parse_args().

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

16.4.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: the following arguments are required: bar

16.4.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(foo=True, bar=False, baz=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=[<class 'str'>, <class '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.

16.4.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=<_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
```

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. Обычно это означает, что будет потреблён один аргумент командной строки и будет произведён один элемент (а не список).

16.4.3.4. const

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

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

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

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

16.4.3.6. тип

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

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)

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

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

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)

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=range(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 для получения более подробной информации.

16.4.3.7. Варианты

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

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

16.4.3.8. обязательный

В целом, модуль 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() сообщит об ошибке, если эта опция отсутствует в командной строке.

Примечание

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

16.4.3.9. справка

Значение 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

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

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

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

Объекты действия используются объектом 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.

16.4.4. Метод parse_args()

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

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

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

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

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

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

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

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

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

16.4.4.5. Выход за пределы `sys.argv`

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

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

16.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:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

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

16.4.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_parser поддерживает дополнительный аргумент aliases, который позволяет нескольким строкам ссылаться на один и тот же подпарсер. В этом примере, как и в svn, co используется как сокращение для checkout:

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

Один из особенно эффективных способов обработки подкоманд — это сочетание использования метода add_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')

16.4.5.2. Объекты FileType

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

Фабрика FileType создаёт объекты, которые могут передаваться в аргумент type метода 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 понимают псевдоаргумент '-' и автоматически преобразуют его в sys.stdin для читаемых объектов FileType и sys.stdout для записываемых объектов FileType:

>>> 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: Ключевые аргументы encodings и errors.

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

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

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

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

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

16.4.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(). Парсер может обработать опцию, даже если это просто префикс одной из известных опций, вместо того чтобы оставить её в списке оставшихся аргументов.

16.4.5.8. Настройка разбора файлов

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

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

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

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

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