argparse – парсер для параметров командной строки, аргументов и подкоманд¶argparse – Parser for command-line options, arguments and subcommands

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

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

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

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

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

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

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

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

Для аргументов 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. Обычно это не то, что нужно:

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

Action классы реализуют 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.

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

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

Недопустимые аргументы¶Invalid arguments

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')

>>> # недопустимый тип
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # недопустимая опция
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # неверное количество аргументов
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger

Аргументы, содержащие -¶Arguments containing -

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')

>>> # нет опций с отрицательными числами, поэтому -1 – позиционный аргумент
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # нет опций с отрицательными числами, поэтому -1 и -5 – позиционные аргументы
>>> 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='?')

>>> # опции с отрицательными числами присутствуют, поэтому -1 – это опция
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # опции с отрицательными числами присутствуют, поэтому -2 – это опция
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # опции с отрицательными числами присутствуют, поэтому обе -1 – это опции
>>> 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 о неоднозначных аргументах для получения дополнительных сведений.

Сокращения аргументов (совпадение по префиксу)¶Argument abbreviations (prefix matching)

Метод 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¶Beyond 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¶The Namespace object

class argparse.Namespace¶

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

Этот класс намеренно прост, всего лишь подкласс object с читаемым строковым представлением. Если нужно dict-подобное представление атрибутов, можно воспользоваться стандартной идиомой 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'

Подкоманды¶Subcommands

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

Пример использования:

>>> # создать парсер верхнего уровня
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='subcommand help')
>>>
>>> # создать парсер для команды "a"
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # создать парсер для команды "b"
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')
>>>
>>> # разобрать некоторые списки аргументов
>>> 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() также поддерживает дополнительный аргумент устарело, который позволяет пометить подпарсер как устаревший.

>>> 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 он должен выполнить. Например:

>>> # функции подкоманд
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # создать парсер верхнего уровня
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(required=True)
>>>
>>> # создать парсер для команды "foo"
>>> 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)
>>>
>>> # создать парсер для команды "bar"
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # разобрать аргументы и вызвать выбранную функцию
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # разобрать аргументы и вызвать выбранную функцию
>>> 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¶FileType objects

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: Добавлены параметры encoding и errors.

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

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 случайно, из-за наследования, и будет удалена в будущем.

Взаимное исключение¶Mutual exclusion

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 случайно, из-за наследования, и будут удалены в будущем.

Умолчания парсера¶Parser defaults

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'

Вывод справки¶Printing help

В большинстве типичных приложений 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.

Частичный разбор¶Partial parsing

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

Настройка разбора файлов¶Customizing file parsing

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

Обратите внимание: при таком переопределении аргумент больше не может содержать пробелы, поскольку каждое отделённое пробелом слово становится отдельным аргументом.

Методы завершения¶Exiting methods

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.

Смешанный разбор¶Intermixed parsing

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.

Регистрация пользовательских типов или действий¶Registering custom types or actions

ArgumentParser.register(registry_name, value, object)¶

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

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

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

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