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]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo help

Чтобы изменить это поведение по умолчанию, можно указать другое значение, используя аргумент prog= для ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

options:
 -h, --help  show this help message and exit

Обратите внимание, что имя программы, определяемое из sys.argv[0] или из аргумента prog=, доступно в справочных сообщениях, использующих спецификатор формата %(prog)s.

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program

использование¶

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]

positional arguments:
 bar          bar help

options:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help

Сообщение по умолчанию можно переопределить с помощью аргумента usage= ключевого слова:

>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]

positional arguments:
 bar          bar help

options:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help

Спецификатор формата %(prog)s доступен для заполнения имени программы в сообщениях об использовании.

описание¶

В большинстве обращений к конструктору ArgumentParser будет использоваться аргумент с ключевым словом description=. Этот аргумент дает краткое описание того, что делает программа и как она работает. В справочных сообщениях описание отображается между строкой использования командной строки и справочными сообщениями для различных аргументов:

>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

options:
 -h, --help  show this help message and exit

По умолчанию описание будет свернуто в строку так, чтобы оно поместилось в заданное пространство. Чтобы изменить это поведение, смотрите аргумент formatter_class.

эпилог¶

Некоторые программы любят выводить дополнительное описание программы после описания аргументов. Такой текст можно задать с помощью аргумента epilog= к ArgumentParser:

>>> parser = argparse.ArgumentParser(
...     description='A foo that bars',
...     epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

options:
 -h, --help  show this help message and exit

And that's how you'd foo a bar

Как и в случае аргумента description, текст epilog= по умолчанию разворачивается в строку, но это поведение можно изменить с помощью аргумента formatter_class на ArgumentParser.

родители¶

Иногда несколько синтаксических анализаторов имеют общий набор аргументов. Вместо того чтобы повторять определения этих аргументов, можно использовать один парсер со всеми общими аргументами и передавать их в parents= аргумент ArgumentParser. Аргумент parents= принимает список объектов ArgumentParser, собирает из них все позиционные и необязательные действия и добавляет эти действия к конструируемому объекту ArgumentParser:

>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)

Обратите внимание, что большинство родительских парсеров будут указывать add_help=False. В противном случае ArgumentParser увидит две опции -h/--help (одну в родительском и одну в дочернем) и выдаст ошибку.

класс_форматера¶

Объекты ArgumentParser позволяют настраивать форматирование справки, указывая альтернативный класс форматирования. В настоящее время существует четыре таких класса:

class argparse.RawDescriptionHelpFormatter¶

class argparse.RawTextHelpFormatter¶

class argparse.ArgumentDefaultsHelpFormatter¶

class argparse.MetavarTypeHelpFormatter¶

RawDescriptionHelpFormatter и RawTextHelpFormatter дают больше возможностей для контроля над тем, как отображаются текстовые описания. По умолчанию объекты ArgumentParser по строкам обертывают тексты описания и эпилога в справочных сообщениях командной строки:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='''this description
...         was indented weird
...             but that is okay''',
...     epilog='''
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

options:
 -h, --help  show this help message and exit

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

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

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

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

options:
 -h, --help  show this help message and exit

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

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

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

positional arguments:
 bar         BAR! (default: [1, 2, 3])

options:
 -h, --help  show this help message and exit
 --foo FOO   FOO! (default: 42)

MetavarTypeHelpFormatter использует имя аргумента type для каждого аргумента в качестве отображаемого имени для его значений (а не использует dest, как это делает обычный форматтер):

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float

positional arguments:
  float

options:
  -h, --help  show this help message and exit
  --foo int

префиксные_значки¶

Большинство опций командной строки будут использовать - в качестве префикса, например -f/--foo. Парсеры, которым требуется поддержка других или дополнительных символов префикса, например, для опций типа +f или /foo, могут указать их с помощью аргумента prefix_chars= в конструкторе ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')

Аргумент prefix_chars= по умолчанию имеет значение '-'. Если предоставить набор символов, не включающий -, то опции -f/--foo будут запрещены.

fromfile_prefix_chars¶

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

аргумент_по_умолчанию¶

Как правило, значения аргументов по умолчанию задаются либо путем передачи значения по умолчанию в add_argument(), либо путем вызова методов set_defaults() с определенным набором пар имя-значение. Однако иногда бывает полезно задать единое для всего синтаксического анализатора значение по умолчанию для аргументов. Этого можно добиться, передав аргумент argument_default= с ключевым словом в ArgumentParser. Например, чтобы глобально подавить создание атрибутов при вызове parse_args(), мы передаем argument_default=SUPPRESS:

>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()

allow_abbrev¶

Обычно, когда вы передаете список аргументов в метод parse_args() метода ArgumentParser, он recognizes abbreviations состоит из длинных опций.

Эту функцию можно отключить, установив allow_abbrev на False:

>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
>>> parser.add_argument('--foobar', action='store_true')
>>> parser.add_argument('--foonley', action='store_false')
>>> parser.parse_args(['--foon'])
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon

обработчик конфликтов¶

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
 ..
ArgumentError: argument --foo: conflicting option string(s): --foo

Иногда (например, при использовании parents) может быть полезно просто переопределить все старые аргументы с той же строкой опций. Чтобы добиться такого поведения, можно передать значение 'resolve' в аргумент conflict_handler= из ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]

options:
 -h, --help  show this help message and exit
 -f FOO      old foo help
 --foo FOO   new foo help

Обратите внимание, что объекты ArgumentParser удаляют действие, только если все его строки опций переопределены. Так, в приведенном выше примере старое действие -f/--foo сохраняется как действие -f, потому что была переопределена только строка опций --foo.

add_help¶

По умолчанию объекты ArgumentParser добавляют опцию, которая просто отображает справочное сообщение парсера. Например, рассмотрим файл с именем myprogram.py, содержащий следующий код:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

Если в командной строке указано -h или --help, будет выведена справка ArgumentParser:

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo help

Иногда бывает полезно отключить добавление этой опции помощи. Этого можно добиться, передав False в качестве аргумента add_help= в ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]

options:
 --foo FOO  foo help

Опция справки обычно представляет собой -h/--help. Исключением является случай, когда указано prefix_chars= и не включает -, в этом случае -h и --help не являются допустимыми опциями. В этом случае первый символ в prefix_chars используется для префикса опций справки:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]

options:
  +h, ++help  show this help message and exit

выход_на_ошибку¶

Обычно, когда вы передаете неверный список аргументов в метод parse_args() метода ArgumentParser, он завершается с информацией об ошибке.

Если пользователь хочет отлавливать ошибки вручную, эту функцию можно включить, установив exit_on_error на False:

>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
...     parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
...     print('Catching an argumentError')
...
Catching an argumentError

имя или флаги¶

Метод 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 или другой объект, реализующий тот же интерфейс. Интерфейс BooleanOptionalAction доступен в argparse и добавляет поддержку булевых действий, таких как --foo и --no-foo:

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)

Рекомендуемый способ создания пользовательского действия - расширить Action, переопределив метод __call__ и, по желанию, методы __init__ и format_usage.

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

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

Для более подробной информации смотрите Action.

nargs¶

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

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

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

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

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

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

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

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

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

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

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

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

Если аргумент с ключевым словом nargs не указан, количество потребляемых аргументов определяется действием. Обычно это означает, что будет потреблен один аргумент командной строки и получен один элемент (не список).

const¶

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

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

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

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

по умолчанию¶

Все необязательные аргументы и некоторые позиционные аргументы могут быть опущены в командной строке. Аргумент default ключевого слова add_argument(), значение которого по умолчанию равно None, указывает, какое значение должно использоваться, если аргумент командной строки отсутствует. Для необязательных аргументов значение default используется, если строка опции не присутствовала в командной строке:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)

Если целевое пространство имен уже имеет набор атрибутов, действие default не будет его перезаписывать:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)

Если значение default является строкой, синтаксический анализатор разбирает значение, как если бы это был аргумент командной строки. В частности, синтаксический анализатор применяет любой аргумент преобразования type, если он предоставлен, перед установкой атрибута на возвращаемое значение Namespace. В противном случае синтаксический анализатор использует значение как есть:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)

Для позиционных аргументов с nargs равным ? или *, значение default используется, если не было аргумента командной строки:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)

Указание default=argparse.SUPPRESS приводит к тому, что атрибут не добавляется, если аргумент командной строки не присутствовал:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')

тип¶

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

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

Аргументом type может быть любая вызываемая функция, принимающая одну строку. Если функция вызывает исключение ArgumentTypeError, TypeError или ValueError, то исключение перехватывается и выводится красиво оформленное сообщение об ошибке. Никакие другие типы исключений не обрабатываются.

Общие встроенные типы и функции могут быть использованы в качестве преобразователей типов:

import argparse
import pathlib

parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)

Также можно использовать функции, определяемые пользователем:

>>> def hyphenated(string):
...     return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')

Функция bool() не рекомендуется в качестве преобразователя типов. Она преобразует пустые строки в False и непустые строки в True. Обычно это не то, что нужно.

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

Например, преобразования JSON или YAML имеют сложные случаи ошибок, которые требуют лучшего отчета, чем может дать ключевое слово type. Ключ JSONDecodeError будет плохо отформатирован, а исключение FileNotFound вообще не будет обработано.

Даже FileType имеет свои ограничения для использования с ключевым словом type. Если в одном аргументе используется FileType, а затем последующий аргумент не работает, сообщается об ошибке, но файл не закрывается автоматически. В этом случае лучше дождаться окончания работы синтаксического анализатора и затем использовать оператор with для управления файлами.

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

выбор¶

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

>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')

Обратите внимание, что включение в контейнер choices проверяется после выполнения любых преобразований type, поэтому тип объектов в контейнере choices должен соответствовать указанному type:

>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

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

Использование enum.Enum не рекомендуется, поскольку трудно контролировать его появление в сообщениях об использовании, справке и ошибках.

Форматированный выбор переопределяет стандартный metavar, который обычно берется из dest. Обычно это то, что вам нужно, потому что пользователь никогда не видит параметр dest. Если такое отображение нежелательно (возможно, потому что вариантов выбора много), просто укажите явный metavar.

требуется¶

В целом, модуль argparse предполагает, что флаги типа -f и --bar указывают на опциональные аргументы, которые всегда можно опустить в командной строке. Чтобы сделать опцию обязательной, True можно указать в качестве аргумента ключевое слово required= в add_argument():

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

Как показано в примере, если опция помечена как required, parse_args() сообщит об ошибке, если эта опция не присутствует в командной строке.

помощь¶

Значение help представляет собой строку, содержащую краткое описание аргумента. Когда пользователь запрашивает помощь (обычно с помощью -h или --help в командной строке), эти help описания будут отображаться с каждым аргументом:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
...                     help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
...                     help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]

positional arguments:
 bar     one of the bars to be frobbled

options:
 -h, --help  show this help message and exit
 --foo   foo the bars before frobbling

Строки help могут включать различные спецификаторы формата, чтобы избежать повторения таких вещей, как имя программы или аргумент default. Доступные спецификаторы включают имя программы, %(prog)s и большинство ключевых аргументов add_argument(), например, %(default)s, %(type)s и т.д.:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
...                     help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar     the bar to frobble (default: 42)

options:
 -h, --help  show this help message and exit

Поскольку строка справки поддерживает %-форматирование, если вы хотите, чтобы литерал % появился в строке справки, вы должны экранировать его как %%.

argparse поддерживает отключение записи справки для определенных опций, устанавливая значение help в argparse.SUPPRESS:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]

options:
  -h, --help  show this help message and exit

метавар¶

Когда ArgumentParser генерирует справочные сообщения, ему необходимо каким-то образом ссылаться на каждый ожидаемый аргумент. По умолчанию объекты ArgumentParser используют значение dest в качестве «имени» каждого объекта. По умолчанию для действий с позиционным аргументом значение dest используется напрямую, а для действий с необязательным аргументом значение dest используется в верхнем регистре. Таким образом, одиночный позиционный аргумент dest='bar' будет называться bar. Одиночный необязательный аргумент --foo, за которым должен следовать одиночный аргумент командной строки, будет обозначаться как FOO. Пример:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo FOO] bar

positional arguments:
 bar

options:
 -h, --help  show this help message and exit
 --foo FOO

Альтернативное имя может быть указано с помощью metavar:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo YYY] XXX

positional arguments:
 XXX

options:
 -h, --help  show this help message and exit
 --foo YYY

Обратите внимание, что metavar изменяет только отображаемое имя - имя атрибута на объекте parse_args() по-прежнему определяется значением dest.

Различные значения nargs могут привести к тому, что метаварь будет использоваться несколько раз. Предоставление кортежа в metavar задает различное отображение для каждого из аргументов:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]

options:
 -h, --help     show this help message and exit
 -x X X
 --foo bar baz

dest¶

Большинство действий ArgumentParser добавляют некоторое значение в качестве атрибута объекта, возвращаемого parse_args(). Имя этого атрибута определяется аргументом dest ключевого слова add_argument(). Для действий с позиционным аргументом dest обычно передается в качестве первого аргумента для add_argument():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')

Для действий с необязательными аргументами значение dest обычно определяется из строк опций. ArgumentParser генерирует значение dest, беря первую длинную строку опций и удаляя начальную строку --. Если длинные строки опций не были предоставлены, dest будет получено из первой короткой строки опций путем удаления начального символа -. Любые внутренние символы - будут преобразованы в символы _, чтобы убедиться, что строка является действительным именем атрибута. Примеры ниже иллюстрируют это поведение:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')

dest позволяет указать имя пользовательского атрибута:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')

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

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

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

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

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

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

• parser - Объект ArgumentParser, который содержит данное действие.

• namespace - объект Namespace, который будет возвращен parse_args(). Большинство действий добавляют атрибут к этому объекту с помощью setattr().

• values - Ассоциированные аргументы командной строки, с любыми примененными преобразованиями типов. Преобразования типов задаются с помощью ключевого слова type в аргументе add_argument().

• option_string - Строка опций, которая была использована для вызова этого действия. Аргумент option_string является необязательным и будет отсутствовать, если действие связано с позиционным аргументом.

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

Подклассы Action могут определить метод format_usage, который не принимает аргументов и возвращает строку, которая будет использоваться при печати использования программы. Если такой метод не определен, будет использовано разумное значение по умолчанию.

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

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

>>> 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() by default позволяет сокращать длинные опции до префикса, если сокращение однозначно (префикс соответствует уникальной опции):

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon

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

За пределами sys.argv¶

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

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
...     'integers', metavar='int', type=int, choices=range(10),
...     nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
...     '--sum', dest='accumulate', action='store_const', const=sum,
...     default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

Объект пространства имен¶

class argparse.Namespace¶

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

Этот класс намеренно прост, это просто подкласс object с удобочитаемым строковым представлением. Если вы предпочитаете иметь диктоподобное представление атрибутов, вы можете использовать стандартную идиому Python, vars():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}

Также может быть полезно, чтобы ArgumentParser присваивал атрибуты уже существующему объекту, а не новому Namespace объекту. Этого можно добиться, указав в качестве аргумента ключевое слово namespace=:

>>> class C:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

Подкоманды¶

ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_strings][, dest][, required][, help][, metavar])¶

Многие программы разделяют свои функции на ряд подкоманд, например, программа svn может вызывать такие подкоманды, как svn checkout, svn update и svn commit. Такое разделение функциональности может быть особенно полезно, когда программа выполняет несколько различных функций, требующих различных типов аргументов командной строки. ArgumentParser поддерживает создание таких подкоманд с помощью метода add_subparsers(). Метод add_subparsers() обычно вызывается без аргументов и возвращает специальный объект действия. Этот объект имеет единственный метод add_parser(), который принимает имя команды и любые аргументы конструктора ArgumentParser и возвращает объект ArgumentParser, который можно модифицировать обычным образом.

Описание параметров:

• title - заголовок для группы субпарсеров в выводе справки; по умолчанию «subcommands», если предоставлено описание, иначе используется заголовок для позиционных аргументов

• description - описание для группы субпарсеров в выводе справки, по умолчанию None.

• prog - информация об использовании, которая будет отображаться в справке подкоманды, по умолчанию имя программы и любые позиционные аргументы перед аргументом субпарсера

• parser_class - класс, который будет использоваться для создания экземпляров субпарсера, по умолчанию класс текущего парсера (например, ArgumentParser).

• action - основной тип действия, которое будет предпринято при встрече данного аргумента в командной строке

• dest - имя атрибута, под которым будет храниться имя подкоманды; по умолчанию None и значение не сохраняется

• required - Должна ли быть предоставлена подкоманда, по умолчанию False (добавлено в 3.7)

• help - помощь для группы субпарсеров в выводе справки, по умолчанию None.

• metavar - строка, представляющая доступные подкоманды в справке; по умолчанию она равна None и представляет подкоманды в виде {cmd1, cmd2, ..}.

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

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

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

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

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

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

options:
  -h, --help  show this help message and exit
  --foo   foo help

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

positional arguments:
  bar     bar help

options:
  -h, --help  show this help message and exit

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

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

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

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

options:
  -h, --help  show this help message and exit

subcommands:
  valid subcommands

  {foo,bar}   additional help

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

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

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

Объекты FileType¶

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

Фабрика FileType создает объекты, которые могут быть переданы в аргумент type функции ArgumentParser.add_argument(). Аргументы, имеющие в качестве типа объекты FileType, будут открывать аргументы командной строки как файлы с запрошенными режимами, размерами буферов, кодировками и обработкой ошибок (подробнее см. функцию open()):

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

Объекты FileType понимают псевдоаргумент '-' и автоматически преобразуют его в sys.stdin для объектов с возможностью чтения FileType и sys.stdout для объектов с возможностью записи FileType:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

Добавлено в версии 3.4: Аргументы ключевых слов encodings и errors.

Группы аргументов¶

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() также принимает аргумент требуется, чтобы указать, что требуется хотя бы один из взаимоисключающих аргументов:

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

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

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