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 ...]

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

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

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

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

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

add_help

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

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

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

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

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

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

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

optional arguments:
 --foo FOO  foo help

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

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

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

exit_on_error

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

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 не перезапишет его:

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

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

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

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

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

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

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

type

По умолчанию парсер читает аргументы командной строки как простые строки. Однако довольно часто строку командной строки следует интерпретировать как другой тип, например, 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

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

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

required

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

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

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

Подклассы 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() по умолчанию разрешает сокращение длинных опций до префикса, если сокращение однозначно (префикс соответствует единственной опции):

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