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

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

Первый шаг при использовании 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.

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 опции (одну в родительском и одну в дочернем) и выдаст ошибку.

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

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

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

>>> parser.add_argument('-f', '--foo')

в то время как позиционный аргумент можно создать так:

>>> parser.add_argument('bar')

Когда вызывается parse_args(), опциональные аргументы будут определяться по префиксу -, а оставшиеся аргументы будут считаться позиционными:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar

действие

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

• 'store' - Это просто сохраняет значение аргумента. Это действие по умолчанию. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo')
  >>> parser.parse_args('--foo 1'.split())
  Namespace(foo='1')
  

• 'store_const' - Это сохраняет значение, указанное аргументом const. Действие 'store_const' чаще всего используется с опциональными аргументами, которые указывают какой-либо флаг. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', action='store_const', const=42)
  >>> parser.parse_args(['--foo'])
  Namespace(foo=42)
  

• 'store_true' и 'store_false' - Это частные случаи 'store_const' для хранения значений True и False соответственно. Кроме того, они создают значения по умолчанию False и True соответственно. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', action='store_true')
  >>> parser.add_argument('--bar', action='store_false')
  >>> parser.add_argument('--baz', action='store_false')
  >>> parser.parse_args('--foo --bar'.split())
  Namespace(foo=True, bar=False, baz=True)
  

• 'append' - Это хранит список и добавляет каждое значение аргумента в список. Это полезно, когда опция может быть указана несколько раз. Пример использования:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', action='append')
  >>> parser.parse_args('--foo 1 --foo 2'.split())
  Namespace(foo=['1', '2'])
  

• 'append_const' - Это хранит список и добавляет значение, указанное аргументом const, в список. (Обратите внимание, что аргумент const по умолчанию равен None.) Действие 'append_const' обычно полезно, когда несколько аргументов должны хранить константы в одном списке. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
  >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
  >>> parser.parse_args('--str --int'.split())
  Namespace(types=[<class 'str'>, <class 'int'>])
  

• 'count' - Это подсчитывает количество раз, когда встречается ключевой аргумент. Например, это полезно для увеличения уровней подробности:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--verbose', '-v', action='count', default=0)
  >>> parser.parse_args(['-vvv'])
  Namespace(verbose=3)
  

  Обратите внимание, что значение по умолчанию будет None, если не задано явно 0.

• 'help' - Это выводит полное сообщение справки для всех опций в текущем анализаторе и затем завершает работу. По умолчанию действие справки автоматически добавляется в анализатор. См. ArgumentParser для получения подробностей о создании вывода.

• 'version' - Это ожидает аргумент version= в вызове add_argument() и выводит информацию о версии и завершает работу при вызове:

  >>> import argparse
  >>> parser = argparse.ArgumentParser(prog='PROG')
  >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
  >>> parser.parse_args(['--version'])
  PROG 2.0
  

• 'extend' - Это хранит список и расширяет каждое значение аргумента до списка. Пример использования:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
  >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
  Namespace(foo=['f1', 'f2', 'f3', 'f4'])
  

  Добавлено в версии 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 not allowed")
...         super().__init__(option_strings, dest, **kwargs)
...     def __call__(self, parser, namespace, values, option_string=None):
...         print('%r %r %r' % (namespace, values, option_string))
...         setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')

Дополнительную информацию см. в Action.

nargs

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

• N (целое число). N аргументов из командной строки будут объединены в список. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', nargs=2)
  >>> parser.add_argument('bar', nargs=1)
  >>> parser.parse_args('c --foo a b'.split())
  Namespace(bar=['c'], foo=['a', 'b'])
  

  Обратите внимание, что nargs=1 создаёт список из одного элемента. Это отличается от значения по умолчанию, в котором элемент создаётся сам по себе.

• '?'. Один аргумент будет потреблён из командной строки, если это возможно, и произведён как один элемент. Если аргумент командной строки отсутствует, будет использовано значение из default. Обратите внимание, что для необязательных аргументов существует дополнительный случай — строка опции присутствует, но за ней не следует аргумент командной строки. В этом случае будет использовано значение из const. Вот некоторые примеры, чтобы проиллюстрировать это:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
  >>> parser.add_argument('bar', nargs='?', default='d')
  >>> parser.parse_args(['XX', '--foo', 'YY'])
  Namespace(bar='XX', foo='YY')
  >>> parser.parse_args(['XX', '--foo'])
  Namespace(bar='XX', foo='c')
  >>> parser.parse_args([])
  Namespace(bar='d', foo='d')
  

  Одно из наиболее распространённых применений nargs='?' — это разрешение необязательных входных и выходных файлов:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
  ...                     default=sys.stdin)
  >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
  ...                     default=sys.stdout)
  >>> parser.parse_args(['input.txt', 'output.txt'])
  Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
            outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
  >>> parser.parse_args([])
  Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
            outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
  

• '*'. Все аргументы командной строки объединяются в список. Обратите внимание, что обычно нет смысла иметь более одного позиционного аргумента с nargs='*', но несколько необязательных аргументов с nargs='*' возможны. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', nargs='*')
  >>> parser.add_argument('--bar', nargs='*')
  >>> parser.add_argument('baz', nargs='*')
  >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
  Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
  

• '+'. Как и в '*', все аргументы командной строки объединяются в список. Кроме того, будет выведено сообщение об ошибке, если аргументов командной строки не было. Например:

  >>> parser = argparse.ArgumentParser(prog='PROG')
  >>> parser.add_argument('foo', nargs='+')
  >>> parser.parse_args(['a', 'b'])
  Namespace(foo=['a', 'b'])
  >>> parser.parse_args([])
  usage: PROG [-h] foo [foo ...]
  PROG: error: the following arguments are required: foo
  

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

const

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

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

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

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 предоставляет фабрику 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')

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

Классы действий реализуют API действий, вызываемый объект, который возвращает вызываемый объект, обрабатывающий аргументы из командной строки. Любой объект, который следует этому API, может быть передан в качестве параметра action методу add_argument().

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

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

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

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

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

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

Синтаксис значения опции

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')

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

>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument

Если у вас есть позиционные аргументы, которые должны начинаться с - и не выглядят как отрицательные числа, вы можете вставить псевдоаргумент '--', который сообщает методу parse_args(), что всё после него является позиционным аргументом:

>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)

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

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

Некоторые примеры использования:

>>> # create the top-level parser
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='sub-command help')
>>>
>>> # create the parser for the "a" command
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create the parser for the "b" command
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
>>>
>>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)

Обратите внимание, что объект, возвращаемый parse_args(), будет содержать только атрибуты для основного парсера и подпарсера, который был выбран командной строкой (а не любые другие подпарсеры). Таким образом, в примере выше, когда указана команда a, присутствуют только атрибуты foo и bar, а когда указана команда b, присутствуют только атрибуты foo и baz.

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

>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
  {a,b}   sub-command help
    a     a help
    b     b help

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

>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar

positional arguments:
  bar     bar help

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

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]

optional arguments:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

Метод add_subparsers() также поддерживает ключевые аргументы title и description. Когда любой из них присутствует, команды подпарсера будут отображаться в своей собственной группе в выводе справки. Например:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
...                                    description='valid subcommands',
...                                    help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage:  [-h] {foo,bar} ...

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

subcommands:
  valid subcommands

  {foo,bar}   additional help

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

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

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

>>> # sub-command functions
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>>
>>> # create the parser for the "foo" command
>>> parser_foo = subparsers.add_parser('foo')
>>> parser_foo.add_argument('-x', type=int, default=1)
>>> parser_foo.add_argument('y', type=float)
>>> parser_foo.set_defaults(func=foo)
>>>
>>> # create the parser for the "bar" command
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))

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

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')

Изменено в версии 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'])

Настройка анализа файлов

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'Exiting because of an error: {message}')
        exit(status)

ArgumentParser.error(message)

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

Смешанный анализ

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

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

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

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