argparse
— Парсер параметров командной строки, аргументов и подкоманд¶
Добавлено в версии 3.2.
Модуль argparse
упрощает написание удобных интерфейсов командной строки.
Программа определяет, какие аргументы ей требуются, и argparse
выяснит,
как их распарсить из sys.argv
. Модуль argparse
также
автоматически генерирует справочные сообщения и сообщения об использовании и
выдает ошибки, когда пользователи предоставляют программе недопустимые
аргументы.
Пример¶
Следующий код представляет собой программу 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'
В следующих разделах мы рассмотрим этот пример.
Создание парсера¶
Первым шагом в использовании 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)¶ Создать новый объект
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
(по умолчанию:True
) - allow_abbrev — позволяет сокращать длинные параметры, если сокращение
однозначно. (По умолчанию:
True
)
Изменено в версии 3.5: Добавлен параметр allow_abbrev.
Изменено в версии 3.8: В предыдущих версиях allow_abbrev также отключал группировку коротких флагов, таких как
-vv
, для обозначения-v -v
.- prog — Название программы (по умолчанию:
В следующих разделах будет описание по использованию каждого из них.
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
usage¶
По умолчанию ArgumentParser
вычисляет сообщение об использовании на
основе содержащихся в нём аргументов:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
Сообщение по умолчанию можно переопределить с помощью ключевого аргумента
usage=
:
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
Описатель формата %(prog)s
доступен для ввода имени программы в сообщения
об использовании.
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.
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
.
parents¶
Иногда у нескольких парсеров есть общее множество аргументов. Вместо того, чтобы
повторять определения этих аргументов, можно использовать один парсер
со всеми общими аргументами и переданный аргумент parents=
в
ArgumentParser
. Аргумент parents=
принимает список объектов
ArgumentParser
, собирает из них все позиционные и необязательные
действия и добавляет эти действия к создаваемому объекту
ArgumentParser
:
>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)
>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)
>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)
Обратите внимание, что большинство родительских парсеров будут указывать
add_help=False
. В противном случае ArgumentParser
увидит два
параметра -h/--help
(один в родительском и один в дочернем) и вызовет
ошибку.
Примечание
Вы должны полностью инициализировать парсеры, прежде чем передавать их через
parents=
. Если вы измените родительские парсеры после дочернего парсера,
эти изменения не будут отражены в дочернем парсере.
formatter_class¶
Объекты ArgumentParser
позволяют настраивать форматирование справки,
задав альтернативный класс форматирования. В настоящее время таких классов
четыре:
-
class
argparse.
RawDescriptionHelpFormatter
¶ -
class
argparse.
RawTextHelpFormatter
¶ -
class
argparse.
ArgumentDefaultsHelpFormatter
¶ -
class
argparse.
MetavarTypeHelpFormatter
¶
RawDescriptionHelpFormatter
и RawTextHelpFormatter
дают
больший контроль над отображением текстовых описаний. По умолчанию объекты
ArgumentParser
переносят тексты description и epilog в справочные
сообщения командной строки:
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... description='''это описание было со
... странным отступом,
... но это нормально''',
... epilog='''
... точно так же и для этого эпилога, чьи пробелы
... будут очищены и чьи слова будут заключены
... в пару строк''')
>>> parser.print_help()
usage: PROG [-h]
это описание было со странным отступом, но это нормально
optional arguments:
-h, --help show this help message and exit
точно так же и для этого эпилога, чьи пробелы будут очищены и чьи
слова будут заключены в пару строк
Передача 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
prefix_chars¶
В большинстве параметров командной строки в качестве префикса используется
-
, например -f/--foo
. Парсеры, которым необходимо поддерживать разные
или дополнительные символы префикса, например для таких параметров, как +f
или /foo
, можно указать их с помощью аргумента prefix_chars=
конструктора ArgumentParser:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')
Аргумент prefix_chars=
по умолчанию равен '-'
. Если задать множество
символов, не включающий -
, параметры -f/--foo
будут запрещены.
fromfile_prefix_chars¶
Иногда, например, при работе с особенно длинными списками аргументов, может
быть полезно сохранить список аргументов в файле, а не вводить его в командной
строке. Если аргумент fromfile_prefix_chars=
передан конструктору
ArgumentParser
, то аргументы, начинающиеся с любого из указанных
символов, будут рассматриваться как файлы и будут заменены содержащимися в них
аргументами. Например:
>>> with open('args.txt', 'w') as fp:
... fp.write('-f\nbar')
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')
Аргументы, считываемые из файла, по умолчанию должны присутствовать
по одному в каждой строке (но см. также convert_arg_line_to_args()
)
и обрабатываются так, как если бы они находились в том же месте, что и исходный
аргумент ссылки на файл в командной строке. Таким образом, в приведённом выше
примере выражение ['-f', 'foo', '@args.txt']
считается эквивалентным
выражению ['-f', 'foo', '-f', 'bar']
.
У аргумента fromfile_prefix_chars=
значение по умолчанию — None
, что
означает, что аргументы никогда не будут обрабатываться как ссылки на файлы.
argument_default¶
Обычно значения аргументов по умолчанию задаются либо путём передачи значения
по умолчанию в add_argument()
, либо путём вызова методов
set_defaults()
с определенным набором пар имя-значение.
Однако иногда может быть полезно указать для аргументов единое значение по
умолчанию для всего парсера. Это можно сделать, передав ключевой аргумент
argument_default=
в ArgumentParser
. Например, чтобы глобально
подавить создание атрибутов для вызовов parse_args()
, мы
предоставляем argument_default=SUPPRESS
:
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()
allow_abbrev¶
Обычно, когда вы передаёте список аргументов методу
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.
conflict_handler¶
Объекты ArgumentParser
не допускают двух действий с одной и той же
строкой параметров. По умолчанию объекты ArgumentParser
вызывают
исключение, если предпринимается попытка создать аргумент со строкой
параметров, которая уже используется:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
..
ArgumentError: argument --foo: conflicting option string(s): --foo
Иногда (например, при использовании parents) может быть полезно просто
переопределить любые старые аргументы той же строкой параметров. Чтобы получить
такое поведение, значение 'resolve'
может быть передано аргументу
conflict_handler=
ArgumentParser
:
>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
Обратите внимание, что объекты ArgumentParser
удаляют действие только
в том случае, если все его строки параметров переопределены. Итак, в
приведённом выше примере старое действие -f/--foo
сохраняется как действие
-f
, потому что была переопределена только строка параметра --foo
.
add_help¶
По умолчанию объекты ArgumentParser добавляют параметр, который просто
отображает справочное сообщение парсера. Например, рассмотрим файл с именем
myprogram.py
, содержащий следующий код:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
Если в командной строке указано -h
или --help
, будет напечатана справка
ArgumentParser:
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
Иногда бывает полезно отключить добавление этой опции справки. Этого можно
добиться, передав False
в качестве аргумента add_help=
в
ArgumentParser
:
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]
optional arguments:
--foo FOO foo help
Параметр справки обычно -h/--help
. Исключением является случай, если
prefix_chars=
указан и не включает -
, и в этом случае -h
и
--help
не являются допустимыми параметрами. В этом случае первый символ в
prefix_chars
используется для префикса параметров справки:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]
optional arguments:
+h, ++help show this help message and exit
Метод add_argument()¶
-
ArgumentParser.
add_argument
(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])¶ Определите, как следует парсить один аргумент командной строки. У каждого параметра есть собственное более подробное описание ниже, но вкратце они следующие:
- name или flags — имя или список строк параметров, например
foo
или-f, --foo
. - action — основной тип действия, которое должно быть выполнено, когда этот аргумент встречается в командной строке.
- nargs — количество аргументов командной строки, которые следует использовать.
- const — постоянное значение, необходимое для некоторых выборок action и nargs.
- default — значение, полученное, если аргумент отсутствует в командной строке.
- type — тип, в который должен быть преобразован аргумент командной строки.
- choices — контейнер допустимых значений для аргумента.
- required — можно ли пропустить параметр командной строки (только для дополнительных параметров).
- help — краткое описание того, что делает аргумент.
- metavar — имя аргумента в сообщениях об использовании.
- dest — имя атрибута, который будет добавлен к объекту, возвращенному
parse_args()
.
- name или flags — имя или список строк параметров, например
В следующих разделах рассказывается, как каждый из них используется.
name или flags¶
Метод 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
action¶
Объекты 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', default=0) >>> parser.parse_args(['-vvv']) Namespace(verbose=3)
Обратите внимание, что default будет
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'])
Добавлено в версии 3.8.
Вы также можете указать произвольное действие, передав подкласс 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 не разрешены")
... 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
.
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. Обычно это означает, что будет использован
один аргумент командной строки и будет создан один элемент (не список).
const¶
Аргумент const
add_argument()
используется для
хранения постоянных значений, которые не считываются из командной строки, но
требуются для различных действий ArgumentParser
. Два наиболее
распространенных его использования:
- Когда
add_argument()
вызывается сaction='store_const'
илиaction='append_const'
. Эти действия добавляют значениеconst
к одному из атрибутов объекта, возвращаемогоparse_args()
. Примеры см. в описании action. - Когда
add_argument()
вызывается со строками опций (например,-f
или--foo
) иnargs='?'
. Создаёт необязательный аргумент, за которым может следовать ноль или один аргумент командной строки. Если при парсинге командной строки встречается строка параметра без аргумента командной строки, следующего за ней, вместо неё будет принято значениеconst
. Примеры см. в описании nargs.
Для действий 'store_const'
и 'append_const'
необходимо указать ключевой
аргумент const
. Для других действий по умолчанию используется None
.
default¶
Все необязательные аргументы и некоторые позиционные аргументы могут быть
пропущены в командной строке. Ключевой аргумент 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')
type¶
По умолчанию объекты 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.
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
, объекты set
и настраиваемые
контейнеры.
required¶
Как правило, модуль argparse
предполагает, что такие флаги, как -f
и
--bar
, указывают на необязательные аргументы, которые всегда
можно пропустить в командной строке. Чтобы сделать обязательный параметр,
можно указать True
для ключевого аргумента required=
для
add_argument()
:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-h] --foo FOO
: error: the following arguments are required: --foo
Как показывает пример, если опция помечена как required
,
parse_args()
сообщит об ошибке, если опция
отсутствует в командной строке.
Примечание
Обязательные параметры обычно считаются дурным тоном, потому что пользователи ожидают, что опции будут необязательными, и поэтому их следует по возможности избегать.
help¶
Значение help
— строка, содержащая краткое описание аргумента. Когда
пользователь запрашивает помощь (обычно используя -h
или --help
в
командной строке), эти описания help
будут отображаться с каждым
аргументом:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
... help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
... help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]
positional arguments:
bar one of the bars to be frobbled
optional arguments:
-h, --help show this help message and exit
--foo foo the bars before frobbling
Строки help
могут включать в себя различные спецификаторы формата, чтобы
избежать повторения таких вещей, как имя программы или аргумент default.
Доступные спецификаторы включают имя программы, %(prog)s
и большинство
ключевых аргументов для add_argument()
, например
%(default)s
, %(type)s
и т. д.:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
... help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]
positional arguments:
bar the bar to frobble (default: 42)
optional arguments:
-h, --help show this help message and exit
Поскольку строка справки поддерживает %-форматирование, если вы хотите, чтобы в
строке справки отображался литерал %
, вы должны использовать его вместо
%%
.
argparse
поддерживает подавление справки для определенных
параметров, задав для help
значение argparse.SUPPRESS
:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]
optional arguments:
-h, --help show this help message and exit
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
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')
Классы Action¶
Классы 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
.
Метод 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='?')
>>> # неверный тип
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'
>>> # неверная опция
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar
>>> # неправильное количество аргументов
>>> 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='?')
>>> # нет опций с отрицательными числами, поэтому -1 - позиционный аргумент
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')
>>> # нет опций с отрицательными числами, поэтому -1 и -5 являются позиционными аргументами
>>> 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='?')
>>> # присутствуют опции с отрицательными числами, поэтому опция -1
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')
>>> # присутствуют опции с отрицательными числами, поэтому опция -2
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2
>>> # присутствуют опции с отрицательными числами, поэтому оба значения -1 являются опциями
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument
Если у вас есть позиционные аргументы, которые должны начинаться с -
и не
похожи на отрицательные числа, вы можете вставить псевдо-аргумент '--'
,
который сообщает parse_args()
, что всё после него
является позиционным аргументом:
>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)
Сокращения аргументов (сопоставление префиксов)¶
Метод parse_args()
по умолчанию
позволяет сокращать длинные параметры до префикса, если сокращение однозначно
(префикс соответствует уникальному параметру):
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon
Вызывается ошибка для аргументов, которые могут давать более одной опции.
Эту функцию можно отключить, установив 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])
Объект 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'
Прочие утилиты¶
Подкоманды¶
-
ArgumentParser.
add_subparsers
([title][, description][, prog][, parser_class][, action][, option_string][, dest][, required][, 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)
- action — основной тип действия, которое должно быть выполнено, когда этот аргумент встречается в командной строке
- dest — имя атрибута, под которым будет храниться имя подкоманды; по
умолчанию
None
, и значение не сохраняется - required — Должна ли быть указана подкоманда, по умолчанию
False
(добавлено в 3.7) - help — справка для подгруппы парсера в выводе справки, по умолчанию
None
- metavar — строка, представляющая доступные подкоманды в справке; по
умолчанию
None
, подкоманды представлены в форме {cmd1, cmd2, ..}
Некоторые примеры использования:
>>> # создать парсер верхнего уровня >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--foo', action='store_true', help='foo help') >>> subparsers = parser.add_subparsers(help='sub-command help') >>> >>> # создать парсер для команды "a" >>> parser_a = subparsers.add_parser('a', help='a help') >>> parser_a.add_argument('bar', type=int, help='bar help') >>> >>> # создать парсер для команды "b" >>> parser_b = subparsers.add_parser('b', help='b help') >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help') >>> >>> # распарсить некоторые списки аргументов >>> 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='допустимые подкоманды', ... 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: допустимые подкоманды {foo,bar} дополнительная помощь
Кроме того,
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 он должен выполнить. Например:>>> # подкомандные функции >>> def foo(args): ... print(args.x * args.y) ... >>> def bar(args): ... print('((%s))' % args.z) ... >>> # создать парсер верхнего уровня >>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers() >>> >>> # создать парсер для команды "foo" >>> 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) >>> >>> # создать парсер для команды "bar" >>> parser_bar = subparsers.add_parser('bar') >>> parser_bar.add_argument('z') >>> parser_bar.set_defaults(func=bar) >>> >>> # распарсить аргументы и вызвать любую выбранную функцию >>> args = parser.parse_args('foo 1 -x 2'.split()) >>> args.func(args) 2.0 >>> >>> # распарсить аргументы и вызвать любую выбранную функцию >>> 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: Новый ключевой аргумент required.
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
Обратите внимание, что любые аргументы, не входящие в ваши пользовательские группы, вернутся в обычные разделы «позиционные аргументы» и «необязательные аргументы».
Взаимное исключение¶
-
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()
.
Параметры парсера по умолчанию¶
-
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'])
Предупреждение
К 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)¶ Этот метод завершает программу, завершая работу с указанным status и, если он задан, перед этим печатает message. Пользователь может переопределить этот метод, чтобы выполнить эти шаги по-другому:
class ErrorCatchingArgumentParser(argparse.ArgumentParser): def exit(self, status=0, message=None): if status: raise Exception(f'Выход из-за ошибки: {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 и будут вызывать исключения,
если используются неподдерживаемые функции. В частности, не поддерживаются
подпарсеры, argparse.REMAINDER
и взаимоисключающие группы, которые включают
как необязательные, так и позиционные.
В следующем примере показано различие между
parse_known_args()
и
parse_intermixed_args()
: первый возвращает ['2', '3']
как нераспрасенные аргументы, а второй собирает все позиционные значения в
rest
.
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])
parse_known_intermixed_args()
возвращает кортеж из двух
элементов, содержащий заполненное пространство имён и список оставшихся строк
аргументов. parse_intermixed_args()
вызывает ошибку, если
остались нераспрасенные строки аргументов.
Добавлено в версии 3.7.
Обновление кода optparse¶
Первоначально модуль argparse
пытался поддерживать совместимость с
optparse
. Однако optparse
было сложно прозрачно расширить,
особенно с изменениями, необходимыми для поддержки новых спецификаторов
nargs=
и улучшенных сообщений об использовании. Когда почти всё в
optparse
было либо скопировано, либо использовались бы
партизанские заплатки (monkey-patched), поэтому пытаться
поддерживать обратную совместимость больше не казалось практичным.
Модуль 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>')
.