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

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

Модуль 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 — добавить в парсер параметр -h/--help (по умолчанию: True)
allow_abbrev — позволяет сокращать длинные параметры, если сокращение однозначно. (По умолчанию: True)

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

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

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

prog¶

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

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

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

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

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

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

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

formatter_class¶

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

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

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

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='''это описание было со
...         странным отступом,
...             но это нормально''',
...     epilog='''
...             точно так же и для этого эпилога, чьи пробелы
...         будут очищены и чьи слова будут заключены
...         в пару строк''')
>>> parser.print_help()
usage: PROG [-h]

это описание было со странным отступом, но это нормально

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

точно так же и для этого эпилога, чьи пробелы будут очищены и чьи
слова будут заключены в пару строк

Передача 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

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 использует имя аргумента 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

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

prefix_chars¶

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

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

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

fromfile_prefix_chars¶

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

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

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

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

argument_default¶

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

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

allow_abbrev¶

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

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

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

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

conflict_handler¶

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

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

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

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

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.

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]

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

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

name или flags — имя или список строк параметров, например foo или -f, --foo.
action — основной тип действия, которое должно быть выполнено, когда этот аргумент встречается в командной строке.
nargs — количество аргументов командной строки, которые следует использовать.
const — постоянное значение, необходимое для некоторых выборок action и nargs.
default — значение, полученное, если аргумент отсутствует в командной строке.
type — тип, в который должен быть преобразован аргумент командной строки.
choices — контейнер допустимых значений для аргумента.
required — можно ли пропустить параметр командной строки (только для дополнительных параметров).
help — краткое описание того, что делает аргумент.
metavar — имя аргумента в сообщениях об использовании.
dest — имя атрибута, который будет добавлен к объекту, возвращенному parse_args().

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

name или flags¶

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

action¶

Объекты 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)
```
Обратите внимание, что default будет None, если явно не установлено значение 0.
'help' — выводит полное справочное сообщение для всех параметров текущего парсингатора и затем закрывается. По умолчанию в парсер автоматически добавляется действие справки. См. ArgumentParser для получения подробной информации о том, как создаётся вывод.

'version' — ожидает ключевой аргумент version= в вызове add_argument(), выводит информацию о версии и завершает работу при вызове:

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

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

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

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

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

Пример настраиваемого действия:

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs не разрешены")
...         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(). Примеры см. в описании action.
Когда add_argument() вызывается со строками опций (например, -f или --foo) и nargs='?'. Создаёт необязательный аргумент, за которым может следовать ноль или один аргумент командной строки. Если при парсинге командной строки встречается строка параметра без аргумента командной строки, следующего за ней, вместо неё будет принято значение const. Примеры см. в описании nargs.

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

default¶

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

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

Если значение default является строкой, парсер анализирует значение, как если бы оно было аргументом командной строки. В частности, парсер применяет любой аргумент преобразования типа, если он предоставлен, перед установкой атрибута для возвращаемого значения 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, поэтому поддерживаются объекты list, объекты 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: [-h] --foo FOO
: error: the following arguments are required: --foo

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

Примечание

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

help¶

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

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

positional arguments:
 bar     one of the bars to be frobbled

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

Классы Action¶

Классы 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.

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

>>> # неверный тип
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # неверная опция
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # неправильное количество аргументов
>>> 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='?')

>>> # нет опций с отрицательными числами, поэтому -1 - позиционный аргумент
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # нет опций с отрицательными числами, поэтому -1 и -5 являются позиционными аргументами
>>> 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='?')

>>> # присутствуют опции с отрицательными числами, поэтому опция -1
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # присутствуют опции с отрицательными числами, поэтому опция -2
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # присутствуют опции с отрицательными числами, поэтому оба значения -1 являются опциями
>>> 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, ..}

Некоторые примеры использования:

>>> # создать парсер верхнего уровня
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='sub-command help')
>>>
>>> # создать парсер для команды "a"
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # создать парсер для команды "b"
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
>>>
>>> # распарсить некоторые списки аргументов
>>> 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='допустимые подкоманды',
...                                    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:
  допустимые подкоманды

  {foo,bar}   дополнительная помощь

Кроме того, 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 он должен выполнить. Например:

>>> # подкомандные функции
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # создать парсер верхнего уровня
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>>
>>> # создать парсер для команды "foo"
>>> 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)
>>>
>>> # создать парсер для команды "bar"
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # распарсить аргументы и вызвать любую выбранную функцию
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # распарсить аргументы и вызвать любую выбранную функцию
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))

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

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')

Изменено в версии 3.7: Новый ключевой аргумент required.

FileType объекты¶

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)¶

Фабрика FileType создаёт объекты, которые можно передать аргументу типа ArgumentParser.add_argument(). Аргументы, у которых есть объекты FileType в качестве своего типа, будут открывать аргументы командной строки как файлы с запрошенными режимами, размерами буфера, кодировками и обработкой ошибок (подробнее см. функцию open()):

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

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

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

Добавлено в версии 3.4: Ключевые аргументы encodings и errors.

Группы аргументов¶

ArgumentParser.add_argument_group(title=None, description=None)¶

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

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> parser.print_help()
usage: PROG [--foo FOO] bar

group:
  bar    bar help
  --foo FOO  foo help

Метод add_argument_group() возвращает объект группы аргументов, у которого есть метод add_argument(), как и обычный ArgumentParser. Когда аргумент добавляется в группу, парсер обрабатывает его так же, как обычный аргумент, но отображает аргумент в отдельной группе для справочных сообщений. Метод add_argument_group() принимает аргументы title и description, которые можно использовать для настройки этого отображения:

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'group1 description')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'group2 description')
>>> group2.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [--bar BAR] foo

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help

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

Взаимное исключение¶

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

class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Выход из-за ошибки: {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 и будут вызывать исключения, если используются неподдерживаемые функции. В частности, не поддерживаются подпарсеры, 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 было либо скопировано, либо использовались бы партизанские заплатки (monkey-patched), поэтому пытаться поддерживать обратную совместимость больше не казалось практичным.

Модуль 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>').

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