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

Новая версия 3.2.

Исходный код: Lib/argparse.py

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

Пример

Следующий код — это программа 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

optional arguments:
 -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)

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

prog - Имя программы (по умолчанию: sys.argv[0])
usage - Строка, описывающая использование программы (по умолчанию: генерируется из аргументов, добавленных в парсер)
description - Текст, отображаемый перед справкой по аргументам (по умолчанию: нет)
epilog - Текст, отображаемый после справки по аргументам (по умолчанию: нет)
parents - Список объектов ArgumentParser, чьи аргументы также должны быть включены
formatter_class - Класс для настройки вывода справки
prefix_chars - Набор символов, являющихся префиксом для необязательных аргументов (по умолчанию: ‘-‘)
fromfile_prefix_chars - Набор символов, являющихся префиксом для файлов, из которых должны быть прочитаны дополнительные аргументы (по умолчанию: None)
argument_default - Глобальное значение по умолчанию для аргументов (по умолчанию: None)
conflict_handler - Стратегия разрешения конфликтующих опциональных аргументов (обычно не требуется)
add_help - Добавить опцию справки к парсеру (по умолчанию: True)
allow_abbrev - Разрешает сокращение длинных опций, если сокращение однозначно. (по умолчанию: True)

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

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

prog

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

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

optional arguments:
 -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]

optional arguments:
 -h, --help  show this help message and exit

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

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

usage

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

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

positional arguments:
 bar          bar help

optional arguments:
 -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

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

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

description

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

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

A foo that bars

optional arguments:
 -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

optional arguments:
 -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 опции (одну в родительском и одну в дочернем) и выдаст ошибку.

Примечание

Необходимо полностью инициализировать парсеры перед передачей их через 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

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

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

optional arguments:
 -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 [bar ...]]

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

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

MetavarTypeHelpFormatter использует имя аргумента тип для каждого аргумента в качестве отображаемого имени его значений (вместо использования 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

optional arguments:
  -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

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

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

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

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

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

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

Новая функция в версии 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

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

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

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

добавить_справку

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

optional arguments:
 -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]

optional arguments:
 --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]

optional arguments:
  +h, ++help  show this help message and exit

Метод add_argument()

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

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

имя или флаги - либо имя, либо список строк опций, например foo или -f, --foo.
действие - базовый тип действия, которое должно быть выполнено при обнаружении этого аргумента в командной строке.
nargs - количество аргументов командной строки, которые должны быть извлечены.
const - постоянное значение, необходимое для некоторых выборов действия и nargs.
значение по умолчанию - значение, которое будет произведено, если аргумент отсутствует в командной строке.
тип - тип, в который должен быть преобразован аргумент командной строки.
choices - контейнер допустимых значений для аргумента.
обязательность - требуется ли аргумент командной строки (только для необязательных).
помощь - краткое описание того, что делает аргумент.
metavar - имя аргумента в сообщениях об использовании.
dest - имя атрибута, которое будет добавлено в объект, возвращаемый parse_args().

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

имя или флаги

Метод 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. Действие '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
```

Вы также можете указать произвольное действие, передав подкласс Action или другой объект, реализующий тот же интерфейс. Рекомендуемый способ сделать это - расширить Action, переопределив метод __call__ и необязательно метод __init__.

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

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super(FooAction, self).__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
```

argparse.REMAINDER. Все оставшиеся аргументы командной строки собираются в список. Это обычно полезно для утилит командной строки, которые перенаправляют вызов на другие утилиты командной строки:
```
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo')
>>> parser.add_argument('command')
>>> parser.add_argument('args', nargs=argparse.REMAINDER)
>>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))
Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
```

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

const

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

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

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

значение по умолчанию

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

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

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)

См. раздел по ключевому аргументу default для получения информации о том, когда аргумент type применяется к аргументам по умолчанию.

Для удобства работы с различными типами файлов модуль argparse предоставляет фабричную функцию FileType, которая принимает аргументы mode=, bufsize=, encoding= и errors= функции open(). Например, FileType('w') можно использовать для создания записываемого файла:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)

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

>>> def perfect_square(string):
...     value = int(string)
...     sqrt = math.sqrt(value)
...     if sqrt != int(sqrt):
...         msg = "%r is not a perfect square" % string
...         raise argparse.ArgumentTypeError(msg)
...     return value
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square

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

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=range(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

См. раздел 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 можно передать любой объект, поддерживающий оператор in, поэтому объекты dict, set, пользовательские контейнеры и т. д. поддерживаются.

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: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required

Как показывает пример, если опция отмечена как required, метод parse_args() сообщит об ошибке, если эта опция отсутствует в командной строке.

Примечание

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

help

Значение help — это строка, содержащая краткое описание аргумента. Когда пользователь запрашивает справку (обычно с помощью -h или --help в командной строке), эти help описания будут отображаться с каждым аргументом:

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

positional arguments:
 bar     one of the bars to be frobbled

optional arguments:
 -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)

optional arguments:
 -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]

optional arguments:
  -h, --help  show this help message and exit

metavar

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

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

positional arguments:
 bar

optional arguments:
 -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

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

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

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

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

optional arguments:
 -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 Action, вызываемый объект, который возвращает вызываемый объект, обрабатывающий аргументы из командной строки. Любой объект, который соответствует этому 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, содержащий этот action.
namespace — объект Namespace, который будет возвращён методом parse_args(). Большинство action добавляют атрибут в этот объект, используя setattr().
values — связанные аргументы командной строки с применёнными преобразованиями типов. Преобразования типов задаются аргументом type для метода add_argument().
option_string — строка опции, которая была использована для вызова этого action. Аргумент option_string является необязательным и отсутствует, если action связан с позиционным аргументом.

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

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

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

Метод 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_string][, 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

optional arguments:
  -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

optional arguments:
  -h, --help  show this help message and exit

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

optional arguments:
  -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} ...

optional arguments:
  -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()
>>>
>>> # 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 создает объекты, которые могут быть переданы в аргумент type метода ArgumentParser.add_argument(). Аргументы, имеющие объекты FileType в качестве типа, будут открывать аргументы командной строки как файлы с запрошенными режимами, размерами буфера, кодировками и обработкой ошибок (см. функцию open() для получения более подробной информации):

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

Объекты FileType понимают псевдоаргумент '-' и автоматически преобразуют его в sys.stdin для читаемых объектов FileType и в sys.stdout для записываемых объектов FileType:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

Новое в версии 3.4: Ключевые аргументы 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

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

Взаимоисключающие аргументы

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

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

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

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

Правила сопоставления по префиксу применяются к 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): Этот метод завершает выполнение программы, завершая ее с указанным status и, при наличии, выводя message перед этим.

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

Следующий пример демонстрирует разницу между parse_known_args() и parse_intermixed_args(): первый возвращает ['2', '3'] в качестве необработанных аргументов, а второй собирает все позиционные аргументы в rest.

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

Метод parse_known_intermixed_args() возвращает кортеж из двух элементов: заполненное пространство имен и список оставшихся строк аргументов. Метод parse_intermixed_args() генерирует ошибку, если есть оставшиеся необработанные строки аргументов.

Введено в версии 3.7.

Обновление кода 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.
Замените аргумент конструктора OptionParser version вызовом parser.add_argument('--version', action='version', version='<the version>').