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

prog

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

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

Это значение по умолчанию почти всегда желательно, так как оно сделает сообщения справки соответствующими строке, используемой для вызова программы в командной строке. Однако, чтобы изменить это поведение по умолчанию, можно использовать другое значение с помощью аргумента prog= к ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

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

Обратите внимание, что имя программы, определяемое из sys.argv[0] или из аргумента prog=, доступно для сообщений справки с использованием формата %(prog)s.

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program

usage

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

>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]

positional arguments:
 bar          bar help

options:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help

Для подстановки имени программы в сообщениях об использовании доступен спецификатор формата %(prog)s.

description

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

По умолчанию описание будет переносить строки, чтобы оно поместилось в заданное пространство. Чтобы изменить это поведение, см. аргумент formatter_class.

epilog

Некоторые программы хотят отобразить дополнительное описание программы после описания аргументов. Такой текст может быть задан с помощью аргумента epilog= к ArgumentParser:

>>> parser = argparse.ArgumentParser(
...     description='A foo that bars',
...     epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

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

And that's how you'd foo a bar

Как и с аргументом description, текст epilog= по умолчанию переносит строки, но это поведение может быть изменено с помощью аргумента formatter_class к ArgumentParser.

parents

Иногда несколько парсеров используют набор общих аргументов. Вместо того, чтобы повторять определения этих аргументов, можно использовать один парсер со всеми общими аргументами, передаваемый в аргумент parents= к ArgumentParser. Аргумент parents= принимает список объектов ArgumentParser, собирает все позиционные и необязательные действия из них и добавляет эти действия к объекту ArgumentParser, который строится:

>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)

Обратите внимание, что большинство парсеров-родителей будут указывать add_help=False. В противном случае, ArgumentParser увидит две -h/--help опции (одну в родителе и одну в ребенке) и выдаст ошибку.

formatter_class

Объекты ArgumentParser позволяют настроить форматирование справки, указав другой класс форматирования. В настоящее время существует четыре таких класса:

class argparse.RawDescriptionHelpFormatter

class argparse.RawTextHelpFormatter

class argparse.ArgumentDefaultsHelpFormatter

class argparse.MetavarTypeHelpFormatter

RawDescriptionHelpFormatter и RawTextHelpFormatter дают больший контроль над тем, как отображаются текстовые описания. По умолчанию, объекты ArgumentParser перенос строк в описании description и epilog в сообщениях справки командной строки:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='''this description
...         was indented weird
...             but that is okay''',
...     epilog='''
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

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

likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines

Передача RawDescriptionHelpFormatter в качестве formatter_class= указывает на то, что description и epilog уже отформатированы и не должны переноситься на новую строку:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('''\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '''))
>>> parser.print_help()
usage: PROG [-h]

Please do not mess up this text!
--------------------------------
   I have indented it
   exactly the way
   I want it

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

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

ArgumentDefaultsHelpFormatter автоматически добавляет информацию о значениях по умолчанию в сообщения справки по каждому из аргументов:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar ...]

positional arguments:
 bar         BAR! (default: [1, 2, 3])

options:
 -h, --help  show this help message and exit
 --foo FOO   FOO! (default: 42)

MetavarTypeHelpFormatter использует имя аргумента type для каждого аргумента в качестве имени отображения его значений (вместо использования dest, как это делает обычный форматировщик):

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float

positional arguments:
  float

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

prefix_chars

Большинство опций командной строки будут использовать - в качестве префикса, например, -f/--foo. Парсеры, которым необходимо поддерживать разные или дополнительные символы префикса, например, для опций, таких как +f или /foo, могут указать их с помощью аргумента prefix_chars= конструктора ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')

Аргумент prefix_chars= по умолчанию равен '-'. Передача набора символов, не включающего - , приведет к тому, что опции -f/--foo будут запрещены.

fromfile_prefix_chars

Иногда при работе со списком аргументов значительной длины может быть целесообразно хранить список аргументов в файле вместо ввода его в командной строке. Если аргумент 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

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

Имя или флаги

Метод add_argument() должен знать, ожидается ли необязательный аргумент, такой как -f или --foo, или позиционный аргумент, такой как список имен файлов. Поэтому первые аргументы, передаваемые add_argument(), должны быть либо серией флагов, либо простым именем аргумента.

Например, необязательный аргумент можно создать так:

>>> parser.add_argument('-f', '--foo')

в то время как позиционный аргумент можно создать так:

>>> parser.add_argument('bar')

Когда вызывается parse_args(), необязательные аргументы будут определяться по префиксу -, а оставшиеся аргументы будут считаться позиционными:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar

Действие

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

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

• 'store_const' - Сохраняет значение, указанное аргументом const; обратите внимание, что аргумент const по умолчанию равен None. Действие 'store_const' чаще всего используется с необязательными аргументами, которые задают некий флаг. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', action='store_const', const=42)
  >>> parser.parse_args(['--foo'])
  Namespace(foo=42)
  

• 'store_true' и 'store_false' - Это частные случаи 'store_const' для хранения значений True и False соответственно. Кроме того, они создают значения по умолчанию False и True соответственно:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', action='store_true')
  >>> parser.add_argument('--bar', action='store_false')
  >>> parser.add_argument('--baz', action='store_false')
  >>> parser.parse_args('--foo --bar'.split())
  Namespace(foo=True, bar=False, baz=True)
  

• 'append' - Сохраняет список и добавляет каждое значение аргумента в список. Это полезно, когда опция может быть указана несколько раз. Если значение по умолчанию не пустое, элементы по умолчанию будут присутствовать в парсированном значении для опции, а любые значения из командной строки будут добавлены после этих значений по умолчанию. Пример использования:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', action='append')
  >>> parser.parse_args('--foo 1 --foo 2'.split())
  Namespace(foo=['1', '2'])
  

• 'append_const' - Сохраняет список и добавляет значение, указанное аргументом const, в список; обратите внимание, что аргумент const по умолчанию равен None. Действие 'append_const' обычно полезно, когда несколько аргументов должны хранить константы в одном списке. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
  >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
  >>> parser.parse_args('--str --int'.split())
  Namespace(types=[<class 'str'>, <class 'int'>])
  

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

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
  >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
  Namespace(foo=['f1', 'f2', 'f3', 'f4'])
  

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

• 'count' - Подсчитывает количество раз, когда появляется ключевой аргумент. Например, это полезно для увеличения уровня подробности:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--verbose', '-v', action='count', default=0)
  >>> parser.parse_args(['-vvv'])
  Namespace(verbose=3)
  

  Обратите внимание, что значение по умолчанию будет None, если не установлено явно 0.

• 'help' - Выводит полное сообщение справки для всех опций в текущем парсере и завершает выполнение. По умолчанию действие справки автоматически добавляется в парсер. См. ArgumentParser для получения подробностей о создании вывода.

• 'version' - Ожидает аргумент version= в вызове add_argument() и выводит информацию о версии, а затем завершает выполнение:

  >>> import argparse
  >>> parser = argparse.ArgumentParser(prog='PROG')
  >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
  >>> parser.parse_args(['--version'])
  PROG 2.0
  

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

class argparse.BooleanOptionalAction

Вы также можете указать произвольное действие, передав подкласс Action или другой объект, реализующий тот же интерфейс. Действие BooleanOptionalAction доступно в argparse и добавляет поддержку для логических действий, таких как --foo и --no-foo:

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

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

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

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

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super().__init__(option_strings, dest, **kwargs)
...     def __call__(self, parser, namespace, values, option_string=None):
...         print('%r %r %r' % (namespace, values, option_string))
...         setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')

Для получения более подробной информации см. Action.

nargs

ArgumentParser объекты обычно связывают один аргумент командной строки с одним действием. Параметр nargs позволяет связать разное количество аргументов командной строки с одним действием. См. также Определение неоднозначных аргументов. Поддерживаемые значения:

• N (целое число). N аргументов из командной строки будут объединены в список. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', nargs=2)
  >>> parser.add_argument('bar', nargs=1)
  >>> parser.parse_args('c --foo a b'.split())
  Namespace(bar=['c'], foo=['a', 'b'])
  

  Обратите внимание, что nargs=1 создаёт список из одного элемента. Это отличается от значения по умолчанию, где элемент выводится самостоятельно.

• '?'. Один аргумент будет получен из командной строки, если это возможно, и выведен как отдельный элемент. Если аргумент командной строки отсутствует, будет использовано значение из default. Обратите внимание, что для необязательных аргументов есть дополнительный случай - строка опции присутствует, но не следует за ней аргумент командной строки. В этом случае будет использовано значение из const. Некоторые примеры для иллюстрации:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
  >>> parser.add_argument('bar', nargs='?', default='d')
  >>> parser.parse_args(['XX', '--foo', 'YY'])
  Namespace(bar='XX', foo='YY')
  >>> parser.parse_args(['XX', '--foo'])
  Namespace(bar='XX', foo='c')
  >>> parser.parse_args([])
  Namespace(bar='d', foo='d')
  

  Одно из наиболее распространённых применений nargs='?' — это разрешение необязательных входных и выходных файлов:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
  ...                     default=sys.stdin)
  >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
  ...                     default=sys.stdout)
  >>> parser.parse_args(['input.txt', 'output.txt'])
  Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
            outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
  >>> parser.parse_args([])
  Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
            outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
  

• '*'. Все аргументы командной строки, присутствующие в списке, будут объединены в список. Обратите внимание, что обычно не имеет смысла иметь более одного позиционного аргумента с nargs='*', но несколько необязательных аргументов с nargs='*' возможны. Например:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', nargs='*')
  >>> parser.add_argument('--bar', nargs='*')
  >>> parser.add_argument('baz', nargs='*')
  >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
  Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
  

• '+'. Как и '*', все присутствующие аргументы командной строки собираются в список. Кроме того, будет выведено сообщение об ошибке, если присутствовал хотя бы один аргумент командной строки. Например:

  >>> parser = argparse.ArgumentParser(prog='PROG')
  >>> parser.add_argument('foo', nargs='+')
  >>> parser.parse_args(['a', 'b'])
  Namespace(foo=['a', 'b'])
  >>> parser.parse_args([])
  usage: PROG [-h] foo [foo ...]
  PROG: error: the following arguments are required: foo
  

Если параметр nargs не указан, количество потребляемых аргументов определяется параметром action. Обычно это означает, что будет потреблён один аргумент командной строки и один элемент (не список) будет выведен. Действия, которые не потребляют аргументы командной строки (например, 'store_const') устанавливают nargs=0.

const

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

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

default

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

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

Если в целевом пространстве имён уже задан атрибут, действие default не перезапишет его:

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

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

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

>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')

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

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

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

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

Обязательность

В общем случае модуль 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 представляет собой строку, содержащую краткое описание аргумента. Когда пользователь запрашивает справку (обычно с помощью -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 используется несколько раз. Передача кортежа в 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 метода add_argument(), который имеет значение по умолчанию False, указывает, является ли аргумент устаревшим и будет ли он удален в будущем. Для аргументов, если deprecated имеет значение True, при использовании аргумента будет выведено предупреждение в sys.stderr:

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

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

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

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

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

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

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

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

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

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

format_usage()

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

Синтаксис значения опции

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)

Для длинных опций (опций с именами длиннее одного символа) опция и значение также могут передаваться как один аргумент командной строки, используя = для разделения:

>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)

Для коротких опций (опций длиной в один символ) опция и её значение могут быть объединены:

>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')

Несколько коротких опций могут быть объединены, используя только один префикс -, при условии, что только последняя опция (или ни одна из них) требует значения:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')

Неверные аргументы

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

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

>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger

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

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

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

>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')

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

>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument

Если у вас есть позиционные аргументы, которые должны начинаться с - и не похожи на отрицательные числа, вы можете вставить псевдоаргумент '--', который сообщает parse_args(), что всё после него — позиционный аргумент:

>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)

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

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

Метод parse_args() по умолчанию позволяет сокращать длинные опции до префикса, если сокращение является однозначным (префикс соответствует уникальной опции):

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon

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

За пределами sys.argv

Иногда может быть полезно, чтобы ArgumentParser обрабатывал аргументы, отличные от тех, что в sys.argv. Этого можно достичь, передав список строк методу parse_args(). Это полезно для тестирования в интерактивном режиме:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
...     'integers', metavar='int', type=int, choices=range(10),
...     nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
...     '--sum', dest='accumulate', action='store_const', const=sum,
...     default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

Объект Namespace

class argparse.Namespace

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

Этот класс преднамеренно прост, это просто подкласс object со удобочитаемым представлением в виде строки. Если вы предпочитаете иметь представление об атрибутах в виде словаря, вы можете использовать стандартный Python-приём, vars():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}

Также может быть полезно, чтобы ArgumentParser присваивал атрибуты уже существующему объекту, а не новому объекту Namespace. Этого можно достичь, указав ключевой аргумент namespace=:

>>> class C:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

Подкоманды

ArgumentParser.add_subparsers(*[, title][, description][, prog][, parser_class][, action][, dest][, required][, help][, metavar])

Многие программы разбивают свою функциональность на ряд подкоманд, например, программа svn может вызывать подкоманды, такие как svn checkout, svn update, и svn commit. Такое разделение функциональности может быть особенно полезно, когда программа выполняет несколько различных функций, которые требуют различных типов аргументов командной строки. ArgumentParser поддерживает создание таких подкоманд с помощью метода add_subparsers(). Метод add_subparsers() обычно вызывается без аргументов и возвращает специальный объект действия. Этот объект имеет один метод, add_parser(), который принимает имя команды и любые аргументы конструктора ArgumentParser, и возвращает объект ArgumentParser, который можно модифицировать как обычно.

Описание параметров:

• title - заголовок группы подпарсеров в выводе справки; по умолчанию «подкоманды», если описание предоставлено, в противном случае используется заголовок для позиционных аргументов
• 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 создает объекты, которые могут передаваться в аргумент типа 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, который является ключом, под которым объект будет зарегистрирован, и 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'