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

prog

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

• sys.argv[0], если в качестве аргумента передан файл, берётся имя файла, возвращаемое функцией base name.
• Имя интерпретатора Python, за которым следует sys.argv[0], если в качестве аргумента передан каталог или zip-файл.
• Имя интерпретатора Python, за которым следует -m, а затем имя модуля или пакета, если использован параметр -m.

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

usage

По умолчанию ArgumentParser формирует сообщение об использовании на основе содержащихся в нём аргументов. Сообщение по умолчанию можно переопределить с помощью именованного аргумента 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 позволяет подставить имя программы в сообщения об использовании.

description

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

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

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

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= указывает, что тексты 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

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

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

При работе с особенно длинным списком аргументов иногда имеет смысл хранить его в файле, а не вводить в командной строке. Если конструктору ArgumentParser передан аргумент fromfile_prefix_chars=, аргументы, начинающиеся с любого из указанных символов, будут считаться именами файлов и заменяться аргументами, содержащимися в этих файлах. Например:

>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) 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'].

Для чтения файла с аргументами ArgumentParser использует кодировку файловой системы и обработчик ошибок.

По умолчанию аргумент 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) бывает полезно просто переопределить все предыдущие аргументы с той же строкой параметра. Чтобы включить такое поведение, аргументу conflict_handler= конструктора ArgumentParser можно передать значение 'resolve':

>>> 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 добавляют параметр, который выводит справочное сообщение анализатора. Если в командной строке указать -h или --help, будет выведена справка ArgumentParser.

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

exit_on_error

Обычно при передаче недопустимого списка аргументов методу parse_args() объекта ArgumentParser он выводит сообщение в sys.stderr и завершает работу с кодом состояния 2.

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

action

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

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

• 'store_const' — сохраняет значение, заданное именованным аргументом const; обратите внимание, что по умолчанию именованный аргумент const равен None. Действие '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'>])
  

• 'extend' — сохраняет список и добавляет в него каждый элемент из списка аргументов с несколькими значениями. Действие 'extend' обычно используется со значением '+' или '*' именованного аргумента nargs. Обратите внимание: если nargs имеет значение None (по умолчанию) или '?', каждый символ строки аргумента будет добавлен в список. Пример использования:

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

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

С позиционными аргументами можно использовать только действия, обрабатывающие аргументы командной строки (например, 'store', 'append' или 'extend').

class argparse.BooleanOptionalAction

Можно также задать произвольное действие, передав подкласс 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)

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

Рекомендуемый способ создания пользовательского действия — унаследовать Action, переопределить метод __call__() и, при необходимости, методы __init__() и format_usage(). Также можно зарегистрировать пользовательские действия с помощью метода register() и обращаться к ним по зарегистрированному имени.

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

>>> 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. Как правило, это означает, что будет обработан один аргумент командной строки и возвращён один элемент (не список). Действия, не обрабатывающие аргументы командной строки (например, 'store_const'), задают значение nargs=0.

const

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

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

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

>>> 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 игнорируется. Например, это относится к позиционным аргументам со значениями nargs, отличными от ? и *, а также к необязательным аргументам, помеченным как required=True.

Если указать 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 может быть вызываемым объектом, принимающим одну строку, или именем зарегистрированного типа (см. register()). Если функция вызывает исключение 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('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 не будет хорошо отформатировано, а исключение FileNotFoundError вообще не будет обработано.

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

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

choices

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

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

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

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

Форматированный список вариантов переопределяет значение 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.

Строки 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 позволяет скрыть запись справки для некоторых параметров, задав значение argparse.SUPPRESS для help:

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

metavar

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

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__().

__call__(parser, namespace, values, option_string=None)

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

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

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

format_usage()

В подклассах 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)

Дополнительные сведения см. также в руководстве по argparse: неоднозначные аргументы.

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

Метод 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][, 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='subcommand 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=('X', 'Y', 'Z'), 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}   subcommand 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 ему следует выполнить. Например:

>>> # subcommand 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(required=True)
>>>
>>> # 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, *[, argument_default][, conflict_handler])

По умолчанию 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

Необязательные параметры, задаваемые только по имени, argument_default и conflict_handler, позволяют точнее настроить поведение группы аргументов. Эти параметры имеют тот же смысл, что и в конструкторе ArgumentParser, но применяются именно к группе аргументов, а не ко всему анализатору.

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

Изменено в версии 3.11: Вызов add_argument_group() для группы аргументов объявлен устаревшим. Эта возможность никогда не поддерживалась и работает некорректно в некоторых случаях. Функция случайно попала в API через наследование и будет удалена в будущем.

Взаимоисключающие аргументы

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_argument_group('Group title', 'Group description')
>>> exclusive_group = group.add_mutually_exclusive_group(required=True)
>>> exclusive_group.add_argument('--foo', help='foo help')
>>> exclusive_group.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [-h] (--foo FOO | --bar BAR)

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

Group title:
  Group description

  --foo FOO   foo help
  --bar BAR   bar help

Изменено в версии 3.11: Вызов add_argument_group() или add_mutually_exclusive_group() для группы взаимоисключающих аргументов объявлен устаревшим. Эти возможности никогда не поддерживались и работают некорректно в некоторых случаях. Функции случайно попали в API через наследование и будут удалены в будущем.

Значения по умолчанию анализатора

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 в sys.stderr. Пользователь может переопределить этот метод, чтобы изменить порядок выполнения этих действий:

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)

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

В следующем примере показана разница между parse_known_args() и parse_intermixed_args(): первый возвращает ['2', '3'] как неразобранные аргументы, а второй собирает все позиционные аргументы в rest.

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

parse_known_intermixed_args() возвращает кортеж из двух элементов: заполненное пространство имён и список строк оставшихся аргументов. Метод parse_intermixed_args() вызывает ошибку, если остаются неразобранные строки аргументов.

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

Регистрация пользовательских типов и действий

ArgumentParser.register(registry_name, value, object)

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

Метод register() принимает три аргумента: registry_name, задающий внутренний реестр для хранения объекта (например, action, type); value — ключ, по которому будет зарегистрирован объект; и сам объект — вызываемый объект для регистрации.

В следующем примере показано, как зарегистрировать пользовательский тип в анализаторе:

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))
>>> parser.add_argument('--foo', type='hexadecimal integer')
_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> parser.parse_args(['--foo', '0xFA'])
Namespace(foo=250)
>>> parser.parse_args(['--foo', '1.2'])
usage: PROG [-h] [--foo FOO]
PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'