argparse
— Парсер для опций, аргументов и подкоманд командной строки¶
Added in version 3.2.
Источник: Lib/argparse.py
Модуль argparse
позволяет легко писать удобные интерфейсы командной строки. Программа определяет, какие аргументы ей нужны, а argparse
разберется, как их разобрать из sys.argv
. Модуль argparse
также автоматически генерирует справку и сообщения об использовании. Модуль также будет выдавать ошибки, если пользователь укажет программе неверные аргументы.
Основная функциональность¶
Поддержка интерфейсов командной строки в модуле argparse
построена вокруг экземпляра argparse.ArgumentParser
. Он является контейнером для спецификаций аргументов и имеет опции, которые применяются к парсеру в целом:
parser = argparse.ArgumentParser(
prog='ProgramName',
description='What the program does',
epilog='Text at the bottom of help')
Метод ArgumentParser.add_argument()
подключает к парсеру индивидуальные спецификации аргументов. Он поддерживает позиционные аргументы, опции, принимающие значения, и флаги включения/выключения:
parser.add_argument('filename') # positional argument
parser.add_argument('-c', '--count') # option that takes a value
parser.add_argument('-v', '--verbose',
action='store_true') # on/off flag
Метод ArgumentParser.parse_args()
запускает парсер и помещает извлеченные данные в объект argparse.Namespace
:
args = parser.parse_args()
print(args.filename, args.count, args.verbose)
Быстрые ссылки для add_argument()¶
Имя |
Описание |
Значения |
---|---|---|
Укажите, как следует обрабатывать аргумент |
|
|
Ограничьте значения определенным набором вариантов |
экземпляр |
|
Сохранить постоянное значение |
||
по умолчанию |
Значение по умолчанию, используемое, когда аргумент не указан |
По умолчанию |
Укажите имя атрибута, используемое в пространстве имен результата |
||
Справочное сообщение для аргумента |
||
Альтернативное отображаемое имя аргумента, как показано в справке |
||
Количество раз, когда аргумент может быть использован |
|
|
Укажите, является ли аргумент обязательным или необязательным |
|
|
Автоматическое преобразование аргумента к заданному типу |
Пример¶
Следующий код представляет собой программу на языке 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
options:
-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'
В следующих разделах мы рассмотрим этот пример.
Создание парсера¶
Первым шагом в использовании argparse
является создание объекта ArgumentParser
:
>>> parser = argparse.ArgumentParser(description='Process some integers.')
Объект ArgumentParser
будет содержать всю информацию, необходимую для разбора командной строки на типы данных Python.
Добавление аргументов¶
Наполнение 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()
, если он не был указан.
Разбор аргументов¶
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
.
Объекты ArgumentParser¶
- class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)¶
Создайте новый объект
ArgumentParser
. Все параметры должны передаваться как аргументы с ключевым словом. Каждый параметр имеет свое более подробное описание ниже, но вкратце они таковы:prog - Имя программы (по умолчанию:
os.path.basename(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
к парсеру (по умолчанию:True
)allow_abbrev - Разрешает сокращать длинные опции, если сокращение однозначно. (по умолчанию:
True
)exit_on_error - Определяет, будет ли ArgumentParser выходить с информацией об ошибке при возникновении ошибки. (по умолчанию:
True
)
Изменено в версии 3.5: Добавлен параметр allow_abbrev.
Изменено в версии 3.8: В предыдущих версиях allow_abbrev также запрещала группировать короткие флаги, такие как
-vv
, в значения-v -v
.Изменено в версии 3.9: Добавлен параметр exit_on_error.
В следующих разделах описано, как используется каждый из них.
прог¶
По умолчанию объекты 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]
options:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
options:
-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]
options:
-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]
options:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
использование¶
По умолчанию 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
options:
-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
options:
-h, --help show this help message and exit
--foo [FOO] foo help
Спецификатор формата %(prog)s
доступен для заполнения имени программы в сообщениях об использовании.
описание¶
В большинстве обращений к конструктору ArgumentParser
будет использоваться аргумент description=
с ключевым словом. Этот аргумент дает краткое описание того, что делает программа и как она работает. В справочных сообщениях описание отображается между строкой использования командной строки и справочными сообщениями для различных аргументов:
>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
options:
-h, --help show this help message and exit
По умолчанию описание будет свернуто в строку так, чтобы оно поместилось в заданное пространство. Чтобы изменить это поведение, смотрите аргумент formatter_class.
эпилог¶
Некоторые программы любят выводить дополнительное описание программы после описания аргументов. Такой текст можно указать с помощью аргумента epilog=
в ArgumentParser
:
>>> parser = argparse.ArgumentParser(
... description='A foo that bars',
... epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
options:
-h, --help show this help message and exit
And that's how you'd foo a bar
Как и в случае с аргументом description, текст epilog=
по умолчанию разворачивается в строку, но это поведение можно изменить с помощью аргумента formatter_class на ArgumentParser
.
родители¶
Иногда несколько парсеров используют общий набор аргументов. Вместо того чтобы повторять определения этих аргументов, можно использовать один парсер со всеми общими аргументами и передавать parents=
аргумент в ArgumentParser
. Аргумент parents=
принимает список объектов ArgumentParser
, собирает из них все позиционные и необязательные действия и добавляет эти действия в конструируемый объект ArgumentParser
:
>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)
>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)
>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)
Обратите внимание, что большинство родительских парсеров будут указывать add_help=False
. В противном случае ArgumentParser
увидит два варианта -h/--help
(один в родительском, другой в дочернем) и выдаст ошибку.
Примечание
Вы должны полностью инициализировать парсеры, прежде чем передавать их через parents=
. Если вы измените родительский парсер после создания дочернего парсера, эти изменения не будут отражены в дочернем.
класс_форматера¶
Объекты ArgumentParser
позволяют настраивать форматирование справки, указывая альтернативный класс форматирования. В настоящее время существует четыре таких класса:
- class argparse.RawDescriptionHelpFormatter¶
- class argparse.RawTextHelpFormatter¶
- class argparse.ArgumentDefaultsHelpFormatter¶
- class argparse.MetavarTypeHelpFormatter¶
Объекты RawDescriptionHelpFormatter
и RawTextHelpFormatter
дают больше возможностей для управления отображением текстовых описаний. По умолчанию объекты 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
options:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
Передача 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
options:
-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 ...]
positional arguments:
bar BAR! (default: [1, 2, 3])
options:
-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
options:
-h, --help show this help message and exit
--foo int
префиксные_значки¶
В большинстве опций командной строки в качестве префикса используется -
, например -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
будут запрещены.
fromfile_prefix_chars¶
Иногда, когда приходится иметь дело с особенно длинным списком аргументов, имеет смысл хранить список аргументов в файле, а не набирать его в командной строке. Если конструктору ArgumentParser
указан аргумент fromfile_prefix_chars=
, то аргументы, начинающиеся с любого из указанных символов, будут рассматриваться как файлы и заменяться аргументами, которые в них содержатся. Например:
>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:
... fp.write('-f\nbar')
...
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')
Аргументы, считываемые из файла, по умолчанию должны быть по одному в строке (но см. также convert_arg_line_to_args()
) и рассматриваются так, как если бы они находились на том же месте, что и исходный аргумент, ссылающийся на файл в командной строке. Поэтому в приведенном выше примере выражение ['-f', 'foo', '@args.txt']
считается эквивалентным выражению ['-f', 'foo', '-f', 'bar']
.
ArgumentParser
использует filesystem encoding and error handler для чтения файла с аргументами.
Аргумент fromfile_prefix_chars=
по умолчанию принимает значение None
, что означает, что аргументы никогда не будут рассматриваться как ссылки на файлы.
Изменено в версии 3.12: ArgumentParser
изменил кодировку и ошибки при чтении файлов аргументов со стандартных (например, locale.getpreferredencoding(False)
и "strict"
) на filesystem encoding and error handler. Файл аргументов должен быть закодирован в UTF-8 вместо ANSI Codepage в Windows.
аргумент_по умолчанию¶
Обычно значения аргументов по умолчанию задаются либо путем передачи значения по умолчанию в 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()
allow_abbrev¶
Обычно, когда вы передаете список аргументов методу parse_args()
в ArgumentParser
, он recognizes abbreviations состоит из длинных опций.
Эту функцию можно отключить, установив значение 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
Added in version 3.5.
обработчик конфликтов¶
Объекты ArgumentParser
не допускают двух действий с одной и той же строкой опций. По умолчанию объекты ArgumentParser
вызывают исключение, если пытаются создать аргумент со строкой опций, которая уже используется:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
..
ArgumentError: argument --foo: conflicting option string(s): --foo
Иногда (например, при использовании 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]
options:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
Обратите внимание, что объекты ArgumentParser
удаляют действие только в том случае, если все его строки опций переопределены. Так, в приведенном выше примере старое действие -f/--foo
сохраняется как действие -f
, поскольку была переопределена только строка опций --foo
.
add_help¶
По умолчанию объекты 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]
options:
-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]
options:
--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]
options:
+h, ++help show this help message and exit
выход_при_ошибке¶
Обычно, когда вы передаете некорректный список аргументов методу parse_args()
в ArgumentParser
, он завершается с информацией об ошибке.
Если пользователь хочет отлавливать ошибки вручную, эту функцию можно включить, установив значение exit_on_error
на False
:
>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
... parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
... print('Catching an argumentError')
...
Catching an argumentError
Added in version 3.9.
Метод add_argument()¶
- ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])¶
Определяет, как должен быть разобран один аргумент командной строки. Ниже приводится более подробное описание каждого параметра, но вкратце они таковы:
name or flags - Либо имя, либо список строк опций, например,
foo
или-f, --foo
.action - Основной тип действия, которое будет выполнено при встрече этого аргумента в командной строке.
nargs - Количество аргументов командной строки, которые должны быть использованы.
const - Постоянное значение, требуемое некоторыми выборами action и nargs.
default - Значение, получаемое, если аргумент отсутствует в командной строке и если он отсутствует в объекте пространства имен.
type - Тип, в который должен быть преобразован аргумент командной строки.
choices - последовательность допустимых значений для аргумента.
required - Можно ли опустить опцию командной строки (только для опций).
help - Краткое описание того, что делает аргумент.
metavar - имя аргумента в сообщениях об использовании.
dest - Имя атрибута, который будет добавлен к объекту, возвращенному командой
parse_args()
.deprecated - Является ли использование аргумента устаревшим или нет.
В следующих разделах описано, как используется каждый из них.
имя или флаги¶
Метод 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
действие¶
Объекты ArgumentParser
связывают аргументы командной строки с действиями. Эти действия могут делать практически все, что угодно с аргументами командной строки, связанными с ними, хотя большинство действий просто добавляют атрибут к объекту, возвращаемому parse_args()
. Ключевой аргумент action
определяет, как следует обрабатывать аргументы командной строки. В комплект поставки входят следующие действия:
'store'
- Это просто сохраняет значение аргумента. Это действие по умолчанию. Например:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo') >>> parser.parse_args('--foo 1'.split()) Namespace(foo='1')
'store_const'
- В этом случае сохраняется значение, указанное аргументом ключевого слова const; обратите внимание, что аргумент ключевого слова const по умолчанию принимает значениеNone
. Действие'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', default=0) >>> parser.parse_args(['-vvv']) Namespace(verbose=3)
Обратите внимание, что по умолчанию будет
None
, если явно не установлено значение 0.'help'
- Выводит полное справочное сообщение для всех опций текущего парсера и завершает работу. По умолчанию действие помощи автоматически добавляется к парсеру. Подробности о том, как создается вывод, см. в разделеArgumentParser
.'version'
- Эта функция ожидает аргументversion=
в виде ключевого слова в вызовеadd_argument()
, печатает информацию о версии и завершает работу при вызове:>>> import argparse >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0') >>> parser.parse_args(['--version']) PROG 2.0
'extend'
- Хранит список и расширяет каждое значение аргумента до списка. Пример использования:>>> parser = argparse.ArgumentParser() >>> parser.add_argument("--foo", action="extend", nargs="+", type=str) >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"]) Namespace(foo=['f1', 'f2', 'f3', 'f4'])
Added in version 3.8.
Вы также можете указать произвольное действие, передав подкласс Action или другой объект, реализующий тот же интерфейс. В BooleanOptionalAction
доступен argparse
и добавляет поддержку булевых действий, таких как --foo
и --no-foo
:
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)
Added in version 3.9.
Рекомендуемый способ создания пользовательского действия - расширить Action
, переопределив метод __call__
и, по желанию, методы __init__
и format_usage
.
Пример пользовательского действия:
>>> class FooAction(argparse.Action):
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
... if nargs is not None:
... raise ValueError("nargs not allowed")
... super().__init__(option_strings, dest, **kwargs)
... def __call__(self, parser, namespace, values, option_string=None):
... print('%r %r %r' % (namespace, values, option_string))
... setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')
Более подробную информацию смотрите в разделе Action
.
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
Если ключевой аргумент nargs
не указан, количество потребляемых аргументов определяется действием. Обычно это означает, что будет использован один аргумент командной строки и получен один элемент (не список).
const¶
Аргумент const
в add_argument()
используется для хранения постоянных значений, которые не считываются из командной строки, но требуются для выполнения различных действий ArgumentParser
. Наиболее часто он используется в двух случаях:
Когда
add_argument()
вызывается вместе сaction='store_const'
илиaction='append_const'
. Эти действия добавляют значениеconst
к одному из атрибутов объекта, возвращаемогоparse_args()
. Примеры см. в описании действия. Еслиconst
не указан вadd_argument()
, он получит значение по умолчаниюNone
.При вызове
add_argument()
со строками опций (например,-f
или--foo
) иnargs='?'
. Это создает дополнительный аргумент, за которым может следовать ноль или один аргумент командной строки. При разборе командной строки, если встречается строка опций без следующего за ней аргумента командной строки, вместо значенияconst
будет принято значениеNone
. Примеры см. в описании nargs.
Изменено в версии 3.11: const=None
по умолчанию, в том числе при action='append_const'
или action='store_const'
.
по умолчанию¶
Все необязательные аргументы и некоторые позиционные аргументы могут быть опущены в командной строке. Аргумент 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 не будет его перезаписывать:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)
Если значение default
является строкой, парсер разбирает его так, как если бы это был аргумент командной строки. В частности, синтаксический анализатор применяет любой аргумент преобразования type, если он был предоставлен, перед установкой атрибута в возвращаемое значение Namespace
. В противном случае синтаксический анализатор использует значение как есть:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)
Для позиционных аргументов с nargs, равными ?
или *
, используется значение default
, если аргумент командной строки не присутствовал:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)
Если указать default=argparse.SUPPRESS
, то атрибут не будет добавлен, если аргумент командной строки не присутствовал:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')
тип¶
По умолчанию парсер считывает аргументы командной строки как простые строки. Однако довольно часто строка командной строки должна быть интерпретирована как другой тип, например float
или int
. Ключевое слово type
для add_argument()
позволяет выполнить все необходимые проверки типов и преобразования типов.
Если ключевое слово type используется вместе с ключевым словом default, преобразование типа применяется только в том случае, если значение по умолчанию - строка.
Аргументом type
может быть любая вызываемая функция, принимающая одну строку. Если функция вызывает исключение ArgumentTypeError
, TypeError
или ValueError
, оно перехватывается и выводится сообщение об ошибке в хорошем формате. Никакие другие типы исключений не обрабатываются.
Обычные встроенные типы и функции могут использоваться в качестве преобразователей типов:
import argparse
import pathlib
parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)
Также можно использовать функции, заданные пользователем:
>>> def hyphenated(string):
... return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')
Функцию bool()
не рекомендуется использовать в качестве преобразователя типов. Она лишь преобразует пустые строки в False
, а непустые - в True
. Обычно это не то, что нужно.
В целом, ключевое слово type
- это удобство, которое следует использовать только для простых преобразований, которые могут вызвать только одно из трех поддерживаемых исключений. Все, что связано с более интересной обработкой ошибок или управлением ресурсами, должно выполняться после разбора аргументов.
Например, преобразования JSON или YAML имеют сложные случаи ошибок, которые требуют более точного отчета, чем может дать ключевое слово type
. Ключ JSONDecodeError
будет плохо отформатирован, а исключение FileNotFoundError
вообще не будет обработано.
Даже FileType
имеет свои ограничения для использования с ключевым словом type
. Если в одном аргументе используется FileType, а затем последующий аргумент не работает, сообщается об ошибке, но файл автоматически не закрывается. В этом случае лучше дождаться окончания работы синтаксического анализатора и затем использовать оператор with
для управления файлами.
Для программ проверки типов, которые просто проверяют фиксированный набор значений, вместо этого используйте ключевое слово 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)
В качестве значения choices может быть передана любая последовательность, поэтому поддерживаются объекты list
, tuple
и пользовательские последовательности.
Использовать enum.Enum
не рекомендуется, поскольку сложно контролировать его появление в сообщениях об использовании, справке и ошибках.
Форматированные варианты переопределяют стандартный metavar, который обычно выводится из dest. Обычно это то, что вам нужно, потому что пользователь никогда не видит параметр dest. Если такое отображение нежелательно (возможно, из-за большого количества вариантов), просто укажите явный metavar.
требуется¶
В общем случае модуль 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: [-h] --foo FOO
: error: the following arguments are required: --foo
Как показано в примере, если опция отмечена как required
, то parse_args()
сообщит об ошибке, если эта опция отсутствует в командной строке.
Примечание
Обязательные опции обычно считаются плохой формой, потому что пользователи ожидают, что опции будут опциональными, и поэтому их следует избегать, когда это возможно.
помощь¶
Значение 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
options:
-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)
options:
-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]
options:
-h, --help show this help message and exit
метавар¶
Когда 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
options:
-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
options:
-h, --help show this help message and exit
--foo YYY
Обратите внимание, что metavar
изменяет только отображаемое имя - имя атрибута в объекте parse_args()
по-прежнему определяется значением dest.
Различные значения nargs
могут привести к тому, что метаварь будет использоваться несколько раз. Предоставление кортежа в metavar
задает разное отображение для каждого из аргументов:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]
options:
-h, --help show this help message and exit
-x X X
--foo bar baz
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')
устаревшие¶
В течение жизни проекта некоторые аргументы могут потребоваться для удаления из командной строки. Перед их удалением необходимо сообщить пользователям, что эти аргументы устарели и будут удалены. Ключевое слово deprecated
аргумента add_argument()
, которое по умолчанию равно False
, указывает, является ли аргумент устаревшим и будет ли он удален в будущем. Если для аргументов deprecated
указано True
, то при использовании этого аргумента в стандартную ошибку будет выведено предупреждение:
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='snake.py')
>>> parser.add_argument('--legs', default=0, type=int, deprecated=True)
>>> parser.parse_args([])
Namespace(legs=0)
>>> parser.parse_args(['--legs', '4'])
snake.py: warning: option '--legs' is deprecated
Namespace(legs=4)
Изменено в версии 3.13.
Классы действий¶
Классы Action реализуют Action 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
.
Подклассы Action могут определить метод format_usage
, который не принимает аргументов и возвращает строку, которая будет использоваться при печати использования программы. Если такой метод не указан, будет использовано разумное значение по умолчанию.
Метод parse_args()¶
- ArgumentParser.parse_args(args=None, namespace=None)¶
Преобразуйте строки аргументов в объекты и присвойте их в качестве атрибутов пространства имен. Возвращает заполненное пространство имен.
Предыдущие вызовы
add_argument()
определяют, какие именно объекты будут созданы и как они будут назначены. Подробности см. в документации кadd_argument()
.
Синтаксис значения опции¶
Метод parse_args()
поддерживает несколько способов указания значения опции (если она принимает его). В простейшем случае опция и ее значение передаются как два отдельных аргумента:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)
Для длинных опций (опции с именами длиннее одного символа) опция и значение также могут быть переданы как один аргумент командной строки, используя =
для их разделения:
>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)
Для коротких опций (опции длиной всего в один символ) опция и ее значение могут быть объединены:
>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')
Несколько коротких опций можно объединить, используя только один префикс -
, если только последняя опция (или ни одна из них) требует значения:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')
Недопустимые аргументы¶
При разборе командной строки parse_args()
проверяет множество ошибок, включая двусмысленные опции, недопустимые типы, недействительные опции, неправильное количество позиционных аргументов и т. д. При обнаружении такой ошибки программа завершает работу и выводит ошибку вместе с сообщением об использовании:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')
>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'
>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar
>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger
Аргументы, содержащие -
¶
Метод parse_args()
пытается выдавать ошибки, когда пользователь явно ошибся, но некоторые ситуации по своей сути неоднозначны. Например, аргумент командной строки -1
может быть либо попыткой указать опцию, либо попыткой предоставить позиционный аргумент. Метод parse_args()
здесь осторожен: позиционные аргументы могут начинаться с -
, только если они выглядят как отрицательные числа, а в парсере нет опций, которые выглядят как отрицательные числа:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')
>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')
>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')
>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')
>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2
>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument
Если у вас есть позиционные аргументы, которые должны начинаться с -
и не похожи на отрицательные числа, вы можете вставить псевдоаргумент '--'
, который сообщает parse_args()
, что все последующее - это позиционный аргумент:
>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)
См. также the argparse howto on ambiguous arguments для более подробной информации.
Сокращения аргументов (сопоставление префиксов)¶
Метод parse_args()
by default позволяет сокращать длинные опции до префикса, если сокращение однозначно (префикс соответствует уникальной опции):
>>> 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
.
За пределами 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])
Объект «Пространство имен¶
- 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'
Другие утилиты¶
Подкоманды¶
- ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_strings][, dest][, required][, help][, metavar])¶
Многие программы разделяют свою функциональность на несколько подкоманд. Например, программа
svn
может вызывать такие подкоманды, какsvn checkout
,svn update
иsvn commit
. Такое разделение функциональности может быть особенно полезно, когда программа выполняет несколько различных функций, требующих разных типов аргументов командной строки.ArgumentParser
поддерживает создание таких подкоманд с помощью методаadd_subparsers()
. Методadd_subparsers()
обычно вызывается без аргументов и возвращает специальный объект action. Этот объект имеет единственный методadd_parser()
, который принимает имя команды и любые аргументы конструктораArgumentParser
и возвращает объектArgumentParser
, который можно изменять обычным образом.Описание параметров:
title - заголовок для группы подпарсеров в выводе справки; по умолчанию «подкоманды», если указано описание, в противном случае используется заголовок для позиционных аргументов
description - описание для группы субпарсеров в выводе справки, по умолчанию
None
prog - информация об использовании, которая будет отображаться в справке по подкомандам, по умолчанию это имя программы и все позиционные аргументы перед аргументом субпарсера
parser_class - класс, который будет использоваться для создания экземпляров субпарсера, по умолчанию это класс текущего парсера (например, ArgumentParser).
action - основной тип действия, которое будет выполнено при встрече этого аргумента в командной строке
dest - имя атрибута, под которым будет храниться имя подкоманды; по умолчанию
None
и значение не сохраняетсяrequired - Обязательно ли предоставлять подкоманду, по умолчанию
False
(добавлено в 3.7)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 options: -h, --help show this help message and exit --foo foo help >>> parser.parse_args(['a', '--help']) usage: PROG a [-h] bar positional arguments: bar bar help options: -h, --help show this help message and exit >>> parser.parse_args(['b', '--help']) usage: PROG b [-h] [--baz {X,Y,Z}] options: -h, --help show this help message and exit --baz {X,Y,Z} baz help
Метод
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} ... options: -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_parser()
поддерживает также дополнительный аргумент deprecated, который позволяет устаревать субпарсер.>>> import argparse >>> parser = argparse.ArgumentParser(prog='chicken.py') >>> subparsers = parser.add_subparsers() >>> run = subparsers.add_parser('run') >>> fly = subparsers.add_parser('fly', deprecated=True) >>> parser.parse_args(['fly']) chicken.py: warning: command 'fly' is deprecated Namespace()
Added in version 3.13.
Один из особенно эффективных способов работы с подкомандами - сочетать использование метода
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(required=True) >>> >>> # create the parser for the "foo" command >>> parser_foo = subparsers.add_parser('foo') >>> parser_foo.add_argument('-x', type=int, default=1) >>> parser_foo.add_argument('y', type=float) >>> parser_foo.set_defaults(func=foo) >>> >>> # create the parser for the "bar" command >>> parser_bar = subparsers.add_parser('bar') >>> parser_bar.add_argument('z') >>> parser_bar.set_defaults(func=bar) >>> >>> # parse the args and call whatever function was selected >>> args = parser.parse_args('foo 1 -x 2'.split()) >>> args.func(args) 2.0 >>> >>> # parse the args and call whatever function was selected >>> args = parser.parse_args('bar XYZYX'.split()) >>> args.func(args) ((XYZYX))
Таким образом, вы можете позволить
parse_args()
вызвать соответствующую функцию после завершения разбора аргументов. Подобное связывание функций с действиями обычно является самым простым способом обработки различных действий для каждого из ваших субпарсеров. Однако если необходимо проверить имя вызванного субпарсера, подойдет аргументdest
с ключевым словом для вызоваadd_subparsers()
:>>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers(dest='subparser_name') >>> subparser1 = subparsers.add_parser('1') >>> subparser1.add_argument('-x') >>> subparser2 = subparsers.add_parser('2') >>> subparser2.add_argument('y') >>> parser.parse_args(['2', 'frobble']) Namespace(subparser_name='2', y='frobble')
Изменено в версии 3.7: Новый обязательный аргумент ключевого слова.
Объекты FileType¶
- class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)¶
Фабрика
FileType
создает объекты, которые могут быть переданы в аргумент типаArgumentParser.add_argument()
. Аргументы, имеющие в качестве типа объектыFileType
, открывают аргументы командной строки как файлы с требуемыми режимами, размерами буферов, кодировками и обработкой ошибок (подробнее см. функциюopen()
):>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0)) >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8')) >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt']) Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)
Объекты FileType понимают псевдоаргумент
'-'
и автоматически преобразуют его в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.
Группы аргументов¶
- 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
Обратите внимание, что все аргументы, не входящие в пользовательские группы, будут возвращены в обычные разделы «позиционные аргументы» и «необязательные аргументы».
Изменено в версии 3.11: Вызов
add_argument_group()
для группы аргументов устарел. Эта функция никогда не поддерживалась и не всегда работает корректно. Функция существует в API случайно, благодаря наследованию, и будет удалена в будущем.
Взаимное исключение¶
- 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()
. Однако взаимоисключающая группа может быть добавлена к группе аргументов, у которой есть название и описание. Например:>>> parser = argparse.ArgumentParser(prog='PROG') >>> group = parser.add_argument_group('Group title', 'Group description') >>> exclusive_group = group.add_mutually_exclusive_group(required=True) >>> exclusive_group.add_argument('--foo', help='foo help') >>> exclusive_group.add_argument('--bar', help='bar help') >>> parser.print_help() usage: PROG [-h] (--foo FOO | --bar BAR) options: -h, --help show this help message and exit Group title: Group description --foo FOO foo help --bar BAR bar help
Изменено в версии 3.11: Вызов
add_argument_group()
илиadd_mutually_exclusive_group()
на взаимоисключающей группе устарел. Эти функции никогда не поддерживались и не всегда работают корректно. Функции существуют в API случайно, благодаря наследованию, и будут удалены в будущем.
Параметры парсера по умолчанию¶
- ArgumentParser.set_defaults(**kwargs)¶
В большинстве случаев атрибуты объекта, возвращаемого
parse_args()
, будут полностью определены путем проверки аргументов командной строки и действий с аргументами.set_defaults()
позволяет добавить некоторые дополнительные атрибуты, которые определяются без проверки командной строки:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', type=int) >>> parser.set_defaults(bar=42, baz='badger') >>> parser.parse_args(['736']) Namespace(bar=42, baz='badger', foo=736)
Обратите внимание, что значения по умолчанию на уровне парсера всегда преобладают над значениями по умолчанию на уровне аргументов:
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default='bar') >>> parser.set_defaults(foo='spam') >>> parser.parse_args([]) Namespace(foo='spam')
Установки по умолчанию на уровне парсера могут быть особенно полезны при работе с несколькими парсерами. Пример такого типа см. в методе
add_subparsers()
.
- ArgumentParser.get_default(dest)¶
Получение значения по умолчанию для атрибута пространства имен, заданного либо
add_argument()
, либоset_defaults()
:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default='badger') >>> parser.get_default('foo') 'badger'
Помощь в печати¶
В большинстве типичных приложений parse_args()
позаботится о форматировании и печати любых сообщений об использовании или ошибках. Однако существует несколько способов форматирования:
- ArgumentParser.print_usage(file=None)¶
Выведите краткое описание того, как
ArgumentParser
должен быть вызван в командной строке. Если file - этоNone
, то предполагаетсяsys.stdout
.
- ArgumentParser.print_help(file=None)¶
Вывод справочного сообщения, включающего информацию об использовании программы и аргументах, зарегистрированных с помощью
ArgumentParser
. Если file - этоNone
, то предполагаетсяsys.stdout
.
Существуют также варианты этих методов, которые просто возвращают строку, а не выводят ее на печать:
- ArgumentParser.format_usage()¶
Возвращает строку, содержащую краткое описание того, как
ArgumentParser
должен быть вызван в командной строке.
- ArgumentParser.format_help()¶
Возвращает строку, содержащую справочное сообщение, включая информацию об использовании программы и аргументах, зарегистрированных с помощью
ArgumentParser
.
Частичный разбор¶
- ArgumentParser.parse_known_args(args=None, namespace=None)¶
Иногда сценарий может разобрать только несколько аргументов командной строки, передав остальные аргументы другому сценарию или программе. В таких случаях может быть полезен метод parse_known_args()
. Он работает так же, как и parse_args()
, за исключением того, что не выдает ошибку при наличии лишних аргументов. Вместо этого он возвращает кортеж из двух элементов, содержащий заполненное пространство имен и список оставшихся строк аргументов.
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])
Предупреждение
Правила Prefix matching применяются к parse_known_args()
. Парсер может использовать опцию, даже если она является префиксом одной из известных ему опций, вместо того чтобы оставить ее в оставшемся списке аргументов.
Настройка разбора файлов¶
- ArgumentParser.convert_arg_line_to_args(arg_line)¶
Аргументы, которые читаются из файла (см. аргумент fromfile_prefix_chars в конструкторе
ArgumentParser
), читаются по одному аргументу в строке. Функцияconvert_arg_line_to_args()
может быть переопределена для более удобного чтения.Этот метод принимает единственный аргумент arg_line, который представляет собой строку, считанную из файла аргументов. Он возвращает список аргументов, разобранных из этой строки. Метод вызывается один раз для каждой строки, считанной из файла аргументов, по порядку.
Полезной переопределением этого метода является метод, который рассматривает каждое слово, разделенное пробелами, как аргумент. Следующий пример демонстрирует, как это сделать:
class MyArgumentParser(argparse.ArgumentParser): def convert_arg_line_to_args(self, arg_line): return arg_line.split()
Выходящие методы¶
- ArgumentParser.exit(status=0, message=None)¶
Этот метод завершает работу программы, выходя из нее с указанным статусом и, если задано, печатает перед этим сообщение. Пользователь может переопределить этот метод, чтобы обрабатывать эти шаги по-другому:
class ErrorCatchingArgumentParser(argparse.ArgumentParser): def exit(self, status=0, message=None): if status: raise Exception(f'Exiting because of an error: {message}') exit(status)
- ArgumentParser.error(message)¶
Этот метод печатает сообщение об использовании, включая message, в стандартную ошибку и завершает работу программы с кодом состояния 2.
Смешанный разбор¶
- ArgumentParser.parse_intermixed_args(args=None, namespace=None)¶
- ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)¶
Ряд команд Unix позволяет перемежать необязательные аргументы с позиционными. Методы parse_intermixed_args()
и parse_known_intermixed_args()
поддерживают этот стиль разбора.
Эти парсеры поддерживают не все функции argparse и будут вызывать исключения, если используются неподдерживаемые функции. В частности, не поддерживаются субпарсеры и взаимоисключающие группы, включающие опциональные и позиционные символы.
Следующий пример показывает разницу между parse_known_args()
и parse_intermixed_args()
: первый возвращает ['2', '3']
в виде непарсированных аргументов, а второй собирает все позиционеры в rest
.
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])
parse_known_intermixed_args()
возвращает кортеж из двух элементов, содержащий заполненное пространство имен и список оставшихся строк аргументов. parse_intermixed_args()
выдает ошибку, если остались неразобранные строки аргументов.
Added in version 3.7.
Обновление кода 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()
, используяparse_intermixed_args()
вместоparse_args()
.Замените действия обратного вызова и аргументы ключевого слова
callback_*
на аргументыtype
илиaction
.Замените строковые имена аргументов ключевого слова
type
на соответствующие объекты типа (например, int, float, complex и т. д.).Замените
optparse.Values
наNamespace
, аoptparse.OptionError
иoptparse.OptionValueError
наArgumentError
.Замените строки с неявными аргументами, такими как
%default
или%prog
, на стандартный синтаксис Python для использования словарей для форматирования строк, то есть%(default)s
и%(prog)s
.Замените аргумент
version
конструктора OptionParser на вызовparser.add_argument('--version', action='version', version='<the version>')
.
Исключения¶
- exception argparse.ArgumentError¶
Ошибка при создании или использовании аргумента (необязательного или позиционного).
Строковое значение этого исключения - сообщение, дополненное информацией об аргументе, который его вызвал.
- exception argparse.ArgumentTypeError¶
Возникает, когда что-то идет не так при преобразовании строки командной строки в тип.