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

>>> 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 доступен для заполнения имени программы в сообщениях usage.

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', encoding=sys.getfilesystemencoding()) as fp:
...     fp.write('-f\nbar')
...
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')

Аргументы, считываемые из файла, по умолчанию должны располагаться по одному на строке (но см. также convert_arg_line_to_args()), и обрабатываются как находящиеся в том же месте, что и аргумент-ссылка на исходный файл в командной строке. Таким образом, в приведённом выше примере выражение ['-f', 'foo', '@args.txt'] считается эквивалентным выражению ['-f', 'foo', '-f', 'bar'].

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

Аргумент fromfile_prefix_chars= по умолчанию имеет значение None, что означает, что аргументы никогда не будут рассматриваться как ссылки на файлы.

argument_default

В целом, значения по умолчанию для аргументов задаются либо путём передачи значения по умолчанию методу add_argument(), либо путём вызова метода set_defaults() с набором пар имя-значение. Иногда, однако, может быть полезно задать единое значение по умолчанию для всех аргументов парсера. Это можно сделать, передав ключевой аргумент argument_default= в ArgumentParser. Например, чтобы глобально подавить создание атрибутов при вызовах parse_args(), мы используем argument_default=SUPPRESS:

>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()

allow_abbrev

Обычно, когда вы передаёте список аргументов методу parse_args() объекта ArgumentParser, он распознаёт сокращения длинных опций.

Эту функцию можно отключить, установив allow_abbrev в False:

>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
>>> parser.add_argument('--foobar', action='store_true')
>>> parser.add_argument('--foonley', action='store_false')
>>> parser.parse_args(['--foon'])
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon

conflict_handler

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
 ..
ArgumentError: argument --foo: conflicting option string(s): --foo

Иногда (например, при использовании parents) может быть полезно просто переопределять более старые аргументы с той же строкой опции. Для получения этого поведения, значение 'resolve' можно передать в аргумент conflict_handler= объекта ArgumentParser:

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

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

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

add_help

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

Указание 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 не рекомендуется, так как сложно контролировать его отображение в подсказках, справке и сообщениях об ошибках.

Отформатированные значения choices переопределяют значение по умолчанию 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 — это строка, содержащая краткое описание аргумента. Когда пользователь запрашивает справку (обычно, используя -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

метапеременная

Когда ArgumentParser генерирует сообщения справки, ей нужен способ ссылки на каждый ожидаемый аргумент. По умолчанию объекты ArgumentParser используют значение dest в качестве «имени» каждого объекта. По умолчанию для позиционных аргументов используется значение dest напрямую, а для необязательных аргументов значение dest преобразуется в верхний регистр. Таким образом, единственный позиционный аргумент с dest='bar' будет обозначаться как bar. Единственный необязательный аргумент --foo, за которым следует один аргумент командной строки, будет обозначен как FOO. Пример:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo FOO] bar

positional arguments:
 bar

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

Альтернативное имя может быть указано с помощью metavar:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo YYY] XXX

positional arguments:
 XXX

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

Обратите внимание, что metavar изменяет только отображаемое имя — имя атрибута в объекте parse_args() всё ещё определяется значением dest.

Различные значения nargs могут привести к многократному использованию метапеременной. Передача кортежа в metavar задаёт разное отображение для каждого аргумента:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]

options:
 -h, --help     show this help message and exit
 -x X X
 --foo bar baz

dest

Большинство действий ArgumentParser добавляют некоторое значение в качестве атрибута объекта, возвращаемого функцией parse_args(). Имя этого атрибута определяется ключевым аргументом dest функции add_argument(). Для позиционных действий аргументов, dest обычно передаётся в качестве первого аргумента функции add_argument():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')

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

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')

dest позволяет указать пользовательское имя атрибута:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')

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

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

См. также аргумент 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][, 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(). Однако группа взаимного исключения может быть добавлена в группу аргументов, которая имеет заголовок и описание. Например:

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

Этот метод завершает программу, выходя с указанным статусом и, если задано, выводит сообщение перед этим. Пользователь может переопределить этот метод, чтобы обработать эти шаги по-другому:

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)

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