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

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

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

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

add_help

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

name or flags

Методу 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', 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='?', 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. Если при вызове 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)

Для аргументов, помеченных как required, значение 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

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

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

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

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

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

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

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

Помимо 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_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: Добавлен новый параметр required, доступный только по имени.

Объекты FileType

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

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

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

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

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

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

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

ArgumentParser.add_argument_group(title=None, description=None, *[, 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)

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