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

Added in version 3.2.

Источник: Lib/argparse.py

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

Основная функциональность

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

parser = argparse.ArgumentParser(
                    prog='ProgramName',
                    description='What the program does',
                    epilog='Text at the bottom of help')

Метод ArgumentParser.add_argument() подключает к парсеру индивидуальные спецификации аргументов. Он поддерживает позиционные аргументы, опции, принимающие значения, и флаги включения/выключения:

parser.add_argument('filename')           # positional argument
parser.add_argument('-c', '--count')      # option that takes a value
parser.add_argument('-v', '--verbose',
                    action='store_true')  # on/off flag

Метод ArgumentParser.parse_args() запускает парсер и помещает извлеченные данные в объект argparse.Namespace:

args = parser.parse_args()
print(args.filename, args.count, args.verbose)

Пример

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

import argparse

parser = argparse.ArgumentParser(description='Process some integers.')
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)')

args = parser.parse_args()
print(args.accumulate(args.integers))

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

$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]

Process some integers.

positional arguments:
 N           an integer for the accumulator

options:
 -h, --help  show this help message and exit
 --sum       sum the integers (default: find the max)

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

$ python prog.py 1 2 3 4
4

$ python prog.py 1 2 3 4 --sum
10

Если переданы недопустимые аргументы, будет выдана ошибка:

$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'

В следующих разделах мы рассмотрим этот пример.

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

Первым шагом в использовании 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.

Объекты ArgumentParser

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

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

  • prog - Имя программы (по умолчанию: os.path.basename(sys.argv[0]))

  • usage - Строка, описывающая использование программы (по умолчанию: генерируется из аргументов, добавляемых парсером)

  • description - Текст для отображения перед справкой по аргументу (по умолчанию без текста).

  • epilog - Текст, который будет отображаться после справки по аргументам (по умолчанию без текста).

  • parents - Список объектов ArgumentParser, аргументы которых также должны быть включены

  • formatter_class - Класс для настройки вывода справки

  • prefix_chars - Набор символов, которые префиксируют необязательные аргументы (по умолчанию: „-„).

  • fromfile_prefix_chars - Набор символов префикса файлов, из которых должны быть считаны дополнительные аргументы (по умолчанию: None)

  • argument_default - Глобальное значение по умолчанию для аргументов (по умолчанию: None)

  • conflict_handler - Стратегия разрешения конфликтующих опций (обычно не нужна)

  • add_help - Добавить опцию -h/--help к парсеру (по умолчанию: True)

  • allow_abbrev - Разрешает сокращать длинные опции, если сокращение однозначно. (по умолчанию: True)

  • exit_on_error - Определяет, будет ли ArgumentParser выходить с информацией об ошибке при возникновении ошибки. (по умолчанию: True)

Изменено в версии 3.5: Добавлен параметр allow_abbrev.

Изменено в версии 3.8: В предыдущих версиях allow_abbrev также запрещала группировать короткие флаги, такие как -vv, в значения -v -v.

Изменено в версии 3.9: Добавлен параметр exit_on_error.

В следующих разделах описано, как используется каждый из них.

прог

По умолчанию объекты 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

использование

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

описание

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

Примечание

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

класс_форматера

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

class argparse.RawDescriptionHelpFormatter
class argparse.RawTextHelpFormatter
class argparse.ArgumentDefaultsHelpFormatter
class argparse.MetavarTypeHelpFormatter

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

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

префиксные_значки

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

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

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

fromfile_prefix_chars

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

>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:
...     fp.write('-f\nbar')
...
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')

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

ArgumentParser использует filesystem encoding and error handler для чтения файла с аргументами.

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

Изменено в версии 3.12: ArgumentParser изменил кодировку и ошибки при чтении файлов аргументов со стандартных (например, locale.getpreferredencoding(False) и "strict") на filesystem encoding and error handler. Файл аргументов должен быть закодирован в UTF-8 вместо ANSI Codepage в Windows.

аргумент_по умолчанию

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

Эту функцию можно отключить, установив значение 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

Added in version 3.5.

обработчик конфликтов

Объекты 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

выход_при_ошибке

Обычно, когда вы передаете некорректный список аргументов методу 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

Added in version 3.9.

Метод add_argument()

ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])

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

  • name or flags - Либо имя, либо список строк опций, например, foo или -f, --foo.

  • action - Основной тип действия, которое будет выполнено при встрече этого аргумента в командной строке.

  • nargs - Количество аргументов командной строки, которые должны быть использованы.

  • const - Постоянное значение, требуемое некоторыми выборами action и nargs.

  • default - Значение, получаемое, если аргумент отсутствует в командной строке и если он отсутствует в объекте пространства имен.

  • type - Тип, в который должен быть преобразован аргумент командной строки.

  • choices - последовательность допустимых значений для аргумента.

  • required - Можно ли опустить опцию командной строки (только для опций).

  • help - Краткое описание того, что делает аргумент.

  • metavar - имя аргумента в сообщениях об использовании.

  • dest - Имя атрибута, который будет добавлен к объекту, возвращенному командой parse_args().

  • deprecated - Является ли использование аргумента устаревшим или нет.

В следующих разделах описано, как используется каждый из них.

имя или флаги

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

    Added in version 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)

Added in version 3.9.

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

Изменено в версии 3.11: const=None по умолчанию, в том числе при action='append_const' или action='store_const'.

по умолчанию

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

тип

По умолчанию парсер считывает аргументы командной строки как простые строки. Однако довольно часто строка командной строки должна быть интерпретирована как другой тип, например 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 в 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.

требуется

В общем случае модуль 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 могут включать различные спецификаторы формата, чтобы избежать повторения таких вещей, как имя программы или аргумент default. Доступные спецификаторы включают имя программы, %(prog)s и большинство ключевых слов-аргументов к add_argument(), например %(default)s, %(type)s и т. д.:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
...                     help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar     the bar to frobble (default: 42)

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

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

argparse поддерживает отключение справки для некоторых опций, установив значение help в argparse.SUPPRESS:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]

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

метавар

Когда 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')

устаревшие

В течение жизни проекта некоторые аргументы могут потребоваться для удаления из командной строки. Перед их удалением необходимо сообщить пользователям, что эти аргументы устарели и будут удалены. Ключевое слово deprecated аргумента add_argument(), которое по умолчанию равно False, указывает, является ли аргумент устаревшим и будет ли он удален в будущем. Если для аргументов deprecated указано True, то при использовании этого аргумента в стандартную ошибку будет выведено предупреждение:

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

Изменено в версии 3.13.

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

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

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

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

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

Экземпляры 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()

ArgumentParser.parse_args(args=None, namespace=None)

Преобразуйте строки аргументов в объекты и присвойте их в качестве атрибутов пространства имен. Возвращает заполненное пространство имен.

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

  • args - Список строк для разбора. По умолчанию берется из sys.argv.

  • namespace - Объект, в который будут помещены атрибуты. По умолчанию используется новый пустой объект Namespace.

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

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

См. также the argparse howto on ambiguous arguments для более подробной информации.

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

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

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

Объект «Пространство имен

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

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='chicken.py')
>>> subparsers = parser.add_subparsers()
>>> run = subparsers.add_parser('run')
>>> fly = subparsers.add_parser('fly', deprecated=True)
>>> parser.parse_args(['fly'])  
chicken.py: warning: command 'fly' is deprecated
Namespace()

Added in version 3.13.

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

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_argument_group('Group title', 'Group description')
>>> exclusive_group = group.add_mutually_exclusive_group(required=True)
>>> exclusive_group.add_argument('--foo', help='foo help')
>>> exclusive_group.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [-h] (--foo FOO | --bar BAR)

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

Group title:
  Group description

  --foo FOO   foo help
  --bar BAR   bar help

Изменено в версии 3.11: Вызов add_argument_group() или add_mutually_exclusive_group() на взаимоисключающей группе устарел. Эти функции никогда не поддерживались и не всегда работают корректно. Функции существуют в API случайно, благодаря наследованию, и будут удалены в будущем.

Параметры парсера по умолчанию

ArgumentParser.set_defaults(**kwargs)

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

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.set_defaults(bar=42, baz='badger')
>>> parser.parse_args(['736'])
Namespace(bar=42, baz='badger', foo=736)

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

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')

Установки по умолчанию на уровне парсера могут быть особенно полезны при работе с несколькими парсерами. Пример такого типа см. в методе add_subparsers().

ArgumentParser.get_default(dest)

Получение значения по умолчанию для атрибута пространства имен, заданного либо add_argument(), либо set_defaults():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'

Помощь в печати

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

ArgumentParser.print_usage(file=None)

Выведите краткое описание того, как ArgumentParser должен быть вызван в командной строке. Если file - это None, то предполагается sys.stdout.

ArgumentParser.print_help(file=None)

Вывод справочного сообщения, включающего информацию об использовании программы и аргументах, зарегистрированных с помощью ArgumentParser. Если file - это None, то предполагается sys.stdout.

Существуют также варианты этих методов, которые просто возвращают строку, а не выводят ее на печать:

ArgumentParser.format_usage()

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

ArgumentParser.format_help()

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

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

ArgumentParser.parse_known_args(args=None, namespace=None)

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

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

Предупреждение

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

Настройка разбора файлов

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)

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

Added in version 3.7.

Обновление кода optparse

Изначально модуль argparse пытался поддерживать совместимость с optparse. Однако optparse было сложно прозрачно расширить, особенно с учетом изменений, необходимых для поддержки новых спецификаторов nargs= и улучшенных сообщений об использовании. Когда почти все в optparse было либо скопировано, либо исправлено, пытаться поддерживать обратную совместимость стало нецелесообразно.

Модуль argparse улучшает модуль стандартной библиотеки optparse по ряду параметров, включая:

  • Работа с позиционными аргументами.

  • Поддерживающие подкоманды.

  • Разрешение альтернативных префиксов опций, таких как + и /.

  • Обработка аргументов в стиле «ноль-или-больше» и «один-или-больше».

  • Создание более информативных сообщений об использовании.

  • Обеспечивает гораздо более простой интерфейс для пользовательских type и action.

Частичный путь обновления с optparse до argparse:

  • Замените все вызовы optparse.OptionParser.add_option() на вызовы ArgumentParser.add_argument().

  • Замените (options, args) = parser.parse_args() на args = parser.parse_args() и добавьте дополнительные вызовы ArgumentParser.add_argument() для позиционных аргументов. Имейте в виду, что то, что раньше называлось options, теперь в контексте argparse называется args.

  • Замените optparse.OptionParser.disable_interspersed_args(), используя parse_intermixed_args() вместо parse_args().

  • Замените действия обратного вызова и аргументы ключевого слова callback_* на аргументы type или action.

  • Замените строковые имена аргументов ключевого слова type на соответствующие объекты типа (например, int, float, complex и т. д.).

  • Замените optparse.Values на Namespace, а optparse.OptionError и optparse.OptionValueError на ArgumentError.

  • Замените строки с неявными аргументами, такими как %default или %prog, на стандартный синтаксис Python для использования словарей для форматирования строк, то есть %(default)s и %(prog)s.

  • Замените аргумент version конструктора OptionParser на вызов parser.add_argument('--version', action='version', version='<the version>').

Исключения

exception argparse.ArgumentError

Ошибка при создании или использовании аргумента (необязательного или позиционного).

Строковое значение этого исключения - сообщение, дополненное информацией об аргументе, который его вызвал.

exception argparse.ArgumentTypeError

Возникает, когда что-то идет не так при преобразовании строки командной строки в тип.