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

prog

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

• base name от sys.argv[0], если в качестве аргумента был передан файл.
• Имя интерпретатора 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], атрибутов модуля __main__ или аргумента 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 можно использовать для подстановки имени программы в сообщения об использовании.

Если для главного анализатора задано пользовательское сообщение об использовании, можно также передать аргумент prog в add_subparsers() или аргументы prog и usage в add_parser(), чтобы обеспечить согласованные префиксы команд и сведения об использовании во всех поданализаторах.

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() с определённым набором пар «имя—значение». Однако иногда бывает полезно указать одно значение по умолчанию для аргументов всего анализатора. Для этого конструктору ArgumentParser можно передать именованный аргумент argument_default=. Например, чтобы глобально запретить создание атрибутов при вызовах 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

suggest_on_error

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

Чтобы включить подсказки при ошибках в вариантах аргументов и именах поданализаторов, можно установить suggest_on_error в значение True. Обратите внимание, что это применяется только к аргументам, для которых варианты заданы строками:

>>> parser = argparse.ArgumentParser(suggest_on_error=True)
>>> parser.add_argument('--action', choices=['debug', 'dryrun'])
>>> parser.parse_args(['--action', 'debugg'])
usage: tester.py [-h] [--action {debug,dryrun}]
tester.py: error: argument --action: invalid choice: 'debugg', maybe you meant 'debug'? (choose from debug, dryrun)

Если вы пишете код, который должен быть совместим с более ранними версиями Python, и хотите использовать suggest_on_error при его наличии, можно задать его как атрибут после инициализации анализатора вместо передачи именованного аргумента:

>>> parser = argparse.ArgumentParser(description='Process some integers.')
>>> parser.suggest_on_error = True

color

По умолчанию справочное сообщение выводится цветным с использованием управляющих последовательностей ANSI. Если нужны справочные сообщения без цвета, эту возможность можно отключить в локальном окружении или непосредственно в анализаторе аргументов, установив color в значение False:

>>> parser = argparse.ArgumentParser(description='Process some integers.',
...                                  color=False)
>>> parser.add_argument('--action', choices=['sum', 'max'])
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.parse_args(['--help'])

Обратите внимание, что при значении color=True цветной вывод зависит как от переменных окружения, так и от возможностей терминала. Однако при значении color=False цветной вывод всегда отключён, даже если заданы такие переменные окружения, как FORCE_COLOR.

имя или флаги

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

По умолчанию argparse автоматически обрабатывает внутренние имена аргументов и их отображаемые имена, упрощая этот процесс и не требуя дополнительной настройки. Поэтому параметры dest и metavar указывать не нужно. Для необязательных аргументов параметр dest по умолчанию равен имени аргумента, при этом подчёркивания _ заменяют дефисы -. Параметр metavar по умолчанию равен имени, записанному заглавными буквами. Например:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo-bar')
>>> parser.parse_args(['--foo-bar', 'FOO-BAR'])
Namespace(foo_bar='FOO-BAR')
>>> parser.print_help()
usage:  [-h] [--foo-bar FOO-BAR]

optional arguments:
 -h, --help  show this help message and exit
 --foo-bar FOO-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', default=['0'])
  >>> parser.parse_args('--foo 1 --foo 2'.split())
  Namespace(foo=['0', '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
  

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

Рекомендуемый способ создания пользовательского действия — унаследовать класс 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='?')
  >>> parser.add_argument('outfile', nargs='?')
  >>> parser.parse_args(['input.txt', 'output.txt'])
  Namespace(infile='input.txt', outfile='output.txt')
  >>> parser.parse_args(['input.txt'])
  Namespace(infile='input.txt', outfile=None)
  >>> parser.parse_args([])
  Namespace(infile=None, outfile=None)
  

• '*'. Все имеющиеся аргументы командной строки собираются в список. Как правило, нет смысла задавать более одного позиционного аргумента с 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. Если для add_argument() не задано значение const, ему будет присвоено значение по умолчанию None.
• При вызове add_argument() со строками параметров (например, -f или --foo) и nargs='?'. Это создаёт необязательный аргумент, за которым может следовать ноль или один аргумент командной строки. При разборе командной строки, если встречается строка параметра, за которой не следует аргумент командной строки, будет использовано значение const. Примеры см. в описании 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)

Поскольку nargs='*' собирает все переданные значения в список, для отсутствующего позиционного аргумента возвращается пустой список ([]). Переопределить это может только значение default, отличное от None (поэтому default=None по-прежнему возвращает []).

Для обязательных аргументов значение 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('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. Обычно это не то, что требуется:

>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('--verbose', type=bool)
>>> parser.parse_args(['--verbose', 'False'])
Namespace(verbose=True)

Распространённые альтернативы см. в разделе BooleanOptionalAction или action='store_true'.

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

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

Даже у 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 можно передать любую последовательность, поэтому поддерживаются объекты list, объекты tuple и пользовательские последовательности.

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

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

Чтобы значения choices были понятны пользователю, рассмотрите возможность использовать пользовательскую обёртку типа, которая преобразует и форматирует значения, либо не указывайте type и выполняйте преобразование в коде приложения.

Форматированные значения 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.

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

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

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

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

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

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

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

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

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, можно задать отдельное отображение для каждого аргумента:

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

Несколько аргументов могут иметь одинаковое значение dest. По умолчанию используется значение последнего такого аргумента, указанного в командной строке. Используйте action='append', чтобы собрать значения всех этих аргументов в список. О конфликтах между строками параметров, а не именами dest, см. в разделе conflict_handler.

deprecated

В течение срока существования проекта некоторые аргументы может потребоваться удалить из командной строки. Прежде чем удалять их, следует предупредить пользователей, что эти аргументы устарели и будут удалены. Именованный аргумент deprecated метода add_argument(), значение которого по умолчанию равно False, указывает, является ли аргумент устаревшим и будет ли он удалён в будущем. Если для аргумента deprecated равно True, при использовании аргумента предупреждение будет выведено в поток sys.stderr:

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='snake.py')
>>> parser.add_argument('--legs', default=0, type=int, deprecated=True)
>>> parser.parse_args([])
Namespace(legs=0)
>>> parser.parse_args(['--legs', '4'])
snake.py: warning: option '--legs' is deprecated
Namespace(legs=4)

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

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

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

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

class argparse.BooleanOptionalAction

Подкласс Action для обработки логических флагов с положительными и отрицательными вариантами. Добавление одного аргумента, например --foo, автоматически создает оба варианта — --foo и --no-foo, которым присваиваются соответственно значения True и False:

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

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

Синтаксис значений параметров

Метод 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: unrecognized arguments: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: unrecognized arguments: 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: unrecognized arguments: -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.

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

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

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='chicken.py')
>>> subparsers = parser.add_subparsers()
>>> run = subparsers.add_parser('run')
>>> fly = subparsers.add_parser('fly', deprecated=True)
>>> parser.parse_args(['fly'])
chicken.py: warning: command 'fly' is deprecated
Namespace()

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

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

Изменено в версии 3.14: На prog подпарсера больше не влияет пользовательское сообщение об использовании в главном парсере.

Объекты 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'>)

Примечание

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

Изменено в версии 3.4: Добавлены параметры encoding и errors.

Устарело начиная с версии 3.14.

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

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

Устарело начиная с версии 3.14: Передача prefix_chars в add_argument_group() теперь считается устаревшей.

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

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, удалено в версии 3.14: Вызов add_argument_group() или add_mutually_exclusive_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)

Обратите внимание: значения по умолчанию можно задать как на уровне парсера с помощью set_defaults(), так и на уровне аргумента с помощью add_argument(). Если оба метода вызваны для одного и того же аргумента, используется последнее заданное значение по умолчанию:

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