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

Создание парсера

Первый шаг при использовании argparse — это создание объекта ArgumentParser:

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

Объект ArgumentParser будет хранить всю необходимую информацию для разбора командной строки в типы данных Python.

Добавление аргументов

Заполнение объекта ArgumentParser информацией об аргументах программы выполняется вызовами метода add_argument(). Как правило, эти вызовы сообщают ArgumentParser, как преобразовать строки из командной строки в объекты. Эта информация хранится и используется при вызове parse_args(). Например:

>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
...                     const=sum, default=max,
...                     help='sum the integers (default: find the max)')

Позже, вызов parse_args() вернёт объект с двумя атрибутами, integers и accumulate. Атрибут integers будет списком из одного или нескольких целых чисел, а атрибут accumulate будет либо функцией sum(), если --sum был указан в командной строке, либо функцией max(), если он не был указан.

Парсинг аргументов

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

>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

В скрипте, parse_args() обычно вызывается без аргументов, и ArgumentParser автоматически определяет аргументы командной строки из sys.argv.

prog

По умолчанию объекты ArgumentParser используют sys.argv[0] для определения того, как отображать имя программы в сообщениях справки. Этот параметр по умолчанию почти всегда желателен, потому что он сделает сообщения справки совпадающими с тем, как программа была вызвана в командной строке. Например, рассмотрим файл с именем myprogram.py со следующим кодом:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

Справка для этой программы отобразит myprogram.py в качестве имени программы (независимо от того, откуда была вызвана программа):

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

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

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

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

positional arguments:
 bar          bar help

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

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

>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

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

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

Аргумент 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 добавляют опцию, которая просто отображает сообщение справки парсера. Например, рассмотрим файл с именем myprogram.py содержащий следующий код:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

Если -h или --help указаны в командной строке, будет выведено сообщение справки ArgumentParser:

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

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

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

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

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo')
  >>> parser.parse_args('--foo 1'.split())
  Namespace(foo='1')
  

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

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

• 'extend' - сохраняет список и расширяет каждое значение аргумента в списке. Пример использования:

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

Вы также можете указать любое действие, передав подкласс 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)

Рекомендуемый способ создания пользовательского действия — наследование от Action, переопределение метода __call__ и необязательно методов __init__ и format_usage.

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

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

const

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

• Когда add_argument() вызывается с action='store_const' или action='append_const'. Эти действия добавляют значение const в одно из атрибутов объекта, возвращаемого методом parse_args(). См. описание действия для примеров. Если 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)

Указание значения 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 может быть любым вызываемым объектом, принимающим одну строку. Если функция вызывает исключение 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('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)

Также можно использовать пользовательские функции:

>>> def hyphenated(string):
...     return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')

Функция bool() не рекомендуется в качестве преобразователя типа. Всё, что она делает, это преобразует пустые строки в False, а непустые строки в True. Обычно это не то, что требуется.

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

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

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

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

choices

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

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

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

>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

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

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

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

required

В общем случае модуль argparse предполагает, что флаги, такие как -f и --bar указывают на необязательные аргументы, которые всегда можно опустить в командной строке. Чтобы сделать опцию обязательной, следует указать True для параметра required= метода add_argument():

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

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
...                     help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
...                     help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]

positional arguments:
 bar     one of the bars to be frobbled

options:
 -h, --help  show this help message and exit
 --foo   foo the bars before frobbling

Строки 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')

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

Классы действий реализуют 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)

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

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

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

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

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

Подклассы 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)

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

Метод 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][, option_strings][, 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='sub-command 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='XYZ', 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}   sub-command help
    a     a help
    b     b help

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

>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar

positional arguments:
  bar     bar help

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

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]

options:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

Метод add_subparsers() также поддерживает ключевые аргументы title и description. Если присутствует любой из них, команды подпарсера будут отображаться в своей собственной группе в выводе справки. Например:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
...                                    description='valid subcommands',
...                                    help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage:  [-h] {foo,bar} ...

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

subcommands:
  valid subcommands

  {foo,bar}   additional help

Кроме того, add_parser поддерживает дополнительный аргумент aliases, который позволяет нескольким строкам ссылаться на один и тот же подпарсер. В этом примере, как и в svn, co используется в качестве сокращения для checkout:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>> checkout = subparsers.add_parser('checkout', aliases=['co'])
>>> checkout.add_argument('foo')
>>> parser.parse_args(['co', 'bar'])
Namespace(foo='bar')

Один из особенно эффективных способов обработки подкоманд — объединить использование метода add_subparsers() с вызовами set_defaults() таким образом, чтобы каждый подпарсер знал, какую функцию Python он должен выполнить. Например:

>>> # sub-command 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)

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

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

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

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

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

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