`argparse` — парсер параметров командной строки, аргументов и подкоманд¶

Добавлено в версии 3.2.

Source code:: source:“Lib/argparse.py“

Модуль 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 (по умолчанию: 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 (по умолчанию: 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 (по умолчанию: find the max)')

Позже вызывающий parse_args() вернет объект с двумя атрибутами, integers и accumulate. Атрибут integers будет содержать список из одного или нескольких int, и атрибут 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 - Текст, отображаемый перед справочным аргументом (по умолчанию: none)
epilog - Текст, отображаемый после справочного аргумента (по умолчанию: none)
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¶

По умолчанию объекты 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='''this description
...         was indented weird
...             but that is okay''',
...     epilog='''
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

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

likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines

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

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('''\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '''))
>>> parser.print_help()
usage: PROG [-h]

Please do not mess up this text!
--------------------------------
   I have indented it
   exactly the way
   I want it

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

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

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

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar [bar ...]]

positional arguments:
 bar         BAR! (по умолчанию: [1, 2, 3])

optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   FOO! (по умолчанию: 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() с заданным набором пары name-value. Однако иногда может оказаться полезно указания один общего парсера по умолчанию для аргументов. Этого можно добиться, передав ключевой аргумент 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 or flags - Либо имя, либо список строк опций, например foo или -f, --foo.
action - Основной тип действия, которое должно быть предпринято, когда этот аргумент встречается в командной строке.
nargs - Количество используемых аргументов командной строки.
const - Константное значение требуемое для action и nargs секций.
default - Значение, полученное, если аргумент отсутствует в командной строке.
type - Тип, в который должен быть преобразован аргумент командной строки.
choices - Контейнер допустимых значений для аргумента.
required - Может ли опция командной строки быть пропущена (только опционально).
help - Краткое описание того, что делает аргумент.
metavar - Имя аргумента в сообщениях об использовании.
dest - Имя атрибута, который будет добавлен к объекту, возвращаемому parse_args().

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

name or 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)
Заметьте, что по умолчанию он установлен в None если явно не установлено 0.
'help' - Печатает все справочные сообщения для всех опций в текущего парсера и затем выходит. По умолчанию действие 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__.

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

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super(FooAction, self).__init__(option_strings, dest, **kwargs)
...     def __call__(self, parser, namespace, values, option_string=None):
...         print('%r %r %r' % (namespace, values, option_string))
...         setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')

Дополнительные сведения см. в разделе Action.

nargs¶

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

N (an integer). 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'>)

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

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 предоставляет Factory 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: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required

Как показано в примере, если параметр помечен как 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)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar     the bar to frobble (по умолчанию: 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 API, вызываемое с возвращаемым вызываемым обрабатывая аргументы из командной строки. Любой объект следующий этому API может быть передан в качестве параметра action в add_argument().

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)¶

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

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

Cущности 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() см. документацию.

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

Синтаксис опционального значения¶

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)

Для длинных опций (опции с именами длиннее одного символа) параметр и значение также может быть передано как один аргумент командной строки, используя символ = для их отделения:

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

Для коротких вариантов (варианты длиной только один символ), опция и её значение может быть связаны:

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

Несколько коротких опций можно объединить, используя только один префикс -, если только последний вариант (или ни один из них) не требует значения:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')

Ошибочные аргументы¶

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')

>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger

Аргументы с `-`¶

Метод parse_args() пытается выдавать ошибки всякий раз когда пользователь явно допустил ошибку, но некоторые ситуации по своей сути неоднозначны. Например, аргумент командной строки -1 может быть попыткой указания параметра или попыткой предоставления позиционного аргумента. Метод parse_args() здесь осторожен: позиционный аргументы могут начинаться только с -, если они выглядят как отрицательные числа и в парсере нет вариантов, которые выглядели бы как отрицательные числа:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')

>>> # нет опций отрицательного числа, поэтому -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 (по умолчанию: 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')
>>>
>>> # создание парсера для команды "а"
>>> 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='valid subcommands',
...                                    help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage:  [-h] {foo,bar} ...

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

subcommands:
  valid subcommands

  {foo,bar}   additional help

Кроме того, add_parser поддерживает дополнительный аргумент aliases, который позволяет множеству строки ссылаться на один и тот же подпарсер. Этот пример, в svn, алиас co более короткая запись checkout:

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

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

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

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

Обратите вниманиеl что parser-level значения по умолчанию всегда переопределяют значения по умолчанию argument-level:

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

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

class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Exiting because of an error: {message}')
        exit(status)

ArgumentParser.error(message)¶: This method prints a usage message including the message to the standard error and terminates the program with a status code of 2.

Смешанный парсинг¶

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

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

Ряд Unix команд позволяет пользователю смешивать необязательные аргументы с позиционными аргументами. parse_intermixed_args() и метод parse_known_intermixed_args() поддерживает этот стиль парсинга.

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

Модуль 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
Замените в конструкторе OptionParser аргумент version вызовом parser.add_argument('--version', action='version', version='<the version>').

argparse — парсер параметров командной строки, аргументов и подкоманд¶